End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller API Management Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller API- Management customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.
End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller Application Delivery Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller Application Delivery customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

Update NGINX Controller Settings with helper.sh

Learn how to update NGINX Controller installation settings and manage the NGINX Controller service using the helper.sh script.

Overview

You can use the NGINX Controller helper.sh script to update NGINX Controller installation settings and manage the NGINX Controller process. This tutorial shows you how to use helper.sh to perform the following tasks:

  • Install the NGINX Controller prerequisites
  • View the version of NGINX Controller that’s installed and running
  • Start, stop, and restart NGINX Controller
  • Back up and restore the NGINX Controller config and encryption keys
  • Restore the embedded config database
  • Get the NGINX Plus repository key and certificate files (deprecated for helper.sh in NGINX Controller v3.9)
  • Update the SMTP settings
  • Update the database settings
  • Update or replace the TLS certificates
  • Print the NGINX Controller logs
  • Create a support package

Install NGINX Controller Prerequisites

You can use the NGINX Controller helper.sh prereqs command to install the required system packages and Docker CE.

Options Description
base Install the required Linux utilities.
docker Install Docker CE.
nfs Install NFS system packages.

To install all of the NGINX Controller prerequisites for your system at the same time, take the following steps:

  1. Download the NGINX Controller installer package from the MyF5 Customer Portal.

  2. Extract the installer package files:

    tar xzf controller-installer-<version>.tar.gz

  3. Run the helper script with the prereqs option:

    cd controller-installer
./helper.sh prereqs
Note:

After you’ve installed NGINX Controller, you can install any of the prerequisites by running the following command:

/opt/nginx-controller/helper.sh prereqs [base|docker|nfs]

 

View the Installed NGINX Version

To see which version of NGINX Controller is installed and running, type the following command:

/opt/nginx-controller/helper.sh version

The output looks similar to the following:

Installed version: 3.14.0
Running version: 3.14.0

 

Start, Stop, and Restart NGINX Controller

You can use the helper.sh script to start, stop, restart, and check the status of the NGINX Controller process.

/opt/nginx-controller/helper.sh controller start
/opt/nginx-controller/helper.sh controller stop
/opt/nginx-controller/helper.sh controller restart
/opt/nginx-controller/helper.sh controller status

 

Back Up and Restore Config and Encryption Keys

After installing NGINX Controller, you should back up the cluster config and encryption keys. You’ll need these if you ever need to restore the NGINX config database on top of a new NGINX Controller installation.

  • To back up the NGINX Controller cluster configuration and encryption keys:

    /opt/nginx-controller/helper.sh cluster-config save

    The file is saved to /opt/nginx-controller/cluster-config.tgz.

  • To restore the cluster’s config and encryption keys, take the following steps:

    /opt/nginx-controller/helper.sh cluster-config load <filename>

 

Restore Embedded Config Database

This section explains how to restore the embedded config database from the latest backup file or a specific, timestamped file.

Important:
If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to restore your NGINX config and encryption keys afterward.

  • To restore the embedded NGINX Controller config database from the latest automated backup, run the following command:

    /opt/nginx-controller/helper.sh backup restore

  • To restore the embedded config database from a specific backup file:

    /opt/nginx-controller/helper.sh backup restore <filename>

    • If you installed the embedded config database on a local volume, the backup files are located in /opt/nginx-controller/postgres_data/.

    • If you installed the embedded config database on an NFS volume, follow the steps in (NFS) Copy Config Database Backup to Local Volume for Restoration to download the backup file to your local volume, and then use the helper.sh script to restore from it.

 

Get NGINX Plus Repository Key and Certificate

To install NGINX Plus as a data plane for NGINX Controller, you need to have the NGINX repository key and certificate files.

Deprecated:
Using the helper.sh script to download your NGINX Plus certificate and key bundle is deprecated in in NGINX Controller v3.9.

See Also:
If you’re running NGINX Controller v3.10+, you can use the REST API to Download the NGINX Plus Cert and Key Bundle.
 

If you’re running NGINX Controller 3.9 or earlier, use the helper.sh script to extract the NGINX repository key and certificate files:

/opt/nginx-controller/helper.sh repository-cred [-c|--cert <file name>] [-k|--key <file name>]
Important:
Make sure that you’ve uploaded your license in NGINX Controller first before running the helper.sh repository-cred command to extract the repository files.
Options Description
-c | --cert Creates a certificate called <file name>. The default file name is nginx-repo.crt in the current directory.
-k | --key Creates a key called <file name>. The default file name is nginx-repo.key in the current directory.

 

Update SMTP Settings

Use the helper.sh script to change the SMTP address; port; TLS; sender; and optionally, the username and password.

/opt/nginx-controller/helper.sh configsmtp <address> <port> <tls> <from> [auth] [username] [password]

For example:

/opt/nginx-controller/helper.sh configsmtp 192.0.2.0 25 false noreply@nginx.test true user1 password1
Options Description
address The host name or IP address of the SMTP server.
port The port of the SMTP server.
tls true or false. Set to true to require SSL for connections to the SMTP server.
from Sender’s email address.
auth true or false. Set to true to authenticate when connecting to the SMTP server.
username The username to use for access to the SMTP server.
password The password to use for access to the SMTP server.

 

Environment Variables

We strongly recommend that you use environment variables, especially for passwords, to prevent exposing sensitive information in system processes (for example, ps, top) and the bash history.

You use these SMTP environment variables with NGINX Controller:

Environment Variables Description
CTR_SMTP_HOST The host name or IP address of the SMTP server.
CTR_SMTP_PORT The port of the SMTP server.
CTR_SMTP_TLS true or false; Set to true to require SSL for connections to the SMTP server.
CTR_SMTP_FROM Sender’s email address.
CTR_SMTP_AUTH true or false; Set to true to authenticate when connecting to the SMTP server.
CTR_SMTP_USER The username to use for access to the SMTP server.
CTR_SMTP_PASS The password to use for access to the SMTP server.

For example:

CTR_SMTP_HOST=192.0.2.0 \
CTR_SMTP_PORT=25 \
CTR_SMTP_TLS=false \
CTR_SMTP_FROM=noreply@nginx.test \
CTR_SMTP_AUTH=true CTR_SMTP_USER=user1 CTR_SMTP_PASS=password1 \
/opt/nginx-controller/helper.sh configsmtp

 

Update Database Settings

Use the helper.sh script to change the external config database address; port; and optionally, the username, password, and certificate authentication. However, if your current installation uses an internal config database, then these settings are read-only and cannot be modified using the helper.sh script (password and certificates will be automatically rotated with each Controller update).

/opt/nginx-controller/helper.sh configdb <address> <port> [username] [password] [ssl] [ca] [cert] [key]

For example:

/opt/nginx-controller/helper.sh configdb 192.0.2.1 5432 user1 password1 false
Options Description
address The host name or IP address of config database.
port The port of the database.
username The username to use for access to the config database.
password The password to use for access to the config database.
ssl true or false. Set to ’true’ to require SSL for connections to the config database.
ca CA certificate file path.
cert Certificate file path.
key Key file path.

 

Environment Variables

We strongly recommend that you use environment variables, especially for passwords, to prevent exposing sensitive information in system processes (for example, ps, top) and the bash history.

You can use these database environment variables with NGINX Controller:

Environment Variables Description
CTR_DB_HOST The host name or IP address of the config database.
CTR_DB_PORT The port of the config database used for incoming connections.
CTR_DB_USER The username for the account to use for access to the config database; must be provided with password.
CTR_DB_PASS The password for the account to use for access to the config database; must be provided with username.
CTR_DB_ENABLE_SSL true or false; Set to true to require SSL for connections to the config database.
CTR_DB_CA CA certificate file path.
CTR_DB_CLIENT_CERT Certificate file path.
CTR_DB_CLIENT_KEY Key file path.

For example:

CTR_DB_HOST=192.0.2.1 \
CTR_DB_PORT=5432 \
CTR_DB_USER=user1 \
CTR_DB_PASS=password1 \
CTR_DB_ENABLE_SSL=false \
/opt/nginx-controller/helper.sh configdb

 

Update or Replace TLS Certificates

Use the helper.sh script to update or replace the TLS certificates that are used to connect to NGINX Controller.

/opt/nginx-controller/helper.sh configtls <cert_file> <key_file>
Options Description
cert_file Certificate file path.
key_file Key file path.

 

To print the NGINX Controller logs, enter the following command:

/opt/nginx-controller/helper.sh logs

 

The NGINX Controller logo in the user interface is replaceable with a custom logo. The requirements being:

  • The logo file is in SVG format.
  • The logo is square in shape.
Note:
The above steps modify the logo in the top left corner and in the menu, not the favicon.

Follow the steps below to replace the logo:

  1. Connect to the NGINX Controller host using ‘ssh’.
  2. Transfer the logo file to NGINX Controller using one of the following methods:
    1. Method 1: Download the file using curl after connecting to the host using the command curl https://example.com/custom-logo.svg.
    2. Method 2: Upload the logo to the host using SCP: scp /local/path/custom-logo.svg user@controller-host:/remote/path.
    3. Method 3: Copy/Paste the logo file.
      1. Copy the logo file to the clipboard before connecting to the host.
      2. After connecting to the host, paste the file.
  3. Run helper.sh setlogo <filename> ( is the name of the SVG file).
  4. Wait for approximately five minutes for the cache to clear and the logo to appear in the user interface.
  5. Re-run the setlogo command on each NGINX Controller node. This has to be done after an upgrade or reinstallation.

 

