- 1 Platform support
- 2 Command line options
- 3 Process signals
- 4 Configuration and pack files
- 5 Control socket commands
- 6 Read-only mode
- 7 Hooks
- 8 See Also
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.
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
- 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
- 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.
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.
# 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]
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 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 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.
Deletes the specified add-on from disk and the add-ons server configuration.
server.cfg to disk immediately.
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.
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.
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.
Initiates an orderly shut down of campaignd.
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 (
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 ADDON_ID NEWPASS
Replaces the passphrase for the specified add-on. NEWPASS must be specified in plain text.
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.
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_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.