Manage the NGINX Controller Service and Installation Settings

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.

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

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 v10+, 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 [email protected] 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 for SMTP Options

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’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=[email protected] \
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.0 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 for DB Options

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.

For 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


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.

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, 3.10, 3.11, 3.12, 3.13 and 3.14.