Create a Support Package

You can create a support package for NGINX Controller that you can use to diagnose issues.

Note:
You will need to provide a support package if you open a ticket with NGINX Support via the MyF5 Customer Portal.
 

/opt/nginx-controller/helper.sh supportpkg [-o|--output <file name>] [-s|--skip-db-dump] [-t|--timeseries-dump <hours>]
Options Description
-o | --output Save the support package file to <file name>.
-s | --skip-db-dump Don’t include the database dump in the support package.
-t | --timeseries-dump <hours> Include the last <n hours> of timeseries data in the support package (default 12 hours).

Take the following steps to create a support package:

  1. Open a secure shell (SSH) connection to the NGINX Controller host and log in as an administrator.

  2. Run the helper.sh utility with the supportpkg option:

    /opt/nginx-controller/helper.sh supportpkg

    The support package is saved to:

    /var/tmp/supportpkg-<timestamp>.tar.gz

    For example:

    /var/tmp/supportpkg-20200127T063000PST.tar.gz

  3. Run the following command on the machine where you want to download the support package to:

    scp <username>@<controller-host-ip>:/var/tmp/supportpkg-<timestamp>.tar.gz /local/path

Support Package Details

The support package is a tarball that includes NGINX Controller configuration information, logs, and system command output. Sensitive information, including certificate keys, is not included in the support package.

The support package gathers information from the following locations:

