Merge pull request #586 from dkerr64/ssh-deploy

Ssh deploy

deploy/README.md

@@ -31,7 +31,146 @@ acme.sh --deploy -d ftp.example.com --deploy-hook kong
 
 ## 3. Deploy the cert to remote server through SSH access
 
-(TODO)
+The ssh deploy plugin allows you to deploy certificates to a remote host
+using SSH command to connect to the remote server.  The ssh plugin is invoked
+with the following command...
+
+```sh
+acme.sh --deploy -d example.com --deploy-hook ssh
+```
+Prior to running this for the first time you must tell the plugin where
+and how to deploy the certificates.  This is done by exporting the following
+environment variables.  This is not required for subsequent runs as the
+values are stored by acme.sh in the domain configuration files.
+
+Required...
+```
+export DEPLOY_SSH_USER=username
+```
+Optional...
+```
+export DEPLOY_SSH_CMD=custom ssh command
+export DEPLOY_SSH_SERVER=url or ip address of remote host
+export DEPLOY_SSH_KEYFILE=filename for private key
+export DEPLOY_SSH_CERTFILE=filename for certificate file
+export DEPLOY_SSH_CAFILE=filename for intermediate CA file
+export DEPLOY_SSH_FULLCHAIN=filename for fullchain file
+export DEPLOY_SSH_REMOTE_CMD=command to execute on remote host
+export DEPLOY_SSH_BACKUP=yes or no
+```
+
+**DEPLOY_SSH_USER**
+Username at the remote host that SSH will login with. Note that
+SSH must be able to login to remote host without a password... SSH Keys
+must have been exchanged with the remote host. Validate and test that you
+can login to USER@URL from the host running acme.sh before using this script.
+
+The USER@URL at the remote server must also have has permissions to write to
+the target location of the certificate files and to execute any commands
+(e.g. to stop/start services).
+
+**DEPLOY_SSH_CMD**
+You can customize the ssh command used to connect to the remote host. For example
+if you need to connect to a specific port at the remote server you can set this
+to, for example, "ssh -p 22" or to use `sshpass` to provide password inline
+instead of exchanging ssh keys (this is not recommended, using keys is
+more secure).
+
+**DEPLOY_SSH_SERVER**
+URL or IP Address of the remote server.  If not provided then the domain
+name provided on the acme.sh --deploy command line is used.
+
+**DEPLOY_SSH_KEYFILE**
+Target filename for the private key issued by LetsEncrypt.
+
+**DEPLOY_SSH_CERTFILE**
+Target filename for the certificate issued by LetsEncrypt.
+If this is the same as the previous filename (for keyfile) then it is
+appended to the same file.
+
+**DEPLOY_SSH_CAFILE**
+Target filename for the CA intermediate certificate issued by LetsEncrypt.
+If this is the same as a previous filename (for keyfile or certfile) then
+it is appended to the same file.
+
+**DEPLOY_SSH_FULLCHAIN**
+Target filename for the fullchain certificate issued by LetsEncrypt.
+If this is the same as a previous filename (for keyfile, certfile or
+cafile) then it is appended to the same file.
+
+**DEPLOY_SSH_REMOTE_CMD**
+Command to execute on the remote server after copying any certificates.  This
+could be any additional command required for example to stop and restart
+the service.
+
+**DEPLOY_SSH_BACKUP**
+Before writing a certificate file to the remote server the existing
+certificate will be copied to a backup directory on the remote server.
+These are placed in a hidden directory in the home directory of the SSH
+user
+```sh
+~/.acme_ssh_deploy/[domain name]-backup-[timestamp]
+```
+Any backups older than 180 days will be deleted when new certificates
+are deployed.  This defaults to "yes" set to "no" to disable backup.
+
+###Eamples using SSH deploy
+The following example illustrates deploying certifcates to a QNAP NAS
+(tested with QTS version 4.2.3)
+
+```sh
+export DEPLOY_SSH_USER="admin"
+export DEPLOY_SSH_KEYFILE="/etc/stunnel/stunnel.pem"
+export DEPLOY_SSH_CERTFILE="/etc/stunnel/stunnel.pem"
+export DEPLOY_SSH_CAFILE="/etc/stunnel/uca.pem"
+export DEPLOY_SSH_REMOTE_CMD="/etc/init.d/stunnel.sh restart"
+
+acme.sh --deploy -d qnap.example.com --deploy-hook ssh
+```
+Note how in this example both the private key and certificate point to
+the same file.  This will result in the certificate being appended
+to the same file as the private key... a common requirement of several
+services.
+
+The next example illustates deploying certificates to a Unifi
+Contolller (tested with version 5.4.11).
+
+```sh
+export DEPLOY_SSH_USER="root"
+export DEPLOY_SSH_KEYFILE="/var/lib/unifi/unifi.example.com.key"
+export DEPLOY_SSH_FULLCHAIN="/var/lib/unifi/unifi.example.com.cer"
+export DEPLOY_SSH_REMOTE_CMD="openssl pkcs12 -export \
+   -inkey /var/lib/unifi/unifi.example.com.key \
+   -in /var/lib/unifi/unifi.example.com.cer \
+   -out /var/lib/unifi/unifi.example.com.p12 \
+   -name ubnt -password pass:temppass \
+ && keytool -importkeystore -deststorepass aircontrolenterprise \
+   -destkeypass aircontrolenterprise \
+   -destkeystore /var/lib/unifi/keystore \
+   -srckeystore /var/lib/unifi/unifi.example.com.p12 \
+   -srcstoretype PKCS12 -srcstorepass temppass -alias ubnt -noprompt \
+ && service unifi restart"
+
+acme.sh --deploy -d unifi.example.com --deploy-hook ssh
+```
+In this exmple we execute several commands on the remote host
+after the certificate files have been copied... to generate a pkcs12 file
+compatible with Unifi, to import it into the Unifi keystore and then finaly
+to restart the service.
+
+Note also that once the certificate is imported
+into the keystore the individual certificate files are no longer
+required. We could if we desired delete those files immediately. If we
+do that then we should disable backup at the remote host (as there are
+no files to backup -- they were erased during deployment). For example...
+```sh
+export DEPLOY_SSH_BACKUP=no
+# modify the end of the remote command...
+&& rm /var/lib/unifi/unifi.example.com.key \
+      /var/lib/unifi/unifi.example.com.cer \
+      /var/lib/unifi/unifi.example.com.p12 \
+&& service unifi restart
+```
 
 ## 4. Deploy the cert to local vsftpd server
 

deploy/ssh.sh

@@ -0,0 +1,205 @@
+#!/usr/bin/env sh
+
+# Script to deploy certificates to remote server by SSH
+# Note that SSH must be able to login to remote host without a password...
+# SSH Keys must have been exchanged with the remote host.  Validate and
+# test that you can login to USER@SERVER from the host running acme.sh before
+# using this script.
+#
+# The following variables exported from environment will be used.
+# If not set then values previously saved in domain.conf file are used.
+#
+# Only a username is required.  All others are optional.
+#
+# The following examples are for QNAP NAS running QTS 4.2 
+# export DEPLOY_SSH_CMD=""  # defaults to ssh
+# export DEPLOY_SSH_USER="admin"  # required
+# export DEPLOY_SSH_SERVER="qnap"  # defaults to domain name
+# export DEPLOY_SSH_KEYFILE="/etc/stunnel/stunnel.pem"
+# export DEPLOY_SSH_CERTFILE="/etc/stunnel/stunnel.pem"
+# export DEPLOY_SSH_CAFILE="/etc/stunnel/uca.pem"
+# export DEPLOY_SSH_FULLCHAIN=""
+# export DEPLOY_SSH_REMOTE_CMD="/etc/init.d/stunnel.sh restart"
+# export DEPLOY_SSH_BACKUP=""  # yes or no, default to yes
+#
+########  Public functions #####################
+
+#domain keyfile certfile cafile fullchain
+ssh_deploy() {
+  _cdomain="$1"
+  _ckey="$2"
+  _ccert="$3"
+  _cca="$4"
+  _cfullchain="$5"
+  _cmdstr=""
+  _homedir='~'
+  _backupprefix="$_homedir/.acme_ssh_deploy/$_cdomain-backup"
+  _backupdir="$_backupprefix-$(_utc_date | tr ' ' '-')"
+
+  if [ -f "$DOMAIN_CONF" ]; then
+    # shellcheck disable=SC1090
+    . "$DOMAIN_CONF"
+  fi
+
+  _debug _cdomain "$_cdomain"
+  _debug _ckey "$_ckey"
+  _debug _ccert "$_ccert"
+  _debug _cca "$_cca"
+  _debug _cfullchain "$_cfullchain"
+
+  # USER is required to login by SSH to remote host.
+  if [ -z "$DEPLOY_SSH_USER" ]; then
+    if [ -z "$Le_Deploy_ssh_user" ]; then
+      _err "DEPLOY_SSH_USER not defined."
+      return 1
+    fi
+  else
+    Le_Deploy_ssh_user="$DEPLOY_SSH_USER"
+    _savedomainconf Le_Deploy_ssh_user "$Le_Deploy_ssh_user"
+  fi
+
+  # SERVER is optional. If not provided then use _cdomain
+  if [ -n "$DEPLOY_SSH_SERVER" ]; then
+    Le_Deploy_ssh_server="$DEPLOY_SSH_SERVER"
+    _savedomainconf Le_Deploy_ssh_server "$Le_Deploy_ssh_server"
+  elif [ -z "$Le_Deploy_ssh_server" ]; then
+    Le_Deploy_ssh_server="$_cdomain"
+  fi
+
+  # CMD is optional. If not provided then use ssh
+  if [ -n "$DEPLOY_SSH_CMD" ]; then
+    Le_Deploy_ssh_cmd="$DEPLOY_SSH_CMD"
+    _savedomainconf Le_Deploy_ssh_cmd "$Le_Deploy_ssh_cmd"
+  elif [ -z "$Le_Deploy_ssh_cmd" ]; then
+    Le_Deploy_ssh_cmd="ssh"
+  fi
+
+  # BACKUP is optional. If not provided then default to yes
+  if [ "$DEPLOY_SSH_BACKUP" = "no" ]; then
+    Le_Deploy_ssh_backup="no"
+  elif [ -z "$Le_Deploy_ssh_backup" ]; then
+    Le_Deploy_ssh_backup="yes"
+  fi
+  _savedomainconf Le_Deploy_ssh_backup "$Le_Deploy_ssh_backup"
+
+  _info "Deploy certificates to remote server $Le_Deploy_ssh_user@$Le_Deploy_ssh_server"
+
+  # KEYFILE is optional.
+  # If provided then private key will be copied to provided filename.
+  if [ -n "$DEPLOY_SSH_KEYFILE" ]; then
+    Le_Deploy_ssh_keyfile="$DEPLOY_SSH_KEYFILE"
+    _savedomainconf Le_Deploy_ssh_keyfile "$Le_Deploy_ssh_keyfile"
+  fi
+  if [ -n "$Le_Deploy_ssh_keyfile" ]; then
+    if [ "$Le_Deploy_ssh_backup" = "yes" ]; then
+      # backup file we are about to overwrite.
+      _cmdstr="$_cmdstr cp $Le_Deploy_ssh_keyfile $_backupdir >/dev/null;"
+    fi
+    # copy new certificate into file.
+    _cmdstr="$_cmdstr echo \"$(cat "$_ckey")\" > $Le_Deploy_ssh_keyfile;"
+    _info "will copy private key to remote file $Le_Deploy_ssh_keyfile"
+  fi
+
+  # CERTFILE is optional.
+  # If provided then private key will be copied or appended to provided filename.
+  if [ -n "$DEPLOY_SSH_CERTFILE" ]; then
+    Le_Deploy_ssh_certfile="$DEPLOY_SSH_CERTFILE"
+    _savedomainconf Le_Deploy_ssh_certfile "$Le_Deploy_ssh_certfile"
+  fi
+  if [ -n "$Le_Deploy_ssh_certfile" ]; then
+    _pipe=">"
+    if [ "$Le_Deploy_ssh_certfile" = "$Le_Deploy_ssh_keyfile" ]; then
+      # if filename is same as previous file then append.
+      _pipe=">>"
+    elif [ "$Le_Deploy_ssh_backup" = "yes" ]; then
+      # backup file we are about to overwrite.
+      _cmdstr="$_cmdstr cp $Le_Deploy_ssh_certfile $_backupdir >/dev/null;"
+    fi
+    # copy new certificate into file.
+    _cmdstr="$_cmdstr echo \"$(cat "$_ccert")\" $_pipe $Le_Deploy_ssh_certfile;"
+    _info "will copy certificate to remote file $Le_Deploy_ssh_certfile"
+  fi
+
+  # CAFILE is optional.
+  # If provided then CA intermediate certificate will be copied or appended to provided filename.
+  if [ -n "$DEPLOY_SSH_CAFILE" ]; then
+    Le_Deploy_ssh_cafile="$DEPLOY_SSH_CAFILE"
+    _savedomainconf Le_Deploy_ssh_cafile "$Le_Deploy_ssh_cafile"
+  fi
+  if [ -n "$Le_Deploy_ssh_cafile" ]; then
+    _pipe=">"
+    if [ "$Le_Deploy_ssh_cafile" = "$Le_Deploy_ssh_keyfile" ] \
+      || [ "$Le_Deploy_ssh_cafile" = "$Le_Deploy_ssh_certfile" ]; then
+      # if filename is same as previous file then append.
+      _pipe=">>"
+    elif [ "$Le_Deploy_ssh_backup" = "yes" ]; then
+      # backup file we are about to overwrite.
+      _cmdstr="$_cmdstr cp $Le_Deploy_ssh_cafile $_backupdir >/dev/null;"
+    fi
+    # copy new certificate into file.
+    _cmdstr="$_cmdstr echo \"$(cat "$_cca")\" $_pipe $Le_Deploy_ssh_cafile;"
+    _info "will copy CA file to remote file $Le_Deploy_ssh_cafile"
+  fi
+
+  # FULLCHAIN is optional.
+  # If provided then fullchain certificate will be copied or appended to provided filename.
+  if [ -n "$DEPLOY_SSH_FULLCHAIN" ]; then
+    Le_Deploy_ssh_fullchain="$DEPLOY_SSH_FULLCHAIN"
+    _savedomainconf Le_Deploy_ssh_fullchain "$Le_Deploy_ssh_fullchain"
+  fi
+  if [ -n "$Le_Deploy_ssh_fullchain" ]; then
+    _pipe=">"
+    if [ "$Le_Deploy_ssh_fullchain" = "$Le_Deploy_ssh_keyfile" ] \
+      || [ "$Le_Deploy_ssh_fullchain" = "$Le_Deploy_ssh_certfile" ] \
+      || [ "$Le_Deploy_ssh_fullchain" = "$Le_Deploy_ssh_cafile" ]; then
+      # if filename is same as previous file then append.
+      _pipe=">>"
+    elif [ "$Le_Deploy_ssh_backup" = "yes" ]; then
+      # backup file we are about to overwrite.
+      _cmdstr="$_cmdstr cp $Le_Deploy_ssh_fullchain $_backupdir >/dev/null;"
+    fi
+    # copy new certificate into file.
+    _cmdstr="$_cmdstr echo \"$(cat "$_cfullchain")\" $_pipe $Le_Deploy_ssh_fullchain;"
+    _info "will copy fullchain to remote file $Le_Deploy_ssh_fullchain"
+  fi
+
+  # REMOTE_CMD is optional.
+  # If provided then this command will be executed on remote host.
+  if [ -n "$DEPLOY_SSH_REMOTE_CMD" ]; then
+    Le_Deploy_ssh_remote_cmd="$DEPLOY_SSH_REMOTE_CMD"
+    _savedomainconf Le_Deploy_ssh_remote_cmd "$Le_Deploy_ssh_remote_cmd"
+  fi
+  if [ -n "$Le_Deploy_ssh_remote_cmd" ]; then
+    _cmdstr="$_cmdstr $Le_Deploy_ssh_remote_cmd;"
+    _info "Will execute remote command $Le_Deploy_ssh_remote_cmd"
+  fi
+
+  if [ -z "$_cmdstr" ]; then
+    _err "No remote commands to excute. Failed to deploy certificates to remote server"
+    return 1
+  elif [ "$Le_Deploy_ssh_backup" = "yes" ]; then
+    # run cleanup on the backup directory, erase all older
+    # than 180 days (15552000 seconds).
+    _cmdstr="{ now=\"\$(date -u +%s)\"; for fn in $_backupprefix*; \
+do if [ -d \"\$fn\" ] && [ \"\$(expr \$now - \$(date -ur \$fn +%s) )\" -ge \"15552000\" ]; \
+then rm -rf \"\$fn\"; echo \"Backup \$fn deleted as older than 180 days\"; fi; done; }; $_cmdstr"
+    # Alternate version of above... _cmdstr="find $_backupprefix* -type d -mtime +180 2>/dev/null | xargs rm -rf; $_cmdstr"
+    # Create our backup directory for overwritten cert files.
+    _cmdstr="mkdir -p $_backupdir; $_cmdstr"
+    _info "Backup of old certificate files will be placed in remote directory $_backupdir"
+    _info "Backup directories erased after 180 days."
+  fi
+
+  _debug "Remote commands to execute: $_cmdstr"
+  _info "Submitting sequence of commands to remote server by ssh"
+  # quotations in bash cmd below intended.  Squash travis spellcheck error
+  # shellcheck disable=SC2029
+  $Le_Deploy_ssh_cmd -T "$Le_Deploy_ssh_user@$Le_Deploy_ssh_server" sh -c "'$_cmdstr'"
+  _ret="$?"
+
+  if [ "$_ret" != "0" ]; then
+    _err "Error code $_ret returned from $Le_Deploy_ssh_cmd"
+  fi
+
+  return $_ret
+}