Some notes on the configuration of my setup
  - All services accessible from the internet run in jails (all jails reside in ''%%/usr/jails%%'' by default on %%FreeBSD%%)
  - I use [[/LibreSSL]] ([[http://freshports.org/security/libressl-devel|LibreSSL port]]) 
  - I use [[http://www.zsh.org/|The Z Shell]] ([[http://freshports.org/shells/zsh|zsh port]])

Things that don't need to run as ''%%root%%'' will be running as an unprivileged user. I will use the user ''%%_letsencrypt%%'' with group ''%%_letsencrypt%%'' as the unprivileged user that will perform the certificate renewal process. Deployment of the keys and certificates will have to be executed with a privileged user, this guide uses ''%%root%%''.

====== Install Letsencrypt.sh ======

The port is available in the ports tree. Install it using the official pkg repository using

<code>
pkg install letsencrypt.sh
</code>

or alternatively (e.g. when you want to use ZSH) build your own using [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports-poudriere.html|Poudriere]] or any of the other building-from-source options and install it. The port works with either ''%%zsh%%'' or ''%%bash%%''.

This will install the actual script into ''%%/usr/local/bin%%''. Configuration will land in ''%%/usr/local/etc/letsencrypt.sh%%'' as will the keys, certificates and certificate-chains. You should want to check that the configuration directory is not world-writable.

====== Prepare user & directories ======

To make life easier all of the challenges (%%LetsEncrypt%% as well as keybase etc) will be hosted in a shared dir ''%%/usr/local/www/.well-known%%'' on the jail running my Apache server. The %%LetsEncrypt%% bits will land in ''%%/usr/local/etc/letsencrypt.sh%%'' on the host system. There's no requirement to run the interaction with the %%LetsEncrypt%% servers as root, so these will run as a non-privileged user. This unprivileged user will have to write to the ''%%acme-challenge%%'' and the directory that will contain the keys and certificates.

<code bash>
pw groupadd -n _letsencrypt -g 443
pw useradd  -n _letsencrypt -u 443 -g 443 -d /usr/local/etc/letsencrypt.sh -w no -s /nonexistent
chown root:_letsencrypt /usr/local/etc/letsencrypt.sh
chmod 770               /usr/local/etc/letsencrypt.sh
mkdir -p -m 775    /usr/jails/http/usr/local/www/.well-known/acme-challenge
chgrp _letsencrypt /usr/jails/http/usr/local/www/.well-known/acme-challenge
</code>

Adapt the ''%%.well-known/acme-challenge%%'' directory to your situation.

====== Modify Apache configuration ======

The acme validation will ''%%GET%%'' a uniquely named file from ''%%http://<example.org>/.well-known/acme-challenge/%%''

Access to the ''%%.well-known%%'' directory is granted in my main Apache config file ''%%/usr/local/etc/apache24/httpd.conf%%''

<code apache>
<Directory "/usr/local/www/.well-known/">
   Options None
   AllowOverride None
   Require all granted
   Header add Content-Type text/plain
</Directory>
</code>

The Content-Type header was in my configs somewhere, shouldn't hurt.\\ 
If you want to only share the ACME challenges you can suffix ''%%.well-known/%%'' with ''%%acme-challenge/%%''

Now every (non-ssl) Virtual Host that I have gets a on-line addition

<code apache>
Alias /.well-known/ /usr/local/www/.well-known/
</code>

<callout type="warning">
You need to make sure that all (sub-)domains that you want to sign have access to this directory!\\ 
That includes rewrites etc.\\ 
The acme validation is done only using **plain http** and will not honour redirects etc.
</callout>

====== Letsencrypt configuration ======

===== Domains to sign =====

The script requires a list of domain names you want to have a SAN cert for in the following format:

<code>
example.com www.example.com
example.net www.example.net wiki.example.net
</code>

Domains and sub-domains that are listed on the //same line// will result in SAN-certificates ([[https://en.wikipedia.org/wiki/SubjectAltName|Subject-Alternative-Name]]).\\ 
Store this as ''%%/usr/local/etc/letsencrypt.sh/domains.txt%%''

The default configuration file requires some changes, these are stored in ''%%/usr/local/etc/letsencrypt.sh/config.sh%%''

<code bash>
BASEDIR="/usr/local/etc/letsencrypt.sh"
WELLKNOWN="/usr/jails/http/usr/local/www/.well-known/acme-challenge"
alias openssl='/usr/local/bin/openssl'
</code>

To make use of %%LibreSSL%% (or %%OpenSSL%% from ports) you must add the ''%%alias openssl%%'' to the config script.

===== Configure periodic job =====

The ''%%security/letsencrypt.sh%%'' port includes a periodic job that makes automation very simple. To automatically renew certificates, add the following to your ''%%/etc/periodic.conf%%''

<code bash>
weekly_letsencrypt_enable="YES"
weekly_letsencrypt_user="_letsencrypt"
weekly_letsencrypt_deployscript="/usr/local/etc/letsencrypt.sh/deploy.sh"
</code>

====== First run ======

You will probably want to run %%LetsEncrypt%% manually the first time

<code bash>
cd /usr/local/etc/letsencrypt.sh
su -m _letsencrypt -c 'zsh /usr/local/bin/letsencrypt.sh --cron'
</code>

(Replace zsh with bash if that's the shell you have installed)

You will end up with a sub-directory ''%%certs%%'' that contains your domains as directories with the Subject-Alternative-Names certs and the corresponding private keys. The symbolic links are useful for deployment.

<code>
example.com/
   cert-1453573903.csr
   cert-1453573903.pem
   cert.csr -> cert-1453573903.csr
   cert.pem -> cert-1453573903.pem
   chain-1453573903.pem
   chain.pem -> chain-1453573903.pem
   fullchain-1453573903.pem
   fullchain.pem -> fullchain-1453573903.pem
   privkey-1453573903.pem
   privkey.pem -> privkey-1453573903.pem
example.net/
   cert-1453576309.csr
   cert-1453576309.pem
   cert.csr -> cert-1453576309.csr
   cert.pem -> cert-1453576309.pem
   chain-1453576309.pem
   chain.pem -> chain-1453576309.pem
   fullchain-1453576309.pem
   fullchain.pem -> fullchain-1453576309.pem
   privkey-1453576309.pem
   privkey.pem -> privkey-1453576309.pem
</code>

====== Deploy new certs ======

We've run the certificate request process as a restricted user but you'll need to run the deploy script as ''%%root%%''.

Here you'll probably need to get creative with scripting. In the host environment, your now have

<code bash>
/usr/local/etc/letsencrypt.sh/certs/example.net/privkey.pem
/usr/local/etc/letsencrypt.sh/certs/example.net/fullchain.pem
</code>

NB: %%%%''%%These are symlinks!!!%%''%%%%\\ 

===== Example (jailed) applications =====

Your Apache server may (should?) run in the ''%%http%%'' jail and you've setup an Apache Virtual Host with

<code apache>
SSLCertificateFile /etc/ssl/certs/example.net.pem
SSLCertificateKeyFile /etc/ssl/priv/example.net.pem
</code>

and your %%OpenSMTPd%% mailserver for example.net in the ''%%mail%%'' jail

<code>
pki example.net certificate "/etc/ssl/certs/example.net.pem"
pki example.net key         "/etc/ssl/priv/example.net.pem"
listen on $lan_addr port 587 tls-require \
       pki example.net hostname example.net auth
</code>

Seen from the host environment your certificates actually need to end up in

<code>
/usr/jails/```http```/etc/ssl
/usr/jails/```mail```/etc/ssl
</code>

===== Example deployment script =====

You could use the following script to deploy new certs

<code bash>
#!/bin/sh
domain="example.net"
letsencryptdir="/usr/local/etc/letsencrypt.sh"
targets="mail http"
for jail in ${targets}; do
  targetdir="/usr/jails/${jail}/etc/ssl"
  # Check if the certificate has changed
  [ -z "`diff -rq ${letsencryptdir}/certs/${domain}/fullchain.pem ${targetdir}/certs/${domain}.pem`" ] && continue
  cp -L "${letsencryptdir}/certs/${domain}/privkey.pem"   "${targetdir}/priv/${domain}.pem"
  cp -L "${letsencryptdir}/certs/${domain}/fullchain.pem" "${targetdir}/certs/${domain}.pem"
  chmod 400 "${targetdir}/priv/${domain}.pem"
  chmod 644 "${targetdir}/certs/${domain}.pem"
  # Restart/-load relevant services
  [ "${jail}" = "http" ] && jexec ${jail} service apache24 restart
  [ "${jail}" = "mail" ] && jexec ${jail} service smtpd    restart
done
# Clean up old keys and certs
/usr/local/bin/letsencrypt.sh --cleanup
</code>

Store this as ''%%/usr/local/etc/letsencrypt.sh/deploy.sh%%'' and make sure the execute bit is set.\\ 
**NB:** Some applications want a private key, certificate and separate chain instead. If this is the case you'll need to copy ''%%cert.pem%%'' and ''%%chain.pem%%'' to the appropriate location in stead.