Installation

FreeBSD Package#

The recommended way to install xmppd on FreeBSD:

pkg install xmppd

This installs all six binaries, the RC script, and a sample configuration file.

Post-Install Setup#

1. Create the configuration#

cp /usr/local/etc/xmppd/xmppd.conf.sample /usr/local/etc/xmppd/xmppd.conf

2. Set your hostname#

Edit /usr/local/etc/xmppd/xmppd.conf and set the hostname to your XMPP domain:

[server]
hostname = example.com

3. Configure TLS#

You need a valid TLS certificate for your domain. Place the certificate and key:

[tls]
cert = /usr/local/etc/xmppd/server.pem
key = /usr/local/etc/xmppd/server.key

The certificate should cover your hostname and any subdomains used for MUC (e.g., conference.example.com). A wildcard certificate (*.example.com) works well.

4. Create the service user#

pw useradd jabber -d /nonexistent -s /usr/sbin/nologin -c "XMPP Server"

5. Create data directories#

mkdir -p /var/db/xmppd /var/log/xmppd /var/run/xmppd
chown jabber:jabber /var/db/xmppd /var/log/xmppd /var/run/xmppd

6. Enable and start#

sysrc xmppd_enable=YES
service xmppd start

7. Create your first user#

xmppctl adduser alice@example.com

You'll be prompted for a password. The user can now connect with any XMPP client (Conversations, Gajim, Dino, Profanity, etc.).

DNS Records#

For clients to discover your server, set up the following DNS records:

; SRV records for client and server connections
_xmpp-client._tcp.example.com. 86400 IN SRV 0 5 5222 xmpp.example.com.
_xmpp-server._tcp.example.com. 86400 IN SRV 0 5 5269 xmpp.example.com.

; A record for the XMPP host
xmpp.example.com. 86400 IN A 203.0.113.10

; MUC subdomain (same server)
conference.example.com. 86400 IN A 203.0.113.10

DANE/TLSA Records#

xmppd uses DANE for S2S federation authentication. Add a TLSA record for your server's TLS certificate:

; DANE-EE (usage=3), SPKI (selector=1), SHA-256 (matching=1)
_5222._tcp.xmpp.example.com. 86400 IN TLSA 3 1 1 <sha256-hash-of-spki>
_5269._tcp.xmpp.example.com. 86400 IN TLSA 3 1 1 <sha256-hash-of-spki>

Generate the hash from your certificate:

openssl x509 -in server.pem -pubkey -noout | \
  openssl pkey -pubin -outform DER | \
  openssl dgst -sha256 -hex | awk '{print $2}'

Firewall#

Open the following ports:

Jail Deployment#

xmppd works well in a FreeBSD jail. Set ip4=inherit or assign a dedicated IP:

# Example jail.conf entry
xmppd {
    host.hostname = "xmppd.example.com";
    path = "/usr/local/jails/xmppd";
    ip4 = inherit;
    exec.start = "/bin/sh /etc/rc";
    exec.stop = "/bin/sh /etc/rc.shutdown";
    mount.devfs;
}

Install xmppd inside the jail with pkg -j xmppd install xmppd.