mirror of
https://github.com/acmesh-official/acme.sh.git
synced 2025-05-10 09:22:47 +00:00
66466b5105
This change aims to make it easier to read through the README.md files, both online and using a simple text editor. Also contains minor corrections. [ci skip]
268 lines
10 KiB
Markdown
268 lines
10 KiB
Markdown
Using the deploy API
|
|
====================
|
|
|
|
Before you can deploy your cert, you must [issue the cert first].
|
|
|
|
[issue the cert first]: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
|
|
|
|
Here are the scripts to deploy the certs/key to the server/services:
|
|
|
|
1. [Deploy the certs to your cpanel host](#deploy-the-certs-to-your-cpanel-host)
|
|
2. [Deploy ssl cert on kong proxy engine based on API](#deploy-ssl-cert-on-kong-proxy-engine-based-on-api)
|
|
3. [Deploy the cert to remote server through SSH access](#deploy-the-cert-to-remote-server-through-ssh-access)
|
|
4. [Deploy the cert to local vsftpd server](#deploy-the-cert-to-local-vsftpd-server)
|
|
5. [Deploy the cert to local exim4 server](#deploy-the-cert-to-local-exim4-server)
|
|
6. [Deploy the cert to OSX Keychain](#deploy-the-cert-to-osx-keychain)
|
|
7. [Deploy to cpanel host using UAPI](#deploy-to-cpanel-host-using-uapi)
|
|
8. [Deploy the cert to your FRITZ!Box router](#deploy-the-cert-to-your-fritzbox-router)
|
|
9. [Deploy the cert to strongSwan](#deploy-the-cert-to-strongswan)
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
Deploy the certs to your cpanel host
|
|
------------------------------------
|
|
|
|
If you want to deploy using cpanel UAPI see
|
|
[Deploy to cpanel host using UAPI].
|
|
|
|
(cpanel deploy hook is not finished yet, this is just an example.)
|
|
|
|
Then you can deploy:
|
|
|
|
export DEPLOY_CPANEL_USER=myusername
|
|
export DEPLOY_CPANEL_PASSWORD=PASSWORD
|
|
acme.sh --deploy -d example.com --deploy-hook cpanel
|
|
|
|
Deploy ssl cert on kong proxy engine based on API
|
|
-------------------------------------------------
|
|
|
|
Before you can deploy your cert, you must [issue the cert first].
|
|
Currently supports Kong-v0.10.x.
|
|
|
|
|
|
acme.sh --deploy -d ftp.example.com --deploy-hook kong
|
|
|
|
Deploy the cert to remote server through SSH access
|
|
---------------------------------------------------
|
|
|
|
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:
|
|
|
|
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 Let's Encrypt.
|
|
|
|
`DEPLOY_SSH_CERTFILE`
|
|
Target filename for the certificate issued by Let's Encrypt. 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 Let's
|
|
Encrypt. 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 Let's Encrypt.
|
|
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
|
|
|
|
~/.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.
|
|
|
|
### Examples using SSH deploy
|
|
|
|
The following example illustrates deploying certificates to a QNAP NAS
|
|
(tested with QTS version 4.2.3)
|
|
|
|
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 illustrates deploying certificates to a UniFi
|
|
Controller (tested with version 5.4.11).
|
|
|
|
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 example 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 finally 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:
|
|
|
|
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
|
|
|
|
Deploy the cert to local vsftpd server
|
|
--------------------------------------
|
|
|
|
acme.sh --deploy -d ftp.example.com --deploy-hook vsftpd
|
|
|
|
The default vsftpd conf file is `/etc/vsftpd.conf`, if your vsftpd conf
|
|
is not in the default location, you can specify one:
|
|
|
|
export DEPLOY_VSFTPD_CONF="/etc/vsftpd.conf"
|
|
|
|
acme.sh --deploy -d ftp.example.com --deploy-hook vsftpd
|
|
|
|
The default command to restart vsftpd server is `service vsftpd
|
|
restart`, if it doesn't work, you can specify one:
|
|
|
|
export DEPLOY_VSFTPD_RELOAD="/etc/init.d/vsftpd restart"
|
|
|
|
acme.sh --deploy -d ftp.example.com --deploy-hook vsftpd
|
|
|
|
Deploy the cert to local exim4 server
|
|
-------------------------------------
|
|
|
|
acme.sh --deploy -d ftp.example.com --deploy-hook exim4
|
|
|
|
The default exim4 conf file is `/etc/exim/exim.conf`, if your exim4 conf
|
|
is not in the default location, you can specify one:
|
|
|
|
export DEPLOY_EXIM4_CONF="/etc/exim4/exim4.conf.template"
|
|
|
|
acme.sh --deploy -d ftp.example.com --deploy-hook exim4
|
|
|
|
The default command to restart exim4 server is `service exim4 restart`,
|
|
if it doesn't work, you can specify one:
|
|
|
|
export DEPLOY_EXIM4_RELOAD="/etc/init.d/exim4 restart"
|
|
|
|
acme.sh --deploy -d ftp.example.com --deploy-hook exim4
|
|
|
|
Deploy the cert to OSX Keychain
|
|
-------------------------------
|
|
|
|
acme.sh --deploy -d ftp.example.com --deploy-hook keychain
|
|
|
|
Deploy to cpanel host using UAPI
|
|
--------------------------------
|
|
|
|
This hook is using UAPI and works in cPanel & WHM version 56 or newer.
|
|
|
|
acme.sh --deploy -d example.com --deploy-hook cpanel_uapi
|
|
|
|
`DEPLOY_CPANEL_USER` is required only if you run the script as root and
|
|
it should contain cpanel username.
|
|
|
|
export DEPLOY_CPANEL_USER=username
|
|
acme.sh --deploy -d example.com --deploy-hook cpanel_uapi
|
|
|
|
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.
|
|
|
|
Deploy the cert to your FRITZ!Box router
|
|
----------------------------------------
|
|
|
|
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:
|
|
|
|
export DEPLOY_FRITZBOX_USERNAME=my_username
|
|
export DEPLOY_FRITZBOX_PASSWORD=the_password
|
|
export DEPLOY_FRITZBOX_URL=https://fritzbox.example.com
|
|
|
|
After the first deployment, these values will be stored in your
|
|
`$HOME/.acme.sh/account.conf`. You may now deploy the certificate like
|
|
this:
|
|
|
|
acme.sh --deploy -d fritzbox.example.com --deploy-hook fritzbox
|
|
|
|
Deploy the cert to strongSwan
|
|
-----------------------------
|
|
|
|
acme.sh --deploy -d ftp.example.com --deploy-hook strongswan
|