diff --git a/readme.md b/readme.md index 4b7ef2b9aa542c0498dd8b441fc9a029179d20e7..ba7283cbe8ad9b6fd21824ce9da7b92707f4d91a 100644 --- a/readme.md +++ b/readme.md @@ -6,153 +6,4 @@ It was written to create/ renew all needed certificates at a central system to d 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> -## 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 - + ... -``` - -## 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 - -A certificate is created for a host and can have additional DNS names (optional). -For integration into a system deployment with Ansible & co the `ensure` prameter -is the best choice because it detects what action is required. -The command - -`[APPPATH]/cm.sh ensure www.example.com mail.example.com` - -creates (or renews if close to expiriation) a certificate with 2 hostnames in it. - -The "manual way" with atomic actions is: - -* Create `[APPPATH]/cm.sh add www.example.com mail.example.com` -* Renew `[APPPATH]/cm.sh renew www.example.com` -* Modify hostnames with add command `[APPPATH]/cm.sh add www.example.com mail.example.com newhost.example.com` what creates a new certificate. Optionally you can/ should revoke the existing certificate with the former host list before (see next command). The impact is: Your SSL certificate on the website is invalid up to the moment you create and deploy the new certificate what can take a few minutes. If you maintain many certificates with the same domain and the request limit is reached your application can be broken broken for an even longer time. -* Deletin the certificates includes a revoke `[APPPATH]/cm.sh delete www.example.com` - -### 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 www.example.com` +See [docs](docs/)