deploy/README.md

   1 # Using deploy api
   2
   3 Before you can deploy your cert, you must [issue the cert first](https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert).
   4
   5 Here are the scripts to deploy the certs/key to the server/services.
   6
   7 ## 1. Deploy the certs to your cpanel host
   8
   9 If you want to deploy using cpanel UAPI see 7.
  10
  11 (cpanel deploy hook is not finished yet, this is just an example.)
  12
  13
  14
  15 Then you can deploy now:
  16
  17 ```sh
  18 export DEPLOY_CPANEL_USER=myusername
  19 export DEPLOY_CPANEL_PASSWORD=PASSWORD
  20 acme.sh --deploy -d example.com --deploy-hook cpanel
  21 ```
  22
  23 ## 2. Deploy ssl cert on kong proxy engine based on api
  24
  25 Before you can deploy your cert, you must [issue the cert first](https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert).
  26 Currently supports Kong-v0.10.x.
  27
  28 ```sh
  29 acme.sh --deploy -d ftp.example.com --deploy-hook kong
  30 ```
  31
  32 ## 3. Deploy the cert to remote server through SSH access
  33
  34 The ssh deploy plugin allows you to deploy certificates to a remote host
  35 using SSH command to connect to the remote server.  The ssh plugin is invoked
  36 with the following command...
  37
  38 ```sh
  39 acme.sh --deploy -d example.com --deploy-hook ssh
  40 ```
  41 Prior to running this for the first time you must tell the plugin where
  42 and how to deploy the certificates.  This is done by exporting the following
  43 environment variables.  This is not required for subsequent runs as the
  44 values are stored by acme.sh in the domain configuration files.
  45
  46 Required...
  47 ```
  48 export DEPLOY_SSH_USER=username
  49 ```
  50 Optional...
  51 ```
  52 export DEPLOY_SSH_CMD=custom ssh command
  53 export DEPLOY_SSH_SERVER=url or ip address of remote host
  54 export DEPLOY_SSH_KEYFILE=filename for private key
  55 export DEPLOY_SSH_CERTFILE=filename for certificate file
  56 export DEPLOY_SSH_CAFILE=filename for intermediate CA file
  57 export DEPLOY_SSH_FULLCHAIN=filename for fullchain file
  58 export DEPLOY_SSH_REMOTE_CMD=command to execute on remote host
  59 export DEPLOY_SSH_BACKUP=yes or no
  60 ```
  61
  62 **DEPLOY_SSH_USER**
  63 Username at the remote host that SSH will login with. Note that
  64 SSH must be able to login to remote host without a password... SSH Keys
  65 must have been exchanged with the remote host. Validate and test that you
  66 can login to USER@URL from the host running acme.sh before using this script.
  67
  68 The USER@URL at the remote server must also have has permissions to write to
  69 the target location of the certificate files and to execute any commands
  70 (e.g. to stop/start services).
  71
  72 **DEPLOY_SSH_CMD**
  73 You can customize the ssh command used to connect to the remote host. For example
  74 if you need to connect to a specific port at the remote server you can set this
  75 to, for example, "ssh -p 22" or to use `sshpass` to provide password inline
  76 instead of exchanging ssh keys (this is not recommended, using keys is
  77 more secure).
  78
  79 **DEPLOY_SSH_SERVER**
  80 URL or IP Address of the remote server.  If not provided then the domain
  81 name provided on the acme.sh --deploy command line is used.
  82
  83 **DEPLOY_SSH_KEYFILE**
  84 Target filename for the private key issued by LetsEncrypt.
  85
  86 **DEPLOY_SSH_CERTFILE**
  87 Target filename for the certificate issued by LetsEncrypt.
  88 If this is the same as the previous filename (for keyfile) then it is
  89 appended to the same file.
  90
  91 **DEPLOY_SSH_CAFILE**
  92 Target filename for the CA intermediate certificate issued by LetsEncrypt.
  93 If this is the same as a previous filename (for keyfile or certfile) then
  94 it is appended to the same file.
  95
  96 **DEPLOY_SSH_FULLCHAIN**
  97 Target filename for the fullchain certificate issued by LetsEncrypt.
  98 If this is the same as a previous filename (for keyfile, certfile or
  99 cafile) then it is appended to the same file.
 100
 101 **DEPLOY_SSH_REMOTE_CMD**
 102 Command to execute on the remote server after copying any certificates.  This
 103 could be any additional command required for example to stop and restart
 104 the service.
 105
 106 **DEPLOY_SSH_BACKUP**
 107 Before writing a certificate file to the remote server the existing
 108 certificate will be copied to a backup directory on the remote server.
 109 These are placed in a hidden directory in the home directory of the SSH
 110 user
 111 ```sh
 112 ~/.acme_ssh_deploy/[domain name]-backup-[timestamp]
 113 ```
 114 Any backups older than 180 days will be deleted when new certificates
 115 are deployed.  This defaults to "yes" set to "no" to disable backup.
 116
 117 ###Examples using SSH deploy
 118 The following example illustrates deploying certificates to a QNAP NAS
 119 (tested with QTS version 4.2.3)
 120
 121 ```sh
 122 export DEPLOY_SSH_USER="admin"
 123 export DEPLOY_SSH_KEYFILE="/etc/stunnel/stunnel.pem"
 124 export DEPLOY_SSH_CERTFILE="/etc/stunnel/stunnel.pem"
 125 export DEPLOY_SSH_CAFILE="/etc/stunnel/uca.pem"
 126 export DEPLOY_SSH_REMOTE_CMD="/etc/init.d/stunnel.sh restart"
 127
 128 acme.sh --deploy -d qnap.example.com --deploy-hook ssh
 129 ```
 130 Note how in this example both the private key and certificate point to
 131 the same file.  This will result in the certificate being appended
 132 to the same file as the private key... a common requirement of several
 133 services.
 134
 135 The next example illustrates deploying certificates to a Unifi
 136 Controller (tested with version 5.4.11).
 137
 138 ```sh
 139 export DEPLOY_SSH_USER="root"
 140 export DEPLOY_SSH_KEYFILE="/var/lib/unifi/unifi.example.com.key"
 141 export DEPLOY_SSH_FULLCHAIN="/var/lib/unifi/unifi.example.com.cer"
 142 export DEPLOY_SSH_REMOTE_CMD="openssl pkcs12 -export \
 143    -inkey /var/lib/unifi/unifi.example.com.key \
 144    -in /var/lib/unifi/unifi.example.com.cer \
 145    -out /var/lib/unifi/unifi.example.com.p12 \
 146    -name ubnt -password pass:temppass \
 147  && keytool -importkeystore -deststorepass aircontrolenterprise \
 148    -destkeypass aircontrolenterprise \
 149    -destkeystore /var/lib/unifi/keystore \
 150    -srckeystore /var/lib/unifi/unifi.example.com.p12 \
 151    -srcstoretype PKCS12 -srcstorepass temppass -alias ubnt -noprompt \
 152  && service unifi restart"
 153
 154 acme.sh --deploy -d unifi.example.com --deploy-hook ssh
 155 ```
 156 In this example we execute several commands on the remote host
 157 after the certificate files have been copied... to generate a pkcs12 file
 158 compatible with Unifi, to import it into the Unifi keystore and then finally
 159 to restart the service.
 160
 161 Note also that once the certificate is imported
 162 into the keystore the individual certificate files are no longer
 163 required. We could if we desired delete those files immediately. If we
 164 do that then we should disable backup at the remote host (as there are
 165 no files to backup -- they were erased during deployment). For example...
 166 ```sh
 167 export DEPLOY_SSH_BACKUP=no
 168 # modify the end of the remote command...
 169 && rm /var/lib/unifi/unifi.example.com.key \
 170       /var/lib/unifi/unifi.example.com.cer \
 171       /var/lib/unifi/unifi.example.com.p12 \
 172 && service unifi restart
 173 ```
 174
 175 ## 4. Deploy the cert to local vsftpd server
 176
 177 ```sh
 178 acme.sh --deploy -d ftp.example.com --deploy-hook vsftpd
 179 ```
 180
 181 The default vsftpd conf file is `/etc/vsftpd.conf`,  if your vsftpd conf is not in the default location, you can specify one:
 182
 183 ```sh
 184 export DEPLOY_VSFTPD_CONF="/etc/vsftpd.conf"
 185
 186 acme.sh --deploy -d ftp.example.com --deploy-hook vsftpd
 187 ```
 188
 189 The default command to restart vsftpd server is `service vsftpd restart`, if it doesn't work, you can specify one:
 190
 191 ```sh
 192 export DEPLOY_VSFTPD_RELOAD="/etc/init.d/vsftpd restart"
 193
 194 acme.sh --deploy -d ftp.example.com --deploy-hook vsftpd
 195 ```
 196
 197 ## 5. Deploy the cert to local exim4 server
 198
 199 ```sh
 200 acme.sh --deploy -d ftp.example.com --deploy-hook exim4
 201 ```
 202
 203 The default exim4 conf file is `/etc/exim/exim.conf`,  if your exim4 conf is not in the default location, you can specify one:
 204
 205 ```sh
 206 export DEPLOY_EXIM4_CONF="/etc/exim4/exim4.conf.template"
 207
 208 acme.sh --deploy -d ftp.example.com --deploy-hook exim4
 209 ```
 210
 211 The default command to restart exim4 server is `service exim4 restart`, if it doesn't work, you can specify one:
 212
 213 ```sh
 214 export DEPLOY_EXIM4_RELOAD="/etc/init.d/exim4 restart"
 215
 216 acme.sh --deploy -d ftp.example.com --deploy-hook exim4
 217 ```
 218
 219 ## 6. Deploy the cert to OSX Keychain
 220
 221 ```sh
 222 acme.sh --deploy -d ftp.example.com --deploy-hook keychain
 223 ```
 224
 225 ## 7. Deploy to cpanel host using UAPI
 226
 227 This hook is using UAPI and works in cPanel & WHM version 56 or newer.
 228 ```
 229 acme.sh  --deploy  -d example.com  --deploy-hook cpanel_uapi
 230 ```
 231 DEPLOY_CPANEL_USER is required only if you run the script as root and it should contain cpanel username.
 232 ```sh
 233 export DEPLOY_CPANEL_USER=username
 234 acme.sh  --deploy  -d example.com  --deploy-hook cpanel_uapi
 235 ```
 236 Please note, that the cpanel_uapi hook will deploy only the first domain when your certificate will automatically renew. Therefore you should issue a separate certificate for each domain.
 237
 238 ## 8. Deploy the cert to your FRITZ!Box router
 239
 240 You must specify the credentials that have administrative privileges on the FRITZ!Box in order to deploy the certificate, plus the URL of your FRITZ!Box, through the following environment variables:
 241 ```sh
 242 $ export DEPLOY_FRITZBOX_USERNAME=my_username
 243 $ export DEPLOY_FRITZBOX_PASSWORD=the_password
 244 $ export DEPLOY_FRITZBOX_URL=https://fritzbox.example.com
 245 ```
 246
 247 After the first deployment, these values will be stored in your $HOME/.acme.sh/account.conf. You may now deploy the certificate like this:
 248
 249 ```sh
 250 acme.sh --deploy -d fritzbox.example.com --deploy-hook fritzbox
 251 ```
 252
 253 ## 9. Deploy the cert to strongswan
 254
 255 ```sh
 256 acme.sh --deploy -d ftp.example.com --deploy-hook strongswan
 257 ```