Campaignd

campaignd is the software used by Wesnoth.org to run the add-ons server since Wesnoth 1.0. Despite its name and the continued use of the "campaign" term both in its protocol and internal implementation details in C++, the add-ons server is capable of serving add-ons of any kind, rather than just campaigns.

This page describes various aspects of the server's functionality. The server's WML protocol is described in CampaignServerWML.

Platform support

As of Wesnoth 1.15.2, campaignd is only properly supported, tested, and used on Wesnoth.org, which runs Debian GNU/Linux. There are portions of campaignd which require POSIX functionality not found on Windows, but other than those it is expected to at least run on that platform.

In particular, the following functionality is only available on POSIX platforms:

• Executing hooks
  Windows does not implement the exec* or fork system calls.
• Reloading the configuration and blacklist on SIGHUP
  Windows does not implement the POSIX signals concept.
• Safe atomic commits of configuration and add-on pack files
  Windows does not offer a mechanism to atomically overwrite files like POSIX does with the rename system call.
• Sending commands to the server through a named pipe (FIFO)
  Windows does not implement POSIX named pipes. It does have a native mechanism to define and use named pipes using the Win32 API — however, in practice it is inaccessible to end users without special tools not included with the operating system. See also issue #4594.

Command line options

As of Wesnoth 1.15.2, campaignd has no command line options.

Process signals

Sending SIGHUP to the campaignd process will instruct it to re-read the configuration file and blacklist file (if applicable) as soon as it finishes the current operation.

Sending SIGINT or SIGTERM will result in the add-ons server process' termination. However, contrary to the message sent out to stderr in this event, it will finish the current operation and flush its configuration before exiting.

Configuration and pack files

campaignd stores information about the add-ons server's structure as WML in a config file located in the process' initial working directory, named ./server.cfg. While all metadata for the add-ons is retrieved from the server configuration WML, the add-ons themselves are stored in packs in the ./data/ directory, each pack file named after the add-on's unique name. Packs are compressed using gzip with a configurable compression level.

As of 1.15.10, campaignd also has database support via mariadbpp to store add-on information and validate topic IDs of uploaded add-ons.

server.cfg

# Path to the blacklist WML file
blacklist_file=""
# Gzip compression level used for packs stored on disk
compress_level=6
# Path to a named pipe (FIFO) used for sending commands to the add-ons server
control_socket=""
# Sets the network WML document size limit, which effectively caps the size of
# uploads. Currently this is 100 MB (104,857,600 bytes) by default and on
# Wesnoth.org
document_size_limit=104857600
# External program after an add-on is successfully deleted from the server
hook_post_erase=""
# External program executed after an add-on is successfully uploaded to the server
hook_post_upload=""
# Port number to listen for client connections. The default number depends on
# the Wesnoth version and is hardcoded in the default_campaignd_port constant in
# src/addon/validation.cpp
port=""
# Whether the add-ons server is operating in read-only mode
read_only=no
# Add-on download requests from IP addresses matching this list of glob patterns
# will not incur in a download count bump. By default this is an empty list, but
# a valid example to avoid LAN and host downloads increasing the count would be
# "192.161.*,127.0.0.1"
stats_exempt_ips=""

# The server info block. Presently, if missing, all values in this are assumed to
# be empty strings. The values below are example values reflecting Wesnoth.org's
# configuration.
[server_info]
    # The format string for add-on feedback URLs used by clients in the Add-ons
    # Manager UI. The server delivers ready-to-use URLs instead of the format
    # string. The only accepted placeholder is $topic_id, corresponding to the
    # topic_id attribute in the [feedback] tag in the .pbl file for that add-on
    feedback_url_format="https://r.wesnoth.org/t$topic_id"
    # a string identifying the server version
    # generally should be of the form "1.14", "1.15", etc
    # required if database support is enabled
    id="1.14"
[/server_info]

