Changeset View
Changeset View
Standalone View
Standalone View
source/tools/lobbybots/README.md
Show All 31 Lines | |||||
#### Choice: Pyrogenesis version compatibility | #### Choice: Pyrogenesis version compatibility | ||||
Decide whether you want to support serving multiple Pyrogenesis versions. | Decide whether you want to support serving multiple Pyrogenesis versions. | ||||
Serving multiple versions of Pyrogenesis allows for seamless version upgrading on the backend and | Serving multiple versions of Pyrogenesis allows for seamless version upgrading on the backend and | ||||
allows players that don't have the most recent version of Pyrogenesis yet to continue to play until | allows players that don't have the most recent version of Pyrogenesis yet to continue to play until | ||||
the new release is available for their platform (applies mostly to linux distributions). | the new release is available for their platform (applies mostly to linux distributions). | ||||
If you decide to do so, you should use a naming pattern that includes the targetted Pyrogenesis version. | If you decide to do so, you should use a naming pattern that includes the targetted Pyrogenesis version. | ||||
For example to provide a Multiplayer Lobby for Pyrogenesis Alpha 23 "Ken Wood", | For example to provide a Multiplayer Lobby for Pyrogenesis Alpha 24, | ||||
name the lobby room `arena23` instead of `arena` and use `xpartamupp23` and `echelon23` as lobby bot names. | name the lobby room `arena24` instead of `arena` and use `xpartamupp24` and `echelon24` as lobby bot names. | ||||
Then when a version 24 of Pyrogenesis is employed, you can easily add `arena24`, `xpartamupp24` and `echelon24`. | Then when a version 25 of Pyrogenesis is employed, you can easily add `arena25`, `xpartamupp25` and `echelon25`. | ||||
If you only want to use the service for local testing, you can stick to a single room and a single gamelist and rating bot. | If you only want to use the service for local testing, you can stick to a single room and a single gamelist and rating bot. | ||||
## 1. Install dependencies | ## 1. Install dependencies | ||||
This section explains how to install the required software on a Debian-based linux distribution. | This section explains how to install the required software on a Debian-based linux distribution. | ||||
For other operating systems, use the according package manager or consult the official documentation of the software. | For other operating systems, use the according package manager or consult the official documentation of the software. | ||||
### 1.1 Install ejabberd | ### 1.1 Install ejabberd | ||||
▲ Show 20 Lines • Show All 224 Lines • ▼ Show 20 Lines | |||||
* Ensure old, vulnerable SSL/TLS protocols are disabled: | * Ensure old, vulnerable SSL/TLS protocols are disabled: | ||||
``` | ``` | ||||
define_macro: | define_macro: | ||||
'TLS_OPTIONS': | 'TLS_OPTIONS': | ||||
- "no_sslv2" | - "no_sslv2" | ||||
- "no_sslv3" | - "no_sslv3" | ||||
- "no_tlsv1" | - "no_tlsv1" | ||||
``` | ``` | ||||
## 3. Configure ejabberd use policy | ## 3. Configure ejabberd use policy | ||||
The settings in this section grant or restrict user access rights. | The settings in this section grant or restrict user access rights. | ||||
* Prevent the rooms from being destroyed if the last client leaves it: | * Prevent the rooms from being destroyed if the last client leaves it: | ||||
``` | ``` | ||||
▲ Show 20 Lines • Show All 48 Lines • ▼ Show 20 Lines | ``` | ||||
max_users: 5000 | max_users: 5000 | ||||
default_room_options: | default_room_options: | ||||
max_users: 1000 | max_users: 1000 | ||||
``` | ``` | ||||
* (Optional) Prevent users from sending too large stanzas. | * (Optional) Prevent users from sending too large stanzas. | ||||
Notice the bots can send large stanzas as well, so don't restrict it too much. | Notice the bots can send large stanzas as well, so don't restrict it too much. | ||||
``` | ``` | ||||
max_stanza_size: 1048576 | max_stanza_size: 1048576 | ||||
``` | ``` | ||||
* (Optional) Prevent users from changing the room topic: | * (Optional) Prevent users from changing the room topic: | ||||
``` | ``` | ||||
mod_muc: | mod_muc: | ||||
default_room_options: | default_room_options: | ||||
allow_change_subj: false | allow_change_subj: false | ||||
Show All 9 Lines | |||||
* (Optional) Enable room chatlogging. | * (Optional) Enable room chatlogging. | ||||
Make sure to mention this collection and the purposes in the Terms and Conditions to comply with personal data laws. | Make sure to mention this collection and the purposes in the Terms and Conditions to comply with personal data laws. | ||||
Ensure that ejabberd has write access to the given folder. | Ensure that ejabberd has write access to the given folder. | ||||
Notice that `ejabberd.service` by default prevents write access to some directories (PrivateTmp, ProtectHome, ProtectSystem). | Notice that `ejabberd.service` by default prevents write access to some directories (PrivateTmp, ProtectHome, ProtectSystem). | ||||
``` | ``` | ||||
modules: | modules: | ||||
mod_muc_log: | mod_muc_log: | ||||
outdir: "/lobby/logs" | outdir: "/0ad-lobby/logs" | ||||
Stan: Maybe the logs location should depend on the version as well ? | |||||
elexisAuthorUnsubmitted Done Inline ActionsThere is a subfolder per room and a room per version. elexis: There is a subfolder per room and a room per version. | |||||
file_format: plaintext | file_format: plaintext | ||||
timezone: universal | timezone: universal | ||||
mod_muc: | mod_muc: | ||||
default_room_options: | default_room_options: | ||||
logging: true | logging: true | ||||
``` | ``` | ||||
* (Optional) Grant specific moderators administrator rights to see the IP address of a user: | * (Optional) Grant specific moderators administrator rights to see the IP address of a user: | ||||
▲ Show 20 Lines • Show All 43 Lines • ▼ Show 20 Lines | * Check list of registered users: | ||||
``` | ``` | ||||
$ ejabberdctl registered_users lobby.wildfiregames.com | $ ejabberdctl registered_users lobby.wildfiregames.com | ||||
``` | ``` | ||||
* Register the accounts of the lobby bots. | * Register the accounts of the lobby bots. | ||||
The rating account is only needed if you decided to enable the rating service. | The rating account is only needed if you decided to enable the rating service. | ||||
``` | ``` | ||||
$ ejabberdctl register echelon23 lobby.wildfiregames.com secure_password | $ ejabberdctl register echelon24 lobby.wildfiregames.com secure_password | ||||
$ ejabberdctl register xpartamupp23 lobby.wildfiregames.com secure_password | $ ejabberdctl register xpartamupp24 lobby.wildfiregames.com secure_password | ||||
``` | ``` | ||||
### 4.2 Authorize lobby bots to see real JIDs | ### 4.2 Authorize lobby bots to see real JIDs | ||||
* The bots need to be able to see real JIDs of users. | * The bots need to be able to see real JIDs of users. | ||||
So either the room must be configured as non-anonymous, i.e. real JIDs are visible to all users of the room, | So either the room must be configured as non-anonymous, i.e. real JIDs are visible to all users of the room, | ||||
or the bots need to receive muc administrator rights. | or the bots need to receive muc administrator rights. | ||||
#### Choice A: Non-anonymous room | #### Choice A: Non-anonymous room | ||||
* (Recommended) This method has the advantage that bots do not gain administrative access that they don't use. | * (Recommended) This method has the advantage that bots do not gain administrative access that they don't use. | ||||
The only possible downside is that room users may not hide their username behind arbitrary nicknames anymore. | The only possible downside is that room users may not hide their username behind arbitrary nicknames anymore. | ||||
``` | ``` | ||||
modules: | modules: | ||||
mod_muc: | mod_muc: | ||||
default_room_options: | default_room_options: | ||||
anonymous: false | anonymous: false | ||||
``` | |||||
#### Choice B: Non-anonymous room | #### Choice B: Semi-anonymous room | ||||
* If you for any reason wish to configure the room as semi-anonymous (only muc administrators can see real JIDs), | * If you for any reason wish to configure the room as semi-anonymous (only muc administrators can see real JIDs), | ||||
then the bots need to be authorized as muc administrators: | then the bots need to be authorized as muc administrators: | ||||
``` | ``` | ||||
access_rules: | access_rules: | ||||
muc_admin: | muc_admin: | ||||
- allow: bots | - allow: bots | ||||
modules: | modules: | ||||
mod_muc: | mod_muc: | ||||
access_admin: muc_admin | access_admin: muc_admin | ||||
``` | ``` | ||||
### 4.3 Authorize lobby bots with ejabberd | ### 4.3 Authorize lobby bots with ejabberd | ||||
* The bots need an ACL to be able to get the IPs of users hosting a match (which is what `mod_ipstamp` does). | * The bots need an ACL to be able to get the IPs of users hosting a match (which is what `mod_ipstamp` does). | ||||
``` | ``` | ||||
acl: | acl: | ||||
## Don't use a regex, to prevent others from obtaining permissions after registering such an account. | ## Don't use a regex, to prevent others from obtaining permissions after registering such an account. | ||||
bots: | bots: | ||||
- user: "xpartamupp23@lobby.wildfiregames.com" | - user: "xpartamupp24@lobby.wildfiregames.com" | ||||
- user: "echelon23@lobby.wildfiregames.com" | - user: "echelon24@lobby.wildfiregames.com" | ||||
``` | ``` | ||||
* Add an access rule for `ipbots` and a rule allowing bots to create PubSub nodes: | * Add an access rule for `ipbots` and a rule allowing bots to create PubSub nodes: | ||||
``` | ``` | ||||
access_rules: | access_rules: | ||||
## Expected by the ipstamp module for XpartaMuPP | ## Expected by the ipstamp module for XpartaMuPP | ||||
ipbots: | ipbots: | ||||
Show All 19 Lines | * Finally reload ejabberd's configuration: | ||||
$ ejabberdctl reload_config | $ ejabberdctl reload_config | ||||
``` | ``` | ||||
### 4.4 Running XpartaMuPP - XMPP Multiplayer Game Manager | ### 4.4 Running XpartaMuPP - XMPP Multiplayer Game Manager | ||||
* Execute the following command to run the gamelist bot: | * Execute the following command to run the gamelist bot: | ||||
``` | ``` | ||||
$ python3 XpartaMuPP.py --domain lobby.wildfiregames.com --login xpartamupp23 --password XXXXXX --nickname GamelistBot --room arena --elo echelon23 | $ python3 XpartaMuPP.py --server localhost --domain lobby.wildfiregames.com --login xpartamupp24 --password XXXXXX --nickname GamelistBot --room arena --elo echelon24 | ||||
user1Unsubmitted Not Done Inline Actionsnotice: https://code.wildfiregames.com/D2630 changes the directory structure and naming convention. user1: notice: https://code.wildfiregames.com/D2630 changes the directory structure and naming… | |||||
``` | ``` | ||||
If you want to run XpartaMuPP without a rating bot, the `--elo` argument should be omitted. | If you want to run XpartaMuPP without a rating bot, the `--elo` argument should be omitted. | ||||
Pass `--disable-tls` if you did not setup valid TLS encryption on the server. | Pass `--disable-tls` if you did not setup valid TLS encryption on the server. | ||||
Run `python3 XpartaMuPP.py --help` for the full list of options | Run `python3 XpartaMuPP.py --help` for the full list of options | ||||
* If the connection and authentication succeeded, you should see the following messages in the console: | * If the connection and authentication succeeded, you should see the following messages in the console: | ||||
``` | ``` | ||||
INFO JID set to: xpartamupp23@lobby.wildfiregames.com/CC | INFO JID set to: xpartamupp24@lobby.wildfiregames.com/CC | ||||
INFO XpartaMuPP started | INFO XpartaMuPP started | ||||
``` | ``` | ||||
### 4.5 Running EcheLOn - XMPP Multiplayer Rating Manager | ### 4.5 Running EcheLOn - XMPP Multiplayer Rating Manager | ||||
This bot can be thought of as a module of XpartaMuPP in that IQs stanzas sent to XpartaMuPP are | This bot can be thought of as a module of XpartaMuPP in that IQs stanzas sent to XpartaMuPP are | ||||
forwarded onto EcheLOn if its corresponding EcheLOn is online and ignored otherwise. | forwarded onto EcheLOn if its corresponding EcheLOn is online and ignored otherwise. | ||||
EcheLOn handles all aspects of operation related to ELO, the chess rating system invented by Arpad Elo. | EcheLOn handles all aspects of operation related to ELO, the chess rating system invented by Arpad Elo. | ||||
Players gain a rating after a rated 1v1 match. | Players gain a rating after a rated 1v1 match. | ||||
The score difference after a completed match is relative to the rating difference of the players. | The score difference after a completed match is relative to the rating difference of the players. | ||||
* (Optional) Some constants of the algorithm may be edited by experienced administrators at the head of `ELO.py`: | * (Optional) Some constants of the algorithm may be edited by experienced administrators at the head of `ELO.py`: | ||||
``` | ``` | ||||
# Difference between two ratings such that it is | # Difference between two ratings such that it is | ||||
# regarded as a "sure win" for the higher player. | # regarded as a "sure win" for the higher player. | ||||
# No points are gained or lost for such a game. | # No points are gained or lost for such a game. | ||||
elo_sure_win_difference = 600.0 | elo_sure_win_difference = 600.0 | ||||
# Lower ratings "move faster" and change more | # Lower ratings "move faster" and change more | ||||
# dramatically than higher ones. Anything rating above | # dramatically than higher ones. Anything rating above | ||||
# this value moves at the same rate as this value. | # this value moves at the same rate as this value. | ||||
elo_k_factor_constant_rating = 2200.0 | elo_k_factor_constant_rating = 2200.0 | ||||
``` | ``` | ||||
* To initialize the `lobby_rankings.sqlite3` database, execute the following command: | * To initialize the `lobby_rankings.sqlite3` database, execute the following command: | ||||
``` | ``` | ||||
$ python3 LobbyRanking.py | $ python3 LobbyRanking.py | ||||
``` | ``` | ||||
* Execute the following command to run the rating bot: | * Execute the following command to run the rating bot: | ||||
``` | ``` | ||||
$ python3 EcheLOn.py --domain lobby.wildfiregames.com --login echelon23 --password XXXXXX --nickname RatingBot --room arena23 | $ python3 EcheLOn.py --server localhost --domain lobby.wildfiregames.com --login echelon24 --password XXXXXX --nickname RatingBot --room arena24 | ||||
StanUnsubmitted Not Done Inline ActionsWere the command reversed ? Stan: Were the command reversed ? | |||||
elexisAuthorUnsubmitted Done Inline ActionsNo elexis: No | |||||
user1Unsubmitted Not Done Inline Actionsnotice: https://code.wildfiregames.com/D2630 changes the directory structure and naming convention. user1: notice: https://code.wildfiregames.com/D2630 changes the directory structure and naming… | |||||
``` | ``` | ||||
Run `python3 EcheLOn.py --help` for the full list of options | Run `python3 EcheLOn.py --help` for the full list of options | ||||
### 4.6 Setup systemd services | |||||
* The bots will now be registered as a systemd service, so that they are started automatically when the system starts. | |||||
* Place the lobby bot source code under `/0ad-lobby/bots/xpartamupp24/` or | |||||
consider a repository checkout of that folder to pull updates or add and revert local changes. | |||||
* Copy and adapt the bot configuration files `/etc/0ad-lobby/xpartamupp24.conf` and `/etc/0ad-lobby/echelon24.conf`. | |||||
* Copy the `xpartamupp@.service` and `echelon@.service` service template files to `/etc/systemd/system/`. | |||||
* Enable an instance of the service template using `systemctl enable xpartamupp@24.service`. | |||||
* Start the service using `systemctl start xpartamupp@24.service`. | |||||
* In case of error, view the log using `journalctl -u xpartamupp@24.service`. | |||||
* Consider hardening of the services. | |||||
### 4.7 Setup backup cronjob | |||||
* Now a cronjob is set up in order to reoccuringly preserve the accounts of the userbase. | |||||
* Copy the two backup scripts to `/0ad-lobby/backup/` | |||||
* Create the folders `/0ad-lobby/backup/ratings/` and `/0ad-lobby/backup/users/` | |||||
* Edit `/etc/crontab` and add the following two lines to call these scripts on a daily base: | |||||
``` | |||||
# m h dom mon dow user command | |||||
0 0 * * * ejabberd /lobby/backup/backup-users.sh | |||||
0 0 * * * root /lobby/backup/backup-ratings.sh | |||||
``` | |||||
* Consider further restricting user access. | |||||
## 5. Configure Pyrogenesis for the new Multiplayer Lobby | ## 5. Configure Pyrogenesis for the new Multiplayer Lobby | ||||
The Pyrogenesis client is now going to be configured to become able to connect to the new Multiplayer Lobby. | The Pyrogenesis client is now going to be configured to become able to connect to the new Multiplayer Lobby. | ||||
The Pyrogenesis documentation of configuration files can be found at <https://trac.wildfiregames.com/wiki/Manual_Settings>. | The Pyrogenesis documentation of configuration files can be found at <https://trac.wildfiregames.com/wiki/Manual_Settings>. | ||||
Available Pyrogenesis configuration settings are specified in `default.cfg`, see <https://code.wildfiregames.com/source/0ad/browse/ps/trunk/binaries/data/config/default.cfg>. | Available Pyrogenesis configuration settings are specified in `default.cfg`, see <https://code.wildfiregames.com/source/0ad/browse/ps/trunk/binaries/data/config/default.cfg>. | ||||
### 5.1 Local Configuration | ### 5.1 Local Configuration | ||||
* Visit <https://trac.wildfiregames.com/wiki/GameDataPaths> to identify the local user's Pyrogenesis configuration path depending on the operating system. | * Visit <https://trac.wildfiregames.com/wiki/GameDataPaths> to identify the local user's Pyrogenesis configuration path depending on the operating system. | ||||
* Create or open `local.cfg` in the configuration path. | * Create or open `local.cfg` in the configuration path. | ||||
* Add the following settings that determine the lobby server connection: | * Add the following settings that determine the lobby server connection: | ||||
``` | ``` | ||||
lobby.room = "arena23" ; Default MUC room to join | lobby.room = "arena24" ; Default MUC room to join | ||||
lobby.server = "lobby.wildfiregames.com" ; Address of lobby server | lobby.server = "lobby.wildfiregames.com" ; Address of lobby server | ||||
lobby.stun.server = "lobby.wildfiregames.com" ; Address of the STUN server. | lobby.stun.server = "lobby.wildfiregames.com" ; Address of the STUN server. | ||||
lobby.require_tls = true ; Whether to reject connecting to the lobby if TLS encryption is unavailable. | lobby.require_tls = true ; Whether to reject connecting to the lobby if TLS encryption is unavailable. | ||||
lobby.verify_certificate = true ; Whether to reject connecting to the lobby if the TLS certificate is invalid. | lobby.verify_certificate = true ; Whether to reject connecting to the lobby if the TLS certificate is invalid. | ||||
lobby.xpartamupp = "xpartamupp23" ; Name of the server-side XMPP-account that manage games | lobby.xpartamupp = "xpartamupp24" ; Name of the server-side XMPP-account that manage games | ||||
lobby.echelon = "echelon23" ; Name of the server-side XMPP-account that manages ratings | lobby.echelon = "echelon24" ; Name of the server-side XMPP-account that manages ratings | ||||
``` | ``` | ||||
If you disabled TLS encryption, set `require_tls` to `false`. | If you disabled TLS encryption, set `require_tls` to `false`. | ||||
If you employed a self-signed certificate, set `verify_certificate` to `false`. | If you employed a self-signed certificate, set `verify_certificate` to `false`. | ||||
### 5.2 Test the Multiplayer Lobby | ### 5.2 Test the Multiplayer Lobby | ||||
You should now be able to join the new multiplayer lobby with the Pyrogenesis client and play multiplayer matches. | You should now be able to join the new multiplayer lobby with the Pyrogenesis client and play multiplayer matches. | ||||
* To confirm that the match hosting works as intended, create two user accounts, host a game with one, join the game with the other account. | * To confirm that the match hosting works as intended, create two user accounts, host a game with one, join the game with the other account. | ||||
* To confirm that the rating service works as intended, resign a rated 1v1 match with two accounts. | * To confirm that the rating service works as intended, resign a rated 1v1 match with two accounts. | ||||
### 5.3 Terms and Conditions | ### 5.3 Terms and Conditions | ||||
Players joining public servers are subject to Terms and Conditions of the service provider and subject to privacy laws such as GDPR. | Players joining public servers are subject to Terms and Conditions of the service provider and subject to privacy laws such as GDPR. | ||||
If you intend to use the server only for local testing, you may skip this step. | If you intend to use the server only for local testing, you may skip this step. | ||||
* The following files should be created by the service provider: | * The following files should be created by the service provider: | ||||
`Terms_of_Service.txt` to explain the service and the contract. | `Terms_of_Service.txt` to explain the service and the contract. | ||||
`Terms_of_Use.txt` to explain what the user should and should not do. | `Terms_of_Use.txt` to explain what the user should and should not do. | ||||
`Privacy_Policy.txt` to explain how personal data is handled. | `Privacy_Policy.txt` to explain how personal data is handled. | ||||
* To use Wildfire Games Terms as a template, obtain our Terms from a copy of the game or from or from | * To use Wildfire Games Terms as a template, obtain our Terms from a copy of the game or from or from | ||||
<https://trac.wildfiregames.com/browser/ps/trunk/binaries/data/mods/public/gui/prelobby/common/terms/> | <https://trac.wildfiregames.com/browser/ps/trunk/binaries/data/mods/public/gui/prelobby/common/terms/> | ||||
* Replace all occurrences of `Wildfire Games` in the files with the one providing the new server. | * Replace all occurrences of `Wildfire Games` in the files with the one providing the new server. | ||||
* Update the `Terms_of_Use.txt` depending on which behavior you would like to (not) see on your service. | * Update the `Terms_of_Use.txt` depending on which behavior you would like to (not) see on your service. | ||||
* Update the `Privacy_Policy.txt` depending on the user data processing in relation to the usage policies. | * Update the `Privacy_Policy.txt` depending on the user data processing in relation to the usage policies. | ||||
Make sure to not violate privacy laws such as GDPR or COPPA while doing so. | Make sure to not violate privacy laws such as GDPR or COPPA while doing so. | ||||
* The retention times of ejabberd logs are relevant to GDPR. | * The retention times of ejabberd logs are relevant to GDPR. | ||||
Visit <https://www.ejabberd.im/Rotating%20logs%20with%20ejabberd/index.html> for details. | Visit <https://www.ejabberd.im/Rotating%20logs%20with%20ejabberd/index.html> for details. | ||||
* The terms should be published online, so users can save and print them. | * The terms should be published online, so users can save and print them. | ||||
Add to your `local.cfg`: | Add to your `local.cfg`: | ||||
``` | ``` | ||||
lobby.terms_url = "https://lobby.wildfiregames.com/terms/"; Allows the user to save the text and print the terms | lobby.terms_url = "https://lobby.wildfiregames.com/terms/"; Allows the user to save the text and print the terms | ||||
``` | ``` | ||||
### 5.4 Distribute the configuration | ### 5.4 Distribute the configuration | ||||
To make this a public server, distribute your `local.cfg`, `Terms_of_Service.txt`, `Terms_of_Use.txt`, `Privacy_Policy.txt`. | To make this a public server, distribute your `local.cfg`, `Terms_of_Service.txt`, `Terms_of_Use.txt`, `Privacy_Policy.txt`. | ||||
It may be advisable to create a mod with a modified `default.cfg` and the new terms documents, | It may be advisable to create a mod with a modified `default.cfg` and the new terms documents, | ||||
see <https://trac.wildfiregames.com/wiki/Modding_Guide>. | see <https://trac.wildfiregames.com/wiki/Modding_Guide>. | ||||
Congratulations, you are now running a custom Pyrogenesis Multiplayer Lobby! | Congratulations, you are now running a custom Pyrogenesis Multiplayer Lobby! |
Wildfire Games · Phabricator
Maybe the logs location should depend on the version as well ?