| 1 | # Backing up a Netdata Agent |
| 2 | |
| 3 | :::tip |
| 4 | |
| 5 | **What You'll Learn** |
| 6 | |
| 7 | How to back up and restore Netdata Agent data including configuration, metrics, and identity files for disaster recovery scenarios. |
| 8 | |
| 9 | ::: |
| 10 | |
| 11 | :::important |
| 12 | |
| 13 | **User Responsibility** |
| 14 | |
| 15 | Users are responsible for backing up, recovering, and ensuring their data's availability because Netdata stores data locally on each system due to its decentralized architecture. |
| 16 | |
| 17 | ::: |
| 18 | |
| 19 | ## Introduction |
| 20 | |
| 21 | When planning a Netdata Agent backup, it's essential to recognize the types of data that can be backed up, either individually or collectively: |
| 22 | |
| 23 | | Data type | Description | Location | |
| 24 | |---------------------|------------------------------------------------------|-----------------------------------------------------------------| |
| 25 | | Agent configuration | Files controlling configuration of the Netdata Agent | [config directory](/docs/netdata-agent/configuration/README.md) | |
| 26 | | Metrics | Database files | /var/cache/netdata | |
| 27 | | Identity | Claim token, API key and some other files | /var/lib/netdata | |
| 28 | |
| 29 | ## Backup and Restore Scenarios |
| 30 | |
| 31 | <details> |
| 32 | <summary><strong>Backing up to restore data in case of a node failure</strong></summary><br/> |
| 33 | |
| 34 | In this standard scenario, you're backing up your Netdata Agent in case of a node failure or data corruption so that the metrics and the configuration can be recovered. The purpose is not to back up/restore the application itself. |
| 35 | |
| 36 | ### Backup Process |
| 37 | |
| 38 | ```mermaid |
| 39 | graph TB |
| 40 | Start("**Start Backup Process**") |
| 41 | |
| 42 | Verify("**Verify Directory Paths**<br/><br/>Check that paths contain<br/>expected information<br/><br/>/etc/netdata/<br/>/var/cache/netdata<br/>/var/lib/netdata") |
| 43 | |
| 44 | Stop("**Stop Netdata Agent**<br/><br/>Recommended for<br/>Metrics/database files") |
| 45 | |
| 46 | Backup("**Create Backup Archive**<br/><br/>tar -cvpzf netdata_backup.tar.gz<br/>/etc/netdata/ /var/cache/netdata<br/>/var/lib/netdata") |
| 47 | |
| 48 | Restart("**Restart Netdata Agent**<br/><br/>Resume monitoring") |
| 49 | |
| 50 | Start --> Verify |
| 51 | Verify --> Stop |
| 52 | Stop --> Backup |
| 53 | Backup --> Restart |
| 54 | |
| 55 | %% Style definitions |
| 56 | classDef startEnd fill:#f9f9f9,stroke:#000000,stroke-width:3px,color:#000000,font-size:16px |
| 57 | classDef process fill:#ffeb3b,stroke:#000000,stroke-width:3px,color:#000000,font-size:16px |
| 58 | classDef complete fill:#4caf50,stroke:#000000,stroke-width:3px,color:#000000,font-size:16px |
| 59 | |
| 60 | %% Apply styles |
| 61 | class Start startEnd |
| 62 | class Verify,Stop,Backup process |
| 63 | class Restart complete |
| 64 | ``` |
| 65 | |
| 66 | 1. **Verify directory paths** |
| 67 | |
| 68 | Verify that the directory paths in the table above contain the information you expect. |
| 69 | |
| 70 | :::note |
| 71 | |
| 72 | **Path Variations** |
| 73 | |
| 74 | The specific paths may vary depending on the installation method, Operating System, and whether it is a Docker/Kubernetes deployment. |
| 75 | |
| 76 | ::: |
| 77 | |
| 78 | 2. **Stop the Netdata Agent** |
| 79 | |
| 80 | It is recommended that you [stop the Netdata Agent](/docs/netdata-agent/start-stop-restart.md) when backing up the Metrics/database files. Backing up the Agent configuration and Identity folders is straightforward as they shouldn't be changing very frequently. |
| 81 | |
| 82 | 3. **Create a backup archive** |
| 83 | |
| 84 | Using a backup tool such as `tar` you will need to run the backup as _root_ or as the _netdata_ user to access all the files in the directories. |
| 85 | |
| 86 | ```bash |
| 87 | sudo tar -cvpzf netdata_backup.tar.gz /etc/netdata/ /var/cache/netdata /var/lib/netdata |
| 88 | ``` |
| 89 | |
| 90 | Stopping the Netdata Agent is typically necessary to back up the database files of the Netdata Agent. |
| 91 | |
| 92 | ### Minimizing Service Interruption |
| 93 | |
| 94 | If you want to minimize the gap in metrics caused by stopping the Netdata Agent, consider implementing a backup job or script that follows this sequence: |
| 95 | |
| 96 | - Back up the Agent configuration Identity directories |
| 97 | - Stop the Netdata service |
| 98 | - Back up the database files |
| 99 | - Restart the Netdata Agent. |
| 100 | |
| 101 | <br/> |
| 102 | </details> |
| 103 | |
| 104 | <details> |
| 105 | <summary><strong>Restoring Netdata</strong></summary><br/> |
| 106 | |
| 107 | ### Restoration Process |
| 108 | |
| 109 | 1. **Prepare for restoration** |
| 110 | |
| 111 | Ensure that the Netdata Agent is installed and is [stopped](/docs/netdata-agent/start-stop-restart.md) |
| 112 | |
| 113 | If you plan to deploy the Agent and restore a backup on top of it, then you might find it helpful to use the [`--dont-start-it`](/packaging/installer/methods/kickstart.md#optional-parameters-for-kickstartsh) option upon installation. |
| 114 | |
| 115 | ```bash |
| 116 | wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh && sh /tmp/netdata-kickstart.sh --dont-start-it |
| 117 | ``` |
| 118 | |
| 119 | :::warning |
| 120 | |
| 121 | **Database File Restoration** |
| 122 | |
| 123 | If you’re going to restore the database files, then you should first ensure that the Metrics directory is empty. |
| 124 | |
| 125 | ```bash |
| 126 | sudo rm -Rf /var/cache/netdata |
| 127 | ``` |
| 128 | |
| 129 | ::: |
| 130 | |
| 131 | 2. **Restore from backup archive** |
| 132 | |
| 133 | ```bash |
| 134 | sudo tar -xvpzf /path/to/netdata_backup.tar.gz -C / |
| 135 | ``` |
| 136 | |
| 137 | 3. **Start the Netdata Agent** |
| 138 | |
| 139 | [Start the Netdata Agent](/docs/netdata-agent/start-stop-restart.md) |
| 140 | |
| 141 | <br/> |
| 142 | </details> |