Letsencrypt/Advanced
This page was originally forked from Letsencrypt page to remove what is not related to the contrib. You can find here the original work that led to the contrib and allow a manual installation, and few advanced configurations.
most of this topics where for SME9, and might not be still valid for SME10
Requiring SSL
Whether you used the contrib, or configured dehydrated manually, you'll probably want to configure your server to force secure web connections. For any i-bays, you can do this using the server-manager page, or using a shell command. For the Primary i-bay, you'll need to use the shell command:
db accounts setprop {accountname} SSL enabled
or
db accounts setprop Primary SSL enabled
Backup
Your certificate, private key, and other important information are stored in /etc/dehydrated, which is not included in the standard SME Server backup routines. Make sure to add this directory to your backups. See, e.g., Backup with dar if you're using the workstation backup feature. If using Affa for backup, add
Include=/etc/dehydrated
to the Affa configuration file. When using the Server-manager backup (dar) make sure the leading "/" in /etc/dehydrated is removed when you make your include file. Otherwise parse errors occur.
Advanced Topics
Obtaining certificates for other servers
The dehydrated client can be used to obtain certificates for other servers on your network, if the hostnames resolve (from outside your network) to your SME Server. Here's how to do this using the smeserver-letsencrypt contrib.
Hosts and Domains
You'll need to create two template fragments: one to add your hostname to /etc/dehydrated/domains.txt, and the second to handle the certificate once it's generated. To create the first, do
mkdir -p /etc/e-smith/templates-custom/etc/dehydrated/domains.txt nano -w /etc/e-smith/templates-custom/etc/dehydrated/domains.txt/15Hostname
You can replace "Hostname" in "15Hostname" with something that's descriptive of the host you're obtaining a certificate for. If you want more than one additional certificate, create separate fragments for each one. In the file, just enter the fully-qualified domain name of the system:
hostname.domain.tld
Then Ctrl-X to exit, Y to save.
Hook Script deployment
The second template fragment will be a portion of the hook script, so the dehydrated client knows what to do with this certificate. This must be present, otherwise dehydrated will configure your SME server to use this certificate rather than the certificate for the SME Server.
mkdir -p /etc/e-smith/templates-custom/usr/bin/hook-script.sh/ nano -w 05deploy_cert_hostname
As above, replace "hostname" with something that describes the host that this script will apply to. The numeric portion can be changed, but MUST be less than 10.
At a minimum, this fragment will need to recognize that it's being called for a certificate other than the main server certificate, and exit in order to prevent later portions of the script from installing that certificate as the main server certificate. The minimal form of this fragment would be:
{
use strict;
use warnings;
use esmith::ConfigDB;
my $configDB = esmith::ConfigDB->open_ro or die("can't open Config DB");
my $letsencryptStatus = $configDB->get_prop( 'letsencrypt', 'status' ) || 'disabled';
if ( $letsencryptStatus ne 'disabled' ) {
$OUT .=<<'_EOF';
if [ $1 = "deploy_cert" ] && [ $2 = "hostname.domain.tld" ]; then
echo "$2 certificate renewed" | mail -s "Certificate renewal" admin@yourdomain.com
exit 0
fi
_EOF
}
}
Depending on the characteristics of the other system, though, this script may be able to install the certificate on that system. The following fragment would copy the certificate files to a remote Linux system running Apache for the web server, and reload Apache to get it to begin using the new certificate:
{
use strict;
use warnings;
use esmith::ConfigDB;
my $configDB = esmith::ConfigDB->open_ro or die("can't open Config DB");
my $letsencryptStatus = $configDB->get_prop( 'letsencrypt', 'status' ) || 'disabled';
if ( $letsencryptStatus ne 'disabled' ) {
$OUT .=<<'_EOF';
if [ $1 = "deploy_cert" ] && [ $2 = "hostname.domain.tld" ]; then
KEY=$3
CERT=$4
CHAIN=$6
scp $CERT root@hostname:/etc/pki/tls/certs/pbx.familybrown.org.crt
scp $KEY root@hostname:/etc/pki/tls/private/pbx.familybrown.org.key
scp $CHAIN root@hostname:/etc/pki/tls/certs/server-chain.crt
ssh root@pbx "/sbin/service httpd reload"
echo "$2 certificate renewed" | mail -s "Certificate renewal" admin@domain.tld
exit 0
fi
_EOF
}
}
The following fragment would install the new certificate on a Proxmox VE host:
{
use strict;
use warnings;
use esmith::ConfigDB;
my $configDB = esmith::ConfigDB->open_ro or die("can't open Config DB");
my $letsencryptStatus = $configDB->get_prop( 'letsencrypt', 'status' ) || 'disabled';
if ( $letsencryptStatus ne 'disabled' ) {
$OUT .=<<'_EOF';
if [ $1 = "deploy_cert" ] && [ $2 = "pve.domain.tld" ]; then
KEY=$3
CHAIN=$5
scp $KEY root@pve:/etc/pve/nodes/pve/pveproxy-ssl.key
scp $CHAIN root@pve:/etc/pve/nodes/pve/pveproxy-ssl.pem
ssh root@pve "systemctl restart pveproxy"
echo "$2 certificate renewed" | mail -s "Certificate renewal" admin@domain.tld
exit 0
fi
_EOF
}
}
Once you've created the template fragments, expand the templates and run dehydrated to generate the certificates:
signal-event console-save dehydrated -c
These certificates will be automatically renewed, just like the main server certificate.
Obtaining certificates for a private SME Server
As noted above in the prerequisites section, your SME Server must ordinarily be accessible from the Internet so that the Let's Encrypt servers can validate that you control it. However, if your SME Server is not accessible from the Internet, the smeserver-letsencrypt contrib provides a method that can be used to validate domain control. In order to use this method, the following conditions must be true:
- The hostname of your internal SME Server (example: internal.mydomain.tld) resolves, on the public Internet, to a valid IP address
- The host to which internal.mydomain.tld resolves (example: external.mydomain.tld) has a running web server on port 80
- The root user from internal.mydomain.tld can connect to external.mydomain.tld via SSH without entering a password (i.e., you've set up SSH public key authentication)
This method uses a simple script that's included in the smeserver-letsencrypt contrib, which requires that four database entries be set:
config setprop letsencrypt hookScript enabled config setprop letsencrypt host external.mydomain.tld config setprop letsencrypt user root config setprop letsencrypt path /home/e-smith/files/ibays/Primary/html/.well-known/acme-challenge signal-event console-save
The parts in bold above should be changed to match your situation; the path variable should be the filesystem location that external.mydomain.tld serves as /.well-known/acme-challenge/ . When dehydrated creates the challenge file, it will transfer it via scp to user@host:path/, and then allow the Let's Encrypt server to validate. Once validation is accomplished, the script will remove the challenge file from user@host:path/