[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Savannah-cvs] [230] https: new page about certbot/let's-encrypt setup
|
From: |
assafgordon |
|
Subject: |
[Savannah-cvs] [230] https: new page about certbot/let's-encrypt setup |
|
Date: |
Sat, 24 Sep 2016 04:53:28 +0000 (UTC) |
Revision: 230
http://svn.sv.gnu.org/viewvc/?view=rev&root=administration&revision=230
Author: agn
Date: 2016-09-24 04:53:26 +0000 (Sat, 24 Sep 2016)
Log Message:
-----------
https: new page about certbot/let's-encrypt setup
Modified Paths:
--------------
trunk/sviki/FrontEndDevelopmentSite.mdwn
trunk/sviki/SavannahHosts.mdwn
Added Paths:
-----------
trunk/sviki/https.mdwn
Modified: trunk/sviki/FrontEndDevelopmentSite.mdwn
===================================================================
--- trunk/sviki/FrontEndDevelopmentSite.mdwn 2016-09-23 03:04:54 UTC (rev
229)
+++ trunk/sviki/FrontEndDevelopmentSite.mdwn 2016-09-24 04:53:26 UTC (rev
230)
@@ -215,9 +215,20 @@
If the file is downloaded successfully, certbot's certificate
registration/renwal process should 'just work'.
+See [[https]] for more information about savannah's
+certbot/let's-encrypt certificates setup. See the section "Registering
+additional sub-domains" at the bottom of that page for example of
+adding a certificate for `jsmith.frontend0`.
-FIXME: Explain Bob's non-root certbot setup.
+After registering an SSL certificate for this new subdomain,
+use the following apache configuration statements:
+ <VirtualHost *:443>
+ [... other SSL related settings ...]
+ SSLCertificateFile
/home/certbot/etc/live/jsmith.frontend0.savannah.gnu.org/cert.pem
+ SSLCertificateKeyFile
/home/certbot/etc/live/jsmith.frontend0.savannah.gnu.org/privkey.pem
+ SSLCertificateChainFile
/home/certbot/etc/live/jsmith.frontend0.savannah.gnu.org/chain.pem
+ </VirtualHost>
### Document root
Modified: trunk/sviki/SavannahHosts.mdwn
===================================================================
--- trunk/sviki/SavannahHosts.mdwn 2016-09-23 03:04:54 UTC (rev 229)
+++ trunk/sviki/SavannahHosts.mdwn 2016-09-24 04:53:26 UTC (rev 230)
@@ -422,12 +422,9 @@
[download0.savannah.gnu.org]
address 208.118.235.200
-FIXME: Needs quite a bit more documentation here on setting up certbot
-for Let's Encrypt. See /home/certbot/README for more details there.
-But start with creating a non-root certbot user.
+See [[https]] for details about SSL certificates setup using
+certbot/let's-encrypt on `frontend0`.
- adduser --disabled-password --gecos Certbot certbot
- ...less /home/certbot/README
Host internal0
--------------
@@ -530,18 +527,15 @@
/etc/apache2/sites-available from frontend
-Set up the HTTP SSL certificates. Currently those are traditional ssl
-certificates. Let's Encrypt certificates required newer software than
-we had available on the old frontend. But now it is easy to set up
-the new Let's Encrypt Certbot certificates. I am in the process of
-writing up that documentation. It is complicated by the fact that the
-official EFF client tries to do too much and requires root priviledges
-that I do not want to give it. Therefore I lock it down into a
-non-privileged user. This makes the use of it more involved but it is
-much safer and more secure that way. FIXME: Add Certbot documentation.
+Set up the HTTP SSL certificates. The current ('old') certificates are
+wildcard SSL certificates from GANDI.NET. Copy them as-is:
/etc/ssl/private installed from frontend
+The new SSL certificates (e.g. for `frontend0`) will use certbot/let's-encrypt.
+See [[https]] for details about them.
+
+
Set up munin-node.
apt-get install munin-node
Added: trunk/sviki/https.mdwn
===================================================================
--- trunk/sviki/https.mdwn (rev 0)
+++ trunk/sviki/https.mdwn 2016-09-24 04:53:26 UTC (rev 230)
@@ -0,0 +1,426 @@
+HTTPS Certificates
+===================
+
+This page describes the HTTPS configuration for savannah's
+new servers (e.g. `frontend0`, `vcs0`).
+The current ('old') servers use a wildcard SSL certificate from GANDI.net.
+The new servers use [Let's Encrypt](https://letsencrypt.org) certificates.
+
+Further reading about savannah's server:
+
+* [[SavannahArchitecture]] - overview of the current ('old') setup
+ (i.e. vcs, mgt, frontend, internal, vcs, download).
+* [[SavannahHosts]] - Configuration of the new servers
+ (i.e. mgt0, vcs0, frontend0, internal0, download0).
+
+Further reading about savannah's frontend:
+
+* [[FrontEnd]] - Notes about the current frontend setup (git,cvs).
+* [[FrontEndDevelopmentSite]] - Setting up development sites for savannah.
+
+
+EFF's CertBot
+-------------
+
+[EFF's CertBot](https://certbot.eff.org) is a python-based package that
+registers and renews "Let's Encrypt" certificates (it is the successor of
+`letencrypt-auto` - the old name of the package, before EFF took over its
+maintenance).
+
+Savannah's configuration uses `webroot` method (aka `certonly`),
+in which the webserver (apache2) exposes a specific directory
+over HTTP, certbot writes the authentication files to this directory
+and comminucates with "Let's Encrypt"'s certificate authority
+to register/renew certificates. For details, see
+<https://certbot.eff.org/docs/using.html#webroot>.
+
+Savannah uses a non-standard `certbot` configuration, which allows it
+to operate without requiring `root` access to the server. By default,
+`certbot` requires root access to register/renew certificates (as the
+certificate's private-key need to be securely stored, and accesible
+only by the webserver). Details of this non-standard setup are
+described below.
+
+
+Typical Certbot/webroot setup
+-----------------------------
+
+*NOTE*: Savannah uses a modified setup which does not require running
+`certbot` as root. This section gives a general overview of `certbot
+--webroot` setup (to help understand savannah's customization,
+below).
+
+Install `certbot` by downloading the prebuilt package for your OS here:
+<https://certbot.eff.org/> or by following detailed instructions here
+<https://certbot.eff.org/docs/using.html#getting-certbot>.
+
+
+### Web-server configuration, part 1
+
+Create a directory where certbot will write the authentication files:
+
+ $ sudo mkdir /var/www/certbot
+
+In the apache configuration file, expose this directory with a pre-set URL:
+
+ Alias /.well-known /var/www/certbot/.well-known
+ <Directory "/var/www/certbot/">
+ AllowOverride None
+ Require all granted
+ </Directory>
+
+If using nginx, use the following (savannah does not yet use nginx):
+
+ location /.well-known {
+ root /var/www/certbot/ ;
+ }
+
+Test the setup by create a file and downloading it
+(the `.well-known` subdirectory is needed for testing, otherwise
+it will be automatically created by `certbot` on one the first run):
+
+ $ sudo mkdir /var/www/certbot/.well-known
+ $ sudo touch /var/www/certbot/.well-known/foo
+ $ wget http://frontend0.sv.gnu.org/.well-known/foo
+
+
+
+### First-time domain registration
+
+Run `certbot` for the first time, registaring the required domain names.
+Multiple domains can be specified, and they will be included in the same
+certificate. "Let's Encrypt" does not support wildcard certificates, so
+all needed domains need to be specified.
+The first listed domain will determine the output file names.
+
+ ./certbot-auto certonly \
+ --email address@hidden \
+ --agree-tos \
+ --keep-until-expiring
+ --webroot \
+ --configdir /etc/letsencrypt/ \
+ -w /var/www/certbot/ \
+ -d frontend0.savannah.gnu.org \
+ -d frontend0.savannah.nongnu.org \
+ -d frontend0.sv.gnu.org \
+ -d frontend0.sv.nongnu.org \
+ -d jsmith.frontend0.savannah.gnu.org \
+ -d jsmith.frontend0.savannah.nongnu.org \
+ -d jsmith.frontend0.sv.gnu.org \
+ -d jsmith.frontend0.sv.nongnu.org \
+ ...
+
+If the registration succeeded, the following files and directories
+will be created (these are the certificates and keys):
+
+ /etc/letsencrypt
+ |-- accounts
+ | `-- acme-v01.api.letsencrypt.org
+ | `-- directory
+ | `-- xxxxxxxxxxxxxxxxxxxxxxxxxxx
+ | |-- meta.json
+ | |-- private_key.json
+ | `-- regr.json
+ |-- archive
+ | `-- frontend0.savannah.gnu.org
+ | |-- cert1.pem
+ | |-- chain1.pem
+ | |-- fullchain1.pem
+ | `-- privkey1.pem
+ |-- csr
+ | `-- 0000_csr-certbot.pem
+ |-- keys
+ | `-- 0000_key-certbot.pem
+ |-- live
+ | `-- frontend0.savannah.gnu.org
+ | |-- cert.pem -> ../../archive/frontend0.savannah.gnu.org/cert1.pem
+ | |-- chain.pem ->
../../archive/frontend0.savannah.gnu.org/chain1.pem
+ | |-- fullchain.pem ->
../../archive/frontend0.savannah.gnu.org/fullchain1.pem
+ | `-- privkey.pem ->
../../archive/frontend0.savannah.gnu.org/privkey1.pem
+ `-- renewal
+ `-- frontend0.savannah.gnu.org.conf
+
+
+### Web-server configuration, part 2 (SSL)
+
+The Apache SSL configuration will be:
+
+ <VirtualHost *:443>
+ SSLEngine on
+
+ SSLCertificateFile
/etc/letsencrypt/live/frontend0.savannah.gnu.org/cert.pem
+ SSLCertificateKeyFile
/etc/letsencrypt/live/frontend0.savannah.gnu.org/privkey.pem
+ SSLCertificateChainFile
/etc/letsencrypt/live/frontend0.savannah.gnu.org/chain.pem
+
+ # Many more SSL-specific configuration (ciphers, protocols, etc.)
+ </VirtualHost>
+
+If using nginx, the configuration is:
+
+ server {
+ listen 443 ssl;
+ ssl on;
+ ssl_certificate
/etc/letsencrypt/live/frontend0.savannah.gnu.org/fullchain.pem;
+ ssl_certificate_key
/etc/letsencrypt/live/frontend0.savannah.gnu.org/privkey.pem;
+
+ # Many more SSL-specific configuration (ciphers, protocols, etc.)
+ }
+
+
+Restart the web-server to load the certificates (check server logs to
+ensure loading suceeded).
+
+
+### SSL certificate testing
+
+
+Use `wget` or `curl` to test if the certificates `just works`:
+
+ $ wget -O- https://frontend0.savannah.gnu.org/
+ --2016-09-07 00:27:08-- https://frontend0.savannah.gnu.org/
+ Resolving frontend0.savannah.gnu.org (frontend0.savannah.gnu.org)...
208.118.235.79
+ Connecting to frontend0.savannah.gnu.org
(frontend0.savannah.gnu.org)|208.118.235.79|:443... connected.
+ ...
+
+
+ $ curl https://frontend0.savannah.gnu.org/
+ ...
+
+
+Or use `openssl` to troubleshoot the connection:
+
+ $ openssl s_client -servername frontend0.savannah.gnu.org \
+ -host frontend0.savannah.gnu.org \
+ -port 443 -CApath /etc/ssl/certs -showcerts </dev/null
+ ...lots of details omitted for brevity...
+ Verify return code: 0 (ok)
+
+
+
+### Certificate renewal
+
+"Let's Encrypt"'s certificate expire after 90 days, and must be routinely
+renewed. It is recommended to run the `renew` command once a month (e.g. in
+`/etc/cron.monthly` to avoid service disruptions).
+
+ certbot-auto --no-self-upgrade \
+ --email address@hidden \
+ --agree-tos \
+ renew \
+ --text \
+ --webroot \
+ --config-dir /etc/letsencrypt \
+ -w /var/www/certbot/
+
+If all worked well, the output will resemble:
+
+
-------------------------------------------------------------------------------
+ Processing /etc/letsencrypt/renewal/frontend0.savannah.gnu.org.conf
+
-------------------------------------------------------------------------------
+
+ The following certs are not due for renewal yet:
+ /etc/letsencrypt/live/frontend0.savannah.gnu.org/fullchain.pem (skipped)
+ No renewals were attempted.
+
+
+### Adding subdomains
+
+"Let's Encrypt" certificates do not support wildcard subdomains (e.g.
+`*.frontend.savannah.gnu.org`). Each domain must be explicitly registered.
+
+One method is to register multiple domains in a single certificate (and a
single
+`certbot-auto` invocation) - they will be stored (and visible) in the
+"Certificate Subject Alternative Name" field of the published certificate.
+To add domains, simply add more `-d MY.SUB.DOMAIN.ORG` parameters to the
+`certbot-auto` command. Make sure to add them *last* and leave the name
+of the first domain unchanged, as the name of the first domain (the
+first `-d` parameter) detemintes the output file names in `/etc/letsencrypt`).
+
+Another method is to create a separate certificate file for each subdomain,
+and run `certbot-auto` separately for each domain. Each certificate will
+have a separate subdirectory under `/etc/letsencrypt/live`. (This is the
+method savannah currently uses).
+
+
+
+Savannah's non-root certbot installation
+----------------------------------------
+
+Bob Proulx developed and installed a modfied configuration which
+allows `certbot-auto` to operate as a non-root user, isolated in its
+own directory. This setup is used on `frontend0`.
+
+Create a dedicated non-root user:
+
+ # adduser --disabled-password --gecos Certbot certbot
+
+Create required directories:
+
+ # su -l certbot
+ $ cd /home/certbot
+ $ mkdir -p bin etc www log tmp
+
+Create two fake root programs (to simulate root environment for
+the `certbot-auto` program):
+
+ $ cd /home/certbot/bin
+
+ $ printf '#!/bin/sh\necho "fake apt-get" "$@"\nexit 0\n' > apt-get
+ $ chmod a+x apt-get
+
+ $ printf '#!/bin/sh\nfakeroot env "$@"' > sudo
+ $ chmod a+x sudo
+
+Install the certbot program into `/home/certbot/src`.
+FIXME: Fill-in exact commands.
+
+When `certbot-auto` is run the first time (as the non-root `certbot`
+user), it will try to install some packages automatically (by calling
+`apt-get`). With the fake `apt-get` in place, the names of the
+required packages will be printed to the screen instead of being
+installed. Install the printed packages as root. The list of pacakges
+will be likely similar to this:
+
+ # apt-get install -y --no-install-recommends python python-dev \
+ python-virtualenv gcc dialog libaugeas0 augeas-lenses \
+ libssl-dev libffi-dev ca-certificates
+
+Run `certbot-auto` as `certbot` user with `-d` parameter to register a
+new domain:
+
+ # su -l certbot
+ $ XDG_DATA_HOME=src \
+ certbot-auto --no-self-upgrade \
+ --email address@hidden \
+ --agree-tos \
+ certonly --text --webroot \
+ --config-dir ~/etc \
+ --work-dir ~/tmp \
+ --logs-dir ~/log \
+ -w ~/www \
+ -d frontend0.savannah.gnu.org \
+ -d frontend0.savannah.nongnu.org
+
+FIXME: Bob's examples in `/home/certbot/README` show a slightly more
complicated
+invocation. Validate above command or fix it.
+
+The content of `/home/certbot` should look like this:
+
+ /home/certbot
+ |-- bin
+ | |-- apt-get
+ | |-- certbot-auto
+ | |-- renew-ssl-certificate
+ | |-- renew-ssl-certificate-cron
+ | `-- sudo
+ |
+ |-- etc [*** equivalent to /etc/letsencrypt in the previous section,
***]
+ | [*** certificates and private keys in PEM format are stored here
***]
+ | |-- accounts
+ | |-- archive
+ | |-- csr
+ | |-- keys
+ | |-- live
+ | `-- renewal
+ |
+ |-- log [*** renewal logs will be saved here ***]
+ |
+ |-- src [*** the installed 'certbot-auto' program ***]
+ | `-- letsencrypt
+ | `-- bin
+ | [...]
+ |
+ |-- tmp
+ `-- www
+ `-- .well-known [*** This directory should be exposed by the webserver
***]
+
+
+### Frontend0's apache configuration
+
+The majority of the apache's configurations are in
+`/etc/apache2/sites-available/sv.inc`. However this file does *not*
+contain SSL configuration - as it is included twice in other files
+(once for gnu, once for nongnu).
+
+The file `/etc/apache2/sites-available/vhosts-gnu.org` contains:
+
+ <VirtualHost *:443>
+ SSLEngine on
+
+ SSLProtocol All -SSLv2 -SSLv3
+ SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
+ SSLHonorCipherOrder On
+
+ SSLCertificateFile
/home/certbot/etc/live/frontend0.savannah.gnu.org/cert.pem
+ SSLCertificateKeyFile
/home/certbot/etc/live/frontend0.savannah.gnu.org/privkey.pem
+ SSLCertificateChainFile
/home/certbot/etc/live/frontend0.savannah.gnu.org/chain.pem
+
+ ServerName frontend0.savannah.gnu.org
+
+ Include sites-available/sv.inc
+ </VirtualHost>
+
+The file `/etc/apache2/sites-available/vhosts-nongnu.org` contains a
+configuration similar to the above, with a different `ServerName`
+statement (recall that the multiple domains gnu/nongnu,savannah/sv are
+registered in the same certificate file - so it is used in all these
+virtual hosts).
+
+
+### Manual Renewal
+
+The script `/home/certbot/bin/renew-ssl-certificate` contains:
+
+ #!/bin/sh
+
+ # Conditionally renew the certificate.
+
+ env XDG_DATA_HOME=src certbot-auto --no-self-upgrade --email
address@hidden --agree-tos renew --text --webroot --config-dir ~/etc --work-dir
~/tmp --logs-dir ~/log -w ~/www
+
+
+### Automatic Renewal (cron)
+
+FIXME: document `/home/certbot/bin/renew-ssl-certificate-cron` once
+the setup is stable.
+
+FIXME: is it symlinked in `/etc/cron.monthly` ?
+
+
+### Registering additional sub-domains
+
+Additional subdomains can be used for [[FrontEndDevelopmentSite]].
+
+The current recommendation is to register new subdomains in a new,
+separate certificate file (as opposed to adding more subdomains to the
+existing certficiate).
+
+ # su - certbot
+ $ env XDG_DATA_HOME=src \
+ certbot-auto --no-self-upgrade --email address@hidden \
+ --agree-tos certonly --text \
+ --webroot \
+ --config-dir ~/etc \
+ --work-dir ~/tmp \
+ --logs-dir ~/log \
+ -w ~/www \
+ -d jsmith.frontend0.savannah.gnu.org \
+ -d jsmith.frontend0.savannah.nongnu.org \
+ -d jsmith.frontend0.sv.gnu.org \
+ -d jsmith.frontend0.sv.nongnu.org
+
+The certificate files for the new subdomain will be stored in
+`/home/certbot/etc/live/jsmith.frontend0.savannah.gnu.org`.
+
+The appropriate apache configuration is:
+
+ <VirtualHost *:443>
+ ServerName jsmith.frontend0.savannah.gnu.org
+ ServerAlias jsmith.frontend0.sv.gnu.org
+ ServerAlias jsmith.frontend0.savannah.nongnu.org
+ ServerAlias jsmith.frontend0.sv.nongnu.org
+
+ [... other SSL related settings ...]
+ SSLCertificateFile
/home/certbot/etc/live/jsmith.frontend0.savannah.gnu.org/cert.pem
+ SSLCertificateKeyFile
/home/certbot/etc/live/jsmith.frontend0.savannah.gnu.org/privkey.pem
+ SSLCertificateChainFile
/home/certbot/etc/live/jsmith.frontend0.savannah.gnu.org/chain.pem
+ </VirtualHost>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Savannah-cvs] [230] https: new page about certbot/let's-encrypt setup,
assafgordon <=