v50 Steam/Premium information for editors
  • v50 information can now be added to pages in the main namespace. v0.47 information can still be found in the DF2014 namespace. See here for more details on the new versioning policy.
  • Use this page to report any issues related to the migration.
This notice may be cached—the current version can be found here.

Difference between revisions of "Utility:Dfterm2"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
(Update supported versions list)
(16 intermediate revisions by 11 users not shown)
Line 1: Line 1:
<small>Note: The most recent guide is in the dfterm2 official [http://genodeen.net/files/dfterm2/manual.pdf manual]. Content from the manual is here with the author's permission.</small>
+
{{Quality|Fine|14:11, 13 June 2014 (UTC)}}
<br>
+
{{uv|DF2012}}
 
+
[http://www.bay12forums.com/smf/index.php?topic=50643.0 '''Dfterm2'''] is a remote Dwarf Fortress playing software for multiple users through telnet. It has been replaced by [[Utility:Dfterm3|Dfterm3]], which has similar functions through an easier-to-use web interface.
 
 
= Introduction =
 
 
 
'''Dfterm2''' is a program that manages Dwarf Fortress games and allows them to be accessed remotely using Telnet and ANSI/VT102
 
compliant terminals, or using a browser with a flash plugin.
 
It has several features designed for building public Dwarf Fortress servers feasible, such as user registration system and a chat.
 
It works on both Windows and Linux platforms, albeit the way the game is handled is a little different. On Windows systems,
 
dfterm2 reads screen data from Dwarf Fortress’ memory. On Linux, Dwarf Fortress must be set to use terminal text mode (i.e.
 
[PRINT_MODE:TEXT]), and dfterm2’s terminal emulator parses this output. Linux version of dfterm2 works also on other
 
programs that use a terminal for their output.
 
Dfterm2 is designed to be easily deployed and configured. There are no configuration files to modify. All settings are set by
 
logging in to it and using the text mode UI. The only exception is setting up an administrator account with which to configure it,
 
but usually the Windows installer can handle even that.
 
Dfterm2 is fully usable, but there are missing features that need to be implemented before a stable version can be released.
 
Dfterm2, as of writing of this, is under constant development and it may happen that this manual becomes out of date with the
 
current features.
 
 
 
= Compatible versions =
 
 
 
*{{version|0.31.14}}
 
*{{version|0.31.13}}
 
*{{version|0.31.12}}
 
*{{version|0.31.11}}
 
*{{version|0.31.10}}
 
*{{version|0.31.09}}
 
*{{version|0.31.08}}
 
*{{version|0.31.06}}
 
*{{version|0.31.03}}
 
*{{version|0.31.02}}
 
*{{version|0.31.01}}
 
*{{version|0.28.181.40d19.2}}
 
*{{version|0.28.181.40d19}}
 
*{{version|0.28.181.40d18}}
 
 
 
<i>Usually only the most recent Dwarf Fortress versions are tested.'' ''It is possible there are changes in dfterm2 that partially break
 
compatibility in older versions. The versions listed are Dwarf Fortress versions that each have dedicated code in dfterm2 to
 
handle them.
 
 
 
 
 
Linux version parses Dwarf Fortress’ text terminal output so it supports any Dwarf Fortress version that supports [PRINT_MODE:TEXT]</i>
 
 
 
= Installation =
 
 
 
===On Windows===
 
For Windows, Dfterm2 comes with an automatic extractor (installer) so it shouldn't pose any problems.
 
 
 
The latest installer for the program can be found [http://www.bay12forums.com/smf/index.php?topic=50643.0. here], on the Bay12 forums.
 
 
 
To connect to the server on Windows you need a third-party program, such as PuTTY, which can be downloaded from [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html here]
 
  
 
===On linux===
 
===On linux===
 
You need to compile the program directly from source. To do so you need to install the following packages:
 
You need to compile the program directly from source. To do so you need to install the following packages:
ICU development libraries
+
* ICU development libraries
 
* Boost development libraries (at least version 1.42)
 
* Boost development libraries (at least version 1.42)
 
* OpenSSL development libraries
 
* OpenSSL development libraries
Line 60: Line 11:
 
* PCRE development libraries
 
* PCRE development libraries
 
* g++ and usual development tools
 
* g++ and usual development tools
* lua
+
* lua ( > 5.1 Doesn't work) (use 5.0)
 
* git
 
* git
<br><br>
+
 
 
First, you need to obtain the source code, using the following commands in git:
 
First, you need to obtain the source code, using the following commands in git:
{| cellspacing="0" cellpadding="0" border="0" align="left" style="background-color:#E0E0E0"
+
<pre>
|$ git clone git://genodeen.net/dfterm2
+
$ git clone git://genodeen.net/dfterm2
|-
+
$ cd dfterm2
|$ cd dfterm2
+
$ git submodule init
|-
+
$ git submodule update
|$ git submodule init
+
</pre>
|-
+
 
|$ git submodule update
 
|-
 
|}
 
<br><br><br><br><br>
 
 
Next, you have to use CMake to configure the building system:
 
Next, you have to use CMake to configure the building system:
{| cellspacing="0" cellpadding="3" border="0" align="left" style="background-color:#E0E0E0"
+
<pre>$ cmake .</pre>
|$ cmake .
+
 
|}
 
<br><br>
 
 
Thirdly, use this command to start the compiling:
 
Thirdly, use this command to start the compiling:
{| cellspacing="0" cellpadding="3" border="0" align="left" style="background-color:#E0E0E0"
+
<pre>$ make</pre>
|$ make  
+
 
|}
+
''If compilation failed, [http://www.bay12forums.com/smf/index.php?topic=50643.0 visit the DFterm2 page on the Bay12 forums] for support.''
<div style="text-align: right">''If compilation failed, [http://www.bay12forums.com/smf/index.php?topic=50643.0 visit the DFterm2 page on the Bay12 forums] for support.''</div>
+
 
<br>
 
 
The final step is to add an administrator account using  
 
The final step is to add an administrator account using  
{| cellspacing="0" cellpadding="3" border="0" align="left" style="background-color:#E0E0E0"
+
<pre>
|$ ./dfterm2_configure --adduser (username) (password) admin  
+
$ ./dfterm2_configure --adduser (username) (password) admin  
|-
+
$ ./dfterm2
|$ ./dfterm2
+
</pre>
|}
 
<br><br>
 
 
 
  
 
To connect to the server from a linux machine, you need to use the following command:
 
To connect to the server from a linux machine, you need to use the following command:
{| cellspacing="0" cellpadding="3" border="0" align="left" style="background-color:#E0E0E0"
+
<pre>$ telnet 127.0.0.1 8000</pre>
|$ telnet 127.0.0.1 8000
 
|}
 
<br><br>
 
 
 
= Configuring =
 
Dfterm2 can be configured in various ways. For example, if you want to play Dwarf Fortress through it, you need to tell it where
 
it can find Dwarf Fortress on your computer.
 
In dfterm2, there’s a concept of slot profiles and slots.
 
Slot profile contains information on what show to in a slot. Typical settings are game executable and working directory, and
 
maximum number of slots of a slot profile.
 
Slots are created from slot profiles. You could say they are instances of slot profiles. A slot is created when a user selects "Launch
 
a new game". This usually launches the game and it can be seen through the slot. Users see the slot in the Game window. When
 
they are not watching a slot, the game window is filled with X letters.
 
 
 
== Main menu ==
 
The main menu items are as follows:
 
*Launch a new game
 
From here, you can launch a new slot from a slot profile.
 
*Join a running game
 
From here you can select the slot you want to watch.
 
*Configure slots
 
Administrator only. From here you can configure slot profiles. There’s more information on them later.
 
*Set MotD
 
Administrator only. You can write a message here to show to anyone who connects to the server. The message will appear in the
 
chat window.
 
*Manage users
 
Administrator only. You can see a list of currently connected people here. Selecting them will allow you to show their IP address
 
and hostname and you can also disconnect them. If you select Show user accounts here, you can see registered users and delete
 
them or change their passwords if you like. Note that you can’t see the passwords of the users because they are hashed with
 
SHA512.
 
*Force close running slot
 
If you select this, the slot you are currently watching will be immdiately closed and the program in it will be killed. You need to
 
have force closer privileges for the slot.
 
*Change your password
 
You can change your password here. You need to know your old password.
 
*Disconnect
 
If you select this, the server disconnects you.
 
*Shutdown server
 
Administrator only. Makes dfterm2 close, closing all games and connections.
 
 
 
== Slot profile configuration ==
 
Slot profiles are created from "Configure slots" menu. You can set the maximum amount of slots that can be run at the same time
 
in this menu. From here, select "Add a new slot profile" to go in the slot profile creation menu.
 
There are a few parameters that can be configured for a new slot profile. Here they are listed with descriptions on what they do.
 
*Slot profile name
 
This is the name of the slot profile. The name will appear in "Launch a new game" menu for users. You need to put something
 
here.
 
*Method of screen scraping
 
This describes how dfterm2 will obtain the symbol data from dfterm2. On Windows, this can be either launching a new Dwarf
 
Fortress process or using an already running Dwarf Fortress process. On Linux, there’s only launching a program in a terminal.
 
*Game executable path
 
This should point directly to the Dwarf Fortress executable file. OnWindows, it could be something like "C:\df_31_12_win\Dwarf
 
Fortress.exe" and on Linux it could be "/home/mikko/df_linux/df"
 
*Game working directory
 
This should point to the directory from where game executable is run. OnWindows, it could be something like "C:\df_31_12_win"
 
and on Linux it could be "/home/mikko/df_linux"
 
*Allowed watchers/launchers/players/force closers
 
This is fine-grained access control on how users can interact with slots created from this slot profile. Under these menus, you
 
can select which users can do the specific action. Watching refers to seeing what’s in the slot. Launching refers to being able to
 
launch the slot from "Launch a new game". Playing refers to being able to give input to the slot. Force closer refers to the ability
 
to forcefully close the slot from main menu.
 
*Forbidden watchers/launchers/players/force closers
 
The opposite of their allowed counterparts. If you set users in these groups, they will not be allowed to do the specific action.
 
The forbidden user groups always override allowed user groups.
 
*Width and height
 
Set the width and height of the slot window. These are ignored on Windows but they are used on Linux to set the terminal size.
 
*Maximum slots
 
Set the maximum number of slots that can be created of this slot profile. For Dwarf Fortress, you probably only want to allow
 
one to avoid players accidentally messing each other’s save files when two Dwarf Fortress processes are running in the same
 
directory. If you want to run many Dwarf Fortress processes on the same computer, create separate slot profiles for them (with
 
different directories).
 
*Create slot profile
 
Select this and the slot profile will be created. You can later modify the slot profile in slot configuration menu.
 
 
 
= User interface =
 
You navigate through the UI in Dfterm2 by using arrow keys and ALT+number keys (or ESC+number keys). Dfterm2 has a
 
simple windowed interface. Windows are automatically arranged and will not overlap unless you are short on terminal screen
 
space.
 
Currently focused window has a blue border. Other windows have gray border. If the currently focused window is also locked,
 
the border is red.
 
You can use CTRL+F to enlarge currently focused window to fullscreen and CTRL+L to lock a window. Locking can be
 
particularly useful in game window where some of the keys used by dfterm2 might conflict with the keys the game uses.
 
CTRL+R can be used to remove the borders of currently focused window.
 
There is a chat in dfterm2 you can access after logging in. In chat, you just type in your message and press enter. You can
 
navigate old chat history by using arrow keys or pgup/pgdown.
 
  
= Security considerations =
+
[[Category:Utilities]]
Dfterm2 strives to be secure in itself but it can’t guarantee the safety of the programs that it runs. For example, if there’s a way
 
in Dwarf Fortress to format the C-drive from inside it, dfterm2 can’t do anything about it.
 
In Linux, be extra careful that there is no way for the program you run in a slot to escape to a shell. For example, don’t run
 
telnet in a slot, because ! key escapes to shell. From there, malicious users can do pretty much anything they want. Chrooted
 
enviroments and narrow privileges are recommended.
 
Dfterm2 uses telnet for connections. This means all the passwords are transmitted in plain text and are not encrypted in any way.
 
It is not recommended that you connect administrators to dfterm2 over insecure links. On Linux, stolen administrator password
 
lets the attacker to access a shell and then do anything they want from there. Dfterm2 may have a built-in SSH server in it in the
 
future.
 
Dfterm2 has some limits on it that somewhat mitigate DoS attacks made against it. These limits are in header file dfterm2_limits.hpp.
 
The limits are as follows.
 
* Maximum number of slots running at a time is 30
 
* Maximum number of slot profiles is 30
 
* Maximum number of registered users is 50
 
* Maximum number of Telnet connections at a time is 50
 
* Maximum number of HTTP connections at a time is 50
 
* Largest file dfterm2 will server through HTTP is 1000000 bytes.
 

Revision as of 12:33, 18 June 2016

This utility page is about v0.34.11, an older version of DF.

Dfterm2 is a remote Dwarf Fortress playing software for multiple users through telnet. It has been replaced by Dfterm3, which has similar functions through an easier-to-use web interface.

On linux

You need to compile the program directly from source. To do so you need to install the following packages:

  • ICU development libraries
  • Boost development libraries (at least version 1.42)
  • OpenSSL development libraries
  • CMake
  • PCRE development libraries
  • g++ and usual development tools
  • lua ( > 5.1 Doesn't work) (use 5.0)
  • git

First, you need to obtain the source code, using the following commands in git:

$ git clone git://genodeen.net/dfterm2
$ cd dfterm2
$ git submodule init
$ git submodule update

Next, you have to use CMake to configure the building system:

$ cmake .

Thirdly, use this command to start the compiling:

$ make

If compilation failed, visit the DFterm2 page on the Bay12 forums for support.

The final step is to add an administrator account using

$ ./dfterm2_configure --adduser (username) (password) admin 
$ ./dfterm2

To connect to the server from a linux machine, you need to use the following command:

$ telnet 127.0.0.1 8000