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: +