HTTPS Certs Manager
Overview
Getting Started with VNS3 Plugin System
Please be familiar with the VNS3 Plug-In Configuration Guide.
HTTPS Certs Manager - What does it do?
Following initial setup, a task will run once per month to perform the following actions:
- Initiate certificate generation/renewal
- Perform challenge verification
- Upload and install certificates to VNS3 via the VNS3 API
HTTPS Certs Manager - What does it need?
- The domain name of your controller, for which certificates will be generated
- An email address to be associated with the certificate, usually your webmaster address
- A refreshing 90-day VNS3 API token for certificate installation
- Outbound internet connectivity
- Inbound tcp80 DNATed to the plugin (only if using HTTP challenge)
You do not need any accounts to use this container with Let’s Encrypt and HTTP challenge type. DNS challenges require a credential or token for auth.
Deploying
Getting the Image
The image is available in the VNS3 UI through the Plugin catalog. Simply navigate to the Plugins -> Catalog page, find the plugin, and click Install.
If you are using an older version of VNS3 or are otherwise unable to use the catalog, you can import the image using this link:
The Linux-based (Ubuntu 20.04) plugin image is accessible at the following URL: https://cohesive-networks.s3.amazonaws.com/plugins/vns3-plugin-httpscertmanager-20250123-3.1.tar.gz
In either case, once the image has imported successfully, its state in the Status Column will change to Ready.
Starting the Plugin
If using a version with Plugin Dashboard, select Start Instance from the Image’s Action menu.
If using an older version or launching from the Developer —> Images page, choose Allocate from the Image’s Action menu.
Name your container, provide a description (optional), and use /opt/cohesive/container_startup.sh as the Command to start the container.
You can allow VNS3 to auto-assign a container network IP, but it is recommended that you choose one explicitly. Take note of this address for the following steps.
If you would like to configure the container with Environment variables, skip to this section before starting the plugin.
Required Firewall Rules
This plugin requires the firewall rules listed below.
# HTTPS Certs Plugin - ONLY needed for http verification - DNAT inbound port 80 to plugin
PREROUTING -i eth0 -m addrtype --dst-type LOCAL --limit-iface-in -p tcp --dport 80 -j DNAT --to ${custom_httpscertsplugin}:80
# HTTPS Certs Plugin - ONLY needed for http verification - allow inbound port 80
FORWARD -i eth0 -p tcp --dport 80 -d ${custom_httpscertsplugin} -j ACCEPT
# HTTPS Certs Plugin internet access - outbound
FORWARD -o eth0 -s ${custom_httpscertsplugin} -j ACCEPT
# HTTPS Certs Plugin internet access - return traffic
FORWARD -o plugin0 -d ${custom_httpscertsplugin} -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
# HTTPS Certs Plugin internet access - outbound SNAT
POSTROUTING -o eth0 -s ${custom_httpscertsplugin} -j MASQUERADE-ONCE
# HTTPS Certs Plugin - VNS3 API access
INPUT -i plugin0 -s ${custom_httpscertsplugin} -p tcp --dport 8000 -j ACCEPT
# HTTPS Certs Plugin - VNS3 API access - return traffic
OUTPUT -o plugin0 -d ${custom_httpscertsplugin} -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
These rules assume you have VNS3 v6 or newer and have created a custom variable named “httpscertsplugin” with the plugin network IP of your plugin. Earlier versions of VNS3 will require that you append “_CUST” to the chain names and replace “${custom_httpscertsplugin}” with your plugin’s IP address manually.
Configuring the Plugin
There are two ways to configure the Let’s Encrypt container: via the Plugin Manager or via Environment Variables specified when you allocate the container.
Using Plugin Manager
Click the name of the plugin instance or choose Manage from the Action menu.
Once you are in the Plugin Manager, you can edit the configuration file the right side. You will need to input the following information at minimum:
- The controller’s DNS name for which certs will be generated
- An email address to be associated with the generated certificates
- A refreshing API token from your VNS3 controller with 90-day lifetime (MUST refresh on use)
Be sure to uncomment the config before saving.
If you are using the DNS challenge type, you must also configure for your DNS provider in the separate config file “DNS Parameters.”
Once config has been saved, run the Gen Certs Executable in Normal mode. You can watch the log for progress. Once complete, refresh your browser and check for the new certificate.
New certificates will be automatically generated and installed on the first of every month.
Using Environment Varaibles
Configuration by environment requires that you provide the following paramters in a comma separated list at launch time:
- The controller’s DNS name for which certs will be generated
- An email address to be associated with the generated certificates
- A refreshable API token from your VNS3 controller with 90-day lifetime
NOTE: The parameters must be in quotes as shown below:
email="support@cohesive.net", domain="test.cohesivetest.net", token="tokentokentoken"
The initial certificate generation and installation happen automatically if sufficient config is provided.
Configuration of DNS challenge type options through env vars is not currently supported; if you require this functionality, please reach out to support.
Final Notes
VNS3 will include your plugin configuration in its system snapshots; we recommend saving these regularly. VNS3 Management System provides options for automatic scheduled snapshotting. Upon recovery with a snapshot file, VNS3 will attempt to download all plugin images from their original URLs and reinstall their saved configuration.
Please reach out to support@cohesive.net with any issues or questions.