Skip to content
Snippets Groups Projects
Select Git revision
  • 41d0a2b4a3840c60f083fabb1fca53237f82bb14
  • master default protected
2 results

30_Usage.md

Blame
  • user avatar
    Hahn Axel (hahn) authored
    4a936124
    History

    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 [--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 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
    
            list-old
                    list all certificates older 65 and older 90 days and exit.
                    Exitcodes:
                      0 - all certs are up to date.
                      1 - certificates to renew were found
                      2 - outdatedt certificates were found
    
            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.