NGINX Documentation

• NGINX Plus
• NGINX Controller
  • Admin Guides
  • Analytics
  • Infrastructure
  • Platform
  • Services
  • API Reference
  • Support
• NGINX App Protect
• NGINX Ingress Controller for Kubernetes
• NGINX Service Mesh
• NGINX Unit
• NGINX Amplify
• F5 DNS Cloud Services

---

What's on this Page

---

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.

---

• Manage Your NGINX Integrations

---