You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

426 lines
14 KiB

8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
7 years ago
8 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
  1. # Using deploy api
  2. Before you can deploy your cert, you must [issue the cert first](https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert).
  3. Here are the scripts to deploy the certs/key to the server/services.
  4. ## 1. Deploy the certs to your cpanel host
  5. If you want to deploy using cpanel UAPI see 7.
  6. (cpanel deploy hook is not finished yet, this is just an example.)
  7. Then you can deploy now:
  8. ```sh
  9. export DEPLOY_CPANEL_USER=myusername
  10. export DEPLOY_CPANEL_PASSWORD=PASSWORD
  11. acme.sh --deploy -d example.com --deploy-hook cpanel
  12. ```
  13. ## 2. Deploy ssl cert on kong proxy engine based on api
  14. Before you can deploy your cert, you must [issue the cert first](https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert).
  15. Currently supports Kong-v0.10.x.
  16. ```sh
  17. acme.sh --deploy -d ftp.example.com --deploy-hook kong
  18. ```
  19. ## 3. Deploy the cert to remote server through SSH access
  20. The ssh deploy plugin allows you to deploy certificates to a remote host
  21. using SSH command to connect to the remote server. The ssh plugin is invoked
  22. with the following command...
  23. ```sh
  24. acme.sh --deploy -d example.com --deploy-hook ssh
  25. ```
  26. Prior to running this for the first time you must tell the plugin where
  27. and how to deploy the certificates. This is done by exporting the following
  28. environment variables. This is not required for subsequent runs as the
  29. values are stored by acme.sh in the domain configuration files.
  30. Required...
  31. ```
  32. export DEPLOY_SSH_USER=username
  33. ```
  34. Optional...
  35. ```
  36. export DEPLOY_SSH_CMD=custom ssh command
  37. export DEPLOY_SSH_SERVER=url or ip address of remote host
  38. export DEPLOY_SSH_KEYFILE=filename for private key
  39. export DEPLOY_SSH_CERTFILE=filename for certificate file
  40. export DEPLOY_SSH_CAFILE=filename for intermediate CA file
  41. export DEPLOY_SSH_FULLCHAIN=filename for fullchain file
  42. export DEPLOY_SSH_REMOTE_CMD=command to execute on remote host
  43. export DEPLOY_SSH_BACKUP=yes or no
  44. ```
  45. **DEPLOY_SSH_USER**
  46. Username at the remote host that SSH will login with. Note that
  47. SSH must be able to login to remote host without a password... SSH Keys
  48. must have been exchanged with the remote host. Validate and test that you
  49. can login to USER@URL from the host running acme.sh before using this script.
  50. The USER@URL at the remote server must also have has permissions to write to
  51. the target location of the certificate files and to execute any commands
  52. (e.g. to stop/start services).
  53. **DEPLOY_SSH_CMD**
  54. You can customize the ssh command used to connect to the remote host. For example
  55. if you need to connect to a specific port at the remote server you can set this
  56. to, for example, "ssh -p 22" or to use `sshpass` to provide password inline
  57. instead of exchanging ssh keys (this is not recommended, using keys is
  58. more secure).
  59. **DEPLOY_SSH_SERVER**
  60. URL or IP Address of the remote server. If not provided then the domain
  61. name provided on the acme.sh --deploy command line is used.
  62. **DEPLOY_SSH_KEYFILE**
  63. Target filename for the private key issued by LetsEncrypt.
  64. **DEPLOY_SSH_CERTFILE**
  65. Target filename for the certificate issued by LetsEncrypt.
  66. If this is the same as the previous filename (for keyfile) then it is
  67. appended to the same file.
  68. **DEPLOY_SSH_CAFILE**
  69. Target filename for the CA intermediate certificate issued by LetsEncrypt.
  70. If this is the same as a previous filename (for keyfile or certfile) then
  71. it is appended to the same file.
  72. **DEPLOY_SSH_FULLCHAIN**
  73. Target filename for the fullchain certificate issued by LetsEncrypt.
  74. If this is the same as a previous filename (for keyfile, certfile or
  75. cafile) then it is appended to the same file.
  76. **DEPLOY_SSH_REMOTE_CMD**
  77. Command to execute on the remote server after copying any certificates. This
  78. could be any additional command required for example to stop and restart
  79. the service.
  80. **DEPLOY_SSH_BACKUP**
  81. Before writing a certificate file to the remote server the existing
  82. certificate will be copied to a backup directory on the remote server.
  83. These are placed in a hidden directory in the home directory of the SSH
  84. user
  85. ```sh
  86. ~/.acme_ssh_deploy/[domain name]-backup-[timestamp]
  87. ```
  88. Any backups older than 180 days will be deleted when new certificates
  89. are deployed. This defaults to "yes" set to "no" to disable backup.
  90. ###Examples using SSH deploy
  91. The following example illustrates deploying certificates to a QNAP NAS
  92. (tested with QTS version 4.2.3)
  93. ```sh
  94. export DEPLOY_SSH_USER="admin"
  95. export DEPLOY_SSH_KEYFILE="/etc/stunnel/stunnel.pem"
  96. export DEPLOY_SSH_CERTFILE="/etc/stunnel/stunnel.pem"
  97. export DEPLOY_SSH_CAFILE="/etc/stunnel/uca.pem"
  98. export DEPLOY_SSH_REMOTE_CMD="/etc/init.d/stunnel.sh restart"
  99. acme.sh --deploy -d qnap.example.com --deploy-hook ssh
  100. ```
  101. Note how in this example both the private key and certificate point to
  102. the same file. This will result in the certificate being appended
  103. to the same file as the private key... a common requirement of several
  104. services.
  105. The next example illustrates deploying certificates to a Unifi
  106. Controller (tested with version 5.4.11).
  107. ```sh
  108. export DEPLOY_SSH_USER="root"
  109. export DEPLOY_SSH_KEYFILE="/var/lib/unifi/unifi.example.com.key"
  110. export DEPLOY_SSH_FULLCHAIN="/var/lib/unifi/unifi.example.com.cer"
  111. export DEPLOY_SSH_REMOTE_CMD="openssl pkcs12 -export \
  112. -inkey /var/lib/unifi/unifi.example.com.key \
  113. -in /var/lib/unifi/unifi.example.com.cer \
  114. -out /var/lib/unifi/unifi.example.com.p12 \
  115. -name ubnt -password pass:temppass \
  116. && keytool -importkeystore -deststorepass aircontrolenterprise \
  117. -destkeypass aircontrolenterprise \
  118. -destkeystore /var/lib/unifi/keystore \
  119. -srckeystore /var/lib/unifi/unifi.example.com.p12 \
  120. -srcstoretype PKCS12 -srcstorepass temppass -alias ubnt -noprompt \
  121. && service unifi restart"
  122. acme.sh --deploy -d unifi.example.com --deploy-hook ssh
  123. ```
  124. In this example we execute several commands on the remote host
  125. after the certificate files have been copied... to generate a pkcs12 file
  126. compatible with Unifi, to import it into the Unifi keystore and then finally
  127. to restart the service.
  128. Note also that once the certificate is imported
  129. into the keystore the individual certificate files are no longer
  130. required. We could if we desired delete those files immediately. If we
  131. do that then we should disable backup at the remote host (as there are
  132. no files to backup -- they were erased during deployment). For example...
  133. ```sh
  134. export DEPLOY_SSH_BACKUP=no
  135. # modify the end of the remote command...
  136. && rm /var/lib/unifi/unifi.example.com.key \
  137. /var/lib/unifi/unifi.example.com.cer \
  138. /var/lib/unifi/unifi.example.com.p12 \
  139. && service unifi restart
  140. ```
  141. ## 4. Deploy the cert to local vsftpd server
  142. ```sh
  143. acme.sh --deploy -d ftp.example.com --deploy-hook vsftpd
  144. ```
  145. The default vsftpd conf file is `/etc/vsftpd.conf`, if your vsftpd conf is not in the default location, you can specify one:
  146. ```sh
  147. export DEPLOY_VSFTPD_CONF="/etc/vsftpd.conf"
  148. acme.sh --deploy -d ftp.example.com --deploy-hook vsftpd
  149. ```
  150. The default command to restart vsftpd server is `service vsftpd restart`, if it doesn't work, you can specify one:
  151. ```sh
  152. export DEPLOY_VSFTPD_RELOAD="/etc/init.d/vsftpd restart"
  153. acme.sh --deploy -d ftp.example.com --deploy-hook vsftpd
  154. ```
  155. ## 5. Deploy the cert to local exim4 server
  156. ```sh
  157. acme.sh --deploy -d ftp.example.com --deploy-hook exim4
  158. ```
  159. The default exim4 conf file is `/etc/exim/exim.conf`, if your exim4 conf is not in the default location, you can specify one:
  160. ```sh
  161. export DEPLOY_EXIM4_CONF="/etc/exim4/exim4.conf.template"
  162. acme.sh --deploy -d ftp.example.com --deploy-hook exim4
  163. ```
  164. The default command to restart exim4 server is `service exim4 restart`, if it doesn't work, you can specify one:
  165. ```sh
  166. export DEPLOY_EXIM4_RELOAD="/etc/init.d/exim4 restart"
  167. acme.sh --deploy -d ftp.example.com --deploy-hook exim4
  168. ```
  169. ## 6. Deploy the cert to OSX Keychain
  170. ```sh
  171. acme.sh --deploy -d ftp.example.com --deploy-hook keychain
  172. ```
  173. ## 7. Deploy to cpanel host using UAPI
  174. This hook is using UAPI and works in cPanel & WHM version 56 or newer.
  175. ```
  176. acme.sh --deploy -d example.com --deploy-hook cpanel_uapi
  177. ```
  178. DEPLOY_CPANEL_USER is required only if you run the script as root and it should contain cpanel username.
  179. ```sh
  180. export DEPLOY_CPANEL_USER=username
  181. acme.sh --deploy -d example.com --deploy-hook cpanel_uapi
  182. ```
  183. 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.
  184. ## 8. Deploy the cert to your FRITZ!Box router
  185. 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:
  186. ```sh
  187. $ export DEPLOY_FRITZBOX_USERNAME=my_username
  188. $ export DEPLOY_FRITZBOX_PASSWORD=the_password
  189. $ export DEPLOY_FRITZBOX_URL=https://fritzbox.example.com
  190. ```
  191. After the first deployment, these values will be stored in your $HOME/.acme.sh/account.conf. You may now deploy the certificate like this:
  192. ```sh
  193. acme.sh --deploy -d fritzbox.example.com --deploy-hook fritzbox
  194. ```
  195. ## 9. Deploy the cert to strongswan
  196. ```sh
  197. acme.sh --deploy -d ftp.example.com --deploy-hook strongswan
  198. ```
  199. ## 10. Deploy the cert to HAProxy
  200. You must specify the path where you want the concatenated key and certificate chain written.
  201. ```sh
  202. export DEPLOY_HAPROXY_PEM_PATH=/etc/haproxy
  203. ```
  204. You may optionally define the command to reload HAProxy. The value shown below will be used as the default if you don't set this environment variable.
  205. ```sh
  206. export DEPLOY_HAPROXY_RELOAD="/usr/sbin/service haproxy restart"
  207. ```
  208. You can then deploy the certificate as follows
  209. ```sh
  210. acme.sh --deploy -d haproxy.example.com --deploy-hook haproxy
  211. ```
  212. The path for the PEM file will be stored with the domain configuration and will be available when renewing, so that deploy will happen automatically when renewed.
  213. ## 11. Deploy your cert to Gitlab pages
  214. You must define the API key and the informations for the project and Gitlab page you are updating the certificate for.
  215. ```sh
  216. # The token can be created in your user settings under "Access Tokens"
  217. export GITLAB_TOKEN="xxxxxxxxxxx"
  218. # The project ID is displayed on the home page of the project
  219. export GITLAB_PROJECT_ID=12345678
  220. # The domain must match the one defined for the Gitlab page, without "https://"
  221. export GITLAB_DOMAIN="www.mydomain.com"
  222. ```
  223. You can then deploy the certificate as follows
  224. ```sh
  225. acme.sh --deploy -d www.mydomain.com --deploy-hook gitlab
  226. ```
  227. ## 12. Deploy your cert to Hashicorp Vault
  228. ```sh
  229. export VAULT_PREFIX="acme"
  230. ```
  231. You can then deploy the certificate as follows
  232. ```sh
  233. acme.sh --deploy -d www.mydomain.com --deploy-hook vault_cli
  234. ```
  235. Your certs will be saved in Vault using this structure:
  236. ```sh
  237. vault write "${VAULT_PREFIX}/${domain}/cert.pem" value=@"..."
  238. vault write "${VAULT_PREFIX}/${domain}/cert.key" value=@"..."
  239. vault write "${VAULT_PREFIX}/${domain}/chain.pem" value=@"..."
  240. vault write "${VAULT_PREFIX}/${domain}/fullchain.pem" value=@"..."
  241. ```
  242. You might be using Fabio load balancer (which can get certs from
  243. Vault). It needs a bit different structure of your certs in Vault. It
  244. gets certs only from keys that were saved in `prefix/domain`, like this:
  245. ```bash
  246. vault write <PREFIX>/www.domain.com cert=@cert.pem key=@key.pem
  247. ```
  248. If you want to save certs in Vault this way just set "FABIO" env
  249. variable to anything (ex: "1") before running `acme.sh`:
  250. ```sh
  251. export FABIO="1"
  252. ```
  253. ## 13. Deploy your certificate to Qiniu.com
  254. 使用 acme.sh 部署到七牛之前,需要确保部署的域名已打开 HTTPS 功能,您可以访问[融合 CDN - 域名管理](https://portal.qiniu.com/cdn/domain) 设置。
  255. 另外还需要先导出 AK/SK 环境变量,您可以访问[密钥管理](https://portal.qiniu.com/user/key) 获得。
  256. ```sh
  257. $ export QINIU_AK="foo"
  258. $ export QINIU_SK="bar"
  259. ```
  260. 完成准备工作之后,您就可以通过下面的命令开始部署 SSL 证书到七牛上:
  261. ```sh
  262. $ acme.sh --deploy -d example.com --deploy-hook qiniu
  263. ```
  264. 假如您部署的证书为泛域名证书,您还需要设置 `QINIU_CDN_DOMAIN` 变量,指定实际需要部署的域名:
  265. ```sh
  266. $ export QINIU_CDN_DOMAIN="cdn.example.com"
  267. $ acme.sh --deploy -d example.com --deploy-hook qiniu
  268. ```
  269. ### English version
  270. You should create AccessKey/SecretKey pair in https://portal.qiniu.com/user/key
  271. before deploying your certificate, and please ensure you have enabled HTTPS for
  272. your domain name. You can enable it in https://portal.qiniu.com/cdn/domain.
  273. ```sh
  274. $ export QINIU_AK="foo"
  275. $ export QINIU_SK="bar"
  276. ```
  277. then you can deploy certificate by following command:
  278. ```sh
  279. $ acme.sh --deploy -d example.com --deploy-hook qiniu
  280. ```
  281. (Optional), If you are using wildcard certificate,
  282. you may need export `QINIU_CDN_DOMAIN` to specify which domain
  283. you want to update:
  284. ```sh
  285. $ export QINIU_CDN_DOMAIN="cdn.example.com"
  286. $ acme.sh --deploy -d example.com --deploy-hook qiniu
  287. ```
  288. ## 14. Deploy your cert on MyDevil.net
  289. Once you have acme.sh installed and certificate issued (see info in [DNS API](../dnsapi/README.md#61-use-mydevilnet)), you can install it by following command:
  290. ```sh
  291. acme.sh --deploy --deploy-hook mydevil -d example.com
  292. ```
  293. That will remove old certificate and install new one.
  294. ## 15. Deploy the cert to remote routeros
  295. ```sh
  296. acme.sh --deploy -d ftp.example.com --deploy-hook routeros
  297. ```
  298. Before you can deploy the certificate to router os, you need to add the id_rsa.pub key to the routeros and assign a user to that key.
  299. The user need to have access to ssh, ftp, read and write.
  300. There are no need to enable ftp service for the script to work, as they are transmitted over SCP, however ftp is needed to store the files on the router.
  301. Then you need to set the environment variables for the deploy script to work.
  302. ```sh
  303. export ROUTER_OS_USERNAME=certuser
  304. export ROUTER_OS_HOST=router.example.com
  305. acme.sh --deploy -d ftp.example.com --deploy-hook routeros
  306. ```
  307. The deploy script will remove previously deployed certificates, and it does this with an assumption on how RouterOS names imported certificates, adding a "cer_0" suffix at the end. This is true for versions 6.32 -> 6.41.3, but it is not guaranteed that it will be true for future versions when upgrading.
  308. If the router have other certificates with the same name as the one beeing deployed, then this script will remove those certificates.
  309. At the end of the script, the services that use those certificates could be updated. Currently only the www-ssl service is beeing updated, but more services could be added.
  310. For instance:
  311. ```
  312. /ip service set www-ssl certificate=$_cdomain.cer_0
  313. /ip service set api-ssl certificate=$_cdomain.cer_0
  314. ```
  315. One optional thing to do as well is to create a script that updates all the required services and run that script in a single command.