1# XMPP
2
3Prosody and coturn run as Nomad/Podman tasks. The production account is
4`clover@paperclover.net`; previews use their generated hostname as the account
5domain. Each fresh preview has separate accounts, archives, uploads, certificates,
6and generated secrets. The DNS provider supplies the existing Cloudflare token
7through a protected Nomad input to the certificate task.
8
9The configuration enables MAM history, message carbons, resumable streams, CSI,
10PEP for OMEMO keys, modern bookmarks, private persistent groups with history,
11100 MiB uploads, mobile push extensions, SASL2/FAST, BOSH, WebSocket, and external
12STUN/TURN discovery. Encryption of message contents is a client feature; enable
13OMEMO in the client. Archives and uploads have no automatic expiry, with a 10 GiB
14upload quota. Open account registration is disabled; the administrator can issue
15invitations through XMPP ad-hoc commands.
16
17Native listeners and the UDP relay range have one source in
18[`network.json`](../service/xmpp/network.json). Only one XMPP instance can reserve
19these host ports; stop its Nomad job before launching another on the same host.
20`setup.py` installs a transient firewall service tagged with the preview ID. It
21removes its rules within ten seconds of preview destruction, and on service stop.
22After a host reboot, repeat the staging command to restore these runtime rules.
23Production firewall rules are declared in `nixos/snowglobe.nix`. The DNS provider
24provisions client, direct-TLS client, and federation SRV records pointing at
25`xmpp.paperclover.net`; the website keeps its existing apex address. Router
26forwarding must send the TCP listeners, UDP TURN listeners, and UDP relay range
27to Snow Globe. `public-ports.service` refreshes UPnP mappings on startup and every five
28minutes, discovering the current description URL with a bounded unicast SSDP
29request to the configured gateway on port 1900. Replies and HTTP description
30hosts must match that gateway; discovery failure fails the refresh. Multicast
31SSDP discovery does not work on this host. Production activation uses the normal
32described-main deployment:
33
34```sh
35SNOWGLOBE_DEPLOY_HOST=root@10.0.0.1 SNOWGLOBE_DEPLOY_PORT=22 python3 tools/deploy.py prod
36```
37
38## Client connections and verification
39
40The owner-readable connection file on Clover's Mac is
41`~/.local/share/snowglobe/xmpp.json`. Monal can use the production JID and its
42generated password; the explicit server is `xmpp.paperclover.net`, port `5223`,
43with direct TLS. Client and federation SRV records resolve to that server.
44A preview has its own connection file and account domain; never copy its
45account database into production.
46
47Test client authentication, two-resource carbons, MAM retrieval, resumable
48streams, OMEMO/PEP keys, private group history, uploads, and WebSocket after
49changing the service. Calling also requires authenticated TURN, the configured
50public relay range, and an off-LAN client check. Push discovery alone does not
51prove delivery through an iOS client's push provider. Recheck external
52connectivity after router or forwarding changes.