diff --git a/docs/10_Home.md b/docs/10_Home.md new file mode 100644 index 0000000000000000000000000000000000000000..62e9c377da41163e10b6918c7fe2254f8c0aab88 --- /dev/null +++ b/docs/10_Home.md @@ -0,0 +1,7 @@ +# iml-certman + +Wrapper for **acme.sh** to create Let's Encrypt certificates based on CSR files using DNS authentication. +It was written to create/ renew all needed certificates at a central system to deploy it from there (Ansible, Puppet, ...). + +source: <https://git-repo.iml.unibe.ch/open-source/iml-certman> +license: GNU GPL 3.0 <http://www.gnu.org/licenses/gpl-3.0.html> diff --git a/docs/20_Installation.md b/docs/20_Installation.md new file mode 100644 index 0000000000000000000000000000000000000000..16dd86eb24d387a1d6851a45903551792c998a94 --- /dev/null +++ b/docs/20_Installation.md @@ -0,0 +1,36 @@ +# Installation + +* Install acme.sh client: <https://github.com/acmesh-official/acme.sh> +* If you use Ansible/ Puppet/ ... to renew and deploy new certificates then you can deactivate the acme cronjob (`crontab -e`) +* Clone or extract files of iml-certman +* Make your changes by copying *dist files to file without ".dist" extension and edit + * inc_config.sh + * set credentials for dns api + * set path to acme.sh script; the default is a relative path for the suggested contellation below. + * optional: set custom target for generated certificates + * optional: for testing enable Let's Encrypt stage server to prevent running into weekly limits during tests + * optional: set a filter that must match to new certificate and all aliases + * templates/csr.txt + * set location, company and department ... remark: (currently?) it is removed by LE + +A suggested structure is having acme.sh and this wrapper below the same parent directory, i.e. + +```text +/opt/letsenecrypt/ + | + +-- acme.sh/ + | | + | + acme.sh + | + ... + | + +-- iml-certman/ + | + +-- certs/ + +-- csr/ + +-- templates/ + + cm.sh + + inc_config.sh + + ... +``` + +Verify a new setup (or changes in the config) with `./cm.sh selftest`. diff --git a/docs/30_Usage.md b/docs/30_Usage.md new file mode 100644 index 0000000000000000000000000000000000000000..b56df32020e0dbddf3d02392f7acad7b5951cd4b --- /dev/null +++ b/docs/30_Usage.md @@ -0,0 +1,139 @@ +# Usage + +## Selftest + +Verify a new setup (or changes in the config) with `./cm.sh selftest`. + +## Show help + +Without any parameter it shows a help. + +```text + +./cm.sh +_______________________________________________________________________________ + + + - - - ---===>>> CERT MANAGER <<<===--- - - - + +_______________________________________________________________________________ + +DEBUG: Using Let's Encrypt STAGE environment ... +DEBUG: You can test and mess around. Do not use certs in production. + +HELP + +The basic syntax is +cm.sh [--trace] ACTION [FQDN] [ALIAS_1 [.. ALIAS_N]] + +The ACTIONs for SINGLE certificate handlings are: + + add FQDN [.. FQDN-N] + create new certificate + The first FQDN is a hostname to generate the certificate for. + Following multiple hostnames will be used as DNS aliases in the + same certificate. + It updates files in ./certs + + ensure FQDN [.. FQDN-N] + It ensures that a certificate with given aliases exists and is up to date. + This param is for simple usage in automation tools like Ansible or Puppet. + It is required to add all aliases as parameters what is unhandy for + direct usage on cli. + + If the cert does not exist it will be created (see "add"). + If fqdn and aliases are the same like in the certificate it performs a renew. + If fqdn and aliases differ: + - the current certificate will be rejected + deleted (see "delete") + - a new certificate will be added () + + delete FQDN + delete all files of a given certificate + + renew FQDN + renew (an already added) certificate + and update files in ./certs + + show FQDN + show place of csr + certificate data and show basic certificate data + (issuer, subject, aliases, ending date) + + transfer FQDN + Transfer cert from acme.sh internal cache to our output dir again. + It is done during add or renew. With transfer command you can repeat it. + +ACTIONs for ALL certs + + list + list all certificates including creation and renew date + + renew-all + renew all certificates (fast mode - without --force) + and update files in ./certs + It is useful for a cronjob. + +other ACTIONs + + selftest + check of health with current setup and requirements. + This command is helpful for initial setups. + +OPTIONS + --trace (it must be the 1st parameter) + the output additionally will be written into a tracelog file + below ./log. + +DEBUG: Using Let's Encrypt STAGE environment ... +DEBUG: You can test and mess around. Do not use certs in production. + +``` + +## CRUD actions for a certificate + +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` + +All other actions need the first domain only. + +The parameter **show** shows details. + +`[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**. + +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. + +`[APPPATH]/cm.sh delete www.example.com` + +Then a certificate does not appear with cm.sh list anymore. + +## The action "ensure" + +In a scenario of automatic deployment with Ansible or Puppet you don't want to find out what action is needed: action add, remove old and add a new certificate or renew. The ensure action is a universal command to ensure somehow that the certificate exists, contains all DNS alt names and is up to date. + +`[APPPATH]/cm.sh ensure www.example.com mail.example.com` + +creates (or renews if close to expiriation) a certificate with 2 hostnames in it. + +## 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` + +## Logs + +In **log/certmanager.log** you find a logging about time of changes for a certificate: when it was added, renewed, deleted. A skipped renew execution (even if it was triggered internally by "ensure") won't be logged. + +Additionally there is a --trace option (must be the 1st param) - an execution output will be put to logfile that contains domain and timestamp.