About Certificates

Administrators can add a certificate of their own generation to GroundWork Monitor 8 by placing it in the revproxy container and restarting nginx.  This is done with a docker_cmd.sh entry point for the system. There's no need to go digging about in the containers for the right path.

As certificates are keyed to a specific hostname (normally a fully-qualified domain name or FQDN), the name of the server has to match that of the generated certificate. That is, if you generated the certificate for the "common name" of "groundwork.example.com", then you have to change the name of the server to "groundwork.example.com". This can be done either separately or when loading a certificate. You can now have up to two names and two certificates for each GroundWork server to respond to, a primary name and an alternate name.

All GroundWork 8 servers have a self-signed certificate installed by default.  

In situations where the GroundWork server itself is acting as an HTTPS client to another system such as parent-child servers, LDAPs, and other situations where root CA certificates (and sometimes intermediate certificates) must be validated on the GroundWork server, you can also upload these to the GroundWork containers. 

This is useful when you are using a private CA, or perhaps a very new CA for which the root CA package included in the GroundWork containers does not include the new root. If you are using self-signed or established public CA certs, you will not need to do this. 

Additionally, you may want to check out this Blog post 

Adding Certificates 

Changing the Server Name

To just change the name, you can do so with the following steps:

  1. Access the command line on your GroundWork server and change to the gw8 directory: 

    cd gw8
    CODE

  2. Issue the following commands, substituting the name of your system for the example name here: 

    TAG=$(grep '^TAG=' .env | sed 's/^TAG=//')
docker run --rm -t \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --name gw8 groundworkdevelopment/gw8:${TAG} \
    /src/docker_cmd.sh setServerName groundwork.example.com

    or, to add or change the alternate name at the same time:

    TAG=$(grep '^TAG=' .env | sed 's/^TAG=//')
docker run --rm -t \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --name gw8 groundworkdevelopment/gw8:${TAG} \
    /src/docker_cmd.sh setServerName groundwork.example.com --alt alternatename.example.com

  3. Restart the nginx process with the following command: 

    docker-compose exec revproxy bash -e -c "nginx -t; /etc/init.d/nginx reload"
    CODE

  4. Typically, the file value of GW8_INSTANCE_NAME in the gw8.env file should be changed to match the primary name, for example: 

    GW8_INSTANCE_NAME=groundwork.example.com

Load Certificates    

To change the name AND load certificates at the same time, follow the steps below. 

Prerequisites

You need the certificate key file, the certificate file, and any intermediate certificate files for the primary and optionally the alternate common names. You also need to know the precise common name you generated it for (unless you are using a wildcard cert, which is more forgiving). 

For example, if your key file is called server.key, your cert file server.crt and your intermediate cert called intermediate.pem, you can follow these steps:

  1. Transfer the certificate key and files to the server and place them in the gw8 directory.

  2. Access the command line on your GroundWork server and change to the gw8 directory: 

    cd gw8
    CODE

  3. Issue the following commands, substituting in the names of your server and cert files for the examples provided:

    TAG=$(grep '^TAG=' .env | sed 's/^TAG=//')
docker run --rm -t \
    -v ${PWD}:/mnt \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --name gw8 groundworkdevelopment/gw8:${TAG} \
    /src/docker_cmd.sh loadCertificates groundwork.example.com \
    primary.server.key primary.server.crt intermediate.pem

    or, if also loading an alternate certificate, for example: 

    TAG=$(grep '^TAG=' .env | sed 's/^TAG=//')
docker run --rm -t \
    -v ${PWD}:/mnt \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --name gw8 groundworkdevelopment/gw8:${TAG} \
    /src/docker_cmd.sh loadCertificates groundwork.example.com \
    --alt alternatename.example.com \
    primary.server.key primary.server.crt intermediate.pem \
    --altcerts alternate.server.key alternate.server.crt intermediate.pem

    Of course, you would use the names of your own servers and certificates here. 

  4. Restart the nginx process with the following command: 

    docker-compose exec revproxy bash -e -c "nginx -t; /etc/init.d/nginx reload"
    CODE

  5. Delete at least the key file from the server disk. Be sure to save it offline, somewhere safe.

    rm server.key
    CODE

  6. Don't forget to change the GW8_INSTANCE_NAME in the gw8.env file if you changed it in the steps above. The primary name and the instance name there should be the same.

    Tips

    • Best practice would be to keep all the certificates and key files in an encrypted offline vault, and only temporarily transfer them around like this.
    • When you specify the cert names, don't include any path information. The command will look in the current directory for the files and pull them from there. If you see errors relating to the cert files not being found, this is most likely the cause. 

Adding Root CA Certs to Containers

If you are using a private CA, and you need to use Parent-Child servers or LDAPS, or in fact any scenario where your GroundWork Monitor server is acting as an HTTPS client, you will need to allow the GroundWork server to establish a secure connection. If your GroundWork server can't validate your CA certs and establish a valid trust chain through any intermediate certs, you may not be able to use those servers effectively, and you will see errors in the logs. 

In addition, often private CA systems use intermediate certs to control revocation. If these are not loaded on the servers you contact, you will similarly be unable to validate the connection. Really, your servers should provide the intermediate certs, but many times this is not done or not done correctly, and the intermediate certs are not served. In this case, you will need to add them to your GroundWork server, at least temporarily. The following procedure can be used to load both Root and Intermediate certificates into the GroundWork Containers. 

To install a additional CA certificates, upload the PEM style root and any intermediate certificates individually using the following process:

  1. Transfer your certificates in .pem format to the GroundWork Monitor server, and place them in the gw8 directory where the docker-compose.yaml file for GroundWork Monitor resides. 

  2.  If your certificate is called my-cacert.pem, for example, you can then log in to the GroundWork Monitor server, cd to the gw8 directory, and enter:

    docker run -d --rm --name gw8-upload -v dockergw8_ulg:/usr/local/groundwork/config alpine:3.11 sleep 600
docker cp my-cacert.pem gw8-upload:/usr/local/groundwork/config/cacerts/
docker stop gw8-upload

  3. After uploading, you should restart GroundWork to load the certificates: 

    docker-compose down
    CODE 
    docker-compose up -d
    CODE

    If you prefer, you can just restart the relevant containers instead of the entire system, These are: groundwork, nagios, monarch, cloudhub, and noma_daemon.

Related Resources