netscaleradc-acme-go

module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 5, 2023 License: Apache-2.0

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.

Back to top


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.

Back to top


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

Back to top

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.

Back to top

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!

Back to top

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.

Back to top

CLI Commands
</TBD>

Back to top

Terraform
</TBD>

Back to top

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.

Back to top


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"

Back to top

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.

Back to top

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

Back to top

Defining environment variables
CLI

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

Back to top

Environment Variables File

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

Back to top

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.

Back to top

Integrations
1Password

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:

Back to top

Configuration mode

Not implemented

The goal is to be able to configure lens from the command line.

Back to top


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.

Back to top

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:

Back to top

Config path

Back to top

Organizations

Back to top

Users

Back to top

Provider parameters

Back to top

Examples

Back to top

Standalone - using SNIP

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

Back to top

Standalone - using NSIP

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

Back to top

High-availability Pair - using SNIP

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

Back to top

High-availability Pair - using NSIP

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

Back to top

Multiple environments

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

Back to top

Multiple environments - with environment variable file

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

Back to top

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

Back to top

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.

Back to top

Challenge
Service

You can either choose one of the pre-defined services, or specify your own ACME Service URL.

  • LE_STAGING: Let's Encrypt STAGING Environment
  • LE_PRODUCTION: Let's Encrypt PRODUCTION Environment

Back to top

Type

We currently either support http-01 or dns-01 as the challenge type.

Back to top

Provider

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-global
  • netscaler-adns

Other DNS providers are to be enabled in a future releases.

Back to top

Provider parameters

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-global
  • netscaler-adns

Other DNS providers are to be enabled in a future releases.

Back to top

DisableDnsPropagationCheck

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.

Back to top

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"

Back to top

Examples

Back to top

Simple certificate

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

Back to top

SAN certificate - using manual entries

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

Back to top

SAN certificate - Replace default NetScaler certificate

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

Back to top

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
    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

Back to top

Simple certificate - multiple installations

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

Back to top


Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL