Skip to content
Snippets Groups Projects
user avatar
Hahn Axel (hahn) authored
6ef2e2c1
History

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.

/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.


./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 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.


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