# the user handler block for the database connection info
[user_handler]
    # the name of the table to store info for uploaded add-on information in
    db_addon_info_table="addon_info"
    # the name of the table used to validate the topic IDs of uploaded add-ons
    db_topics_table="topics"
    # not strictly required, but needed to silence an error due to code shared with wesnothd
    mp_mod_group=0
    # where the database is hosted
    db_host="localhost"
    # the name of the database
    db_name="wesnoth"
    # the password to connect to the database with
    db_password="wesnoth"
    # the user to connect to the database with
    db_user="my_user"
[/user_handler]

[campaigns]
    # Documented further below
[/campaigns]

Blacklist WML

The blacklist WML file specified in blacklist_file contains four attributes, each containing a list of glob patterns. Add-ons whose metadata matches one of these patterns may not be uploaded or updated, but they may still be deleted.

name=""
title=""
description=""
author=""
ip=""
email=""

[campaigns] tag

The [campaigns] tag contains a collection of [campaign] tags, each one describing a singular add-on using the same WML described in the [request_campaign_list] response in CampaignServerWML, plus a few sensitive or server-specific attributes:

# The add-on maintainer's email address as per PblWML
email=""
# The IP address that originated the latest upload of this add-on
upload_ip=""
# The salt and MD5 hashed passphrase for the add-on, both in Base64 format
passsalt=""
passhash=""
# Add-on's passphrase in plain text (OBSOLETE, will be converted on server startup)
passphrase=""

# The [feedback] info for the add-on as per PblWML
[feedback]
    topic_id=""
[/feedback]

Add-on packs

Add-on packs are gzipped WML with the same format and contents used for delivery to clients described in CampaignServerWML.

Control socket commands

On POSIX platforms, campaignd can be controlled while running by sending newline-separated commands to a configured named pipe (FIFO) much like wesnothd. The path to the FIFO is specified in server.cfg with the control_socket= attribute. Commands will always be executed after the current ongoing operation (if any) has completed.

delete

Syntax: delete ADDON_ID

Deletes the specified add-on from disk and the add-ons server configuration.

flush

Syntax: flush

Flushes campaignd's server.cfg to disk immediately.

hide/unhide

Syntax: hide/unhide ADDON_ID

Flags the specified add-on as hidden, preventing clients from performing any uploads, downloads, deletion, or passphrase change requests on it, as well as excluding it from the server contents list response.

readonly

Syntax: read_only [{true|yes|false|no}]

If an argument is specified, sets the add-ons server's read only mode to enabled or disabled depending on the provided value. If no argument is specified it just prints to stderr whether read only mode is enabled or disabled.

reload

Syntax: reload [blacklist]

Reloads campaignd's configuration files as if SIGHUP had been sent. If blacklist is provided as an argument, then only the blacklist file is reloaded.

shut_down

Syntax: shut_down

Initiates an orderly shut down of campaignd.

setattr

Syntax: setattr ADDON_ID ATTRIBUTE_KEY ATTRIBUTE_VALUE

Overwrites the specified WML attribute for the add-on in its [campaigns][campaign] metadata block, but not in the add-on's pack file (issue #4595). This is only practical for single-line values since it's not possible to send a multi-line string (such as the add-on's description) as part of a single socket command at this time.

Authentication attributes (passphrase=, passhash=, passsalt=) cannot be modified using this mechanism. Use setpass for those instead. Likewise, it is not possible to use this to rename an add-on (name=) or set attributes that are not already recorded in its metadata block.

setpass

Syntax: setpass ADDON_ID NEWPASS

Replaces the passphrase for the specified add-on. NEWPASS must be specified in plain text.

Read-only mode

It is possible to set campaignd to run in read-only mode by modifying the server configuration directly or using the readonly command. When in read-only mode, campaignd will refuse requests to upload, delete, or change the passphrase of add-ons, and download counts will remain unchanged.

Hooks

Back in the WesCamp-i18n days, there was an attempt to implement automated submitting of add-ons to WesCamp for generating and updating translation catalogues and templates. This functionality was never fully implemented and traces of it remain in the form of the hook_post_erase and hook_post_upload hooks, executed after the successful deletion and upload of an add-on, respectively.

The programs executed for these hooks are specified in server.cfg, and invoked with the add-on's unique name as their only command-line argument.

In the present day, this functionality is wholly untested and unsupported.

See Also

• CampaignServerWML
• PblWML