diff options
Diffstat (limited to 'roles/prosody_letsencrypt_proxy/README.md')
-rw-r--r-- | roles/prosody_letsencrypt_proxy/README.md | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/roles/prosody_letsencrypt_proxy/README.md b/roles/prosody_letsencrypt_proxy/README.md new file mode 100644 index 0000000..b7cc234 --- /dev/null +++ b/roles/prosody_letsencrypt_proxy/README.md @@ -0,0 +1,74 @@ +Prosody LetsEncrypt Proxy +========================= + +Description +----------- + +The `prosody_letsencrypt_proxy` role is used to copy certificates from your +webserver to your XMPP server. + +Because XMPP clients require certificates matching the bare JID domain, it's +difficult to acquire LetsEncrypt certificates unless your XMPP and web server +are on the same host. + +This role has two modes: `master` and `slave`. + +The `master` role should be run on your domain's webserver. Certificates for +retrieved from LetsEncrypt via Certbot, and placed in a special `sftp`-accessible +location. + +The `slave` role should be run on your XMPP host. It periodically scrapes the +new certificates from the `master`, and reloads Prosody if necessary. + + +Variables +--------- + +This role **accepts** the following variables: + +Variable | Default | Description +-------------------------|------------------------|------------ +`prosody_le_role` | `slave` | Either `master` or `slave` +`prosody_le_domains` | `{{ prosody_vhosts }}` | XMPP domains +`prosody_le_proxy_host` | | Host to retrieve certificates from +`prosody_le_ssh_privkey` | | SSH private key for SFTP +`prosody_le_ssh_pubkey` | | SSH public key for SFTP + +Usage +----- + +Example playbook: + +````yaml +- name: configure webserver + hosts: www1 + roles: + - role: apache_vhost + apache_server_name: www.example.com + apache_server_aliases: [example.com] + apache_canonical_hostname: www.example.com + apache_document_root: /var/www/www.example.com + apache_letsencrypt: yes + + - role: prosody_letsencrypt_proxy + vars: + prosody_le_role: master + prosdy_le_domains: + - example.com + prosody_le_pubkey: | + -----BEGIN OPENSSH PUBLIC KEY----- + AAAAAAAAetc + +- name: configure prosody + hosts: xmpp_servers + roles: + - role: prosody + vars: + prosody_vhosts: + - example.com + prosody_le_role: slave + prosdy_le_proxy_host: www1 + prosody_ssh_privkey: | + -----BEGIN OPENSSH PRIVATE KEY----- + AAAAAAAAetc +```` |