Jump To: Support > KB > NetManager > SSL > certmanage

Using certmanage to centrally manage your certificates

The certmanage script allows you to automate the installation of certificates and private keys across a variety of different server types. At the time of writing it supports:

• Generic Apache webserver (type = apache) - NetBSD-only
• Generic sendmail SMTP server (type = sendmail) - NetBSD-only
• Generic Dovecot IMAP/POP3 server (type = dovecot) - NetBSD-only
• Remote NetManager (all services) (type = netmanager)
• Local NetManager (all services) (type = local)
• NetScaler (type = netscaler)
• Microsoft IIS (including Citrix Storefront) (type = iis)
• UniFi controller (type = unifi) - Linux-only

Services in development:

• Microsoft Network Policy Server (for RADIUS)
• Microsoft Active Directory LDAP

As mentioned above, for some service types, only NetBSD servers are currently supported (i.e. pkgsrc-specific configuration paths and service control scripts).

The services can be checked before installation so that no changes will be made if the certificate is up-to-date. Remote systems are accessed using ssh. Some assumptions are made about how the remote system is configured (e.g. where certificates are stored).

A configuration is used to list and describe the servers to be managed. If you have multiple certificates, you'd use a separate configuration file for each.

Configuration file format

The configuration file is a text file consisting of a list of sections, one per server. The section for each server begins with a friendly name surrounded by [ and ]. For example:

[website]
type=apache
host=root@webserver
testhost=www.mydomain.com
certlink=/etc/openssl/domain.crt
keylink=/etc/openssl/private/domain.key
[mail]
type=netmanager
host=root@netmanager
[netscaler]
type=netscaler
host=nsroot@netscaler01
vservers=StoreFront_HTTPS,Internet
[xdc01]
type=iis
host=administrator@domain@xdc01
testhost=xdc01

Syntax

Syntax:
        certmanage [-fhl] [-s <service>] [-c <config file>] <cert file prefix>
or:
        certmanage [-fhl] [-s <service>] [-c <config file>] -d <domain>

        -c = use given config file, otherwise /etc/certmanage.conf
             or /etc/certmanage.d/<domain>.conf
        -d = look for cert matching this ACME domain instead of prefix
        -f = force installation (skip testhost check)
        -h = this help
        -l = list services and exit (no need to specify cert file)
        -s = only install on named service

If -c is used, the specified configuration file will be used otherwise:

• If -d <domain> is given, then if /etc/certmanage.d/<domain>.conf it will be used otherwise /etc/certmanage.conf
• If -d is not given, then /etc/certmanage.conf will be used

If the prefix is given as e.g. 2026/domain.202604, then the certificate 2026/domain.202604.crt and the key 2026/domain.202604.key will be used.

Generic Apache webserver (type = apache)

Set up root ssh key access as usual for a Linux/Unix machine (add contents of id_ed25519.pub to ~/.ssh/authorized_keys).

Set up your httpd.conf file to use fixed certificate and key names. The intermediate is currently not handled by certmanage, so specify that manually:

SSLCertificateFile /etc/openssl/domain.crt
SSLCertificateKeyFile /etc/openssl/private/domain.key
SSLCACertificateFile /etc/openssl/RapidSSLTLSRSACAG1.cer

Configuration file should include:

• type=apache - to select Apache mode
• host=root@webserver - the host to ssh to, including username
• testhost=www.mydomain.com - the server to check the certificate against. If no port is given, port 443 will be used (otherwise put :port on the end). If a different IP is required (in case of spoofed-up internal DNS record), use testhost=www.domain.com@IP.AD.DR.ES.SS:443
• certlink=/etc/openssl/domain.crt - certificate will be copied with its original filename. If this does not match the given certlink name, then a symbolic link will be created with the given name
• keylink=/etc/openssl/private/domain.key - as above, but for the private key

Generic sendmail SMTP server (type = sendmail)

Set up root ssh key access as usual for a Linux/Unix machine (add contents of id_ed25519.pub to ~/.ssh/authorized_keys).

Set up your .mc file (in /usr/pkg/share/sendmail/cf) to use fixed certificate and key names:

