cert_manage

With cert_manage, you can configure and manage

You can only configure one type of certificate authority at a time; internal or external. When an external CA is configured, Lighthouse cannot revert to using its internal CA. To switch certificate authorities, you must create a new deployment of Lighthouse or perform a factory reset of your Lighthouse instance.

Caution:

For an internal certificate authority:

  • Running cert_manage run may cause nodes to temporarily disconnect from Lighthouse, and/or secondary Lighthouse instances to temporarily disconnect from the primary.
  • The certificate manager may take a while to complete. If running manually, do not interrupt the process.
  • Renewing a CA certificate will result in each node being updated with the new CA details. A status summary of these update jobs can be shown using cert_manage status.
    It is recommended that these be allowed to complete before using cert_manage run to make further changes. If renewing the CA and Lighthouse VPN certificates, the certificate processing will occur on separate scheduled runs to avoid a limitation where the Lighthouse VPN certificate is renewed before all nodes are informed of the CA renewal.
    If the Lighthouse VPN certificate renewal is forced too early, any nodes that did not receive the CA renewal notification will be disconnected and will require re-enrollment into Lighthouse.

For an external certificate authority:

  • An external CA can only be configured on a Lighthouse that does not have any Opengear devices or secondary instances enrolled.
  • The cert_manage sub commands run, renew, validity, and offset are disabled and an error message is displayed when they are run.

 

Command Description
cert_manage

  • The cert_manage CLI tool can only be run on a primary lighthouse, by a root user. A lighthouse user may sudo to assume root permissions.

  • This tool cannot be run on a secondary Lighthouse.

  • The cert_manage tool is not tied to a specific license or subscription.

  • For internal CA's only, certificate renewal jobs are scheduled using cron to run at 1am (Lighthouse time), every day. An administrator may choose to update the frequency of the cron job under /etc/cron.d/rotate_certificates.cron.
Syntax
cert_manage [-h] [--config CONFIG_URI] {run,renew,show,status,validity,offset,external-ca,logs}
Option Description
-h | --help Display usage information and exit.
--config CONFIG_URI Config file for lipy.
Sub-Command Description
run Process certificates due for renewal (current time > renewal time) and rotate them.
renew Schedule certificates for early renewal. Updates the renewal time of specified certificates to current time. The next certificate manager run will renew them. This will happen overnight or can be triggered using the run command. The number of certificates being scheduled or processed for renewal is displayed.
show Show certificate or default value information. Display information for all specified certificates, or it can display the default values that are used for newly created certificates.
status Show status summary including job status.
validity Set default validity period for new certificates.
offset Set renewal offset period in days to update the delta between expiry and renewal time for the specified certificates. The renewal period is calculated from the certificate expiry date using the offset.
external-ca Configure external Certificate Authority for Lighthouse.
logs Prints the last 20 logs from the log file /var/log/cert_manager.log.

Sub-Command :: run

Note: When an external CA is configured, this sub-command is disabled.

Syntax
cert_manage run [-h] [--dry-run]
Option Description
-h | --help Display usage information and exit.
--dry-run Lists affected certificates.

Sub-Command :: renew

Note: When an external CA is configured, this sub-command is disabled.

Syntax
cert_manage renew [-h] (--cn COMMON_NAMES [COMMON_NAMES ...] | --ca | --nodes | --all-clients) [--dry-run]
Option Description
-h | --help Display usage information and exit.
--cn COMMON_NAMES [COMMON_NAMES ...] Specify certificates by Common Name.
--ca Certificate Authority certificate.
--nodes Certificates for all enrolled nodes.
--all-clients All existing client certificates.
--dry-run Lists affected certificates without executing the action.

Sub-Command :: show

Syntax
cert_manage show [-h] (--cn COMMON_NAMES [COMMON_NAMES ...] | --ca | --nodes | --all-clients | --defaults)
Option Description
-h | --help Display usage information and exit.
--cn COMMON_NAMES [COMMON_NAMES ...] Specify certificates by Common Name.
--ca Certificate Authority certificate.
--nodes Certificates for all enrolled nodes.
--all-clients All existing client certificates.
--defaults Show certificate defaults.

Sub-Command :: validity

Note: When an external CA is configured, this sub-command is disabled.

Syntax
cert_manage validity [-h] --days NUM_DAYS (--default-client | --default-ca) [--dry-run]
Option Description
-h | --help Display usage information and exit.
--days NUM_DAYS Number of days from current time.
--default-client Specify the default value for new client certificates.
--default-ca Specify the default value for new CA certificates.
dry-run Lists affected certificates without executing the action.

Sub-Command :: offset

Note: When an external CA is configured, this sub-command is disabled.

Syntax
cert_manage offset [-h] --days NUM_DAYS (--cn COMMON_NAMES [COMMON_NAMES ...] | --ca | --nodes | --all-clients | --default-client | --default-ca) [--dry-run]
Option Description
-h | --help Display usage information and exit.
--days NUM_DAYS Number of days from expiry.
--cn COMMON_NAMES [COMMON_NAMES ...] Specify certificates by Common Name.
--ca Certificate Authority certificate.
--nodes Certificates for all enrolled nodes.
--all-clients All existing client certificates.
--default-client Specify the default value for new client certificates.
--default-ca Specify the default value for new CA certificates.
dry-run Lists affected certificates without executing the action.

Sub-Command :: logs

Syntax
cert_manage logs [-h]
Option Description
-h | --help Display usage information and exit.

Sub-Command :: external-ca

Syntax
cert_manage external-ca [-h] ([--show] | [--edit] | [--init] | [--check-cert-status])
Option Description
-h | --help Show this help message and exit.
--show Display the current external certificate authority configuration.
--edit Add or edit the external certificate authority configuration.
--init Initialize the external certificate after configuration.
--check-cert-status Query the external CA using OCSP to determine the status of all active certificates.