gptbot/0ad
1
0
Fork 0
forked from mirrors/0ad
Code Pull Requests Activity

Complete the lobby server readme and provide a sample ejabberd configuration file.

Browse Source 
Describe Wildfire Games undocumented, but relevant or even required
configuration settings.
Add chapter on ejabberd connectivity: TLS encryption (1beb96cb20, refs
#4705), STUN (61261d14fc / D364), IPv6.
Elaborate use policy configuration, add nickname restrictions from
23d8bc11a5.
Brief Terms and Conditions notification (81883806ec, 54e5ad2ae9).
Recommend to run bots without administrative access (but explain the
alternative too for fans of the setting).
Explain how to configure and test 0 A.D. with new lobbies and how to
distribute the settings.

Differential Revision: https://code.wildfiregames.com/D1659
Fixes #4671
Reviewed By: user1
Comments By: Dunedan
This was SVN commit r21925.
This commit is contained in:
elexis
2018-11-07 15:59:28 +00:00
parent ccef625280
commit 214d6caf43
3 changed files with 1398 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
binaries/data/mods/public/gui/session/session.js
+1
View File
@@ -1567,6 +1567,7 @@ function sendLobbyPlayerlistUpdate()
/**
* Send a report on the gamestatus to the lobby.
* Keep in sync with source/tools/XpartaMuPP/LobbyRanking.py
*/
function reportGame()
{
source/tools/XpartaMuPP/README.md
+542 -96
View File
@@ -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 <https://docs.ejabberd.im/admin/installation/>.
```
$ 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 @@ You should now be able to connect to this XMPP server using a normal XMPP client
$ 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 <https://docs.ejabberd.im/admin/configuration/>.
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
### Ejabberd configuration
The settings in this section ensure that connections can be built where intended, and only where intended.
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.
The rest of this section should be done by editing `/etc/ejabberd/ejabberd.yml`.
* Allow users to create accounts using the game via in-band registration:
### 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:
```
access:
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 <https://localhost:5280/admin> from external access by disabling or restriction to `localhost`:
```
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
```
#### Choice B: Self-signed certificate
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.
* 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
```
* 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:
<https://letsencrypt.org/getting-started/>
<https://blog.process-one.net/securing-ejabberd-with-tls-encryption/>
* 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
```
### 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.
```
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
```
* (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:
```
mod_muc:
default_room_options:
allow_change_subj: false
```
* (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.
```
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:
admin:
user:
- "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
```
* `XpartaMuPP` and `EcheLOn` need a user accountsto function, so create them using:
* Register the accounts of the lobby bots.
The rating account is only needed if you decided to enable the rating service.
```
$ ejabberdctl register echelon lobby.wildfiregames.com secure_password
$ ejabberdctl register xpartamupp lobby.wildfiregames.com secure_password
$ ejabberdctl register echelon23 lobby.wildfiregames.com secure_password
$ ejabberdctl register xpartamupp23 lobby.wildfiregames.com secure_password
```
* The bots also need to be able to get the IPs of users hosting a match, which is what
`mod_ipstamp` does.
### 4.2 Authorize lobby bots to see real JIDs
* Create an ACL for the bot (or bots):
* 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.
```
acl:
bots:
user:
- "echelon@lobby.wildfiregames.com"
- "xpartamupp@lobby.wildfiregames.com"
```
modules:
mod_muc:
default_room_options:
anonymous: false
* Add an access rule (name it `ipbots` since that is what the module expects):
#### 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:
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 for `ipbots` and a rule allowing bots to create PubSub nodes:
```
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
You need to have Python 3 and SleekXmpp 1.3.1+ installed
# apt-get install python3 python3-sleekxmpp
If you would like to run the leaderboard database, you will need to install SQLAlchemy for Python 3.
# apt-get install python3-sqlalchemy
Then execute the following command to setup the database.
$ python3 LobbyRanking.py
Execute the following command to run the bot with default options:
$ python3 XpartaMuPP.py
or rather a similar command to run a properly configured program:
$ python3 XpartaMuPP.py --domain lobby.wildfiregames.com --login wfgbot --password XXXXXX --nickname WFGbot --room arena
or if you want to run XpartaMuPP with the corresponding rating bot detailed in the next section:
$ python3 XpartaMuPP.py --domain lobby.wildfiregames.com --login wfgbot --password XXXXXX --nickname WFGbot --room arena --elo echelon
```
$ python3 XpartaMuPP.py --domain lobby.wildfiregames.com --login xpartamupp23 --password XXXXXX --nickname GamelistBot --room arena --elo echelon23
```
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
If everything is fine you should see something along these lines in your console
* If the connection and authentication succeeded, you should see the following messages in the console:
INFO Negotiating TLS
INFO Using SSL version: 3
INFO Node set to: wfgbot@lobby.wildfiregames.com/CC
```
INFO JID set to: xpartamupp23@lobby.wildfiregames.com/CC
INFO XpartaMuPP started
```
Congratulations, you are now running XpartaMuPP - the 0 A.D. Multiplayer Game Manager.
## Run EcheLOn - XMPP Rating Bot
### 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
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.
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.
To run EcheLOn:
* (Optional) Some constants of the algorithm may be edited by experienced administrators at the head of `ELO.py`:
$ python3 EcheLOn.py --domain lobby.wildfiregames.com --login echelon --password XXXXXX --nickname Ratings --room arena
```
# 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 rating bot:
```
$ python3 EcheLOn.py --domain lobby.wildfiregames.com --login echelon23 --password XXXXXX --nickname RatingBot --room arena23
```
Run `python3 EcheLOn.py --help` for the full list of options
## 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 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>.
### 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.
* Create or open `local.cfg` in the configuration path.
* Add the following settings that determine the lobby server connection:
```
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
```
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
<https://trac.wildfiregames.com/browser/ps/trunk/binaries/data/mods/public/gui/prelobby/common/terms/>
* Replace all occurrences of `Wildfire Games` in the files with the one providing the new server.
* 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 <https://www.ejabberd.im/Rotating%20logs%20with%20ejabberd/index.html> for details.
* The terms should be published online, so users can save and print them.
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`.
It may be advisable to create a mod with a modified `default.cfg` and the new terms documents,
see <https://trac.wildfiregames.com/wiki/Modding_Guide>.
Congratulations, you are now running a custom Pyrogenesis Multiplayer Lobby!
source/tools/XpartaMuPP/ejabberd_example.yml
+855
View File
@@ -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: