xmppd uses a single INI-style configuration file. All daemons read this file
via --config (or -c). CLI flags override config file values.
Default location: /usr/local/etc/xmppd/xmppd.conf
[server] — Global Settings#
Settings shared across all daemons.
| Key | Default | Description |
|---|---|---|
hostname |
(required) | XMPP virtual host domain (e.g., example.com) |
bind_address |
0.0.0.0 |
Address to bind listeners on |
c2s_port |
5222 |
STARTTLS client port |
user |
jabber |
Unprivileged user for child processes |
db_path |
/var/db/xmppd |
Storage base directory |
log_file |
/var/log/xmppd/xmppd.log |
Log file (used with --background) |
pidfile |
/var/run/xmppd/xmppd.pid |
PID file path |
The master supervisor creates subdirectories auth/, op/, and archive/
under db_path automatically.
[tls] — TLS Settings#
Certificate and key for STARTTLS on C2S and S2S connections.
| Key | Default | Description |
|---|---|---|
cert |
(required) | Path to PEM certificate file |
key |
(required) | Path to PEM private key file |
Comment out the entire [tls] section to run without TLS (development only).
You can also use --no-tls on the command line.
[core] — Connection Handler#
Settings for xmppd-core, the C2S connection handler.
| Key | Default | Description |
|---|---|---|
workers |
auto |
Worker threads: 1, 4, or auto (CPU count) |
max_sessions |
4096 |
Max simultaneous client connections |
fan_out_batch_size |
32 |
MUC occupants delivered per event loop tick |
Each worker has its own kqueue event loop and SO_REUSEPORT_LB listener. The kernel distributes incoming connections across workers.
Memory cost is approximately 60KB per session. With max_sessions = 4096,
expect ~240MB of memory usage for session buffers alone.
[auth] — Authentication#
Settings for xmppd-auth, the local authentication daemon.
| Key | Default | Description |
|---|---|---|
socket |
/var/run/xmppd/auth.sock |
IPC socket path |
max_per_account |
5 |
Max auth attempts per account per window |
max_per_ip |
20 |
Max auth attempts per IP per window |
window_seconds |
120 |
Rate limiting window duration |
lockout_duration |
300 |
Temporary lockout duration (seconds) |
lockout_threshold |
10 |
Consecutive failures before lockout |
registration |
false |
Enable in-band registration (XEP-0077) |
require_invite |
true |
Require invitation code for registration |
[s2s] — S2S Federation#
Settings for xmppd-s2s, the federation daemon.
| Key | Default | Description |
|---|---|---|
socket |
/var/run/xmppd/s2s.sock |
IPC socket path |
port |
5269 |
S2S listening port |
[muc] — Multi-User Chat#
Settings for the built-in MUC service (XEP-0045).
| Key | Default | Description |
|---|---|---|
host |
conference.{hostname} |
MUC service hostname |
[master] — Supervisor#
Settings for the master supervisor process.
| Key | Default | Description |
|---|---|---|
core_path |
(alongside xmppd) | Path to xmppd-core binary |
auth_path |
(alongside xmppd) | Path to xmppd-auth binary |
s2s_path |
(alongside xmppd) | Path to xmppd-s2s binary |
[oidc] — OpenID Connect (Optional)#
When this section is present, the master spawns xmppd-auth-oidc instead of
xmppd-auth. Users authenticate via OAUTHBEARER or PLAIN (delegated to IdP).
| Key | Default | Description |
|---|---|---|
issuer |
(required) | OIDC issuer URL |
client_id |
(required) | OIDC client ID |
client_secret |
(required) | OIDC client secret |
token_endpoint |
(required) | Token endpoint URL |
jwks_uri |
(required) | JWKS endpoint for JWT verification |
introspection_endpoint |
(optional) | Token introspection endpoint (RFC 7662) |
ca_file |
(optional) | CA certificate for IdP TLS verification |
Complete Example#
[server]
hostname = example.com
user = jabber
db_path = /var/db/xmppd
[tls]
cert = /usr/local/etc/xmppd/server.pem
key = /usr/local/etc/xmppd/server.key
[core]
workers = auto
max_sessions = 4096
[auth]
socket = /var/run/xmppd/auth.sock
[s2s]
port = 5269
[muc]
host = conference.example.com
[master]
core_path = /usr/local/libexec/xmppd/xmppd-core
auth_path = /usr/local/libexec/xmppd/xmppd-auth
s2s_path = /usr/local/libexec/xmppd/xmppd-s2s
Command-Line Flags#
All daemons accept the following flags:
| Flag | Description |
|---|---|
-c, --config |
Path to configuration file |
-b, --background |
Daemonize (master only) |
--no-tls |
Disable TLS (development only) |
--log-file |
Override log file path |