define(`confSERVER_KEY',`/etc/openssl/private/domain.key')
define(`confSERVER_CERT',`/etc/openssl/sendmail.pem')
define(`confCACERT_PATH',`/etc/openssl/')
define(`confCACERT', `/etc/openssl/sendmail.pem')

Configuration file should include:

• type=sendmail - to select Sendmail mode
• host=root@mailserver - the host to ssh to, including username
• testhost=smtp.mydomain.com:25 - the server to check the certificate against. The port should be specified (25 or 587 will use STARTTLS, 465 will not)
• keylink=/etc/openssl/private/domain.key - key will be copied with its original filename. If this does not match the given keylink name, then a symbolic link will be created with the given name
• intermediate=<filename> - the intermediate certificate to use
• mc=<filename> - optionally, the name of a .mc configuration file in /usr/pkg/share/sendmail/cf to rebuild the configuration from. If not given, the service will just be restarted

Generic Dovecot IMAP/POP3 server (type = dovecot)

Set up root ssh key access as usual for a Linux/Unix machine (add contents of id_ed25519.pub to ~/.ssh/authorized_keys).

Set up your dovecot.conf to use fixed certificate and key names:

ssl_cert=</etc/openssl/dovecot.pem
ssl_key=</etc/openssl/private/domain.key

Configuration file should include:

• type=dovecot - to select Dovecot mode
• host=root@mailserver - the host to ssh to, including username
• testhost=imap.mydomain.com:993 - the server to check the certificate against. The port should be specified (143 will use STARTTLS, 993 will not)
• keylink=/etc/openssl/private/domain.key - key will be copied with its original filename. If this does not match the given keylink name, then a symbolic link will be created with the given name
• intermediate=<filename> - the intermediate certificate to use

Remote NetManager (all services) (type = netmanager)

Set up root ssh key access as usual for a NetManager (add contents of id_ed25519.pub to ~/.ssh/authorized_keys.local and run /usr/libexec/build/ssh).

Configuration file should include:

• type=netmanager - to select NetManager mode
• host=root@mailserver - the host to ssh to, including username

Local NetManager (all services) (type = local)

Configuration file should include:

• type=local - to select NetManager mode

NetScaler (type = netscaler)

Set up ssh access by:

1. ssh to the primary NetScaler: ssh nsroot@netscaler
2. Drop to a command line: shell
3. Append the contents of id_ed25519.pub by running cat >> /nsconfig/ssh/authorized_keys and pasting the contents of your id_ed25519.pub file into the window. Enter Ctrl-D on a newline to end
4. Ensure the file is readable: chmod 0644 /nsconfig/ssh/authorized_keys

Configuration file should include:

• type=netscaler - to select NetScaler mode
• host=nsroot@netscaler01 - the host to ssh to, including username
• testhost=access.mydomain.com - the server to check the certificate against. If no port is given, port 443 will be used (otherwise put :port on the end). If a different IP is required (in case of spoofed-up internal DNS record), use testhost=www.domain.com@IP.AD.DR.ES.SS:443
• intermediate=<cert name> - OPTIONAL: the name of the certificate that you have already imported into the certificate store, not the filename. The new certificate will be linked to this. This must be specified if not using ACME
• vservers=<vserver1,vserver2,...> - a comma-separated list of vServer names to install the certificate on

Microsoft IIS (including Citrix Storefront) (type = iis)

Set up ssh access to your IIS server by:

1. Go to Manage optional features by searching for optional features on the start menu
2. Find OpenSSH Server and install. Wait for completion
3. Open Services and find the OpenSSH Server service. Set its start type to Automatic (probably initially set Manual)
4. Reboot
5. From NetManager ssh to the Windows server: ssh administrator@domain@server
6. Login with administrator password
7. Write the contents of the id_ed25519.pub file to C:\ProgramData\ssh\administrators_authorized_keys:

   echo <paste contents of id_ed25519.pub> > C:\ProgramData\ssh\administrators_authorized_keys
   

8. Set permissions on authorized_keys file:

   icacls.exe C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"
   

Configuration file should include:

• type=iis - to select IIS mode
• host=administrator@domain@xdc01 - the host to ssh to, including username
• testhost=xdc01 - the server to check the certificate against. If no port is given, port 443 will be used (otherwise put :port on the end)
• site=<sitename> - optionally, the name of the site in IIS to bind the certificate to. If not given, will use the default of Default Web Site

UniFi controller (type = unifi)

Set up root ssh key access as usual for a Linux/Unix machine (add contents of id_ed25519.pub to ~/.ssh/authorized_keys).

Configuration file should include:

• type=unifi - to select UniFi mode
• host=root@netscaler01 - the host to ssh to, including username
• testhost=unifi.mydomain.com - the server to check the certificate against. If no port is given, port 443 will be used (otherwise put :port on the end)