opts-310 (#1780)

Update 2.compile-br.md
vesoft-inc · Nov 25, 2022 · 00da75d · 00da75d
1 parent d2a164d
commit 00da75d
Show file tree

Hide file tree

Showing 5 changed files with 140 additions and 38 deletions.
diff --git a/docs-2.0/backup-and-restore/nebula-br/1.what-is-br.md b/docs-2.0/backup-and-restore/nebula-br/1.what-is-br.md
@@ -19,11 +19,9 @@ The BR has the following features. It supports:
 - Supports full backup, but not incremental backup.
 - Currently, NebulaGraph Listener and full-text indexes do not support backup.
 - If you back up data to the local disk, the backup files will be saved in the local path of each server. You can also mount the NFS on your host to restore the backup data to a different host.
-- The backup graph space can be restored to the original cluster only. Cross clusters restoration is not supported.
 - During the backup process, both DDL and DML statements in the specified graph spaces are blocked. We recommend that you do the operation within the low peak period of the business, for example, from 2:00 AM to 5:00 AM.
-- Supports restoration of data on clusters of the same topologies only, which means both clusters must have exactly the same number of hosts.
+- The backup graph space can be restored to the original cluster only. Cross clusters restoration is not supported. Make sure the number of hosts in the cluster is not changed. Restoring a specified graph space will delete all other graph spaces in the cluster.
 - We recommend that you restore the data OFFLINE because it requires removing the data and restart the service.
-- If you back up data of a specified graph space in cluster A and restore the graph space data to cluster B, the data of other graph spaces in cluster B will be deleted.
 <!---When backing up or restoring the data deployed in Docker, network configuration should be done, such as IP and port mapping. -->
 
 <!--
@@ -144,6 +142,6 @@ This figure shows how the restoration process is implemented.
 
 To use the BR, follow these steps:
 
-1. [Compile BR](2.compile-br.md).
+1. [Install BR](2.compile-br.md).
 2. [Use BR to back up data](3.br-backup-data.md).
 3. [Use BR to restore data from backup files](4.br-restore-data.md).
diff --git a/docs-2.0/backup-and-restore/nebula-br/2.compile-br.md b/docs-2.0/backup-and-restore/nebula-br/2.compile-br.md
@@ -1,15 +1,54 @@
-# Compile BR
+# Install BR
 
-For now, the BR is not provided as a package. You need to compile the BR first.
+This topic introduces how to install BR.
 
-## Prerequisites
 
-To compile the BR, do a check of these:
+## Notes
+
+To use the BR (Enterprise Edition) tool, you need to install the NebulaGraph Agent service, which is taken as a daemon for each machine in the cluster that starts and stops the NebulaGraph service, and uploads and downloads backup files. The BR (Enterprise Edition) tool and the Agent plug-in are installed as described below.
+
+
+## Version compatibility
+
+|NebulaGraph|BR |Agent |
+|:---|:---|:---|
+|3.0 ~ 3.2|{{br.release}}|0.1.0 ~ 0.2.0|
+
+
+## Install BR with a binary file
+
+1. Install BR.
+
+  ```
+  wget https://github.com/vesoft-inc/nebula-br/releases/download/{{br.tag}}/br-{{br.release}}-linux-amd64
+  ```
+
+2. Change the binary file name to `br`.
+
+  ```
+  sudo mv br-{{br.release}}-linux-amd64 br
+  ```
+
+3. Grand execute permission to BR.
+
+  ```
+  sudo chmod +x br
+  ```
+
+4. Run `./br version` to check BR version.
+
+  ```
+  [nebula-br]$ ./br version
+  Nebula Backup And Restore Utility Tool,V-{{br.release}}
+  ```
+
+## Install BR with the source code
+
+Before compiling the BR, do a check of these:
 
 - [Go](https://github.com/golang/go "Click to go to GitHub") 1.14.x or a later version is installed.
 - make is installed.
 
-## Procedures
 
 To compile the BR, follow these steps:
 
@@ -35,5 +74,68 @@ Users can enter `bin/br version` on the command line. If the following results a
 
 ```bash
 [nebula-br]$ bin/br version
-Nebula Backup And Restore Utility Tool,V-{{br.release}}
+NebulaGraph Backup And Restore Utility Tool,V-{{br.release}}
 ```
+## Install Agent 
+
+NebulaGraph Agent is installed as a binary file in each machine and serves the BR tool with the RPC protocol.
+
+In **each machine**, follow these steps:
+
+1. Install Agent.
+
+  ```
+  wget https://github.com/vesoft-inc/nebula-agent/releases/download/v{{agent.release}}/agent-{{agent.release}}-linux-amd64
+  ```
+
+2. Rename the Agent file to `agent`.
+
+  ```
+  sudo mv agent-{{agent.release}}-linux-amd64 agent
+  ```
+
+3. Add execute permission to Agent. 
+
+  ```
+  sudo chmod +x agent
+  ```
+
+4. Start Agent.
+
+  !!! note
+
+        Before starting Agent, make sure that the Meta service has been started and Agent has read and write access to the corresponding NebulaGraph cluster directory and backup directory. 
+
+  ```
+  sudo nohup ./nebula_agent --agent="<agent_node_ip>:8888" --meta="<metad_node_ip>:9559" > nebula_agent.log 2>&1 &
+  ```
+
+  - `--agent`: The IP address and port number of Agent.
+  - `--meta`: The IP address and access port of any Meta service in the cluster.
+  - `--ratelimit`: Optional (this option is only available in Agent 0.2.0 and higher versions). Limits the speed of file uploads and downloads to prevent bandwidth from being filled up and making other services unavailable. Unit: Bytes.
+
+  For example: 
+
+  ```
+  sudo nohup ./nebula_agent --agent="192.168.8.129:8888" --meta="192.168.8.129:9559" --ratelimit=1048576 > nebula_agent.log 2>&1 &
+  ```
+  !!! caution
+
+        The IP address format for `--agent`should be the same as that of Meta and Storage services set in the [configuration files](../../5.configurations-and-logs/1.configurations/1.configurations.md). That is, use the real IP addresses or use `127.0.0.1`. Otherwise Agent does not run.
+
+5. Log into NebulaGraph and then run the following command to view the status of Agent.
+
+  ```
+  nebula> SHOW HOSTS AGENT;
+  +-----------------+------+----------+---------+--------------+---------+
+  | Host            | Port | Status   | Role    | Git Info Sha | Version |
+  +-----------------+------+----------+---------+--------------+---------+
+  | "192.168.8.129" | 8888 | "ONLINE" | "AGENT" | "96646b8"    |         |
+  +-----------------+------+----------+---------+--------------+---------+  
+  ```
+
+## FAQ
+
+### The error `E_LIST_CLUSTER_NO_AGENT_FAILURE
+
+If you encounter `E_LIST_CLUSTER_NO_AGENT_FAILURE` error, it may be due to the Agent service is not started or the Agent service is not registered to Meta service. First, execute `SHOW HOSTS AGENT` to check the status of the Agent service on all nodes in the cluster, when the status shows `OFFLINE`, it means the registration of Agent failed, then check whether the value of the `--meta` option in the command to start the Agent service is correct.
diff --git a/docs-2.0/backup-and-restore/nebula-br/3.br-backup-data.md b/docs-2.0/backup-and-restore/nebula-br/3.br-backup-data.md
@@ -1,17 +1,15 @@
 # Use BR to back up data
 
-After the BR is compiled, you can back up data of the entire graph space. This topic introduces how to use the BR to back up data.
+After the BR is installed, you can back up data of the entire graph space. This topic introduces how to use the BR to back up data.
 
 ## Prerequisites
 
 To back up data with the BR, do a check of these:
 
-- The BR is compiled. For more information, see [Compile BR](2.compile-br.md).
+- [Install BR and Agent](2.compile-br.md) and run Agent on each host in the cluster.
 
 - The NebulaGraph services are running.
 
-- The [nebula-agent](https://github.com/vesoft-inc/nebula-agent) has been downloaded and the nebula-agent service is running on each host in the cluster.
-
 - If you store the backup files locally, create a directory with the same absolute path on the meta servers, the storage servers, and the BR machine for the backup files and get the absolute path. Make sure the account has write privileges for this directory.
 
   !!! note
@@ -20,19 +18,19 @@ To back up data with the BR, do a check of these:
 
 ## Procedure
 
-Run the following command to perform a full backup for the entire cluster.
+In the BR installation directory (the default path of the compiled BR is `./bin/br`), run the following command to perform a full backup for the entire cluster.
 
 !!! Note
 
     Make sure that the local path where the backup file is stored exists.
 
 ```bash
-$ ./bin/br backup full --meta <ip_address> --storage <storage_path>
+$ ./br backup full --meta <ip_address> --storage <storage_path>
 ```
 
 For example: 
 
-- Run the following command to perform a full backup for the entire cluster whose meta service address is `127.0.0.1:9559`, and save the backup file to `/home/nebula/backup/`.
+- Run the following command to perform a full backup for the entire cluster whose meta service address is `192.168.8.129:9559`, and save the backup file to `/home/nebula/backup/`.
 
   !!! caution
 
@@ -43,24 +41,24 @@ For example:
         If you back up data to a local disk, only the data of the leader metad is backed up by default. So if there are multiple metad processes, you need to manually copy the directory of the leader metad (path `<storage_path>/meta`) and overwrite the corresponding directory of other follower meatd processes.
 
   ```bash
-  $ ./bin/br backup full --meta "127.0.0.1:9559" --storage "local:///home/nebula/backup/"
+  $ ./br backup full --meta "192.168.8.129:9559" --storage "local:///home/nebula/backup/"
   ```
 
-- Run the following command to perform a full backup for the entire cluster whose meta service address is `127.0.0.1:9559`, and save the backup file to `backup` in the `br-test` bucket of the object storage service compatible with S3 protocol.
+- Run the following command to perform a full backup for the entire cluster whose meta service address is `192.168.8.129:9559`, and save the backup file to `backup` in the `br-test` bucket of the object storage service compatible with S3 protocol.
 
   ```bash
-  $ ./bin/br backup full --meta "127.0.0.1:9559" --s3.endpoint "http://127.0.0.1:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region=default
+  $ ./br backup full --meta "192.168.8.129:9559" --s3.endpoint "http://192.168.8.129:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region=default
   ```
 
 The parameters are as follows.
 
 | Parameter    | Data type | Required | Default value | Description                                                                 |
 | ---          | ---      | ---           | ---                                                                         | ---       |
 | `-h,-help`     | -         | No       | None          | Checks help for restoration.                                                |
-| `-debug` | - | No | None | Checks for more log information. |
-| `-log`        | string    | No       | `"br.log"`        | Specifies detailed log path for restoration and backup. |
-| `-meta`        | string    | Yes       | None        | The IP address and port of the meta service. |
-| `-name`        | string    | Yes       | None        | The name of backup. |
+| `--debug` | - | No | None | Checks for more log information. |
+| `--log`        | string    | No       | `"br.log"`        | Specifies detailed log path for restoration and backup. |
+| `--meta`        | string    | Yes       | None        | The IP address and port of the meta service. |
+| `--space`        | string    | Yes       | None        | (Experimental feature) Specifies the names of the spaces to be backed up. All spaces will be backed up if not specified. Multiple spaces can be specified, and format is `--spaces nba_01 --spaces nba_02`. |
 | `--storage` | string | Yes | None | The target storage URL of BR backup data. The format is: \<Schema\>://\<PATH\>. <br>Schema: Optional values are `local` and `s3`. <br>When selecting s3, you need to fill in `s3.access_key`, `s3.endpoint`, `s3.region`, and `s3.secret_key`.<br>PATH: The path of the storage location. |
 | `--s3.access_key` | string | No | None | Sets AccessKey ID. |
 | `--s3.endpoint` | string | No | None | Sets the S3 endpoint URL, please specify the HTTP or HTTPS scheme explicitly. |

diff --git a/docs-2.0/backup-and-restore/nebula-br/4.br-restore-data.md b/docs-2.0/backup-and-restore/nebula-br/4.br-restore-data.md
@@ -14,24 +14,25 @@ If you use the BR to back up data, you can use it to restore the data to NebulaG
 
 To restore data with the BR, do a check of these:
 
-- The BR is compiled. For more information, see [Compile BR](2.compile-br.md).
-
-- Download [nebula-agent](https://github.com/vesoft-inc/nebula-agent) and start the agent service in each cluster(including metad, storaged, graphd) host.
+- [Install BR and Agent](2.compile-br.md) and run Agent on each host in the cluster.
 
 - No application is connected to the target NebulaGraph cluster.
 
 - Make sure that the target and the source NebulaGraph clusters have the same topology, which means that they have exactly the same number of hosts. The number of data folders for each host is consistently distributed.
 
 ## Procedures
 
+In the BR installation directory (the default path of the compiled BR is `./bin/br`), run the following command to perform a full backup for the entire cluster.
+
 1. Users can use the following command to list the existing backup information:
 
   ```bash
-  $ ./bin/br show --storage <storage_path>
+  $ ./br show --storage <storage_path>
   ```
+
   For example, run the following command to list the backup information in the local `/home/nebula/backup` path.
   ```bash
-  $ ./bin/br show --storage "local:///home/nebula/backup"
+  $ ./br show --storage "local:///home/nebula/backup"
   +----------------------------+---------------------+------------------------+-------------+------------+
   |            NAME            |     CREATE TIME     |         SPACES         | FULL BACKUP | ALL SPACES |
   +----------------------------+---------------------+------------------------+-------------+------------+
@@ -40,9 +41,9 @@ To restore data with the BR, do a check of these:
   +----------------------------+---------------------+------------------------+-------------+------------+
   ```
 
-  Or, you can run the following command to list the backup information stored in S3 URL `s3://127.0.0.1:9000/br-test/backup`.
+  Or, you can run the following command to list the backup information stored in S3 URL `s3://192.168.8.129:9000/br-test/backup`.
   ```bash
-  $ ./bin/br show --s3.endpoint "http://127.0.0.1:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region=default
+  $ ./br show --s3.endpoint "http://192.168.8.129:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region=default
   ```
 
   | Parameter    | Data type | Required | Default value | Description                                                                 |
@@ -60,18 +61,18 @@ To restore data with the BR, do a check of these:
 2. Run the following command to restore data.
 
   ```
-  $ ./bin/br restore full --meta <ip_address> --storage <storage_path> --name <backup_name>
+  $ ./br restore full --meta <ip_address> --storage <storage_path> --name <backup_name>
   ```
 
-  For example, run the following command to upload the backup files from the local `/home/nebula/backup/` to the cluster where the meta service's address is `127.0.0.1:9559`.
+  For example, run the following command to upload the backup files from the local `/home/nebula/backup/` to the cluster where the meta service's address is `192.168.8.129:9559`.
 
   ```
-  $ ./bin/br restore full --meta "127.0.0.1:9559" --storage "local:///home/nebula/backup/" --name BACKUP_2021_12_08_18_38_08
+  $ ./br restore full --meta "192.168.8.129:9559" --storage "local:///home/nebula/backup/" --name BACKUP_2021_12_08_18_38_08
   ```
 
-  Or, you can run the following command to upload the backup files from the S3 URL `s3://127.0.0.1:9000/br-test/backup`.
+  Or, you can run the following command to upload the backup files from the S3 URL `s3://192.168.8.129:9000/br-test/backup`.
   ```bash
-  $ ./bin/br restore full --meta "127.0.0.1:9559" --s3.endpoint "http://127.0.0.1:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region="default" --name BACKUP_2021_12_08_18_38_08
+  $ ./br restore full --meta "192.168.8.129:9559" --s3.endpoint "http://192.168.8.129:9000" --storage="s3://br-test/backup/" --s3.access_key=minioadmin --s3.secret_key=minioadmin --s3.region="default" --name BACKUP_2021_12_08_18_38_08
   ```
 
   If the following information is returned, the data is restored successfully.
@@ -101,7 +102,7 @@ To restore data with the BR, do a check of these:
 3. Run the following command to clean up temporary files if any error occurred during backup. It will clean the files in cluster and external storage. You could also use it to clean up old backups files in external storage.
 
   ```bash
-  $ ./bin/br cleanup --meta <ip_address> --storage <storage_path> --name <backup_name>
+  $ ./br cleanup --meta <ip_address> --storage <storage_path> --name <backup_name>
   ```
 
   The parameters are as follows.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -206,6 +206,9 @@ extra:
     release: 0.6.1
     branch: master
     tag: v0.6.1
+  agent:
+    release: 0.2.0
+    tag: v0.2.0
   cpp:
     release: 3.0.2
     branch: release-3.0
@@ -470,7 +473,7 @@ nav:
   - Backup & Restore:
       - NebulaGraph BR:
           - What is Backup & Restore: backup-and-restore/nebula-br/1.what-is-br.md
-          - Compile BR: backup-and-restore/nebula-br/2.compile-br.md
+          - Install BR: backup-and-restore/nebula-br/2.compile-br.md
           - Use BR to back up data: backup-and-restore/nebula-br/3.br-backup-data.md
           - Use BR to restore data: backup-and-restore/nebula-br/4.br-restore-data.md
       - Manage snapshots: backup-and-restore/3.manage-snapshot.md