Index: ps/trunk/binaries/data/mods/public/gui/session/session.js
===================================================================
--- ps/trunk/binaries/data/mods/public/gui/session/session.js
+++ ps/trunk/binaries/data/mods/public/gui/session/session.js
@@ -1567,6 +1567,7 @@
/**
* Send a report on the gamestatus to the lobby.
+ * Keep in sync with source/tools/XpartaMuPP/LobbyRanking.py
*/
function reportGame()
{
Index: ps/trunk/source/tools/XpartaMuPP/README.md
===================================================================
--- ps/trunk/source/tools/XpartaMuPP/README.md
+++ ps/trunk/source/tools/XpartaMuPP/README.md
@@ -1,37 +1,102 @@
-# 0 A.D. Multiplayer Lobby Setup
+# 0 A.D. / Pyrogenesis Multiplayer Lobby Setup
-## Introduction
+This README explains how to setup a custom Pyrogenesis Multiplayer Lobby server that can be used with the Pyrogenesis game.
-Some commands assume some apt-get based distribution. `lobby.wildfiregames.com` should be replaced
-by your own domain name (or `localhost`) in all commands below.
+## Service description
+The Pyrogenesis Multiplayer Lobby consists of three components:
-## ejabberd
+* **XMPP server: ejabberd**:
+ The XMPP server provides the platform where users can register accounts, chat in a public room, and can interact with lobby bots.
+ Currently, ejabberd is the only XMPP server software supported (by the ipstamp module for XpartaMuPP).
-These instructions for ejabberd assume you're running a Debian version where at least ejabberd
-17.03 is available (currently Debian Stretch with enabled backports), as that's the minimum
-ejabberd version which is required for the custom ejabberd module to work.
+* **Gamelist bot: XpartaMuPP**:
+ This bot allows players to host and join online multiplayer matches.
+ It utilizes the ejabberd ipstamp module to inform players of IP addresses of hosting players.
-### Install ejabberd
+* **Rating bot: EcheLOn**:
+ This bot allows players to gain a rating that reflects their skill based on online multiplayer matches.
+ It is by no means necessary for the operation of a lobby in terms of match-making and chatting.
-* Install `ejabberd`:
+## Service choices
+Before installing the service, you have to make some decisions:
+
+#### Choice: Domain Name
+Decide on a domain name where the service will be provided.
+This document will use `lobby.wildfiregames.com` as an example.
+If you intend to use the server only for local testing, you may choose `localhost`.
+
+#### Choice: Rating service
+Decide whether or not you want to employ the rating service.
+If you decide to not provide the rating service, you may skip the instructions for the rating bot in this document.
+
+#### Choice: Pyrogenesis version compatibility
+Decide whether you want to support serving multiple Pyrogenesis versions.
+
+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
+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.
+For example to provide a Multiplayer Lobby for Pyrogenesis Alpha 23 "Ken Wood",
+name the lobby room `arena23` instead of `arena` and use `xpartamupp23` and `echelon23` as lobby bot names.
+Then when a version 24 of Pyrogenesis is employed, you can easily add `arena24`, `xpartamupp24` and `echelon24`.
+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
+
+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.
+
+### 1.1 Install ejabberd
+
+The version requirement for ejabberd is 17.03 or later (due to the ipstamp module format).
+
+* Install `ejabberd` using the following command. Alternatively see .
```
$ apt-get install ejabberd
```
-* Configure it, by setting the domain name (e.g. `localhost` if you installed it on your
- development computer) and add an admin user.:
+* Confirm that the ejabberd version you installed is the one mentioned above or later:
+
+ ```
+ $ ejabberdctl status
+ ```
+
+* Configure ejabberd by setting the domain name of your choice and add an `admin` user.:
```
$ dpkg-reconfigure ejabberd
````
-You should now be able to connect to this XMPP server using a normal XMPP client.
+You should now be able to connect to this XMPP server using any XMPP client.
-### Installation of the custom ejabberd module
+### 1.2 Install python3 and SleekXmpp
-* Adjust `/etc/ejabberd/ejabberdctl.cfg` and set `CONTRIB_MODULES_PATH` to the directory where
- you want to store `mod_ipstamp`:
+* The lobby bots are programmed in python3 and use SleekXMPP to connect to the lobby. Install these dependencies using:
+
+ ```
+ $ apt-get install python3 python3-sleekxmpp
+ ```
+
+* Confirm that the SleekXmpp version is 1.3.1 or later:
+
+ ```
+ pip3 show sleekxmpp
+ ```
+
+* If you would like to run the rating bot, you will need to install SQLAlchemy for python3:
+
+ ```
+ $ apt-get install python3-sqlalchemy
+ ```
+
+### 1.3 Install ejabberd ipstamp module
+
+The ejabberd ipstamp module has the purpose of inserting the IP address of the hosting players into the gamelist packet.
+That enables players to connect to each others games.
+
+* Adjust `/etc/ejabberd/ejabberdctl.cfg` and set `CONTRIB_MODULES_PATH` to the directory where you want to store `mod_ipstamp`:
```
CONTRIB_MODULES_PATH=/opt/ejabberd-modules
@@ -52,142 +117,523 @@
$ ejabberdctl module_install mod_ipstamp
```
-* Add `mod_ipstamp` to the modules ejabberd should load in`/etc/ejabberd/ejabberd.yml`:
+## 2. Configure ejabberd mod_ipstamp
+
+The ejabberd configuration in the remainder of this document is performed by editing `/etc/ejabberd/ejabberd.yml`.
+The directory containing this README includes a preconfigured `ejabberd_example.yml` that only needs few setting changes to work with your setup.
+For a full documentation of the ejabberd configuration, see .
+If something goes wrong with ejabberd, check `/var/log/ejabberd/ejabberd.log`
+
+* Add `mod_ipstamp` to the modules ejabberd should load:
```
modules:
mod_ipstamp: {}
```
-* Reload ejabberd's configuration:
+* Reload the ejabberd config.
+ This should be done every few steps, so that configuration errors can be identified as soon as possible.
```
$ ejabberdctl reload_config
```
-If something goes wrong, check `/var/log/ejabberd/ejabberd.log`
+## 3. Configure ejabberd connectivity
+
+The settings in this section ensure that connections can be built where intended, and only where intended.
+
+### 3.1 Disable IPv6
+* Since the enet library which Pyrogenesis uses for multiplayer mode does not support IPv6, ejabberd must be configured to not use IPv6:
+
+ ```
+ listen:
+ ip: "0.0.0.0"
+ ```
+
+### 3.2 Enable STUN
+* ejabberd and Pyrogenesis support the STUN protocol. This allows players to connect to each others games even if the host did not configure
+the router and forward the UDP port. Enabling STUN is optional but recommended.
+
+ ```
+ listen:
+ -
+ port: 3478
+ transport: udp
+ module: ejabberd_stun
+ ```
+
+### 3.3 Enable keep-alive
+
+* This helps with users becoming disconnected:
+
+ ```
+ modules:
+ mod_ping:
+ send_pings: true
+ ```
+
+### 3.3 Disable unused services
+
+* Disable the currently unused server-to-server communication:
+
+ ```
+ listen:
+ ## -
+ ## port: 5269
+ ## ip: "::"
+ ## module: ejabberd_s2s_in
+ ```
+
+* Protect the administrative webinterface at from external access by disabling or restriction to `localhost`:
-### Ejabberd configuration
+ ```
+ listen:
+ -
+ port: 5280
+ ip: "127.0.0.1"
+ ```
+
+* Disable some unused modules:
+
+ ```
+ modules:
+ ## mod_echo: {}
+ ## mod_irc: {}
+ ## mod_shared_roster: {}
+ ## mod_vcard: {}
+ ## mod_vcard_xupdate: {}
+ ```
+
+### 3.4 Setup TLS encryption
+
+Depending on whether you use the server for a player audience or only for local testing,
+you may have to either obtain and install a certificate with ejabberd or disable TLS encryption.
+
+#### Choice A: No encryption
+* If you intend to use the server solely for local testing, you may disable TLS encryption in the ejabberd config:
+
+ ```
+ listen:
+ starttls_required: false
+ ```
-A web administration interface is available at http://localhost:5280/admin. Use the admin user
-credentials (full JID (user@domain)) to log in. Changing settings there is also possible, but some
-of those might not persist on restart.
+#### Choice B: Self-signed certificate
-The rest of this section should be done by editing `/etc/ejabberd/ejabberd.yml`.
+If you want to use the server for local testing only, you may use a self-signed certificate to test encryption.
+Notice the lobby bots currently reject self-signed certificates.
-* Allow users to create accounts using the game via in-band registration:
+* Enable TLS over the default port:
+ ```
+ listen:
+ starttls: true
+ ```
+* Create the key file for certificate:
+
+ ```
+ openssl genrsa -out key.pem 2048
+ ```
+* Create the certificate file. “common name” should match the domainname.
+
+ ```
+ openssl req -new -key key.pem -out request.pem
```
- access:
+
+* Sign the certificate:
+
+ ```
+ openssl x509 -req -days 900 -in request.pem -signkey key.pem -out certificate.pem
+ ```
+
+* Store it as the ejabberd certificate:
+
+ ```
+ $ cat key.pem request.pem > /etc/ejabberd/ejabberd.pem
+ ```
+
+#### Choice C: Let's Encrypt certificate
+To secure user authentication and communication with modern encryption and to comply with privacy laws,
+ejabberd should be configured to use TLS with a proper, trusted certificate.
+
+* A free, valid, and trusted TLS certificate may be obtained from some certificate authorites, such as Let's Encrypt:
+
+
+
+* Enable TLS over the default port:
+ ```
+ listen:
+ starttls: true
+ ```
+
+* Setup the contact address if Let's Encrypt found an authentication issue:
+
+ ```
+ acme:
+ contact: "mailto:admin@example.com"
+ ```
+
+* Ensure old, vulnerable SSL/TLS protocols are disabled:
+
+ ```
+ define_macro:
+ 'TLS_OPTIONS':
+ - "no_sslv2"
+ - "no_sslv3"
+ - "no_tlsv1"
+ ```
+
+## 3. Configure ejabberd use policy
+
+The settings in this section grant or restrict user access rights.
+
+* Prevent the rooms from being destroyed if the last client leaves it:
+
+ ```
+ access_rules:
+ muc_admin:
+ - allow: admin
+ modules:
+ mod_muc:
+ access_persistent: muc_admin
+ default_room_options:
+ persistent: true
+ ```
+
+* Allow users to create accounts using the game via in-band registration.
+ ```
+ access_rules:
register:
- all: allow
+ - all: allow
```
-* Check list of registered users:
+### Optional use policies
+* (Optional) It is recommended to restrict usernames to alphanumeric characters (so that playernames are easily typeable for every participant).
+ The username may be restricted in length (because very long usernames are uncomfortably time-consuming to read and may not fit into the playername fields).
+ Notice the username regex below is also used by the 0 A.D. client to indicate invalid names to the user.
```
- $ ejabberdctl registered_users lobby.wildfiregames.com
+ acl:
+ validname:
+ user_regexp: "^[0-9A-Za-z._-]{1,20}$"
+
+ access_rules:
+ register:
+ - allow: validname
+
+ modules:
+ mod_register:
+ access: register
+ ```
+
+* (Optional) Prevent users from creating new rooms:
+
+ ```
+ modules:
+ mod_muc:
+ access_create: muc_admin
+ ```
+
+* (Optional) Increase the maximum number of users from the default 200:
+
+ ```
+ mod_muc:
+ max_users: 5000
+ default_room_options:
+ max_users: 1000
```
-* `XpartaMuPP` and `EcheLOn` need a user accountsto function, so create them using:
+* (Optional) Prevent users from sending too large stanzas.
+ Notice the bots can send large stanzas as well, so don't restrict it too much.
+
+ ```
+ max_stanza_size: 1048576
+ ```
+
+
+* (Optional) Prevent users from changing the room topic:
```
- $ ejabberdctl register echelon lobby.wildfiregames.com secure_password
- $ ejabberdctl register xpartamupp lobby.wildfiregames.com secure_password
+ mod_muc:
+ default_room_options:
+ allow_change_subj: false
```
-* The bots also need to be able to get the IPs of users hosting a match, which is what
- `mod_ipstamp` does.
+* (Optional) Prevent malicious users from registering new accounts quickly if they were banned.
+ Notice this also prevents players using the same internet router from registering for that time if they want to play together.
- * Create an ACL for the bot (or bots):
+ ```
+ registration_timeout: 3600
+ ```
+
+* (Optional) Enable room chatlogging.
+ 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.
+ Notice that `ejabberd.service` by default prevents write access to some directories (PrivateTmp, ProtectHome, ProtectSystem).
+
+ ```
+ modules:
+ mod_muc_log:
+ outdir: "/lobby/logs"
+ file_format: plaintext
+ timezone: universal
+ mod_muc:
+ default_room_options:
+ logging: true
+ ```
+
+* (Optional) Grant specific moderators administrator rights to see the IP address of a user:
+ See also `https://xmpp.org/extensions/xep-0133.html#get-user-stats`.
```
acl:
- bots:
+ admin:
user:
- - "echelon@lobby.wildfiregames.com"
- - "xpartamupp@lobby.wildfiregames.com"
+ - "username@lobby.wildfiregames.com"
+ ```
+
+* (Optional) Grant specific moderators to :
+ See also `https://xmpp.org/extensions/xep-0133.html#get-user-stats`.
+
+ ```
+ modules:
+ mod_muc:
+ access_admin: muc_admin
+ ```
+
+* (Optional) Ban specific IP addresses or subnet masks for persons that create new accounts after having been banned from the room:
+
+ ```
+ acl:
+ blocked:
+ ip:
+ - "12.34.56.78"
+ - "12.34.56.0/8"
+ - "12.34.0.0/16"
+ ...
+ access_rules:
+ c2s:
+ - deny: blocked
+ - allow
+ register:
+ - deny: blocked
+ - allow
+ ```
+
+## 4. Setup lobby bots
+
+### 4.1 Register lobby bot accounts
+
+* Check list of registered users:
+
+ ```
+ $ ejabberdctl registered_users lobby.wildfiregames.com
+ ```
+
+* Register the accounts of the lobby bots.
+ The rating account is only needed if you decided to enable the rating service.
+
+ ```
+ $ ejabberdctl register echelon23 lobby.wildfiregames.com secure_password
+ $ ejabberdctl register xpartamupp23 lobby.wildfiregames.com secure_password
+ ```
+
+### 4.2 Authorize lobby bots to see real JIDs
+
+* 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,
+ or the bots need to receive muc administrator rights.
+
+#### Choice A: Non-anonymous room
+* (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.
+
+ ```
+ modules:
+ mod_muc:
+ default_room_options:
+ anonymous: false
+
+#### Choice B: Non-anonymous room
+* 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:
+
+ ```
+ access_rules:
+ muc_admin:
+ - allow: bots
+
+ modules:
+ mod_muc:
+ access_admin: muc_admin
+ ```
+
+### 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).
+
+ ```
+ acl:
+ ## Don't use a regex, to prevent others from obtaining permissions after registering such an account.
+ bots:
+ - user: "xpartamupp23@lobby.wildfiregames.com"
+ - user: "echelon23@lobby.wildfiregames.com"
```
-* Add an access rule (name it `ipbots` since that is what the module expects):
+* Add an access rule for `ipbots` and a rule allowing bots to create PubSub nodes:
```
- access:
+ access_rules:
+ ## Expected by the ipstamp module for XpartaMuPP
ipbots:
- bots: allow
+ - allow: bots
+
+ pubsub_createnode:
+ - allow: bots
```
* Due to the amount of traffic the bot may process, give the group containing bots either unlimited
or a very high traffic shaper:
```
- c2s_shaper:
- admin: none
- bots: none
- all: normal
+ shaper_rules:
+ c2s_shaper:
+ - none: admin, bots
+ - normal
```
-* The bots need the real JIDs of the MUC users, which are only available for admin users,
- therefore the following setting is necessary:
+* Finally reload ejabberd's configuration:
```
- access:
- muc_admin:
- admin: allow
- bots: allow
+ $ ejabberdctl reload_config
```
-### MUC room setup
+### 4.4 Running XpartaMuPP - XMPP Multiplayer Game Manager
-To enable the bot to send the game list to players it needs the JIDs of the players, so the MUC
-room has to be configured as non-anonymous room. In case that you want to host multiple lobby
-rooms adding an ACL for MUC admins to which the bots are added, which is used for `access_admin`
-in the `mod_muc` configuration would be advisable.
+* Execute the following command to run the gamelist bot:
-## Running XpartaMuPP - XMPP Multiplayer Game Manager
+ ```
+ $ python3 XpartaMuPP.py --domain lobby.wildfiregames.com --login xpartamupp23 --password XXXXXX --nickname GamelistBot --room arena --elo echelon23
+ ```
-You need to have Python 3 and SleekXmpp 1.3.1+ installed
+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.
+Run `python3 XpartaMuPP.py --help` for the full list of options
- # apt-get install python3 python3-sleekxmpp
+* If the connection and authentication succeeded, you should see the following messages in the console:
-If you would like to run the leaderboard database, you will need to install SQLAlchemy for Python 3.
+ ```
+ INFO JID set to: xpartamupp23@lobby.wildfiregames.com/CC
+ INFO XpartaMuPP started
+ ```
- # apt-get install python3-sqlalchemy
+### 4.5 Running EcheLOn - XMPP Multiplayer Rating Manager
-Then execute the following command to setup the database.
+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.
+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.
+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`:
+
+ ```
+ # Difference between two ratings such that it is
+ # regarded as a "sure win" for the higher player.
+ # No points are gained or lost for such a game.
+ elo_sure_win_difference = 600.0
+
+ # Lower ratings "move faster" and change more
+ # dramatically than higher ones. Anything rating above
+ # this value moves at the same rate as this value.
+ elo_k_factor_constant_rating = 2200.0
+ ```
+
+* To initialize the `lobby_rankings.sqlite3` database, execute the following command:
+ ```
$ python3 LobbyRanking.py
+ ```
-Execute the following command to run the bot with default options:
+* Execute the following command to run the rating bot:
- $ python3 XpartaMuPP.py
+ ```
+ $ python3 EcheLOn.py --domain lobby.wildfiregames.com --login echelon23 --password XXXXXX --nickname RatingBot --room arena23
+ ```
-or rather a similar command to run a properly configured program:
+Run `python3 EcheLOn.py --help` for the full list of options
- $ python3 XpartaMuPP.py --domain lobby.wildfiregames.com --login wfgbot --password XXXXXX --nickname WFGbot --room arena
+## 5. Configure Pyrogenesis for the new Multiplayer Lobby
-or if you want to run XpartaMuPP with the corresponding rating bot detailed in the next section:
+The Pyrogenesis client is now going to be configured to become able to connect to the new Multiplayer Lobby.
- $ python3 XpartaMuPP.py --domain lobby.wildfiregames.com --login wfgbot --password XXXXXX --nickname WFGbot --room arena --elo echelon
+The Pyrogenesis documentation of configuration files can be found at .
+Available Pyrogenesis configuration settings are specified in `default.cfg`, see .
-Run `python3 XpartaMuPP.py --help` for the full list of options
+### 5.1 Local Configuration
-If everything is fine you should see something along these lines in your console
+ * Visit to identify the local user's Pyrogenesis configuration path depending on the operating system.
- INFO Negotiating TLS
- INFO Using SSL version: 3
- INFO Node set to: wfgbot@lobby.wildfiregames.com/CC
- INFO XpartaMuPP started
+ * Create or open `local.cfg` in the configuration path.
-Congratulations, you are now running XpartaMuPP - the 0 A.D. Multiplayer Game Manager.
+ * Add the following settings that determine the lobby server connection:
-## Run EcheLOn - XMPP Rating Bot
+ ```
+ lobby.room = "arena23" ; Default MUC room to join
+ lobby.server = "lobby.wildfiregames.com" ; Address of lobby 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.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.echelon = "echelon23" ; Name of the server-side XMPP-account that manages ratings
+ ```
-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. This is by no
-means necessary for the operation of a lobby in terms of creating/joining/listing games.
-EcheLOn handles all aspects of operation related to ELO.
+ If you disabled TLS encryption, set `require_tls` to `false`.
+ If you employed a self-signed certificate, set `verify_certificate` to `false`.
+
+### 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.
+
+* 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.
+
+### 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.
+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:
+
+ `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.
+ `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
+
+
+* 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 `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.
+
+* The retention times of ejabberd logs are relevant to GDPR.
+Visit for details.
+
+* The terms should be published online, so users can save and print them.
+ Add to your `local.cfg`:
+
+ ```
+ lobby.terms_url = "https://lobby.wildfiregames.com/terms/"; Allows the user to save the text and print the terms
+ ```
+
+### 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 run EcheLOn:
+It may be advisable to create a mod with a modified `default.cfg` and the new terms documents,
+see .
- $ python3 EcheLOn.py --domain lobby.wildfiregames.com --login echelon --password XXXXXX --nickname Ratings --room arena
+Congratulations, you are now running a custom Pyrogenesis Multiplayer Lobby!
Index: ps/trunk/source/tools/XpartaMuPP/ejabberd_example.yml
===================================================================
--- ps/trunk/source/tools/XpartaMuPP/ejabberd_example.yml
+++ ps/trunk/source/tools/XpartaMuPP/ejabberd_example.yml
@@ -0,0 +1,855 @@
+###
+###' ejabberd configuration file
+###
+###
+
+### The parameters used in this configuration file are explained in more detail
+### in the ejabberd Installation and Operation Guide.
+### Please consult the Guide in case of doubts, it is included with
+### your copy of ejabberd, and is also available online at
+### http://www.process-one.net/en/ejabberd/docs/
+
+### The configuration file is written in YAML.
+### Refer to http://en.wikipedia.org/wiki/YAML for the brief description.
+### However, ejabberd treats different literals as different types:
+###
+### - unquoted or single-quoted strings. They are called "atoms".
+### Example: dog, 'Jupiter', '3.14159', YELLOW
+###
+### - numeric literals. Example: 3, -45.0, .0
+###
+### - quoted or folded strings.
+### Examples of quoted string: "Lizzard", "orange".
+### Example of folded string:
+### > Art thou not Romeo,
+### and a Montague?
+---
+###. =======
+###' LOGGING
+
+##
+## loglevel: Verbosity of log files generated by ejabberd.
+## 0: No ejabberd log at all (not recommended)
+## 1: Critical
+## 2: Error
+## 3: Warning
+## 4: Info
+## 5: Debug
+##
+loglevel: 4
+
+##
+## rotation: Disable ejabberd's internal log rotation, as the Debian package
+## uses logrotate(8).
+log_rotate_size: 0
+log_rotate_date: ""
+
+##
+## overload protection: If you want to limit the number of messages per second
+## allowed from error_logger, which is a good idea if you want to avoid a flood
+## of messages when system is overloaded, you can set a limit.
+## 100 is ejabberd's default.
+log_rate_limit: 100
+
+##
+## watchdog_admins: Only useful for developers: if an ejabberd process
+## consumes a lot of memory, send live notifications to these XMPP
+## accounts.
+##
+## watchdog_admins:
+## - "bob@example.com"
+
+###. ===============
+###' NODE PARAMETERS
+
+##
+## net_ticktime: Specifies net_kernel tick time in seconds. This options must have
+## identical value on all nodes, and in most cases shouldn't be changed at all from
+## default value.
+##
+## net_ticktime: 60
+
+###. ================
+###' SERVED HOSTNAMES
+
+##
+## hosts: Domains served by ejabberd.
+## You can define one or several, for example:
+## hosts:
+## - "example.net"
+## - "example.com"
+## - "example.org"
+##
+hosts:
+ - "localhost"
+
+##
+## route_subdomains: Delegate subdomains to other XMPP servers.
+## For example, if this ejabberd serves example.org and you want
+## to allow communication with an XMPP server called im.example.org.
+##
+## route_subdomains: s2s
+
+###. ============
+###' Certificates
+
+## List all available PEM files containing certificates for your domains,
+## chains of certificates or certificate keys. Full chains will be built
+## automatically by ejabberd.
+##
+certfiles:
+ - "/etc/ejabberd/ejabberd.pem"
+
+## If your system provides only a single CA file (CentOS/FreeBSD):
+## ca_file: "/etc/ssl/certs/ca-bundle.pem"
+
+###. =================
+###' TLS configuration
+
+## Note that the following configuration is the default
+## configuration of the TLS driver, so you don't need to
+## uncomment it.
+##
+define_macro:
+ 'TLS_CIPHERS': "HIGH:!aNULL:!eNULL:!3DES:@STRENGTH"
+ 'TLS_OPTIONS':
+ - "no_sslv2"
+ - "no_sslv3"
+ - "no_tlsv1"
+ - "cipher_server_preference"
+ - "no_compression"
+ ## 'DH_FILE': "/path/to/dhparams.pem" # generated with: openssl dhparam -out dhparams.pem 2048
+
+## c2s_dhfile: 'DH_FILE'
+## s2s_dhfile: 'DH_FILE'
+c2s_ciphers: 'TLS_CIPHERS'
+s2s_ciphers: 'TLS_CIPHERS'
+c2s_protocol_options: 'TLS_OPTIONS'
+s2s_protocol_options: 'TLS_OPTIONS'
+
+###. ===============
+###' LISTENING PORTS
+
+##
+## listen: The ports ejabberd will listen on, which service each is handled
+## by and what options to start it with.
+##
+listen:
+ -
+ port: 5222
+ ip: "0.0.0.0"
+ module: ejabberd_c2s
+ starttls: true
+ starttls_required: false
+ protocol_options: 'TLS_OPTIONS'
+ max_stanza_size: 1048576
+ shaper: c2s_shaper
+ access: c2s
+
+ ## port: 5269
+ ## ip: "::"
+ ## module: ejabberd_s2s_in
+
+ -
+ port: 5280
+ ip: "127.0.0.1"
+ module: ejabberd_http
+ request_handlers:
+ "/ws": ejabberd_http_ws
+ "/bosh": mod_bosh
+ "/api": mod_http_api
+ ## "/pub/archive": mod_http_fileserver
+ web_admin: true
+ ## register: true
+ ## captcha: true
+ tls: true
+ protocol_options: 'TLS_OPTIONS'
+
+ ##
+ ## ejabberd_service: Interact with external components (transports, ...)
+ ##
+ ## -
+ ## port: 8888
+ ## ip: "::"
+ ## module: ejabberd_service
+ ## access: all
+ ## shaper_rule: fast
+ ## ip: "127.0.0.1"
+ ## privilege_access:
+ ## roster: "both"
+ ## message: "outgoing"
+ ## presence: "roster"
+ ## delegations:
+ ## "urn:xmpp:mam:1":
+ ## filtering: ["node"]
+ ## "http://jabber.org/protocol/pubsub":
+ ## filtering: []
+ ## hosts:
+ ## "icq.example.org":
+ ## password: "secret"
+ ## "sms.example.org":
+ ## password: "secret"
+
+ ##
+ ## ejabberd_stun: Handles STUN Binding requests
+ ##
+ -
+ port: 3478
+ transport: udp
+ module: ejabberd_stun
+
+ ##
+ ## To handle XML-RPC requests that provide admin credentials:
+ ##
+ ## -
+ ## port: 4560
+ ## ip: "::"
+ ## module: ejabberd_xmlrpc
+ ## maxsessions: 10
+ ## timeout: 5000
+ ## access_commands:
+ ## admin:
+ ## commands: all
+ ## options: []
+
+ ##
+ ## To enable secure http upload
+ ##
+ ## -
+ ## port: 5444
+ ## ip: "::"
+ ## module: ejabberd_http
+ ## request_handlers:
+ ## "": mod_http_upload
+ ## tls: true
+ ## protocol_options: 'TLS_OPTIONS'
+ ## dhfile: 'DH_FILE'
+ ## ciphers: 'TLS_CIPHERS'
+
+## Disabling digest-md5 SASL authentication. digest-md5 requires plain-text
+## password storage (see auth_password_format option).
+disable_sasl_mechanisms: "digest-md5"
+
+###. ==================
+###' S2S GLOBAL OPTIONS
+
+##
+## s2s_use_starttls: Enable STARTTLS for S2S connections.
+## Allowed values are: false, optional or required
+## You must specify 'certfiles' option
+##
+s2s_use_starttls: required
+
+##
+## S2S whitelist or blacklist
+##
+## Default s2s policy for undefined hosts.
+##
+## s2s_access: s2s
+
+##
+## Outgoing S2S options
+##
+## Preferred address families (which to try first) and connect timeout
+## in seconds.
+##
+## outgoing_s2s_families:
+## - ipv4
+## - ipv6
+## outgoing_s2s_timeout: 190
+
+###. ==============
+###' AUTHENTICATION
+
+##
+## auth_method: Method used to authenticate the users.
+## The default method is the internal.
+## If you want to use a different method,
+## comment this line and enable the correct ones.
+##
+auth_method: internal
+
+##
+## Store the plain passwords or hashed for SCRAM:
+## auth_password_format: plain
+auth_password_format: scram
+##
+## Define the FQDN if ejabberd doesn't detect it:
+## fqdn: "server3.example.com"
+
+##
+## Authentication using external script
+## Make sure the script is executable by ejabberd.
+##
+## auth_method: external
+## extauth_program: "/path/to/authentication/script"
+
+##
+## Authentication using SQL
+## Remember to setup a database in the next section.
+##
+## auth_method: sql
+
+##
+## Authentication using PAM
+##
+## auth_method: pam
+## pam_service: "pamservicename"
+
+##
+## Authentication using LDAP
+##
+## auth_method: ldap
+##
+## List of LDAP servers:
+## ldap_servers:
+## - "lw"
+##
+## Encryption of connection to LDAP servers:
+## ldap_encrypt: none
+## ldap_encrypt: tls
+##
+## Port to connect to on LDAP servers:
+## ldap_port: 389
+## ldap_port: 636
+##
+## LDAP manager:
+## ldap_rootdn: "dc=example,dc=com"
+##
+## Password of LDAP manager:
+## ldap_password: "******"
+##
+## Search base of LDAP directory:
+## ldap_base: "dc=example,dc=com"
+##
+## LDAP attribute that holds user ID:
+## ldap_uids:
+## - "mail": "%u@mail.example.org"
+##
+## LDAP filter:
+## ldap_filter: "(objectClass=shadowAccount)"
+
+##
+## Anonymous login support:
+## auth_method: anonymous
+## anonymous_protocol: sasl_anon | login_anon | both
+## allow_multiple_connections: true | false
+##
+## host_config:
+## "public.example.org":
+## auth_method: anonymous
+## allow_multiple_connections: false
+## anonymous_protocol: sasl_anon
+##
+## To use both anonymous and internal authentication:
+##
+## host_config:
+## "public.example.org":
+## auth_method:
+## - internal
+## - anonymous
+
+###. ==============
+###' DATABASE SETUP
+
+## ejabberd by default uses the internal Mnesia database,
+## so you do not necessarily need this section.
+## This section provides configuration examples in case
+## you want to use other database backends.
+## Please consult the ejabberd Guide for details on database creation.
+
+##
+## MySQL server:
+##
+## sql_type: mysql
+## sql_server: "server"
+## sql_database: "database"
+## sql_username: "username"
+## sql_password: "password"
+##
+## If you want to specify the port:
+## sql_port: 1234
+
+##
+## PostgreSQL server:
+##
+## sql_type: pgsql
+## sql_server: "server"
+## sql_database: "database"
+## sql_username: "username"
+## sql_password: "password"
+##
+## If you want to specify the port:
+## sql_port: 1234
+##
+## If you use PostgreSQL, have a large database, and need a
+## faster but inexact replacement for "select count(*) from users"
+##
+## pgsql_users_number_estimate: true
+
+##
+## SQLite:
+##
+## sql_type: sqlite
+## sql_database: "/path/to/database.db"
+
+##
+## ODBC compatible or MSSQL server:
+##
+## sql_type: odbc
+## sql_server: "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"
+
+##
+## Number of connections to open to the database for each virtual host
+##
+## sql_pool_size: 10
+
+##
+## Interval to make a dummy SQL request to keep the connections to the
+## database alive. Specify in seconds: for example 28800 means 8 hours
+##
+## sql_keepalive_interval: undefined
+
+###. ===============
+###' TRAFFIC SHAPERS
+
+shaper:
+ ##
+ ## The "normal" shaper limits traffic speed to 1000 B/s
+ ##
+ normal: 1000
+
+ ##
+ ## The "fast" shaper limits traffic speed to 50000 B/s
+ ##
+ fast: 50000
+
+##
+## This option specifies the maximum number of elements in the queue
+## of the FSM. Refer to the documentation for details.
+##
+max_fsm_queue: 10000
+
+###. ====================
+###' ACCESS CONTROL LISTS
+acl:
+ ##
+ ## The 'admin' ACL grants administrative privileges to XMPP accounts.
+ ## You can put here as many accounts as you want.
+ ##
+ admin:
+ user:
+ - "admin@localhost"
+
+ ## Don't use a regex, to prevent others from obtaining permissions after registering such an account.
+ bots:
+ - user: "echelon23@localhost"
+ - user: "wfgbot23@localhost"
+
+ # Keep playernames short and easily typeable for everyone
+ validname:
+ user_regexp: "^[0-9A-Za-z._-]{1,20}$"
+
+ ##
+ ## Blocked users
+ ##
+ ## blocked:
+ ## user:
+ ## - "baduser@example.org"
+ ## - "test"
+
+ ## Local users: don't modify this.
+ ##
+ local:
+ user_regexp: ""
+
+ ##
+ ## More examples of ACLs
+ ##
+ ## jabberorg:
+ ## server:
+ ## - "jabber.org"
+ ## aleksey:
+ ## user:
+ ## - "aleksey@jabber.ru"
+ ## test:
+ ## user_regexp: "^test"
+ ## user_glob: "test*"
+
+ ##
+ ## Loopback network
+ ##
+ loopback:
+ ip:
+ - "127.0.0.0/8"
+ - "::1/128"
+ - "::FFFF:127.0.0.1/128"
+
+ ##
+ ## Bad XMPP servers
+ ##
+ ## bad_servers:
+ ## server:
+ ## - "xmpp.zombie.org"
+ ## - "xmpp.spam.com"
+
+##
+## Define specific ACLs in a virtual host.
+##
+## host_config:
+## "localhost":
+## acl:
+## admin:
+## user:
+## - "bob-local@localhost"
+
+###. ============
+###' SHAPER RULES
+
+shaper_rules:
+ ## Maximum number of simultaneous sessions allowed for a single user:
+ max_user_sessions: 10
+ ## Maximum number of offline messages that users can have:
+ max_user_offline_messages:
+ - 5000: admin
+ - 100
+ ## For C2S connections, all users except admins use the "normal" shaper
+ c2s_shaper:
+ - none: admin
+ - none: bots
+ - normal
+ ## All S2S connections use the "fast" shaper
+ s2s_shaper: fast
+
+###. ============
+###' ACCESS RULES
+access_rules:
+ ## This rule allows access only for local users:
+ local:
+ - allow: local
+ ## Only non-blocked users can use c2s connections:
+ c2s:
+ - deny: blocked
+ - allow
+ ## Only admins can send announcement messages:
+ announce:
+ - allow: admin
+ ## Only admins can use the configuration interface:
+ configure:
+ - allow: admin
+ ## Expected by the ipstamp module for XpartaMuPP
+ ipbots:
+ - allow: bots
+ muc_admin:
+ - allow: admin
+ ## Bots must be able to create nodes for games, ratings and boards lists
+ pubsub_createnode:
+ - allow: admin
+ - allow: bots
+ ## In-band registration allows registration of any possible username.
+ ## To disable in-band registration, replace 'allow' with 'deny'.
+ register:
+ - deny: blocked
+ - allow: validname
+ ## Only allow to register from localhost
+ trusted_network:
+ - allow: loopback
+ ## Do not establish S2S connections with bad servers
+ ## If you enable this you also have to uncomment "s2s_access: s2s"
+ ## s2s:
+ ## - deny:
+ ## - ip: "XXX.XXX.XXX.XXX/32"
+ ## - deny:
+ ## - ip: "XXX.XXX.XXX.XXX/32"
+ ## - allow
+
+## ===============
+## API PERMISSIONS
+## ===============
+##
+## This section allows you to define who and using what method
+## can execute commands offered by ejabberd.
+##
+## By default "console commands" section allow executing all commands
+## issued using ejabberdctl command, and "admin access" section allows
+## users in admin acl that connect from 127.0.0.1 to execute all
+## commands except start and stop with any available access method
+## (ejabberdctl, http-api, xmlrpc depending what is enabled on server).
+##
+## If you remove "console commands" there will be one added by
+## default allowing executing all commands, but if you just change
+## permissions in it, version from config file will be used instead
+## of default one.
+##
+api_permissions:
+ "console commands":
+ from:
+ - ejabberd_ctl
+ who: all
+ what: "*"
+ "admin access":
+ who:
+ - access:
+ - allow:
+ - acl: loopback
+ - acl: admin
+ - oauth:
+ - scope: "ejabberd:admin"
+ - access:
+ - allow:
+ - acl: loopback
+ - acl: admin
+ what:
+ - "*"
+ - "!stop"
+ - "!start"
+ "public commands":
+ who:
+ - ip: "127.0.0.1/8"
+ what:
+ - "status"
+ - "connected_users_number"
+
+## By default the frequency of account registrations from the same IP
+## is limited to 1 account every 10 minutes. To disable, specify: infinity
+registration_timeout: 3600
+
+##
+## Define specific Access Rules in a virtual host.
+##
+## host_config:
+## "localhost":
+## access:
+## c2s:
+## - allow: admin
+## - deny
+## register:
+## - deny
+
+###. ================
+###' DEFAULT LANGUAGE
+
+##
+## language: Default language used for server messages.
+##
+language: "en"
+
+##
+## Set a different default language in a virtual host.
+##
+## host_config:
+## "localhost":
+## language: "ru"
+
+###. =======
+###' CAPTCHA
+
+##
+## Full path to a script that generates the image.
+##
+## captcha_cmd: "/usr/share/ejabberd/captcha.sh"
+
+##
+## Host for the URL and port where ejabberd listens for CAPTCHA requests.
+##
+## captcha_host: "example.org:5280"
+
+##
+## Limit CAPTCHA calls per minute for JID/IP to avoid DoS.
+##
+## captcha_limit: 5
+
+###. ====
+###' ACME
+##
+## In order to use the acme certificate acquiring through "Let's Encrypt"
+## an http listener has to be configured to listen to port 80 so that
+## the authorization challenges posed by "Let's Encrypt" can be solved.
+##
+## A simple way of doing this would be to add the following in the listening
+## section and to configure port forwarding from 80 to 5281 either via NAT
+## (for ipv4 only) or using frontends such as haproxy/nginx/sslh/etc.
+## -
+## port: 5281
+## ip: "::"
+## module: ejabberd_http
+
+acme:
+
+ ## A contact mail that the ACME Certificate Authority can contact in case of
+ ## an authorization issue, such as a server-initiated certificate revocation.
+ ## It is not mandatory to provide an email address but it is highly suggested.
+ contact: "mailto:example-admin@example.com"
+
+
+ ## The ACME Certificate Authority URL.
+ ## This could either be:
+ ## - https://acme-v01.api.letsencrypt.org - (Default) for the production CA
+ ## - https://acme-staging.api.letsencrypt.org - for the staging CA
+ ## - http://localhost:4000 - for a local version of the CA
+ ca_url: "https://acme-v01.api.letsencrypt.org"
+
+###. =======
+###' MODULES
+
+##
+## Modules enabled in all ejabberd virtual hosts.
+##
+modules:
+ mod_adhoc: {}
+ mod_admin_extra: {}
+ mod_announce: # recommends mod_adhoc
+ access: announce
+ mod_blocking: {} # requires mod_privacy
+ mod_caps: {}
+ mod_carboncopy: {}
+ mod_client_state: {}
+ mod_configure: {} # requires mod_adhoc
+ ## mod_delegation: {} # for xep0356
+ mod_disco: {}
+ ## mod_echo: {}
+ ## ipstamp module used by XpartaMuPP to insert IP addresses into the gamelist
+ mod_ipstamp: {}
+ ## mod_irc: {}
+ mod_bosh: {}
+ ## mod_http_fileserver:
+ ## docroot: "/var/www"
+ ## accesslog: "/var/log/ejabberd/access.log"
+ ## mod_http_upload:
+ ## # docroot: "@HOME@/upload"
+ ## put_url: "https://@HOST@:5444"
+ ## thumbnail: false # otherwise needs the identify command from ImageMagick installed
+ ## mod_http_upload_quota:
+ ## max_days: 30
+ mod_last: {}
+ ## XEP-0313: Message Archive Management
+ ## You might want to setup a SQL backend for MAM because the mnesia database is
+ ## limited to 2GB which might be exceeded on large servers
+ ## mod_mam: {} # for xep0313, mnesia is limited to 2GB, better use an SQL backend
+ mod_muc:
+ ## host: "conference.@HOST@"
+ access:
+ - allow
+ access_admin: muc_admin
+ access_create: muc_admin
+ access_persistent: muc_admin
+ max_users: 5000
+ default_room_options:
+ allow_change_subj: false
+ logging: true
+ max_users: 1000
+ persistent: true
+ mod_muc_admin: {}
+ mod_muc_log:
+ outdir: "/lobby/logs"
+ dirtype: plain
+ file_format: plaintext
+ timezone: universal
+ ## mod_multicast: {}
+ mod_offline:
+ access_max_user_messages: max_user_offline_messages
+ mod_ping:
+ send_pings: true
+ ## mod_pres_counter:
+ ## count: 5
+ ## interval: 60
+ mod_privacy: {}
+ mod_private: {}
+ ## mod_proxy65: {}
+ mod_pubsub:
+ access_createnode: pubsub_createnode
+ ## reduces resource comsumption, but XEP incompliant
+ ignore_pep_from_offline: true
+ ## XEP compliant, but increases resource comsumption
+ ## ignore_pep_from_offline: false
+ last_item_cache: false
+ plugins:
+ - "flat"
+ - "hometree"
+ - "pep" # pep requires mod_caps
+ mod_push: {}
+ mod_push_keepalive: {}
+ mod_register:
+ ##
+ ## Protect In-Band account registrations with CAPTCHA.
+ ##
+ ## captcha_protected: true
+ ##
+ ## Set the minimum informational entropy for passwords.
+ ##
+ ## password_strength: 32
+ ##
+ ## After successful registration, the user receives
+ ## a message with this subject and body.
+ ##
+ ## welcome_message:
+ ## subject: "Welcome!"
+ ## body: |-
+ ## Hi.
+ ## Welcome to this XMPP server.
+ ##
+ ## When a user registers, send a notification to
+ ## these XMPP accounts.
+ ##
+ ## registration_watchers:
+ ## - "admin1@example.org"
+ ##
+ ## Only clients in the server machine can register accounts
+ ##
+ ## ip_access: trusted_network
+ ##
+ ## Local c2s or remote s2s users cannot register accounts
+ ##
+ ## access_from: deny
+ access: register
+ mod_roster:
+ versioning: true
+ ## mod_shared_roster: {}
+ mod_stats: {}
+ mod_time: {}
+ ## mod_vcard:
+ ## search: false
+ ## mod_vcard_xupdate: {}
+ ## Convert all avatars posted by Android clients from WebP to JPEG
+ ## mod_avatar: # this module needs compile option --enable-graphics
+ ## convert:
+ ## webp: jpeg
+ mod_version: {}
+ mod_stream_mgmt:
+ resend_on_timeout: if_offline
+ ## Non-SASL Authentication (XEP-0078) is now disabled by default
+ ## because it's obsoleted and is used mostly by abandoned
+ ## client software
+ ## mod_legacy_auth: {}
+ ## The module for S2S dialback (XEP-0220). Please note that you cannot
+ ## rely solely on dialback if you want to federate with other servers,
+ ## because a lot of servers have dialback disabled and instead rely on
+ ## PKIX authentication. Make sure you have proper certificates installed
+ ## and check your accessibility at https://check.messaging.one/
+ mod_s2s_dialback: {}
+ mod_http_api: {}
+
+##
+## Enable modules with custom options in a specific virtual host
+##
+## host_config:
+## "localhost":
+## modules:
+## mod_echo:
+## host: "mirror.localhost"
+
+##
+## Enable modules management via ejabberdctl for installation and
+## uninstallation of public/private contributed modules
+## (enabled by default)
+##
+
+allow_contrib_modules: true
+
+###.
+###'
+### Local Variables:
+### mode: yaml
+### End:
+### vim: set filetype=yaml tabstop=8 foldmarker=###',###. foldmethod=marker:
+