Skip to content
Snippets Groups Projects
Commit 37ff1a06 authored by Hahn Axel (hahn)'s avatar Hahn Axel (hahn)
Browse files

update docs

parent 91dbbecd
No related branches found
No related tags found
1 merge request!1Handle dns alias domain
# 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>
# 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`.
# 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.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment