README
¶
Let's Encrypt for NetScaler ADC
Table of Contents
Introduction
Changelog
v0.3.1
System Requirements
Operating System
Native NetScaler ADC binary
Certificate Authorities
NetScaler ADC
User Permission
CLI Commands
Terraform
Running on NetScaler natively
Running Lens
Request mode
Environment variables
Defining environment variables
CLI
Environment variables file
Referencing environment variables
Integrations
1Password
Configuration mode
Configuration
Global configuration
Config path
Organizations
Users
Provider parameters
Examples
Certificate configuration
Request
Challenge
Service
Type
Provider
Provider parameters
Disable DNS propagation check
Installation
Introduction
Let's Encrypt for NetScaler ADC (aka LENS) is a tool which allows you to generate certificates based on the well-known ACME protocol. It is based on the fantastic library from the people at https://github.com/go-acme/lego to provide the functionality to talk to different DNS providers, but now also NetScaler ADC.
Changelog
v0.3.1
-
Changed global application flags to accommodate a global configuration file and environment variables file flag
- changed -f / --config to -c / --configFile
- added -e / --envFile
- This also frees up the -f parameter to be changed later to a --force parameter
-
Added provider parameters to global configuration file for use with DNS providers which require environment variables to be set when being used.
- For more information on available providers, see https://go-acme.github.io/lego/dns/
System requirements
Operating system
We provide binaries for different operating systems and architectures:
- Linux (amd64/arm64)
- MacOS (Intel/Apple Silicon)
- Windows (amd64/arm64)
- FreeBSD (amd64/arm64), versions > FreeBSD 11
Native NetScaler ADC binary
Lens was initially designed to be run on NetScaler appliances directly as well.
Since NetScaler is based on a heavily modified FreeBSD, this shouldn't pose any problems.
This tool is based on Go 1.21, because we wanted to make use of the standard library structured logging (slog) to provide a uniform logging infrastructure across all our tools/libraries. However, since Go 1.19, support for FreeBSD 11 and older was dropped, given that the last version of FreeBSD 11 (11.4) was end-of-life since June 23, 2020. For more information, visit https://tip.golang.org/doc/go1.18#freebsd
The latest release of NetScaler, 14.1 is still based on FreeBSD 11.4
> uname -p -r -s -m
FreeBSD 11.4-NETSCALER-14.1 amd64 amd64
Again, NetScaler is based on a heavily modified FreeBSD operating system, but base OS is still FreeBSD 11.4. As such, it is currently not possible to run the tool on a NetScaler directly.
Certificate Authorities
By default, we support both staging and production environments for Let's Encrypt. Lens is designed to work with other certificate authorities who provide access through the ACME protocol.
If you are a user of other ACME-protocol based services, such as Sectigo, please reach out, so we can ensure maximum compatibility!
NetScaler ADC
User permissions
- You will need a user account with the following permissions:
- <TBD>
For easy configuration, we provide the necessary commands to create the command policy on NetScaler ADC in the section below.
</TBD>
</TBD>
Running on NetScaler ADC natively
If you run the binary natively on NetScaler ADC:
- You will need internet access to connect to your ACME service of choice if you want to run natively on NetScaler ADC
- You wil need connectivity with either the NSIP or SNIP address for the environments to which you will connect.
Running Lens
__ _______ _______
/ / / ____/ | / / ___/
/ / / __/ / |/ /\__ \
/ /___/ /___/ /| /___/ /
/_____/_____/_/ |_//____/
Let's Encrypt for NetScaler ADC
Usage:
lens [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
request Request mode
Flags:
-c, --configFile string config file name (default "config.yaml")
-e, --envFile string environment file name (default "variables.env")
-h, --help help for lens
-l, --loglevel string log level
-p, --path string config file path, do not use with -s
-s, --search strings config file search paths, do not use with -p (default [/etc/corelayer/lens,/nsconfig/ssl/LENS,$HOME/.lens,$PWD,%APPDATA%/corelayer/lens,%LOCALAPPDATA%/corelayer/lens,%PROGRAMDATA%/corelayer/lens])
Use "lens [command] --help" for more information about a command.
NOTE: do not use the same file name for both the config file and environment variables file, e.g. config.yaml and config.env, unless you specify the path of the config files using the -p flag
Due to a bug in spf13/viper, the wrong file might get loaded in memory, causing an unexpected application exit.
By default, lens will be looking for a global configuration file in the following paths:
- /etc/corelayer/lens
- /nsconfig/ssl/LENS
- $HOME/.lens
- $PWD (the current working directory)
- %APPDATA%
- %LOCALAPPDATA%
- %PROGRAMDATA%
Global Flags:
-
-c / --configFile: allows you to specify a custom global configuration file
-
-e / --envFile: allows you to specify an environment variables file
-
-p / --path: allows you to specify to path for the global configuration file
-
-s / --search: allows you to specify multiple search paths
-
-l / --loglevel [debug | info | warning | error]: allows you to specify a loglevel, the default is "info"
Request mode
__ _______ _______
/ / / ____/ | / / ___/
/ / / __/ / |/ /\__ \
/ /___/ /___/ /| /___/ /
/_____/_____/_/ |_//____/
Let's Encrypt for NetScaler ADC - Request Mode
Usage:
lens request [flags]
Flags:
-a, --all request all
-h, --help help for request
-n, --name string request name
Global Flags:
-c, --configFile string config file name (default "config.yaml")
-e, --envFile string environment file name (default "variables.env")
-l, --loglevel string log level
-p, --path string config file path, do not use with -s
-s, --search strings config file search paths, do not use with -p (default [/etc/corelayer/lens,/nsconfig/ssl/LENS,$HOME/.lens,$PWD,%APPDATA%/corelayer/lens,%LOCALAPPDATA%/corelayer/lens,%PROGRAMDATA%/corelayer/lens])
You can either request one single certificate or all configured certificates at once. For a single certificate, you need to specify the name of the configuration using the -n/--name flag.
Flags:
- -a / --all: make a request for all configured certificates
- -n / --name: specify the certificate to be requested
Both flags are mutually exclusive!
The global flags are still applicable and can be used accordingly.
Environment variables
Environment variables can be set in two ways:
- Directly on the command-line
- Using an .env file
NOTE: both can be used at the same time
Defining environment variables
Always prefix the environment variable with LENS_.
Other environment variables will not be used to replace variable placeholders in the config files.
Example:
LENS_NAME=corelayer_acme lens request -a
You do not need to prefix the environment variable in the file. However, when referencing the variable in a config file, you must prefix
Example: variables.env
NAME=corelayer_acme
CLI: lens request -e variables.env
Referencing environment variables
You can reference the environment variables in the global configuration file.
If we take the preceding sections as an example, we have LENS_NAME or NAME as an environment variable.
We can now use that variable as a reference using ${LENS_NAME} as the value of a parameter.
See Multiple environments - with environment variable file for more information.
Integrations
Using 1password-CLI (op), you can integrate your password vault for use with environment variables.
For more information, check out 1Password Command-Line tool and the documentation.
When you have set up 1password-CLI, you can start referencing items in your vault:
Configuration mode
Not implemented
The goal is to be able to configure lens from the command line.
Configuration
Configuration for lens is done using YAML files and is split up in 2 parts:
- global configuration
- certificate configuration
As the global configuration needs to have all account details for the different environments to which you need to connect, this file is separated and can be stored in a secured location with appropriate permissions.
- On Linux, this would typically be /etc/corelayer/lens for example, which can have the necessary permissions to only allow root access or access from the user account intended to run lens.
The individual certificate configuration files can be stored elsewhere on the system with more permissive access, as it will only contain the certificate configuration. References to the environments are made using the name of the configured environment.
Global configuration
configPath: <path to the individual certificate configuration files>
organizations:
- name: <organization name>
environments:
- name: <environment name>
type: <standalone | hapair | cluster>
management:
name: <name for the management address>
address: <management ip address / fqdn>
nodes:
- name: <name for the individual node>
address: <NSIP address / fqdn>
credentials:
username: <username>
password: <password>
connectionSettings:
useSsl: <true | false>
timeout: 3000
validateServerCertificate: <true | false>
logTlsSecrets: <true | false>
autoLogin: <true | false>
users:
- name: <user name for reference in certificate configuration files>
email: <user e-mail address>
eab:
kid: <kid for external account binding>
hmacEncoded: <hmac key for external account binding>
- name: <user name for reference in certificate configuration files>
email: <user e-mail address>
eab:
kid: <kid for external account binding>
hmacEncoded: <hmac key for external account binding>
providerParameters:
- name: <name for the set of parameters>
variables:
- name: <environment variable name>
value: <environment variable value>
- name: <environment variable name>
value: <environment variable value>
As you can see, the global configuration has several sections, which we will discuss in more detail below:
Config path
Organizations
Users
Provider parameters
Examples
- Standalone - using SNIP
- Standalone - using NSIP
- High-Availability pair - using SNIP
- High-Availability pair - using NSIP
- Multiple environments
- Multiple environments - with environment variable file
Global configuration:
configPath: conf.d
organizations:
- name: corelayer
environments:
- name: development
type: standalone
management:
name: vpx-dev-snip
address: 192.168.1.10
nodes:
- name: vpx-dev-001
address: 192.168.1.11
credentials:
username: nsroot
password: nsroot
connectionSettings:
useSsl: true
timeout: 3000
validateServerCertificate: false
logTlsSecrets: false
autoLogin: false
users:
- name: corelayer_acme
email: fake@email.com
Global configuration:
configPath: conf.d
organizations:
- name: corelayer
environments:
- name: development
type: standalone
nodes:
- name: vpx-dev-001
address: 192.168.1.11
credentials:
username: nsroot
password: nsroot
connectionSettings:
useSsl: true
timeout: 3000
validateServerCertificate: false
logTlsSecrets: false
autoLogin: false
users:
- name: corelayer_acme
email: fake@email.com
Global configuration:
configPath: conf.d
organizations:
- name: corelayer
environments:
- name: development
type: hapair
management:
name: vpx-dev-snip
address: 192.168.1.10
nodes:
- name: vpx-dev-001
address: 192.168.1.11
- name: vpx-dev-002
address: 192.168.1.12
credentials:
username: nsroot
password: nsroot
connectionSettings:
useSsl: true
timeout: 3000
validateServerCertificate: false
logTlsSecrets: false
autoLogin: false
users:
- name: corelayer_acme
email: fake@email.com
Global configuration:
configPath: conf.d
organizations:
- name: corelayer
environments:
- name: development
type: hapair
nodes:
- name: vpx-dev-001
address: 192.168.1.11
- name: vpx-dev-002
address: 192.168.1.12
credentials:
username: nsroot
password: nsroot
connectionSettings:
useSsl: true
timeout: 3000
validateServerCertificate: false
logTlsSecrets: false
autoLogin: false
users:
- name: corelayer_acme
email: fake@email.com
Global configuration:
configPath: conf.d
organizations:
- name: corelayer
environments:
- name: development
type: hapair
nodes:
- name: vpx-dev-001
address: 192.168.1.11
- name: vpx-dev-002
address: 192.168.1.12
credentials:
username: nsroot
password: nsroot
connectionSettings:
useSsl: true
timeout: 3000
validateServerCertificate: false
logTlsSecrets: false
autoLogin: false
- name: test
type: hapair
management:
name: vpx-tst
address: vpx-tst.test.local
nodes:
- name: vpx-tst-001
address: 192.168.2.11
- name: vpx-tst-002
address: 192.168.2.12
credentials:
username: nsroot
password: nsroot
connectionSettings:
useSsl: true
timeout: 3000
validateServerCertificate: false
logTlsSecrets: false
autoLogin: false
users:
- name: corelayer_acme
email: fake@email.com
Environment variables file:
NAME1=corelayer_acme1
DEV_PASS=secretPassword
TST_PASS=anotherPassword
Global configuration:
configPath: conf.d
organizations:
- name: corelayer
environments:
- name: development
type: hapair
nodes:
- name: vpx-dev-001
address: 192.168.1.11
- name: vpx-dev-002
address: 192.168.1.12
credentials:
username: nsroot
password: ${LENS_DEV_PASS}
connectionSettings:
useSsl: true
timeout: 3000
validateServerCertificate: false
logTlsSecrets: false
autoLogin: false
- name: test
type: hapair
management:
name: vpx-tst
address: vpx-tst.test.local
nodes:
- name: vpx-tst-001
address: 192.168.2.11
- name: vpx-tst-002
address: 192.168.2.12
credentials:
username: nsroot
password: {LENS_TST_PASS}
connectionSettings:
useSsl: true
timeout: 3000
validateServerCertificate: false
logTlsSecrets: false
autoLogin: false
users:
- name: ${LENS_NAME1}
email: fake@email.com
Certificate configuration
name: <name>
request:
target:
organization: <organization name>
environment: <environment name>
user: <user name referenced from users section in global config file>
challenge:
service: LE_STAGING | LE_PRODUCTION | <custom url>
type: <http-01 | dns-01>
provider: <netscaler-http-global | netscaler-adns | <name of dns provider>
providerParameters: <providerParameters name from global config file>
disableDnsPropagationCheck: <true | false>
keyType: <RSA20248 | RSA4096 | RSA8192 | EC256 | EC384>
content:
commonName: <common name>
subjectAlternativeNames:
- <subjectAlternativeName>
- <subjectAlternativeName>
subjectAlternativeNamesFile: <filename | filepath>
installation:
- target:
organization: <organization name>
environment: <environment name>
replaceDefaultCertificate: <true | false>
sslVirtualServers:
- name: <ssl vserver name>
sniEnabled: <true | false>
sslServices:
- name: <ssl service name>
sniEnabled: <true | false>
As you can see, the configuration is split up in two parts:
- request
- installation
Request
This section holds all the details to be able to request a certificate from your ACME service of choice. We need to specify the organization and environment name to select which NetScaler to talk to.
You can either choose one of the pre-defined services, or specify your own ACME Service URL.
LE_STAGING: Let's Encrypt STAGING EnvironmentLE_PRODUCTION: Let's Encrypt PRODUCTION Environment
We currently either support http-01 or dns-01 as the challenge type.
This tool is primarily meant for use with NetScaler ADC, both for the certificate request as for the installation of the certificate. However, we do support external DNS providers.
netscaler-http-globalnetscaler-adns
Other DNS providers are to be enabled in a future releases.
This tool is primarily meant for use with NetScaler ADC, both for the certificate request as for the installation of the certificate. However, we do support external DNS providers.
netscaler-http-globalnetscaler-adns
Other DNS providers are to be enabled in a future releases.
In case you are executing a challenge from within a network that has split-DNS (different DNS responses on the internet compared to the local network), you might need to set DisableDnsPropagationCheck to true.
When enabled, lens will not wait for any propagation to happen, nor will it check if propagation has succeeded in order for it to complete the challenge.
Installation
Once the certificate request is done, we can install the certificate onto multiple ssl vservers in multiple environments. This is especially useful when having SAN-certificates or wildcard certificates, so they can be bound appropriately on different NetScaler environments.
Note that you cannot have the option replaceDefaultCertificate set to true while having endpoints defined under "sslVserver" and/or "sslServices"
Examples
- Simple certificate
- SAN certificate - using manual entries
- SAN certificate - replace default NetScaler certificate
- SAN certificate - using external file
Certificate configuration:
name: corelogic_dev
request:
target:
organization: corelayer
environment: development
user: corelayer_acme
challenge:
service: LE_STAGING
type: http-01
provider: netscaler-http-global
keyType: RSA4096
content:
commonName: corelogic.dev.corelayer.eu
installation:
- target:
organization: corelayer
environment: development
sslVirtualServers:
- name: CSV_DEV_SSL
sniEnabled: true
Certificate configuration:
name: corelogic_dev
request:
target:
organization: corelayer
environment: development
user: corelayer_acme
challenge:
service: LE_STAGING
type: http-01
provider: netscaler-http-global
keyType: RSA4096
content:
commonName: corelogic.dev.corelayer.eu
subjectAlternativeNames:
- demo.dev.corelayer.eu
- my.dev.corelayer.eu
installation:
- target:
organization: corelayer
environment: development
sslVirtualServers:
- name: CSV_DEV_SSL
sniEnabled: true
Certificate configuration:
name: corelogic_dev
request:
target:
organization: corelayer
environment: development
user: corelayer_acme
challenge:
service: LE_STAGING
type: http-01
provider: netscaler-http-global
keyType: RSA4096
content:
commonName: vpx.dev.corelayer.eu
subjectAlternativeNames:
- vpx-001.dev.corelayer.eu
- vpx-002.dev.corelayer.eu
installation:
- target:
organization: corelayer
environment: development
replaceDefaultCertificate: true
Certificate configuration:
name: corelogic_dev
request:
target:
organization: corelayer
environment: development
user: corelayer_acme
challenge:
service: LE_STAGING
type: http-01
provider: netscaler-http-global
keyType: RSA4096
content:
commonName: corelogic.dev.corelayer.eu
subjectAlternativeNamesFile: corelogic_dev_san.txt
installation:
- target:
organization: corelayer
environment: development
sslVirtualServers:
- name: CSV_DEV_SSL
sniEnabled: true
Subject Alternative Names File (stored next to the certificate configuration file):
demo.dev.corelayer.eu
my.dev.corelayer.eu
Certificate configuration:
name: corelogic_dev
request:
target:
organization: corelayer
environment: development
user: corelayer_acme
challenge:
service: LE_STAGING
type: http-01
provider: netscaler-http-global
keyType: RSA4096
content:
commonName: corelogic.dev.corelayer.eu
installation:
- target:
organization: corelayer
environment: development
sslVirtualServers:
- name: CSV_DEV_SSL
sniEnabled: true
- name: CSV_PUBLICDEV_SSL
sniEnabled: false
- target:
organization: corelayer
environment: test
sslVirtualServers:
- name: CSV_TST_SSL
sniEnabled: true
Directories