Utility:Dfterm2

Note: The most recent guide is in the dfterm2 official manual. Content from the manual is here with the author's permission. The relevant Bay12 thread with the most up to date information is here

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

• ^v0.31.14
• ^v0.31.13
• ^v0.31.12
• ^v0.31.11
• ^v0.31.10
• ^v0.31.09
• ^v0.31.08
• ^v0.31.06
• ^v0.31.03
• ^v0.31.02
• ^v0.31.01
• ^{v0.28.181.40d19.2}
• ^{v0.28.181.40d19}
• ^{v0.28.181.40d18}

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]

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 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 here

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
• 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

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

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.