Adding certificates to HTTPS

Administrators can add certificates of their own generation to GroundWork Monitor 8 by placing them 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. 

By default all GroundWork 8 servers have a self-signed certificate.  

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
  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"
  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
  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"
  5. Delete at least the key file from the server disk: 

    rm server.key
  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.

Encrypted offline vault

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.

No path

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. 

Related articles