diff options
Diffstat (limited to 'content/ejabberd.md')
| -rw-r--r-- | content/ejabberd.md | 140 |
1 files changed, 84 insertions, 56 deletions
diff --git a/content/ejabberd.md b/content/ejabberd.md index 76e6678..b8579cd 100644 --- a/content/ejabberd.md +++ b/content/ejabberd.md @@ -6,34 +6,45 @@ tags: ['service'] short_desc: "A chat server based on XMPP." --- -[Ejabberd](https://ejabberd.im) is a server for the XMPP protocol -written in Erlang. It\'s easier to configure and setup than -[Prosody](/prosody) due to having most of its modules built-in and -pre-configured by default. +[Ejabberd](https://ejabberd.im) is a server for the XMPP protocol written in Erlang. It's more scalable, and easier to setup than [Prosody](/prosody) due to having most of its modules built-in and pre-configured by default. ## Prerequisites ### Subdomains -Ejabberd presumes that you have already created all the **required and -optional subdomains** for its operation prior to running it. +Ejabberd presumes that you have already created all the **required and optional subdomains** for its operation prior to running it. -Depending on the usecase, you may need any or all of the following -domains for XMPP functionality: +Depending on the usecase, you may need any or all of the following domains for XMPP functionality: - **example.org** - Your XMPP hostname - **conference.example.org** - For Multi User Chats (MUCs) - **upload.example.org** - For file upload support - **proxy.example.org** - For SOCKS5 proxy support -- **pubsub.example.org** - For publish-subscribe support +- **pubsub.example.org** - For publish-subscribe support (A fancier RSS) This guide will assume **all these subdomains** have been created. +#### Custom Subdomains + +If you wish to customize any of these domains, edit `/etc/ejabberd.yml` and under every appropriate module that needs a subdomain, add the following setting: +```yml +mod_muc: + host: {{<hl>}}muc.example.org{{</hl>}} +``` + ## Installation -Ejabberd is available in the Debian repositories: +To get the latest version of ejabberd, you need to first setup the ejabberd apt repositories: ```sh +curl -o /etc/apt/sources.list.d/ejabberd.list https://repo.process-one.net/ejabberd.list +curl -o /etc/apt/trusted.gpg.d/ejabberd.gpg https://repo.process-one.net/ejabberd.gpg +``` + +Then update the repositories and install the `ejabberd` package: + +```sh +apt update apt install ejabberd ``` @@ -68,15 +79,20 @@ for both the fullchain cert and private key. Using certbot, this process can be easily automated with these commands: -```sh -$DOMAIN={{<hl>}}subdomain.example.org{{</hl>}} -certbot --nginx -d $DOMAIN certonly; mkdir -p /etc/ejabberd/certs/$DOMAIN -cp /etc/letsencrypt/live/$DOMAIN/fullchain.pem /etc/ejabberd/certs/$DOMAIN -cp /etc/letsencrypt/live/$DOMAIN/privkey.pem /etc/ejabberd/certs/$DOMAIN -``` +```bash +DOMAIN={{<hl>}}example.org{{</hl>}} -This should be ran with your XMPP hostname **(example.org)** and -repeated for all your desired subdomains. +# Set the domain names you want here +declare -a subdomains=("" "conference." "proxy." "pubsub." "upload.") + +for i in "${subdomains[@]}"; do + certbot --nginx -d $i$DOMAIN certonly + mkdir -p /etc/ejabberd/certs/$i$DOMAIN + cp /etc/letsencrypt/live/$i$DOMAIN/fullchain.pem /etc/ejabberd/certs/$i$DOMAIN + cp /etc/letsencrypt/live/$i$DOMAIN/privkey.pem /etc/ejabberd/certs/$i$DOMAIN +done +``` +*Note: Just like with Prosody, you might want to write this script to a file and setup a [cronjob](/cron) to run it periodically. This should help prevent your certificates from expiring.* Make sure all the certificates are readable by the `ejabberd` user: ```sh @@ -105,11 +121,29 @@ acl: This would make **admin@example.org** the user with administrator privileges. +### File Uploads + +To ensure full compliance with XMPP standards, add the following configuration to `mod_http_upload`: + +```yaml +mod_http_upload: + put_url: https://@HOST@:5443/upload + docroot: {{<hl>}}/var/www/upload{{</hl>}} + custom_headers: + "Access-Control-Allow-Origin": "https://@HOST@" + "Access-Control-Allow-Methods": "GET,HEAD,PUT,OPTIONS" + "Access-Control-Allow-Headers": "Content-Type" +``` + +Make sure to create and give the `ejabberd` user ownership of `/var/www/upload` or any other directory you choose to use for file uploads: + +```sh +chown -R ejabberd:ejabberd /var/www/upload +``` + ### Message Archives -The ejabberd server supports keeping archives of messages through its -`mod_mam` module. This can be enabled by uncommenting the following -lines: +The ejabberd server supports keeping archives of messages through its `mod_mam` module. This can be enabled by uncommenting the following lines: ```yml mod_mam: @@ -121,8 +155,7 @@ mod_mam: ### Why use a database? -In the `mod_mam` section of the ejabberd config file, the following -message is in comments: +We can find the following comment in the `mod_mam` section of `/etc/ejabberd.yml`: ```yml mod_mam: @@ -132,14 +165,7 @@ mod_mam: ## db_type: sql ``` -As these comments imply, an **SQL backend** is strongly recommended if -you wish to use your ejabberd server for anything more than just -testing. Ejabberd supports **MySQL, SQLite** and **PostgreSQL.** - -While all of those are suitable choices, the best database system to use -is PostgreSQL. It\'s the same database backend used by -[PeerTube](/peertube) and [Matrix](/matrix), making it the most -convenient option if you\'re already running those too. +As these comments imply, an **SQL backend** is strongly recommended if you wish to use your ejabberd server for anything more than just testing. Ejabberd supports **MySQL, SQLite** and **PostgreSQL.** For the purpose of efficiency, this guide will use **PostgresSQL** because other server software like [Matrix](/matrix) and [PeerTube](/peertube) support it. ### Installing PostgreSQL @@ -171,8 +197,7 @@ su -c "psql -c 'CREATE DATABASE ejabberd OWNER ejabberd;'" postgres ### Importing Database Scheme -Ejabberd doesn\'t create the database scheme by default; It has to be -imported into the database before use. +Ejabberd does **not** create the database scheme by default; It has to be imported into the database before use. ```sh su -c "curl -s https://raw.githubusercontent.com/processone/ejabberd/master/sql/pg.sql | psql ejabberd" postgres @@ -185,17 +210,16 @@ Finally, add the following configuration to `ejabberd.yml`: ```yml sql_type: pgsql sql_server: "localhost" -sql_database: "ejabberd" -sql_username: "ejabberd" -sql_password: "psql_password" +sql_database: "{{<hl>}}ejabberd{{</hl>}}" +sql_username: "{{<hl>}}ejabberd{{</hl>}}" +sql_password: "{{<hl>}}psql_password{{</hl>}}" ``` -Once you\'ve ensured your database name, username and password are all -correct, enable SQL storage for `mod_mam`: +Once you've ensured your database name, username and password are all correct, enable SQL storage for `mod_mam`: ```yml mod_mam: - ## (Other parameters) + ## (Other parameters above) db_type: sql ``` @@ -209,8 +233,7 @@ To begin using ejabberd, firstly start the ejabberd daemon: systemctl restart ejabberd ``` -Then, using `ejabberdctl` as the ejabberd user, register the admin user -which is set in `ejabberd.yml`: +Then, using `ejabberdctl` as the ejabberd user, register the admin user which is set in `ejabberd.yml`: ```sh su -c "ejabberdctl register {{<hl>}}admin example.org password{{</hl>}}" ejabberd @@ -220,25 +243,24 @@ This will create the user **admin@example.org.** ### Using the Web Interface -By default, ejabberd has a web interface accessible from -**http://example.org:5280/admin**. When accessing this interface, you -will be prompted for the admin credentials: +By default, ejabberd has a web interface accessible from **http://example.org:5280/admin**. When accessing this interface, you will be prompted for the admin credentials: -{{< img src="/pix/ejabberd-login.jpg" >}} +{{< img src="/pix/ejabberd-login.webp" >}} After signing in with the admin credentials, you will be able to manage your ejabberd server from this web interface: -{{< img src="/pix/ejabberd-admin.jpg" >}} +{{< img src="/pix/ejabberd-admin.webp" >}} ## TURN & STUN for Calls -Ejabberd supports the **TURN** and **STUN** protocols to allow internet -users behind NATs to perform voice and video calls with other XMPP -users. +Ejabberd supports the **TURN** and **STUN** protocols to allow internet users behind NATs to perform voice and video calls with other XMPP users. **This is enabled by default using [ejabberd_stun](https://docs.ejabberd.im/admin/configuration/listen#ejabberd-stun-1).** + +**However,** if you plan on running ejabberd alongside **other applications** that require TURN and STUN, such as Matrix, then you'll have to setup your own external TURN server using Coturn. -Firstly, setup a TURN and STUN server with [Coturn,](/coturn) using -an **authentication secret.** +### Setup with Coturn and `mod_stun_disco` + +Firstly, setup a TURN and STUN server with [Coturn,](/coturn) using an **authentication secret.** Then, edit `mod_stun_disco` to contain the appropriate information for your turnserver: @@ -255,11 +277,17 @@ your turnserver: type: turn ``` -And with that, you\'ve successfully setup your ejabberd XMPP server! +## Further Configuration + +For a deeper look into all the modules and options, have a look at the following ejabberd documentation: +- Ejabberd's [Listen Modules](https://docs.ejabberd.im/admin/configuration/listen/) and [Listen Options](https://docs.ejabberd.im/admin/configuration/listen-options/) +- Ejabberd's [Top-Level Options](https://docs.ejabberd.im/admin/configuration/toplevel/) +- Ejabberd's [Modules' Options](https://docs.ejabberd.im/admin/configuration/modules/) ------------------------------------------------------------------------- +*And with that, you've successfully setup your ejabberd XMPP server!* -*Written by [Denshi.](https://denshi.org) +--- -Donate Monero at 48dnPpGgo8WernVJp5VhvhaX3u9e46NujdYA44u8zuMdETNC5jXiA9S7JoYMM6qRt1ZcKpt1J3RZ3JPuMyXetmbHH7Mnc9C -[\[QR\]](https://denshi.org/images/xmr.png)* +Written by [Denshi.](https://denshi.org) +Donate Monero at: +`48dnPpGgo8WernVJp5VhvhaX3u9e46NujdYA44u8zuMdETNC5jXiA9S7JoYMM6qRt1ZcKpt1J3RZ3JPuMyXetmbHH7Mnc9C` |