Dedicated server

The Drawpile client has a builtin server for quickly hosting drawing sessions, but a dedicated server is also included. The dedicated server has the following extra features:

  • No GUI, so it can run on headless boxes
  • Multiple sessions on a single server
  • Sessions that can be joined again even after every user has left
  • Systemd socket activation support
  • SSL support
  • Access controls

Typical use cases for running the dedicated server instead of using the built-in are:

  • Home network is behind a NAT firewall
  • A public or private server for a group of users
  • Hosting long running sessions

Installing the server (on Linux)

The easiest way to install the server is to download the AppImage. The server will not run as root, so it’s a good idea to create a new username just for it. Copy the AppImage onto the server and give it execute permissions (chmod a+x Drawpile-srv-1.0.6.AppImage)

You can then simply run the AppImage to start the server with default settings: ./Drawpile-srv-1.0.6.AppImage.

Tip: make a symlink (ln -s Drawpile-srv-1.0.6.AppImage drawpile-srv) to always refer to the latest version.

Starting from the command line

Run drawpile-srv -h to get a list of supported command line parameters. These are the most commonly needed:

  • --verbose makes the server print extra debugging information
  • --port <port> selects the port on which the server will listen
  • --listen <address> restricts the server to listening on just the specified address
  • --persistent enables support for persistent sessions
  • --config read settings from a configuration file, subject to command line overrides (see below)
  • --host-password <password> sets the password needed to host sessions on this server
  • --title <title> sets the server title that is shown in the session selection dialog when a user logs in. The title may include line breaks and URLs will be turned into clickable links.
  • --ssl-key and --ssl-cert enables SSL support. See the /Security%7CHelp%3A%20Security page for more information.

Simply running drawpile-srv will start the server with reasonable defaults. Note that there is no default hosting password, so if you do not want to run a server where anyone may host sessions, use --host-password!

By default, the server supports multiple sessions. A user who is logging in will be presented a dialog box for selecting which session to join. Using the parameter --sessions 1 puts the server in single session mode (like the built-in server), in which case users will automatically join the only available session.

Config file format

The config file, which uses an INI format, may be used to specify options normally passed on the command line.

verbose=true
persistent=true
expire=1d
title=Local Drawpile
ssl-cert=/home/drawpile/drawpile.server.crt
ssl-key=/home/drawpile/drawpile.server.key

The config file is overridden by the command line. The use of backslashes in paths may be problematic; try slashes instead.

Using systemd

Drawpile server can be started in two ways using systemd. The server can be started directly with systemctl start drawpile-srv or by socket activation using systemctl start drawpile-srv.socket. When socket activation is used, the server is started on-demand when the first client connects. Note that when using SA, the --port and --listen parameters are ignored. The listening address is configured in the drawpile-srv.socket unit file.

Use systemctl enable drawpile-srv or systemctl enable drawpile-srv.socket to automatically start the server on boot.

The current server AppImage does not have systemd support compiled in, so it does not support socket activation. Here is a sample unit file that works with it (place in /etc/systemd/system/drawpile-srv.service):

[Unit]
Description=Drawpile dedicated server
After=network.target
Documentation=man:drawpile-srv

[Service]
ExecStart=/home/my_server/drawpile-srv -c /home/my_server/settings.cfg
Type=simple
Restart=always
User=my_server

[Install]
WantedBy=multi-user.target

Replace my_server with the username you will run the server as. Best practice is to create a user just for running the server. Note that for security reasons, the server will not run as root!

Persistent sessions

Normally, a session is automatically deleted after the last user logs out. Running the server with the --persistent option allows sessions to remain available even after they are vacated. Note that the user must explicitly request for the session to be made persistent. This is done by checking the “Persistent” checkbox on the hosting dialog. The session can also later be made (non)persistent using the /persistence on/off operator command.

To prevent old sessions from piling up, it is a good idea to use the --expire option. Setting this option will cause vacant sessions to be deleted after the given time. For example, --expire 12h or --expire 0.5d will set the expiration time to 12 hours.

When session hibernation is enabled, persistent sessions can be stored on disk after a period of inactivity or when the server is stopped. Enable hibernation by setting the directory where to store the sessions with the --hibernation option. Normally, sessions are hibernated only when the server is stopped, but setting the --auto-hibernate flag will cause expired sessions to hibernate instead of terminating.

Session templates

(New feature in version 1.0.3)

Session templates allow you to provide default sessions that always exist on the server. They are similar to hibernated sessions, with the difference that when activated, the template is just hidden and not removed. When a template session is activated (by a user joining it), it is loaded from disk just like a regular hibernated session. The template is hidden until the active session ends, so no more than one instance of a template can exist at a time.

Session templates are put in the same directory as hibernated sessions and hibernation must be enabled for them to work. A session template is identified by its filename. The filename follows the same pattern as hibernation files, except the suffix is .dptpl. (Pattern: session.XXXX.dptpl, where XXXX is the session ID.)

Templates can be created in two ways: the easiest is to just make a copy of a hibernated session. Another way, which gives you more control over the initial content, is to craft the template manually. The easiest way to do this is to write a dptxt file (take a look in the tests directory for examples) and convert it into a dptpl by using the txt2dprec tool.

Example: txt2dprec --title "My Demo Session" --founder "My Username" demo.dptxt session.demo.dptpl

Access controls

User authentication

Since version 0.9.2, Drawpile supports password protected usernames. There are two login types: guest and authenticated. If an entry in the userfile exists for a given username, a password is needed to log in as that user. Identified users can be granted special privileges, such as the right to host sessions. A user can also be flagged as a moderator, which gives them a permanent session operator status and allows access to closed and password protected sessions.

The server can potentially support a number of authentication back ends, but currently only a userfile based one is implemented. See doc/logins.md for more information about authenticated logins.

To use the file based authentication backend, use the --userfile command line parameter to select the file containing the usernames. You can use the included usertool.py script to manage the user file. The file is automatically reloaded when it is changed, so there is no need to restart the server after making changes.

IP ban list

Clients can be blocked on an IP address or subnet basis with a banlist file. Use the --banlist parameter to set it. As with --userfile, the file will be automatically reloaded. The file format is simple:

# Lines starting with '#' are comments
# Ban individual addresses:
192.168.1.1
::1

# Ban by subnet
192.168.1.1/24
::1/64

Session announcement server whitelist

By default, users can have the server make session announcemnets at any server. A whitelist file can be set with --announce-whitelist.

The whitelist file consists of regular expressions:

# Limit API calls to URLs ending with /listing/
^https?://.*/listing/$

Use a blank whitelist file to disable session announcement.

Recording sessions

The server can automatically record all sessions. Use the --record parameter to set the file name pattern. When starting a recording, the filename is created by filling out the following placeholders:

  • %d is replaced with the current date (YYYY-MM-DD)
  • %t is replaced with the current time (HH.MM.SS)
  • %i is replaced with the session ID

For example, --record "~/recordings/session-%i (%d %t).dprec" might produce a file named session-1 (2014-05-20 15.35.04).dprec

If the filename points to a directory, the default name pattern %d %t session %i.dprec will be used.

As of 0.9.4, adding the extension .gz to the file name pattern will create a compressed recording.