diff --git a/docs/30_Usage.md b/docs/30_Usage.md index 7d37cb28e93c2979d2433fe611e522ff387c8828..6a495b1f28d93aeee7b4f88d78f62d83c33f334b 100644 --- a/docs/30_Usage.md +++ b/docs/30_Usage.md @@ -118,23 +118,101 @@ other ACTIONs ## CRUD actions for a certificate +### Create (Issue) + With parameter `add` you need to add all domains that should be included in a new certificate. `[APPPATH]/cm.sh add www.example.com mail.example.com` +#### Mehtod: DNS auth + +By default the cert manager tries to use the DNS challenge + +`[APPPATH]/cm.sh add www.example.com mail.example.com` + +In the configuration you need these variables: + +* CM_certmatch defines the domains that are allowed to use DNS auth.<br>to allow all: `export CM_certmatch="."`<br>To allow a specific subdomain: `export CM_certmatch="\.org\.example\.com"` +* CM_challenge_alias is the domain you can manage via DNS api. <br>All hosts of this domain will be issued by a TXT record.<br>External domains need a CNAME. See <https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode> + +#### Mehtod: Http - using webroot + +If you have a http website of a domain you can authorize with a written challenge file. The file will be written below webroot. +The SSL provider will make an http request `http://www.example.com/.well-known/acme-challenge/<generated-challenge-file>` + +The parameter --webroot is used to define the webroot of the existing web (without /.well-known/acme-challenge). + +Example: + +`[APPPATH]/cm.sh --webroot <webroot> add www.example.com mail.example.com` + +#### Mehtod: Http - using alias + +You can use an alias to place the generated challenge file outside webroot. +The SSL provider will make an http request `http://www.example.com/.well-known/acme-challenge/<generated-challenge-file>` - this url must fit here too. + +(1) Create a .well-known directory + +Remark: this path is hardcoded :-/ + +The directory is ../alias-dir/ - one directory outside the cm.sh. +If your installation is in `/opt/letsencrypt/iml-certman/` then you need to create this directory: `/opt/letsencrypt/alias-dir/.well-known` + +(2) In Webserver enable mod_alias + +eg. on Debian /etc/apache2/mods-enabled/alias.load + +``` +LoadModule alias_module /usr/lib/apache2/modules/mod_alias.so +``` + +(3) In Webserver create an alias pointing to your .well-known directory + +In your vhost (or global apache config) define an alias. + +```text +Alias /.well-known "/opt/letsencrypt/alias-dir/.well-known" +``` + +If you have rewrite rules or proxy rules in the webroot keep in mind to have an exclude to allow file access on challenge files. + +```text +RewriteEngine On +RewriteCond %{REQUEST_URI} !^/.well-known +RewriteRule ^(.*)$ index.php [QSA,L] +``` + +(4) Issue the cert + +use the parameter --alias without any value to create the challenge file in ../alias-dir/. + +Example: + +`[APPPATH]/cm.sh --alias add www.example.com mail.example.com` + All other actions need the first domain only. -The parameter **show** shows details. +### Read + +Use the parameter **list** to show all certificates, aliases and dates. + +`[APPPATH]/cm.sh list` + +The parameter **show** shows details of a single certificate. `[APPPATH]/cm.sh show www.example.com` -If a certificate reaches the time for renewing (i.e. 4 weeks before expiration) you can renew it with **renew**. +### Update (renew) + +If a certificate reaches the time for renewing (i.e. 4 weeks before expiration) you can renew it with **renew**. Remark: if you try to renew before renewing date this results in a skip message (and exitcode 0). `[APPPATH]/cm.sh renew www.example.com` -With a delete command the certificate will be revoked and the local files will be deleted. +With a delete command the certificate will be revoked and the local files will be deleted. + +### Delete `[APPPATH]/cm.sh delete www.example.com` @@ -156,14 +234,6 @@ This ensure action handles the logic if a certificate must be It detects if a domain in the certificate can use a txt record or needs dns auth mode. -## Show certificate data - -Use the listing `[APPPATH]/cm.sh list` or maybe filter it `[APPPATH]/cm.sh list | grep "mail."` - -to get a list of existing certs an then use the hostname in the 1st column to show details: - -`[APPPATH]/cm.sh show mail.example.com` - ## Renew all certificates `[APPPATH]/cm.sh renew-all`