Signiant Support

How do I renew the certificate for an off-line Agent? Print


Problem

An off-line Agent cannot contact the Signiant Manager using https.  All Agents renew their certificates with their Manager in an automated fashion provided they can contact the Signiant Manager using https. When the Agent cannot contact the Signiant Manager, the certificate expires. 

Jobs using the Agent will experience expired certificate errors such as:
 
50038 Server certificate rejected: certificate has expired
50035 Secure sockets layer (SSL) handshake failure on the process control client: certificate verify failed
54034 The attempt to connect to agent (sign01srv) has failed

Solution

Complete the following procedures:

Obtain Request File (Windows Agent)
 
A request file is needed from the Agent. This is also known as the Certificate Signing Request (CSR).  On a Windows Agent, do the following to generate a CSR:
  1. Log into the Agent as an Administrator. If the certificate is still reading as valid you must revoke it.
  2. To revoke the certificate, select Trusts > Local Certificates, select the Agent and click Revoke. Be sure to deslect the box to delete the Agent before you click OK.
  3. Find the Signiant install directory. By default this is, c:\Program Files\Signiant\Mobilize\.
  4. Shut down the Signiant Services. There are three services: Signiant Process Controller, Signiant UDP Relay and Signiant Event Monitor.
  5. In the Signiant install directory, backup the bin and security folders. These are important if a recovery is necessary.
  6. In a command window change folder to the Signiant install folder and then change folder to the bin folder
  7. Run the following commands from the command line:    
    > erase *.pem
    > dds_cert getnewcert -key keyless

    Most Agent installations are keyless. If you are unsure if keys are used in Agent installations at your site, assume that they are keyless. If keyed installations are being used, then you can obtain a key from the Manager.  (Obtaining keys is out of the scope of this article.)
    The above command produces a file in the current directory. It is named for the Agent hostname and ends with '_req.pem (for example myserver.acme.com_req.pem). This is the Request file or CSR.
Obtain Request File (UNIX, Linux and OSX Agent)

A request file is needed from the Agent. This is also known as the Certificate Signing Request (CSR).  On a UNIX, Linux or OSX agent, do the following to generate a CSR:
  1. Log into the Agent as the root user.
  2. Locate the bin directory under the Signiant install directory. By default this is /usr/signiant/dds/bin.
  3. Shut down the Signiant Services with the following command:
         > ../init/siginit stop
  4. In the Signiant install directory, backup the bin and security folders. These are important if a recovery is necessary.
  5. In a command window change directory to the Signiant install folder and then change folder to the bin directory.
  6. Run the following commands:
         > rm -f  *.pem
      > ./dds_cert getnewcert -key keyless

    Most Agent installations are keyless. If you are unsure if keys are used in Agent installations at your site, assume that they are keyless. If keyed installations are being used, then you can obtain a key from the Siginant Manager. (Obtaining keys is out of the scope of this article.)
    The above command produces a file in the current directory.  It is named for the Agent hostname and ends with '_req.pem (for example myserver.acme.com_req.pem).  This is the Request file or CSR.

Sign the Request

The Signiant Manager is used to sign the request generated by the dds_cert command. To sign the request do the following:
  1. Login to the Siginant Manager and navigate to Administration > Agents > Install and click Sign Certificate.
  2. Fill out the form. If keyed agent installations are used then supply a key, otherwise enable This organization is keyless. Configure Platform as required.
  3. The large field accepts the contents of the request file. It is not necessary to copy the request file to the Signiant Manager to get the contents of the file into this field. Most operators open the request file on the agent and use the copy and paste commands to get the file content into the field. Copy the entire file contents INCLUDING the BEGIN and END lines. Ensure there are no blank spaces at the beginning or end.
  4. Click Submit Request. The signed certificate is made available. This file is named for the hostname of the Agent and ends with _cert.pem (for example, myserver.acme.com_cert.pem).
  5. Download this file to the computer running the web browser and copy the signed certificate to the Agent. Use a temporary directory or folder like c:\tmp or /tmp on the agent for this file.
Install Signed Certificate (Windows Agent)

There are two ways to import the signed certificate file onto the Agent:
  • If the Signiant install program and sigsetup.inf file are still available, then run the install. The program has an Import Certificate option that can be used to import the file. 
  • If the installer program is not available then use the dds_cert utility to import the signed certificate:
     > dds_cert update -newcert signed_cert_file
    signed_cert_file is the full path to the signed certificate file that was copied onto the Agent.

Install Signed Certificate (UNIX, Linux and OSX Agents)

From a command prompt, run the following command:

> ./dds_cert update -newcert signed_cert_file

signed_cert_file is the full path to the signed certificate file that was copied onto the Agent.

Start the Signiant Processes on the Agent and Test

The last step is to start the Signiant processes on the Agent:
  • On a Windows machine this is done by starting the Signiant services in the Services panel
  • On UNIX, Linux or OSX, run the following:
     > ../init/siginit start
Test that the Agent certificate is valid by accessing the agent using the Signiant Manager, go to Administration > Agents > Configure > Agent Hostname.

Click Status. If information about the Agent is returned then the certificate is goo then run jobs using the Agent to test further.