Difference between revisions of "Campaignd"

From The Battle for Wesnoth Wiki
(Created page with "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 protoc...")
 
(Configuration and pack files)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
<div class="tright"> __TOC__ </div>
 +
 
[[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.
 
[[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.
  
Line 7: Line 9:
 
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.
 
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:
+
In particular, the following functionality is only available on POSIX platforms:
  
* Executing hooks<br>Windows does not implement the <code>exec*</code> or <code>fork</code> system calls.
+
* <b>Executing hooks</b><br>Windows does not implement the <code>exec*</code> or <code>fork</code> system calls.
* Reloading the configuration and blacklist on SIGHUP<br>Windows does not implement the POSIX signals concept.
+
* <b>Reloading the configuration and blacklist on SIGHUP</b><br>Windows does not implement the POSIX signals concept.
* Safe atomic commits of configuration and add-on pack files<br>Windows does not offer a mechanism to atomically overwrite files like POSIX does with the <code>rename</code> system call.
+
* <b>Safe atomic commits of configuration and add-on pack files</b><br>Windows does not offer a mechanism to atomically overwrite files like POSIX does with the <code>rename</code> system call.
* Sending commands to the server through a named pipe (FIFO)<br>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 pratice it is inaccessible to end users without specific tools not included with the operating system.
+
* <b>Sending commands to the server through a named pipe (FIFO)</b><br>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 [https://github.com/wesnoth/wesnoth/issues/4594 issue #4594].
  
== Command line options and signals ==
+
== Command line options ==
  
 
As of Wesnoth 1.15.2, campaignd has no 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 <b>will</b> flush its configuration before exiting, although it may be left in an inconsistent state if an add-on is currently being uploaded or deleted.
+
== 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 <b>will</b> finish the current operation and flush its configuration before exiting.
  
 
== Configuration and pack files ==
 
== 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 <code>./server.cfg</code>. While all metadata for the add-ons is retrieved from the server configuration WML, the add-ons themselves are stored in packs in the <code>./data/</code> directory, each pack file named after the add-on's unique name. Packs are compressed using gzip with a configurable compression level.
 
campaignd stores information about the add-ons server's structure as WML in a config file located in the process' initial working directory, named <code>./server.cfg</code>. While all metadata for the add-ons is retrieved from the server configuration WML, the add-ons themselves are stored in packs in the <code>./data/</code> 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 ===
 
=== server.cfg ===
Line 33: Line 41:
 
# Path to a named pipe (FIFO) used for sending commands to the add-ons server
 
# Path to a named pipe (FIFO) used for sending commands to the add-ons server
 
control_socket=""
 
control_socket=""
# Command line executed after an add-on is successfully deleted from the server
+
# 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=""
 
hook_post_erase=""
# Command line executed after an add-on is successfully uploaded to the server
+
# External program executed after an add-on is successfully uploaded to the server
 
hook_post_upload=""
 
hook_post_upload=""
 
# Port number to listen for client connections. The default number depends on
 
# Port number to listen for client connections. The default number depends on
Line 58: Line 70:
 
     # topic_id attribute in the [feedback] tag in the .pbl file for that add-on
 
     # 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"
 
     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]
 
[/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]
 
[campaigns]
Line 101: Line 135:
 
=== Add-on packs ===
 
=== Add-on packs ===
  
Add-on packs are gzipped WML with the same format and contents used for delivery to clients described in [[CampaignServerWML|CampaignServerWML#Response_2]].
+
Add-on packs are gzipped WML with the same format and contents used for delivery to clients described in [[CampaignServerWML#Response_2|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 <code>server.cfg</code> with the <code>control_socket=</code> attribute. Commands will always be executed after the current ongoing operation (if any) has completed.
 +
 
 +
=== delete ===
 +
 
 +
<b>Syntax:</b> <code>delete <var>ADDON_ID</var></code>
 +
 
 +
Deletes the specified add-on from disk and the add-ons server configuration.
 +
 
 +
=== flush ===
 +
 
 +
<b>Syntax:</b> <code>flush</code>
 +
 
 +
Flushes campaignd's <code>server.cfg</code> to disk immediately.
 +
 
 +
=== hide/unhide ===
 +
 
 +
<b>Syntax:</b> <code>hide/unhide <var>ADDON_ID</var></code>
 +
 
 +
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 ===
 +
 
 +
<b>Syntax:</b> <code>read_only [{true|yes|false|no}]</code>
 +
 
 +
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 ===
 +
 
 +
<b>Syntax:</b> <code>reload [blacklist]</code>
 +
 
 +
Reloads campaignd's configuration files as if SIGHUP had been sent. If <code>blacklist</code> is provided as an argument, then only the blacklist file is reloaded.
 +
 
 +
=== shut_down ===
 +
 
 +
<b>Syntax:</b> <code>shut_down</code>
 +
 
 +
Initiates an orderly shut down of campaignd.
 +
 
 +
=== setattr ===
 +
 
 +
<b>Syntax:</b> <code>setattr <var>ADDON_ID</var> <var>ATTRIBUTE_KEY</var> <var>ATTRIBUTE_VALUE</var></code>
 +
 
 +
Overwrites the specified WML attribute for the add-on in its <code>[campaigns][campaign]</code> metadata block, but not in the add-on's pack file ([https://github.com/wesnoth/wesnoth/issues/4595 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 (<code>passphrase=</code>, <code>passhash=</code>, <code>passsalt=</code>) cannot be modified using this mechanism. Use <code>setpass</code> for those instead. Likewise, it is not possible to use this to rename an add-on (<code>name=</code>) or set attributes that are not already recorded in its metadata block.
 +
 
 +
=== setpass ===
 +
 
 +
<b>Syntax:</b> <code>setpass <var>ADDON_ID</var> <var>NEWPASS</var></code>
 +
 
 +
Replaces the passphrase for the specified add-on. <var>NEWPASS</var> must be specified in plain text.
 +
 
 +
== Read-only mode ==
 +
 
 +
It is possible to set campaignd to run in <b>read-only mode</b> by modifying the server configuration directly or using the <code>readonly</code> 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 <code>hook_post_erase</code> and <code>hook_post_upload</code> hooks, executed after the successful deletion and upload of an add-on, respectively.
 +
 
 +
The programs executed for these hooks are specified in <code>server.cfg</code>, 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]]
  
 
[[Category:Server Documentation]]
 
[[Category:Server Documentation]]

Latest revision as of 04:36, 17 March 2021

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

This page was last edited on 17 March 2021, at 04:36.