Configure NGINX Controller with the Helper Script

Overview

You can use the helper.sh script found at /opt/nginx-controller/ to:

  • Retrieve NGINX license information.
  • Start, stop, and restart NGINX Controller.
  • Update the NGINX Controller settings that were applied during the installation process.

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.

Usage

/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

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

NGINX Controller 3.10 and Later

If you’re running NGINX Controller 3.10 or later, use the NGINX Controller API to get the NGINX Plus certificate and key bundle. To do this, send a GET request to the /platform/licenses/nginx-plus-licenses/controller-provided endpoint (Note: controller-provided is the default license name).

NGINX Controller 3.0–3.9

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:
Ensure you have 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

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

Environment Variables

Important: 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 set these SMTP options as environment variables for NGINX Controller:

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

Example

CTR_SMTP_HOST=192.0.2.0 \
CTR_SMTP_PORT=25 \
CTR_SMTP_TLS=false \
CTR_SMTP_FROM=[email protected] \
CTR_SMTP_AUTH=true CTR_SMTP_USER=user1 CTR_SMTP_PASS=password1 \
/opt/nginx-controller/helper.sh configsmtp

Command-line Interface

Usage

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

Example

/opt/nginx-controller/helper.sh configsmtp 192.0.2.0 25 false [email protected] true user1 password1

Update Database Settings

You can 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).

Environment Variables

Important: 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 set these database options as environment variables for NGINX Controller:

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

Example

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

Command-Line Interface

Usage

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

Example

/opt/nginx-controller/helper.sh configdb 192.0.2.0 5432 user1 password1 false

Update or Replace TLS Certificates

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

Command-Line Interface

Usage

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

This documentation applies to the following versions of NGINX Controller Documentation:
3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9 and 3.10.