Requesting a certificate for foo.mit.edu:
=========================================

1. Run as pony@scripts:
     ~/Scripts/turbogears/ScriptsPony/send_mitcert_request.py LOCKER HOSTNAME [HOSTNAME...]
   (You may optionally omit the ‘.mit.edu’ suffix.)

   The rest happens automatically:

   send_mitcert_requests.py generates a CSR (with the first HOSTNAME
   as subject and all HOSTNAMEs as subjectAltNames) and mails it to
   mitcert as scripts-tls@mit.edu.  Replies come back through pony’s
   procmailrc to handle_cert_mail.py, which extracts the certificate
   download URL, downloads the certificate, does some validation, and
   adds it to LDAP.

   An hourly (hh:38) cron job running as scripts@scripts runs sudo
   /etc/httpd/export-scripts-certs on all servers, which updates the
   certificate configuration in /var/lib/scripts-certs from LDAP and
   reloads Apache if necessary.


Requesting a certificate for other hostnames:
=============================================

1. Run as pony@scripts:
     /usr/bin/sudo /etc/pki/tls/gencsr-pony LOCKER HOSTNAME [HOSTNAME...]
   This generates a CSR (with the first HOSTNAME as subject and all
   HOSTNAMEs as subjectAltNames) and prints it to stdout.

2. Use the CSR to get a certificate with a lifetime of at least 1
   year.

3. Feed the entire PEM-formatted certificate chain to:
     scripts-locker/sbin/vhostcert import < chain.pem
   This orders the chain correctly, removes any self-signed root, and
   outputs to stdout a space-separated string of base64 blobs suitable
   for importing into LDAP.

4. Add two attributes to the corresponding scriptsVhost record in
   LDAP:
     scriptsVhostCertificateKeyFile: scripts-2048.key
     scriptsVhostCertificate: MIIFqDCC...9IhlCgR0 MIIF+TCC...JKZWCYwk MIIFdzCC...xyHNwu8=

   The hourly cron job described above handles the rest.

TODO: Shiny web interface.

Requesting a cert for infrastructure hostnames:
===============================================

That is: scripts.mit.edu, scripts-cert.mit.edu, *.scripts.mit.edu.

These certs live in /etc/pki/tls/certs/. Each cert has a single DNS name --
scripts.mit.edu, scripts-cert.mit.edu, *.scripts.mit.edu.

1. As root@scripts, run ./req-scripts-infra-certs.sh in /etc/pki/tls/certs to
   generate the CSRs.

2. Email the CSRs to mitcert@

3. Wait for mitcert to issue the certs. You should get a replies like
   "Enrollment Successful - Your SSL certificate for scripts.mit.edu is ready".
   Download the "Certificate (w/ issuer after), PEM encoded" (format=pemia)
   files, saving them over the various {star.scripts,scripts,scripts-cert}.pem
   files. `git diff` should show the first cert in the file being updated, but
   not the later ones (the CA chain). Commit the certs.

4. On each server, check that `/srv/scripts_config/` is generally up to date.
   Then do `git pull --ff-only` or similar to pull the new certs, and then
   `apachectl graceful` to load them.
    - You should see the per-realserver nagios checks (eg,
      nagios.shining-armor.HTTPS) clear as you reload Apache on each server.
    - You can also check that the new certs were loaded with commands like
      `curl -v https://scripts-cert.mit.edu --connect-to
      scripts-cert.mit.edu:443:s-a.mit.edu:443 > /dev/null`

5. For the F30 servers, there's probably an Ansible way to do it. But the
   Ansible setup is currently a bit broken, so here's a workaround. Place the
   pem files in the "ansible-realserver" branch in "ansible/roles/real-httpd/files/certs/".
   On each F30 server (as root) do something like:
     su - scripts-build bash -c "cd /srv/repository && git pull --ff-only" 
     cp /srv/repository/ansible/roles/real-httpd/files/certs/*.pem /etc/pki/tls/certs/
     apachectl graceful

Renewing users' *.mit.edu certs:
================================

- Cert renewal is done automatically every Tuesday.
- To renew certs manually, as pony on F20 run:
  ~/Scripts/turbogears/ScriptsPony/renew_mit_certs.py
    - That should automatically send renewal requests for each cert on our
      platform that's within 14 days of expiry.
    - You might get lines that look like "failed to send CSR for sql.mit.edu,
      sql, 18.181.0.52:  sql.mit.edu" -- the bit after the colon is an
      exception, and if it's a bare hostname it probably means that said
      hostname no longer points at us.