NGINX Docs
    • DevCentral

      Connect & learn in our hosted community

    • MyF5

      Your key to everything F5, including support, registration keys, and subscriptions

    • NGINX

      Learn more about NGINX Open Source and read the community blog

Back up and restore

NGINX Instance Manager includes several scripts for backing up and restoring configuration files, secrets, and databases used by the platform.

The backup and restore scripts are provided for reference and may need to be adjusted to suit your specific deployment.

NGINX Instance Manager 2.14.1 and earlier:
If you’re using NGINX Instance Manager version 2.14.1 or earlier, you’ll need to install SQLite to run the backup and recovery scripts.
Some commands and directories still use nms in their paths or names because they were established when NGINX Instance Manager was part of the NGINX Management Suite. These names remain unchanged in this version for consistency with the existing file structure.

To follow the instructions in this guide, make sure you have the following:

  • An installed version of NGINX Instance Manager

  • NGINX Instance Manager services must be running:

    sudo systemctl start nms

To run the backup and restore scripts, you need to set their permissions to make them executable.

  1. Open a secure shell (SSH) connection to the NGINX Instance Manager host and log in.

  2. Navigate to the directory where the scripts are located:

    cd /etc/nms/scripts

  3. Run the following commands to make the scripts executable:

    shell
    sudo chmod +x backup.sh
sudo chmod +x restore.sh
sudo chmod +x support-package.sh

To back up configuration files, secrets, and databases:

  1. Open a secure shell (SSH) connection to the NGINX Instance Manager host and log in.

  2. Run the following commands to back up NGINX Instance Manager:

    shell
    cd /etc/nms/scripts
sudo ./backup.sh

    The backup will be saved as a tarball, similar to this example: /tmp/nms-backup-<DATETIME>.tgz.

To restore NGINX Instance Manager:

  1. Open a secure shell (SSH) connection to the NGINX Instance Manager host and log in.

  2. Run the following commands to restore NGINX Instance Manager:

    shell
    cd /etc/nms/scripts
sudo ./restore.sh /tmp/nms-backup-<DATETIME>.tgz

To complete the steps in this guide, ensure the following:

  • An installed version of NGINX Instance Manager

  • Root Access: You’ll need superuser (sudo) access to run the backup and restore scripts, which use the kubectl command to interact with the Kubernetes API. Ensure that the root user has access to the Kubernetes cluster.

    To verify root access to the Kubernetes API, run this command:

    sudo kubectl -n nms get pods

    If there are no errors and you see a list of running pods/nodes, root access is confirmed.

    If the root user lacks access, configure the Kubernetes API access for root or provide the Kubernetes configuration file path through the KUBECONFIG environment variable:

    KUBECONFIG=/etc/kubernetes/admin.conf

    Replace /etc/kubernetes/admin.conf with the actual configuration path for your cluster if it differs.

  • Utility Pod: Ensure the utility pod is installed in your Kubernetes cluster:

    1. Update your Helm Deployment values.yaml file, adding the following line to enable the utility pod:
    yaml
    global:
    utility: true

    1. Upgrade your NGINX Instance Manager deployment.

    2. Download the Helm chart for the installed version of NGINX Instance Manager:

    shell
    helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update
helm pull nginx-stable/nms
tar zxvf nms-<version>.tgz

To back up NGINX Instance Manager deployed in a Kubernetes cluster:

  1. Copy the backup script k8s-backup.sh from the extracted Helm chart to your working directory:

    cp nms-<version>/charts/nms-hybrid/backup-restore/k8s-backup.sh .

  2. Make the script executable:

    chmod +x k8s-backup.sh

  3. Run the backup script:

    ./k8s-backup.sh
    The backup script does not require sudo permissions or the utility pod.

  4. The script will prompt you for the NGINX Instance Manager namespace. It will create a backup archive called k8s-backup-<timestamp>.tar.gz.

To restore NGINX Instance Manager to the same Kubernetes cluster:

  1. Copy the restore script k8s-restore.sh from the extracted Helm chart to your working directory:

    cp nms-<version>/charts/nms-hybrid/backup-restore/k8s-restore.sh .

  2. Make the script executable:

    chmod +x k8s-restore.sh

  3. Copy your backup file (k8s-backup-<timestamp>.tar.gz) to the same directory as k8s-restore.sh.

  4. Run the restore script:

    sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-restore.sh -i k8s-backup-<timestamp>.tar.gz -r

    If the Kubernetes configuration is different, update the path accordingly.

    The restore script requires root access.

  5. After specifying the NGINX Instance Manager namespace, the script will use the provided backup archive.

    The script uses the utility pod to restore databases and core secrets. It stops service pods during the restoration and restarts them afterward.

To restore NGINX Instance Manager to a different Kubernetes cluster:

  1. Copy the restore script k8s-restore.sh from the extracted Helm chart to your working directory:

    cp nms-<version>/charts/nms-hybrid/backup-restore/k8s-restore.sh .

  2. Make the script executable:

    chmod +x k8s-restore.sh

  3. Copy your backup file (k8s-backup-<timestamp>.tar.gz) to the same directory as k8s-restore.sh.

  4. Run the restore script:

    sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-restore.sh -i k8s-backup-<timestamp>.tar.gz -r -d

    If the Kubernetes configuration differs, update the path accordingly.

    The restore script requires root access.

  5. After specifying the NGINX Instance Manager namespace, the script will restore the databases and core secrets.

If you want to restore user passwords, extract the backup archive and run the following commands:

shell
cd k8s-backup-<version>/secrets
kubectl -n nms apply -f nms-auth.json
kubectl -n nms delete pod apigw-<hash>

ClickHouse supports backup and restore on versions greater than v22.

Refer to ClickHouse’s documentation for backup and restore instructions.

To check your ClickHouse version, run:

clickhouse-server --version