| Line 58: |
Line 58: |
| | config show modSSL > "/root/db_configuration_modSSL_backup_$(date +%Y%m%d_%H%M%S)" | | config show modSSL > "/root/db_configuration_modSSL_backup_$(date +%Y%m%d_%H%M%S)" |
| | | | |
| − | ==Contrib Installation of Dehydrated== | + | ==Installation of Dehydrated letsencrypt contrib== |
| | John Crisp has prepared a contrib that installs the dehydrated script, creates the appropriate configuration files, and integrates with the SME templates system. This is the simplest way to install dehydrated on your SME Server. | | John Crisp has prepared a contrib that installs the dehydrated script, creates the appropriate configuration files, and integrates with the SME templates system. This is the simplest way to install dehydrated on your SME Server. |
| | | | |
| Line 90: |
Line 90: |
| | failure to do this might leave the contribution not working and your certificates not renewed. | | failure to do this might leave the contribution not working and your certificates not renewed. |
| | | | |
| − | ===Configuration===
| + | ==Configuration== |
| | There are several configuration database entries that need to be made in order to set up this contrib. Most of them tell the scripts which hostnames need to be part of your certificate. | | There are several configuration database entries that need to be made in order to set up this contrib. Most of them tell the scripts which hostnames need to be part of your certificate. |
| | | | |
| Line 242: |
Line 242: |
| | signal-event console-save | | signal-event console-save |
| | dehydrated -c -x | | dehydrated -c -x |
| − |
| |
| − | ==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#Adding_Files_and_Directories|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.
| |
| | | | |
| | == Troubleshooting == | | == Troubleshooting == |
| Line 423: |
Line 410: |
| | https://forums.contribs.org/index.php/topic,53147.0.html | | https://forums.contribs.org/index.php/topic,53147.0.html |
| | | | |
| − | ==Advanced Topics== | + | == Advanced Topics == |
| − | ===Obtaining certificates for other servers===
| + | see [[Letsencrypt/Advanced]] |
| − | 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====
| |
| − | {{Note box| This section is not necessary as far as I am aware. You should just be able to set a host with "HostType local" and an InternalIP address as letsencryptSSLcert enabled and then regenerate domains.txt}}
| |
| − | | |
| − | 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/
| |
| | | | |
| | = Bugs = | | = Bugs = |