.
├── database
│   ├── common.dump                                - full dump of the common database
│   ├── common.dump_stderr                         - any errors when dumping the database
│   ├── common-apimgmt-api-client-api-keys.txt     - contents of apimgmt_api_client_api_keys table from the common database
│   ├── common-apimgmt-api-client-groups.txt       - contents of apimgmt_api_client_groups table from the common database
│   ├── common-email-verification.txt              - contents of email_verification table from the common database
│   ├── common-oauth-clients.txt                   - contents of oauth_clients table from the common database
│   ├── common-settings-license.txt                - contents of settings_license table from the common database
│   ├── common-settings-nginx-plus.txt             - contents of settings_nginx_plus table from the common database
│   ├── common-table-size.txt                      - list of all tables and their size in the common database
│   ├── data-table-size.txt                        - list of all tables and their size in the data database
│   ├── postgres-database-size.txt                 - size of every database
│   ├── postgres-long-running-queries.txt          - all queries running longer than 10 seconds
│   ├── system.dump                                - full dump of the system database
│   ├── system-account-limits.txt                  - contents of account_limits table from the system database
│   ├── system-accounts.txt                        - contents of accounts table from the system database
│   ├── system-deleted-accounts.txt                - contents of deleted_accounts table from the system database
│   ├── system-deleted-users.txt                   - contents of deleted_users table from the system database
│   ├── system-users.txt                           - contents of users table from the system database
│   └── system-table-size.txt                      - list of all tables and their size in the system database
├── k8s                                            - output of `kubectl cluster-info dump -o yaml` augmented with some extra info
│   ├── apiservices.txt                            - output of `kubectl get apiservice`
│   ├── kube-system                                - contents of the kube-system namespace
│   │   ├── coredns-5c98db65d4-6flb9
│   │   │   ├── desc.txt                           - pod description
│   │   │   ├── logs.txt                           - current logs
│   │   │   └── previous-logs.txt                  - previous logs, if any
│   │   ├── ...
│   │   ├── daemonsets.yaml                        - list of daemonsets
│   │   ├── deployments.yaml                       - list of deployments
│   │   ├── events.yaml                            - all events in this namespace
│   │   ├── namespace.yaml                         - details of the namespace, including finalizers
│   │   ├── pods.txt                               - output of `kubectl get pods --show-kind=true -o wide`
│   │   ├── pods.yaml                              - list of all pods
│   │   ├── replicasets.yaml                       - list of replicasets
│   │   ├── replication-controllers.yaml           - list of replication controllers
│   │   ├── resources.txt                          - all Kubernetes resources in this namespace
│   │   └── services.yaml                          - list of services
│   ├── nginx-controller                           - contents of the nginx-controller namespace
│   │   ├── apigw-8fb64f768-9qwcm
│   │   │   ├── desc.txt                           - pod description
│   │   │   ├── logs.txt                           - current logs
│   │   │   └── previous-logs.txt                  - previous logs, if any
│   │   ├── ...
│   │   ├── daemonsets.yaml                        - list of daemonsets
│   │   ├── deployments.yaml                       - list of deployments
│   │   ├── events.yaml                            - all events in this namespace
│   │   ├── namespace.yaml                         - details of the namespace, including finalizers
│   │   ├── pods.txt                               - output of `kubectl get pods --show-kind=true -o wide`
│   │   ├── pods.yaml                              - list of all pods
│   │   ├── replicasets.yaml                       - list of replicasets
│   │   ├── replication-controllers.yaml           - list of replication controllers
│   │   ├── resources.txt                          - all Kubernetes resources in this namespace
│   │   ├── services.yaml                          - list of services
│   ├── nodes.txt                                  - output of `kubectl describe nodes`
│   ├── nodes.yaml                                 - list of nodes
│   ├── resources.txt                              - all non-namespaced Kubernetes resources (including PersistentVolumes)
│   └── version.yaml                               - Kubernetes version
├── logs                                           - copy of /var/log/nginx-controller/
│   └── nginx-controller-install.log
├── os
│   ├── cpuinfo.txt                                - output of `cat /proc/cpuinfo`
│   ├── df-h.txt                                   - output of `df -h`
│   ├── df-i.txt                                   - output of `df -i`
│   ├── docker-container-ps.txt                    - output of `docker container ps`
│   ├── docker-images.txt                          - output of `docker images`
│   ├── docker-info.txt                            - output of `docker info`
│   ├── docker-stats.txt                           - output of `docker stats --all --no-stream`
│   ├── docker-version.txt                         - output of `docker version`
│   ├── du-mcs.txt                                 - output of `du -mcs /opt/nginx-controller/* /var/log /var/lib`
│   ├── env.txt                                    - output of `env`
│   ├── firewall-cmd.txt                           - output of `firewall-cmd --list-all`
│   ├── free.txt                                   - output of `free -m`
│   ├── hostname-all-fqdns.txt                     - output of `hostname --all-fqdns`
│   ├── hostname-fqdn.txt                          - output of `hostname --fqdn`
│   ├── hostname.txt                               - output of `hostname`
│   ├── hostsfile.txt                              - output of `cat /etc/hosts`
│   ├── ip-address.txt                             - output of `ip address`
│   ├── ip-neigh.txt                               - output of `ip neigh`
│   ├── ip-route.txt                               - output of `ip route`
│   ├── iptables-filter.txt                        - output of `iptables -L -n -v`
│   ├── iptables-mangle.txt                        - output of `iptables -L -n -v -t mangle`
│   ├── iptables-nat.txt                           - output of `iptables -L -n -v -t nat`
│   ├── iptables-save.txt                          - output of `iptables-save`
│   ├── journal-kubelet.txt                        - output of `journalctl -q -u kubelet --no-pager`
│   ├── lspci.txt                                  - output of `lspci -vvv`
│   ├── netstat-nr.txt                             - output of `netstat -nr`
│   ├── ps-faux.txt                                - output of `ps faux`
│   ├── pstree.txt                                 - output of `pstree`
│   ├── ps.txt                                     - output of `ps aux --sort=-%mem`
│   ├── resolvconf.txt                             - output of `cat /etc/resolv.conf`
│   ├── selinux-mode.txt                           - output of `getenforce`
│   ├── ss-ltunp.txt                               - output of `ss -ltunp`
│   ├── swapon.txt                                 - output of `swapon -s`
│   ├── sysctl.txt                                 - output of `sysctl -a --ignore`
│   ├── systemd.txt                                - output of `journalctl -q --utc`
│   ├── top.txt                                    - output of `top -b -o +%CPU -n 3 -d 1 -w512 -c`
│   ├── uname.txt                                  - output of `uname -a`
│   ├── uptime.txt                                 - output of `cat /proc/uptime`
│   └── vmstat.txt                                 - output of `cat /proc/vmstat`
├── timeseries
│   ├── table-sizes.stat                           - stat table containing controller table sizes
│   ├── events.csv                                 - events table dump in csv
│   ├── events.sql                                 - events table schema
│   ├── metrics_1day.csv                           - metrics_1day table dump in csv
│   ├── metrics_1day.sql                           - metrics_1day table schema
│   ├── metrics_1hour.csv                          - metrics_1hour table dump in csv
│   ├── metrics_1hour.sql                          - metrics_1hour table schema
│   ├── metrics_5min.csv                           - metrics_5min table dump in csv
│   ├── metrics_5min.sql                           - metrics_5min table schema
│   ├── metrics.csv                                - metrics table dump in csv
│   ├── metrics.sql                                - metrics table schema
│   ├── system-asynchronous-metrics.stat           - shows info about currently executing events or consuming resources
│   ├── system-events.stat                         - information about the number of events that have occurred in the system
│   ├── system-metrics.stat                        - system metrics
│   ├── system-parts.stat                          - information about parts of a table in the MergeTree family
│   ├── system-settings.stat                       - information about settings that are currently in use
│   └── system-tables.stat                         - information about all the tables
└── version.txt                                    - Controller version information