prosody: add docs

1 files changed, 93 insertions, 0 deletions

diff --git a/roles/prosody/README.md b/roles/prosody/README.md
new file mode 100644
index 0000000..f9db9ab
--- /dev/null
+++ b/roles/prosody/README.md
@@ -0,0 +1,93 @@
+Prosdy
+======
+
+Description
+-----------
+
+The `prosody` role installs and configures the [Prosody](https://prosody.im/)
+XMPP server.
+
+Modern XMPP features are supported, like
+[client state indication](https://prosody.im/doc/modules/mod_csi),
+[message carbons](https://prosody.im/doc/modules/mod_carbons),
+[message archive management](https://prosody.im/doc/modules/mod_mam), and
+[HTTP file upload](https://modules.prosody.im/mod_http_upload).
+
+Users authenticate against the local FreeIPA domain using
+[mod\_auth\_ldap](https://prosody.im/doc/modules/mod_auth_ldap).
+Rosters are automatically populated with all local users via a
+[script](templates/usr/local/bin/prosody-update-roster.j2).
+
+The Jabber ID for each user is taken from the `jid` attribute of the FreeIPA
+User object.
+
+
+### Certificates
+
+XMPP certificates are a bit unusual. Clients expect a server to present a
+certificate for the _JID domain_, rather than for the FQDN of the XMPP server.
+
+For example, if your JID is `user@example.com` with XMPP server `xmpp.example.com`,
+your XMPP server actually needs a certificate for the bare domain `example.com`!
+
+Unless you run your XMPP server and webserver on the same host, this poses a
+problem for LetsEncrypt certificates.
+
+I didn't want to deal with DNS challenges for just this one use-case, so I made
+the [prosody\_letsencrypt\_proxy](../prosody_letsencrypt_proxy) role to retrieve
+certificates from an existing webserver.
+
+
+Variables
+---------
+
+This role **accepts** the following variables:
+
+Variable                         | Default                    | Description
+---------------------------------|----------------------------|------------
+`prosody_admins`                 |  `[]`                      | JIDs of server admins
+`prosody_vhosts`                 |  `['{{ email_domain }}']`  | XMPP domains to serve
+`prosody_conference_vhosts`      |  `conference.`vhosts       | XMPP conference domains (usually `conference.example.com`)
+`prosody_user`                   |  `s-prosody`               | Prosody FreeIPA user (will be created)
+`prosody_db_name`                |  `prosody`                 | Prosody database name (will be created)
+`prosody_db_host`                | `{{ postgresql_host }}`    | Prosody database host
+`prosody_archive_expires_after`  |  `4w`                      | How long to keep message archives
+`prosody_http_port`              |  5280                      | Local port for HTTP server
+`prosody_http_host`              |  `{{ ansible_fqdn }}`      | Public HTTP hostname
+`prosody_sysaccount_username`    |  `prosody`                 | FreeIPA [sysaccount](https://www.freeipa.org/page/HowTo/LDAP#System_Accounts) uid for LDAP authentication
+`prosody_sysaccount_password`    |                       | FreeIPA [sysaccount](https://www.freeipa.org/page/HowTo/LDAP#System_Accounts) password
+`prosody_ldap_hosts`             | `{{ freeipa_hosts }}`      | FreeIPA LDAP hosts
+`prosody_access_group`           | `role-xmpp-access`         | FreeIPA group for users allowed XMPP access (will be created)
+`prosody_upload_file_size_limit` | 52428800                   | HTTP upload size limit (bytes)
+`prosody_upload_expire_after`    | 604800                     | How long to keep file uploads (seconds)
+`prosody_upload_quota`           | 10737418240                | Per-user upload quota (bytes)
+`prosody_turn_secret`            | `{{ coturn_auth_secret }}` | [TURN server](https://prosody.im/doc/turn) secret
+`prosody_turn_host`              | `{{ coturn_realm }}`       | [TURN server](https://prosody.im/doc/turn) public hostname
+`prosody_turn_port`              | 3478                       | [TURN server](https://prosody.im/doc/turn) port
+
+
+Usage
+-----
+
+Example playbook:
+
+````yaml
+- name: configure prosody
+  hosts: xmpp_servers
+  roles:
+    - role: prosody
+      vars:
+        prosody_admins:
+          - johndoe@example.com
+          - greybeard@example.net
+        prosody_vhosts:
+          - example.com
+          - example.net
+        prosody_http_host: xmpp.example.com
+        prosody_access_group: jabber-users
+        prosody_turn_host: turn.example.com
+        prosody_turn_secret: s3cret
+        prosody_db_host: postgres.ipa.example.com
+        
+
+````