Differential D1661 Diff 8428 source/tools/lobbybots/README.md

Changeset 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 317 Lines • ▼ Show 20 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"
StanUnsubmitted Not Done Inline Actions Maybe the logs location should depend on the version as well ? Stan: Maybe the logs location should depend on the version as well ?
elexisAuthorUnsubmitted Done Inline Actions There 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 --domain lobby.wildfiregames.com --login xpartamupp24 --password XXXXXX --nickname GamelistBot --room arena --elo echelon24
		user1Unsubmitted Not Done Inline Actions notice: 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.
Show All 18 Lines	* 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 --domain lobby.wildfiregames.com --login echelon24 --password XXXXXX --nickname RatingBot --room arena24
		StanUnsubmitted Not Done Inline Actions Were the command reversed ? Stan: Were the command reversed ?
		elexisAuthorUnsubmitted Done Inline Actions No elexis: No
		user1Unsubmitted Not Done Inline Actions notice: 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`.

## 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.
▲ Show 20 Lines • Show All 44 Lines • Show Last 20 Lines