Dockerfile to build an ejabberd container image.
Since version 16.12, ejabberd has it's own docker container based on the work of this container included in the source tree. See more in this blogpost. We can expect more work on this in the future.
Current Version: 21.01
Docker Tag Names are based on ejabberd versions in git branches and tags. The image tag :latest is based on the master branch.
You can start of with the following container:
docker run -d \
--name "ejabberd" \
-p 5222:5222 \
-p 5269:5269 \
-p 5280:5280 \
-h 'xmpp.example.de' \
-e "XMPP_DOMAIN=example.de" \
-e "[email protected] [email protected]" \
-e "[email protected]:password1234 [email protected]" \
-e "TZ=Europe/Berlin" \
rroemhild/ejabberdor with the docker-compose example
wget https://raw.githubusercontent.com/rroemhild/docker-ejabberd/master/examples/docker-compose/docker-compose.yml
docker-compose upFor storage of the application data, you can mount volumes at
/opt/ejabberd/ssl/opt/ejabberd/backup/opt/ejabberd/upload/opt/ejabberd/database
or use a data container
docker create --name ejabberd-data rroemhild/ejabberd-data
docker run -d --name ejabberd --volumes-from ejabberd-data rroemhild/ejabberdTLS is enabled by default and the run script will auto-generate two snake-oil certificates during boot if you don't provide your SSL certificates.
To use your own certificates, there are two options.
-
Mount the volume
/opt/ejabberd/sslto a local directory with the.pemfiles:- /tmp/ssl/host.pem (SERVER_HOSTNAME)
- /tmp/ssl/xmpp_domain.pem (XMPP_DOMAIN)
Make sure that the certificate and private key are in one
.pemfile. If one file is missing it will be auto-generated. I.e. you can provide your certificate for your XMMP_DOMAIN and use a snake-oil certificate for theSERVER_HOSTNAME. -
Specify the certificates via environment variables: EJABBERD_SSLCERT_HOST and EJABBERD_SSLCERT_EXAMPLE_COM. For the domain certificates, make sure you match the domain names given in XMPP_DOMAIN and replace dots and dashes with underscore.
Build your own ejabberd container image and add your config templates, certificates or extend it for your needs.
FROM rroemhild/ejabberd
ADD ./ejabberd.yml.tpl /opt/ejabberd/conf/ejabberd.yml.tpl
ADD ./ejabberdctl.cfg.tpl /opt/ejabberd/conf/ejabberdctl.cfg.tpl
ADD ./example.com.pem /opt/ejabberd/ssl/example.com.pem
If you need root privileges switch to USER root and go back to USER ejabberd when you're done.
By default ejabberd runs as user ejabberd(999). To run ejabberd as root add the -u root argument to docker run.
docker run -d -u root -P rroemhild/ejabberdThe docker-compose-cluster example demonstrates how to extend this container image to setup a multi-master cluster.
You can additionally provide extra runtime configuration in a downstream image by replacing the config template ejabberd.yml.tpl with one based on this image's template and include extra interpolation of environment variables. The template is parsed by Jinja2 with the runtime environment (equivalent to Python's os.environ available as env).
By default the container will serve the XMPP domain localhost. In order to serve a different domain at runtime, provide the XMPP_DOMAIN variable with a domain name. You can add more domains separated with whitespace.
XMPP_DOMAIN=example.ninja xyz.io test.com
Authentication methods can be set with the EJABBERD_AUTH_METHOD environment variable. The default authentication mode is internal.
Supported authentication methods:
- anonymous
- internal
- external
- ldap
Internal and anonymous authentication example:
EJABBERD_AUTH_METHOD=internal anonymous
External authentication example:
EJABBERD_AUTH_METHOD=external
EJABBERD_EXTAUTH_PROGRAM="/opt/ejabberd/scripts/authenticate-user.sh"
EJABBERD_EXTAUTH_INSTANCES=3
EJABBERD_EXTAUTH_CACHE=600
EJABBERD_EXTAUTH_INSTANCES must be an integer with a minimum value of 1. EJABBERD_EXTAUTH_CACHE can be set to "false" or an integer value representing cache time in seconds. Note that caching should not be enabled if internal auth is also enabled.
The variable EJABBERD_AUTH_PASSWORD_FORMAT controls in which format user passwords are
stored. Possible values are plain and scram. The default is to store
SCRAMbled
passwords, meaning that it is impossible to obtain the original plain password from the
stored information.
NOTE: SCRAM does not work with SIP/TURN foreign authentication methods. In this case, you may have to disable the option. More details can be found here: https://docs.ejabberd.im/admin/configuration/#internal
If using SCRAM with an SQL database that has plaintext passwords stored, use the command
ejabberdctl convert_to_scram example.org
to convert all your existing plaintext passwords to scrambled format.
Set EJABBERD_AUTH_METHOD=external and EJABBERD_EXTAUTH_PROGRAM=/opt/ejabberd/scripts/lib/auth_mysql.py to enable MySQL authentication. Use the following environment variables to configure the database connection and the layout of the database. Password changing, registration, and unregistration are optional features and are enabled only if the respective queries are provided.
- AUTH_MYSQL_HOST: The MySQL host
- AUTH_MYSQL_USER: Username to connect to the MySQL host
- AUTH_MYSQL_PASSWORD: Password to connect to the MySQL host
- AUTH_MYSQL_DATABASE: Database name where to find the user information
- AUTH_MYSQL_HASHALG: Format of the password in the database. Default is cleartext. Options are
crypt,md5,sha1,sha224,sha256,sha384,sha512.cryptis recommended, as it is salted. When setting the password,cryptuses SHA-512 (prefix$6$). - AUTH_MYSQL_QUERY_GETPASS: Get the password for a user. Use the placeholders
%(user)s,%(host)s. Example:SELECT password FROM users WHERE username = CONCAT(%(user)s, '@', %(host)s) - AUTH_MYSQL_QUERY_SETPASS: Update the password for a user. Leave empty to disable. Placeholder
%(password)scontains the hashed password. Example:UPDATE users SET password = %(password)s WHERE username = CONCAT(%(user)s, '@', %(host)s) - AUTH_MYSQL_QUERY_REGISTER: Register a new user. Leave empty to disable. Example:
INSERT INTO users ( username, password ) VALUES ( CONCAT(%(user)s, '@', %(host)s), %(password)s ) - AUTH_MYSQL_QUERY_UNREGISTER: Removes a user. Leave empty to disable. Example:
DELETE FROM users WHERE username = CONCAT(%(user)s, '@', %(host)s)
Note that the MySQL authentication script writes a debug log into the file /var/log/ejabberd/extauth.log. To get its content, execute the following command:
docker exec -ti ejabberd tail -n50 -f /var/log/ejabberd/extauth.logTo find out more about the mysql authentication script, check out the ejabberd-auth-mysql repository.
Full documentation http://docs.ejabberd.im/admin/guide/configuration/#ldap.
Connection
- EJABBERD_LDAP_SERVERS: List of IP addresses or DNS names of your LDAP servers. This option is required.
- EJABBERD_LDAP_ENCRYPT: The value
tlsenables encryption by using LDAP over SSL. The default value is:none. - EJABBERD_LDAP_TLS_VERIFY:
false|soft|hardThis option specifies whether to verify LDAP server certificate or not when TLS is enabled. The default isfalsewhich means no checks are performed. - EJABBERD_LDAP_TLS_CACERTFILE: Path to file containing PEM encoded CA certificates.
- EJABBERD_LDAP_TLS_DEPTH: Specifies the maximum verification depth when TLS verification is enabled. The default value is 1.
- EJABBERD_LDAP_PORT: The default port is
389if encryption is disabled; and636if encryption is enabled. - EJABBERD_LDAP_ROOTDN: Bind DN. The default value is "" which means ‘anonymous connection’.
- EJABBERD_LDAP_PASSWORD: Bind password. The default value is "".
- EJABBERD_LDAP_DEREF_ALIASES:
never|always|finding|searchingWhether or not to dereference aliases. The default isnever.
Authentication
- EJABBERD_LDAP_BASE: LDAP base directory which stores users accounts. This option is required.
- EJABBERD_LDAP_UIDS:
ldap_uidattr:ldap_uidattr_formatThe default attributes areuid:%u. - EJABBERD_LDAP_FILTER: RFC 4515 LDAP filter. The default Filter value is undefined.
- EJABBERD_LDAP_DN_FILTER:
{ Filter: FilterAttrs }This filter is applied on the results returned by the main filter. By default ldap_dn_filter is undefined.
Set one or more admin user (seperated by whitespace) with the EJABBERD_ADMINS environment variable. You can register admin users with the EJABBERD_USERS environment variable during container startup, use you favorite XMPP client or the ejabberdctl command line utility.
Automatically register users during container startup. Uses random password if you don't provide a password for the user. Format is JID:PASSWORD. Register more users separated with whitespace.
Register the admin user from EJABBERD_ADMINS with a give password:
[email protected]:password1234
Or without a random password printed to stdout (check container logs):
Register more than one user:
[email protected]:password1234 [email protected] [email protected]
Automatically create roster groups and register users during container startup. To create shared roster groups, separate with whitespace:
To add users to shared roster groups, separate with whitespace:
To add all registered users on a virtual host to a shared roster group:
EJABBERD_GROUP_MEMBERS=@all@@example.ninja:[email protected]
Please take a note of the format: @all@@example.ninja. You need to specify not only the special directive @all@ but also a virtual host separated by @.
- EJABBERD_SKIP_MAKE_SSLCERT: Skip generating ssl certificates. Default: false
- EJABBERD_SSLCERT_HOST: SSL Certificate for the hostname.
- EJABBERD_SSLCERT_EXAMPLE_COM: SSL Certificates for XMPP domains.
- EJABBERD_STARTTLS: Set to
falseto disable StartTLS for client to server connections. Defaults totrue. - EJABBERD_S2S_SSL: Set to
falseto disable SSL in server 2 server connections. Defaults totrue. - EJABBERD_HTTPS: If your proxy terminates SSL you may want to disable HTTPS on port 5280 and 5443. Defaults to
true. - EJABBERD_PROTOCOL_OPTIONS_TLSV1: Allow TLSv1 protocol. Defaults to
false. - EJABBERD_PROTOCOL_OPTIONS_TLSV1_1: Allow TLSv1.1 protocol. Defaults to
true. - EJABBERD_CIPHERS: Cipher suite. Defaults to
HIGH:!aNULL:!3DES. - EJABBERD_DHPARAM: Set to
trueto use or generate custom DH parameters. Defaults tofalse. - EJABBERD_SKIP_MAKE_DHPARAM: Skip generating DH params. Default: false
- EJABBERD_STUN: Do you want to enable the STUN service on port 3478 (tcp and udp) and port 5439 (TLS enabled). Default: false
- EJABBERD_TURN_IP: Which IP to use for the TURN service on port 3478 (tcp and udp) and port 5439 (TLS enabled). Default: no default
- ERLANG_NODE: Allows to explicitly specify erlang node for ejabberd. Set to
ejabberdlets erlang add the hostname. Defaults toejabberd@localhost. - ERLANG_COOKIE: Set erlang cookie. Defaults to auto-generated cookie.
- ERLANG_OPTIONS: Overwrite additional options passed to erlang while starting ejabberd.
- EJABBERD_SKIP_MODULES_UPDATE: If you do not need to update ejabberd modules specs, skip the update task and speedup start. Defaults to
false. - EJABBERD_MOD_MUC_ADMIN: Activate the mod_muc_admin module. Defaults to
false. - EJABBERD_MUC_CREATE_ADMIN_ONLY: Only allow admins to create rooms. Defaults to
false. - EJABBERD_MOD_ADMIN_EXTRA: Activate the mod_admin_extra module. Defaults to
true. - EJABBERD_REGISTER_ADMIN_ONLY: Only allow admins to register users. Defaults to
false. - EJABBERD_REGISTER_TRUSTED_NETWORK_ONLY: Only allow user registration from the trusted_network access rule. Defaults to
true. - EJABBERD_MOD_VERSION: Activate the mod_version module. Defaults to
true. - EJABBERD_SOURCE_MODULES: List of modules, which will be installed from sources localized in ${EJABBERD_HOME}/module_source.
- EJABBERD_CONTRIB_MODULES: List of modules, which will be installed from contrib repository.
- EJABBERD_RESTART_AFTER_MODULE_INSTALL: If any modules were installed, restart the server, if the option is enabled.
- EJABBERD_CUSTOM_AUTH_MODULE_OVERRIDE: If a custom module was defined for handling auth, we need to override the pre-defined auth methods in the config.
Use the EJABBERD_LOGLEVEL environment variable to set verbosity. Defaults to 4 (Info).
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
If you prefer to use your own configuration files and avoid passing docker environment variables (-e), you can do so by mounting a host directory.
Pass in an additional -v to the docker run command, like so:
docker run -d \
--name "ejabberd" \
-p 5222:5222 \
-p 5269:5269 \
-p 5280:5280 \
-h 'xmpp.example.de' \
-v /<host_path>/conf:/opt/ejabberd/conf \
rroemhild/ejabberd
Your /<host_path>/conf folder should look like so:
/<host_path>/conf/
├── ejabberdctl.cfg
├── ejabberd.yml
└── inetrc
Example configuration files can be downloaded from the ejabberd github page.
When these files exist in /opt/ejabberd/conf, the run script will ignore the configuration templates.
You may use MySQL as a default database for all module that supports MySQL.
- EJABBERD_CONFIGURE_ODBC: Set this to
trueto enable ODBC plugin - EJABBERD_ODBC_TYPE: Set this to
mysql - EJABBERD_ODBC_SERVER: domain or ip to MySQL Server
- EJABBERD_ODBC_DATABASE: MySQL database name
- EJABBERD_ODBC_USERNAME: MySQL username
- EJABBERD_ODBC_PASSWORD: MySQL password
- EJABBERD_AUTH_METHOD: Set to
sqlto enable storing authentication using MySQL Auth internal implementation.
The ejabberdctl command is in the search path and can be run by:
docker exec CONTAINER ejabberdctl helpdocker exec CONTAINER ejabberdctl register user XMPP_DOMAIN PASSWORDCreate a backupfile with ejabberdctl and copy the file from the container to localhost
docker exec CONTAINER ejabberdctl backup /opt/ejabberd/backup/ejabberd.backup
docker cp CONTAINER:/opt/ejabberd/backup/ejabberd.backup /tmp/ejabberd.backupCopy the backupfile from localhost to the running container and restore with ejabberdctl
docker cp /tmp/ejabberd.backup CONTAINER:/opt/ejabberd/backup/ejabberd.backup
docker exec CONTAINER ejabberdctl restore /opt/ejabberd/backup/ejabberd.backupSet -i and -t option and append live to get an interactive erlang shell:
docker run -i -t -P rroemhild/ejabberd liveYou can terminate the erlang shell with q()..
docker run -i -t rroemhild/ejabberd shelldocker run -i -t rroemhild/ejabberd env- 4560 (XMLRPC)
- 5222 (Client 2 Server)
- 5269 (Server 2 Server)
- 5280 (HTTP admin/websocket/http-bind)
- 5443 (HTTP Upload)
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent