Back Up and Recovery

Follow the steps in this guide to back up and restore the essential system files for the NGINX Management Suite platform and modules.

Overview

NGINX Management Suite includes several scripts, which you can run to back up and restore the configuration files, secrets, and databases used by the NGINX Management Suite platform.
Additionally, to back up and restore data for specific modules, such as API Connectivity Manager, you can edit the provided scripts and uncomment the commands in the relevant sections.

Important:
The backup and recovery scripts are provided for reference and may need to be adapted to suit the requirements of your deployment.

NGINX Management Suite and modules deployed in a Virtual Machine or Bare Metal

Before You Begin

To complete the instructions in this guide, you need the following:

An installed version of Instance Manager
(optional) An installed version of API Connectivity Manager
(optional) An installed version of App Delivery Manager
An installed version of SQLite. Refer to the Install SQLite guide for installation instructions.
The NGINX Management Suite services must be running:
```
sudo systemctl start nms
```

Make Scripts Executable

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

Open a secure shell (SSH) connection to the NGINX Management Suite host and log in.
Change to the directory where the scripts are located:
```
cd /etc/nms/scripts
```

Run the following commands to make the scripts executable:

sudo chmod +x backup.sh
sudo chmod +x restore.sh
sudo chmod +x backup-acm.sh
sudo chmod +x restore-acm.sh
sudo chmod +x backup-adm.sh
sudo chmod +x restore-adm.sh
sudo chmod +x support-package.sh

Back Up and Restore NGINX Management Suite

To back up the NGINX Management Suite configuration files, secrets, and databases:

Open a secure shell (SSH) connection to the NGINX Management Suite host and log in.
To back up NGINX Management Suite, run the following commands:
```
cd /etc/nms/scripts
sudo ./backup.sh
```
The backup is saved to a tarball file similar to the following example: /tmp/nms-backup-<DATETIME>.tgz

To restore NGINX Management Suite:

Open a secure shell (SSH) connection to the NGINX Management Suite host and log in.

To restore NGINX Management Suite, run the following commands:

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

Back Up and Restore Individual Modules

By default, the data for modules isn’t included in backups for NGINX Management Suite. If you’d like to back up the module data, follow these steps:

Open a secure shell (SSH) connection to the NGINX Management Suite host and log in.

Edit the backup.sh and restore.sh scripts and uncomment the commands in the relevant sections.

To back up and restore data for API Connectivity Manager, uncomment the following lines, like so:

backup.sh: enable backups for API Connectivity Manager

## Back up API Connectivity Manager
# Uncomment the following line to back up API Connectivity Manager.
./backup-acm.sh

Uncomment the following section as well:

## Back up API Connectivity Manager
# Uncomment the following line to back up API Connectivity Manager.
ACM_ACTIVE=$(systemctl is-active --quiet nms-acm)
IS_ACM_ACTIVE=$?
if [ $IS_ACM_ACTIVE -ne 0 ]; then
    echo "You need to start the required NGINX Management Suite services before running the backup script."
    echo "Please ensure the following nms service is running:"
    echo "nms-acm"
    exit 1
fi

restore.sh: enable restore for API Connectivity Manager

## Restore the API Connectivity Manager database.
# Uncomment the following line to restore API Connectivity Manager.
./restore-acm.sh

To back up and restore data for App Delivery Manager, uncomment the following lines, like so:

This topic documents an early access feature. These features are provided for you to try before they are generally available. You shouldn't use early access features for production purposes.

backup.sh: enable backups for App Delivery Manager

## Back up App Delivery Manager
# Uncomment the following line to back up App Delivery Manager.
./backup-adm.sh

restore.sh: enable restore for App Delivery Manager

## Restore the App Delivery Manager database.
# Uncomment the following line to restore App Delivery Manager.
./restore-adm.sh

To create a backup, run the back up script:
```
sudo ./backup.sh
```
To restore from a backup:
- Run sudo rm -rf /var/lib/nms/dqlite/* to remove the existing database files.
- Make sure the NGINX Management Suite service is stopped
```
sudo systemctl stop nms
```
- Run the restore script:
```
sudo ./restore.sh /tmp/nms-backup-<DATETIME>.tgz
```

NGINX Management Suite and modules deployed in a Kubernetes Cluster

Before You Begin

To complete the instructions in this guide, you need the following:

An installed version of NGINX Management Suite and Instance Manager
(optional) An installed version of API Connectivity Manager
(optional) An installed version of App Delivery Manager
An installed version of SQLite. Refer to the Install SQLite guide for installation instructions.

Root Access

The Kubernetes backup and restore scripts for NGINX Management Suite are executed using sudo and use the Kubernetes command kubectl internally to access the Kubernetes API. It is necessary to ensure the target Kubernetes cluster is accessible to the root user.

To confirm that the root user has access to the Kubernetes API, execute the following command:
```
sudo kubectl -n nms get pods
```
If the result is error-free and the output is the list of currently running pods/nodes the root user has the required access.

If the root user does not have the required access, you will need to configure the root user to have Kubernetes API access, or provide the script with the location of the Kubernetes configuration via the environment variable KUBECONFIG. For example:
- To back up NGINX Management Suite:
```
sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-backup.sh
```
- To restore NGINX Management Suite:
```
sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-restore.sh -i <path to backup file> -r
```
In the examples above, /etc/kubernetes/admin.conf is the default configuration location of a Kubernetes cluster. If the configuration location is different for the target Kubernetes cluster, update the commands above accordingly.
Utility pod

This topic documents an early access feature. These features are provided for you to try before they are generally available. You shouldn't use early access features for production purposes.

To back up and restore NGINX Management Suite in a Kubernetes cluster, you need to install the utility pod in your Kubernetes cluster. Optionally, for each module you want to back up and restore, you need to configure the utility pod accordingly:
1. Update your Helm Deployment values.yaml file, add the utility: true line to enable the utility pod, and the required sections under nmsModules to enable the modules you want to back up and restore. For example, if you have API Connectivity Manager and App Delivery Manager installed, add the following:
```
global:
    utility: true
    nmsModules :
        nsm—acm:
            enabled: true
            addClaimsToUtility: true
        nms—adm :
            enabled: true
            addClaimsToUtility: true
```
2. Upgrade your NGINX Management Suite deployment to apply the changes.
3. Download the NGINX Management Suite Helm chart for your currently installed version of NGINX Management Suite:
```
helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update
helm pull nginx-stable/nms
tar zxvf nms-<version>.tgz
```

Back Up

To back up NGINX Management Suite deployed in a Kubernetes cluster, follow these steps:

Copy the extracted backup scripts to your working directory:
- For NGINX Management Suite and API Connectivity Manager, copyk8s-backup.sh from the nms-<version>/charts/nms-hybrid/backup-restore/ directory.
- (Optional) For App Delivery Manager, copy k8s-backup-adm.sh from the nms-<version>/charts/nms-adm/backup-restore/directory.
```
cp nms-<version>/charts/nms-hybrid/backup-restore/k8s-backup.sh .
cp nms-<version>/charts/nms-adm/backup-restore/k8s-backup-adm.sh .
```

Make the scripts executable:

chmod +x k8s-backup.sh
chmod +x k8s-backup-adm.sh

(Optional) For App Delivery Manager modules, uncomment the related section in the k8s-backup.sh script as follows:

##  Back up App Delivery Manager
# Uncomment the following lines to back up App Delivery Manager.
export PACKAGE_DIR NMS_HELM_NAMESPACE
./k8s-backup-adm.sh

Run the backup script:
```
./k8s-backup.sh
```
Note:
The backup script does not need the utility pod or sudo permissions to create a backup.
The command will ask for the NGINX Management Suite namespace. The script will create a backup archive in the same directory called k8s-backup-<timestamp>.tar.gz.

Full Restoration: Same Kubernetes Cluster

To restore NGINX Management Suite and the installed modules deployed in the same Kubernetes cluster, follow these steps:

Copy the extracted backup scripts to your working directory:
- For NGINX Management Suite and API Connectivity Manager, copyk8s-restore.sh from the nms-<version>/charts/nms-hybrid/backup-restore/ directory.
- (Optional) For App Delivery Management, copy k8s-restore-adm.sh from the nms-<version>/charts/nms-adm/backup-restore/directory.
```
cp nms-<version>/nms/charts/nms-hybrid/backup-restore/k8s-restore.sh .
cp nms-<version>/nms/charts/nms-adm/backup-restore/k8s-restore-adm.sh .
```

Make the scripts executable:

chmod +x k8s-restore.sh
chmod +x k8s-restore-adm.sh

Copy your k8s-backup-.tar.gz file to the same directory as the k8s-restore.sh script.
Run the restore script:
```
sudo ./k8s-restore.sh -r -i k8s-backup-<timestamp>.tar.gz
```
Note:
The restore script needs root access to Kubernetes for the restore operation.
The script will ask for the NGINX Management Suite namespace. Once the namespace has been provided, the script will consume the specified backup archive.

Note:
The script will use the utility pod to access all the mounted volumes to restore database directories and core-secrets; and kubectl to restore the k8s configmaps and secrets. Before starting the restoration, the script will stop all service pods and start the utility pod. After finishing the restore, it will stop the utility pod and start all service pods.

Data-only Restoration: Restoration to a Different Cluster

To restore NGINX Management Suite and the installed modules into a different Kubernetes cluster, follow these steps:

Copy the extracted backup scripts to your working directory:
- For NGINX Management Suite and API Connectivity Manager, copyk8s-restore.sh from the nms-<version>/charts/nms-hybrid/backup-restore/ directory.
- (Optional) For App Delivery Management, copy k8s-restore-adm.sh from the nms-<version>/charts/nms-adm/backup-restore/directory.
```
cp nms-<version>/nms/charts/nms-hybrid/backup-restore/k8s-restore.sh .
cp nms-<version>/nms/charts/nms-adm/backup-restore/k8s-restore-adm.sh .
```

Make the scripts executable:

chmod +x k8s-restore.sh
chmod +x k8s-restore-adm.sh

Copy your k8s-backup-.tar.gz file to the same directory as the k8s-restore.sh script.
Run the restore script:
```
sudo ./k8s-restore.sh -r -i k8s-backup-<timestamp>.tar.gz -d
```
Note:
The restore script needs root access to Kubernetes for the restore operation.
The script will ask for the NGINX Management Suite namespace. Once the namespace has been provided, the script will consume the specified backup archive.

The restore script will only restore the databases and core secrets. If you want to restore the user passwords too, run the following commands:

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

ClickHouse

ClickHouse supports backup and restore on versions greater than v22.

For instructions on how to back up and restore the ClickHouse database, please refer to ClickHouse’s documentation.

To check your ClickHouse version, run the following command:

clickhouse-server --version