Let's Encrypt

Let’s Encrypt Container Detail

Getting Started with VNS3 Plugin System

The Let’s Encrypt container is deployed to VNS3 as a plugin using the container system.

Please be familiar with the VNS3 Plug-In Configuration Guide.

Let’s Encrypt Container - What does it do?

Following initial setup, the container will run once per month to perform the following actions:

  • Initiate certificate generation/renewal by Let’s Encrypt
  • Perform Let’s Encrypt http challenge verification
  • Upload and install certificates to VNS3 via the VNS3 API

You do not need a Let’s Encrypt account to use this container.

Let’s Encrypt Container - What does it need?

  • A domain name for which certificates will be generated; an A record which resolves to your VNS3 controller’s public IP address must exist.
  • An email address to be associated with the certificate, usually your webmaster address.
  • Your VNS3 controller’s container network IP address. This will be the first address in your container subnet; for example, if your container network is 198.51.100.0/28, VNS3’s address is 198.51.100.1. You can also specify an external VNS3 controller for certificate installation.
  • A VNS3 API token for certificate installation.

Deploying the Let’s Encrypt Container

Getting the Let’s Encrypt Container

The Let’s Encrypt container is available in the VNS3 UI through the Plugin catalog. If you are using an older version of VNS3 or are otherwise unable to use the catalog, you can deploy using the steps below:

The Linux-based (Ubuntu 20.04) Let’s Encrypt Container Image is accessible at the following URL: https://vns3-containers-read-all.s3.amazonaws.com/LetsEncrypt/letsencrypt-2.1-20220623.tar.gz

This is a read-only Amazon S3 storage location. Only Cohesive Networks can update or modify files stored in this location.

This URL can be used in a VNS3 Controller via the Web UI or API to import the container image for use in that controller, or the image can be downloaded locally and uploaded to the controller. General screenshot walkthrough and help available in the Plug-In Configuration Document.

From the Container —> Images page, choose Upload Image.

Provide a name for the image and a short description if you wish.

Select Image File URL and enter the Let’s Encrypt Container Image file URL: https://vns3-containers-read-all.s3.amazonaws.com/LetsEncrypt/letsencrypt-2.1-20220623.tar.gz

Click Upload.

Uploading the Container Image to VNS3

When the Image has imported successfully, its state will be Ready in the Status Column.

Starting a Container from the Image

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.

Allocating a Container from the Image

Name your container, provide a description (optional), and /usr/bin/supervisord as the Command to start the container. If you would like to configure the container with Environment variables, skip to this section.

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.

Launching the Let’s Encrypt Container

Let’s Encrypt Container Firewall Rules

The Let’s Encrypt Container requires the following firewall rules be added to the VNS3 controller. If using VNS3 v6.x or newer, you can create a custom firewall object “lecontainer” from the Variables page and install the following rules as they appear here:

# LetsEncrypt http DNS verification
PREROUTING -i eth0 -m addrtype --dst-type LOCAL --limit-iface-in -p tcp --dport 80 -j DNAT --to ${custom_lecontainer}:80
# LetsEncrypt Container internet access
FORWARD -o eth0 -s ${custom_lecontainer} -j ACCEPT
# LetsEncrypt Container internet access
FORWARD -o plugin0 -d ${custom_lecontainer} -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
# LetsEncrypt Container internet access
POSTROUTING -o eth0 -s ${custom_lecontainer} -j MASQUERADE-ONCE
# LetsEncrypt container API access
INPUT -i plugin0 -s ${custom_lecontainer} -p tcp --dport 8000 -j ACCEPT
# LetsEncrypt container API access
OUTPUT -o plugin0 -d ${custom_lecontainer} -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT

If using an older (whitebox firewall) version of VNS3, use the following rules, replacing ‘<container_ip>’ with your LetsEncrypt container’s address noted in the previous step.

# LetsEncrypt http DNS verification
PREROUTING_CUST -i eth0 -p tcp --dport 80 -j DNAT --to <container_ip>:80
# LetsEncrypt Container internet access
FORWARD_CUST -o eth0 -s <container_ip> -j ACCEPT
FORWARD_CUST -o plugin0 -d <container_ip> -j ACCEPT
POSTROUTING_CUST -s <container_ip> -o eth0 -j MASQUERADE-ONCE
# LetsEncrypt container API access
INPUT_CUST -i plugin0 -s <container_ip> -p tcp --dport 8000 -j ACCEPT
OUTPUT_CUST -o plugin0 -d <container_ip> -p tcp --sport 8000 -j ACCEPT

Configuring the Let’s Encrypt Container

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.

Configuring with Plugin Manager

Choose Manage from the Image’s Action menu.

Navigate to the container Plugin Manager

Once you are in the Plugin Manager, you can edit the configuration file the right side. You will need to input the following information:

  • The controller’s DNS address
  • An email address to be associated with the generated certificates
  • Your VNS3 controller’s Container Network IP address (198.51.100.1)
  • A refreshable API token from your VNS3 controller with 90-day lifetime

Be sure to uncomment the 4 lines before saving the new config.

Lets Encrypt Plugin Manager configuration

Once it is saved you will need to RUN the executable in order for Let’s Encyrpt to pull in the configruation.

Plugin Manager, run executable: RUN NOW

The script will then generate and install a Let’s Encrypt HTTPS certificate, and it will renew that certificate every month for as long as the container runs.

Once the initial certificate generation process has completed (indicated by the message finished_ok), you may log out of the container.

Configuring with Environment Varaibles

If you would like to configure the contianer via Environment Variables , you will need to specify the four following paramters in a comma separated list.

  • The controller’s DNS address
  • An email address to be associated with the generated certificates
  • Your VNS3 controller’s Container Network IP address (198.51.100.1)
  • 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", address="198.51.100.1", token="tokentokentoken"

Allocate. The initial verification and certificate installation happen automatically.

Export a Container Image

In the event that your VNS3 controller needs to be replaced or upgraded, you will need a copy of your configured Let’s Encrypt Container. We recommend creating and downloading an image of your container as a final step of the deployment process:

From the Containers page in the VNS3 web UI, select Action > Save as Image for your new Let’s Encrypt Container. Once that process is complete, you’ll be brought to the Images page. Select Action > Export on the new image, and provide a name.

Once Exporting is complete, you will have the option to download the image locally.