Using TLS
Tip. This feature is only available on GuardMode 2024.1 or higher.
Transport Layer Security (TLS) is an essential protocol for securing network communications. GuardMode's support for TLS ensures that data transmitted via the Swagger API is encrypted, safeguarding the integrity and confidentiality of your data. This chapter provides a guide on how to implement and manage TLS within GuardMode.
Preparing the TLS Certificate
To use HTTPS with the Swagger API, you will need a certificate file with a .pfx extension. Your certificate needs to be placed in the Certificate subdirectory within the GuardMode installation directory and protected with a password.
Note. If the certificate expires or the password is incorrect, you must replace the expired certificate with a new one or correct the password. Place the new certificate in the designated directory and use the correct password in the TLS enable command as shown below.
Enabling TLS
Attention! GuardMode ensures the TLS certificate’s existence, accessibility, and expiration status at each agent launch. However, it does not validate the certificate against the domain it is intended for. Using a certificate for an incorrect domain will result in failure to establish secure connections.
To enable TLS in GuardMode, run the following CLI command:
This command configures GuardMode to use the specified PFX certificate. If you do not specify a port using the --port option, GuardMode will default to port 5001.
Tip. Instead of using the password directly in the command, you can use the GM_CERTIFICATE_PASSWORD environment variable.
After enabling TLS, you must restart the GuardMode agent to apply the changes.
To restart the GuardMode agent on Linux, run:
To restart the GuardMode agent on Windows, run:
Once you restart the service on Windows, open a new PowerShell session.
Disabling TLS
Deactivate TLS with this CLI command:
A confirmation message will indicate that TLS has been successfully disabled. After disabling TLS, you must restart the GuardMode agent to apply the changes.
Managing Environment Variables
GuardMode handles environment variables differently on Linux and Windows.
On Linux, enabling TLS adds an environment variable to
etc/systemd/system/Catalogic.GuardMode.Agent.service.d/override.conf.On Windows, the environment variables active at the start of a session persist throughout that session. Consequently, any new environment variables are accessible only in future PowerShell sessions, not the current one.
Certificate Expiry and Replacement
An expired TLS certificate will prevent the use of the Swagger API, even with HTTP. The system checks the certificate every time the agent launches.
To update an expired certificate, run the enable command with the new certificate details. You don't need to disable the previous one.
GuardMode TLS CLI Help
For additional help with TLS configuration commands, use the --help option:
This displays usage information, descriptions, and options for the command.
Last updated