From 4121ea3bc5bdc81f6b39dbac359f4bcecacab754 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Tue, 13 Apr 2021 16:43:09 +0800 Subject: [PATCH 1/9] add mirror-init/mirror-rotate/cluster-patch --- tiup/tiup-command-mirror-init.md | 44 +++++++++++++++ tiup/tiup-command-mirror-rotate.md | 60 ++++++++++++++++++++ tiup/tiup-component-cluster-patch.md | 84 ++++++++++++++++++++++++++++ 3 files changed, 188 insertions(+) create mode 100644 tiup/tiup-command-mirror-init.md create mode 100644 tiup/tiup-command-mirror-rotate.md create mode 100644 tiup/tiup-component-cluster-patch.md diff --git a/tiup/tiup-command-mirror-init.md b/tiup/tiup-command-mirror-init.md new file mode 100644 index 0000000000000..0a41f3b9def19 --- /dev/null +++ b/tiup/tiup-command-mirror-init.md @@ -0,0 +1,44 @@ +--- +title: tiup mirror init +--- + +# tiup mirror init + +The command `tiup mirror init` is used to initialize an empty mirror. The initialized mirror does not contain any components or component owners. The command only generates the following files for the initialized mirror: + +``` ++ # Mirror's root directory +|-- root.json # Mirror's root certificate +|-- 1.index.json # Component/user index +|-- snapshot.json # Mirror's latest snapshot +|-- timestamp.json # Mirror's latest timestamp +|--+ keys # Mirror's private key (can be moved to other locations) + |-- {hash1..hashN}-root.json # Private key of the root certificate + |-- {hash}-index.json # Private key of the indexes + |-- {hash}-snapshot.json # Private key of the snapshots + |-- {hash}-timestamp.json # Private key of the timestamps +``` + +For the specific usage and content format of the above files, refer to [TiUP Mirror Reference Guide](/tiup/tiup-mirror-reference.md). + +## Syntax + +```shell +tiup mirror init [flags] +``` + +`` is used to specify a local directory where TiUP generates and stores mirror files. The local directory can be a relative path. If the specified directory already exists, it must be empty; if it does not exist, TiUP creates it automatically. + +## Options + +### -k, --key-dir + +- Specifies the directory where TiUP generates private key files. If the specified directory does not exist, TiUP automatically creates it. +- Data type: `STRING` +- If this option is not specified in the command, TiUP generates private key files in `{path}/keys` by default. + +### Outputs + +- If the command is executed successfully, there is no output. +- If the specified `` is not empty, TiUP reports the error `Error: the target path '%s' is not an empty directory`. +- If the specified `` is not a directory, TiUP reports the error `Error: fdopendir: not a directory`. diff --git a/tiup/tiup-command-mirror-rotate.md b/tiup/tiup-command-mirror-rotate.md new file mode 100644 index 0000000000000..ae9d664f5f6e8 --- /dev/null +++ b/tiup/tiup-command-mirror-rotate.md @@ -0,0 +1,60 @@ +--- +title: tiup mirror rotate +--- + +# tiup mirror rotate + +`root.json` is an important file in a TiUP mirror. It stores the public keys needed for the entire system and is the basis of the chain of trust in TiUP. It mainly contains the following parts: + +- Signatures of mirror administrators. For an official mirror, there are five signatures. For a default initialized mirror, there are three signatures. +- The public keys used to verify the following files: + - root.json + - index.json + - snapshot.json + - timestamp.json +- Expiration date of `root.json`. For an official mirror, the expiration date is one year later than the creation date of `root.json`. + +For detailed description of TiUP mirror, see [TiUP Mirror Reference](/tiup/tiup-mirror-reference.md). + +You need to update `root.json` in the following cases: + +- Replace the key of the mirror. +- Update the expiration date of certificate files. + +After the content of `root.json` is updated, the file must be re-signed by all administrators, or the client rejects the file. The update process is as follows: + +1. Update the content of `root.json`. +2. All administrators sign the new `root.json` file. +3. Update `snapshot.json` to record the version of the new `root.json` file. +4. All administrators sign the new `snapshot.json` file. +5. Update `timestamp.json` to record the hash value of the new `snapshot.json` file. +6. All administrators sign the new `timestamp.json` file. + +TiUP uses the command `tiup mirror rotate` to automate the above process. + +> **Note:** +> +> + In TiUP versions earlier than v1.3.0, running this command does not returns a correct new `root.json` file. See [#983](https://github.com/pingcap/tiup/issues/983). +> + Before using this command, make sure that all TiUP clients are upgraded to v1.3.0 or later versions. + +## Syntax + +```shell +tiup mirror rotate [flags] +``` + +After executing this command, TiUP starts an editor to modify the file content to target value, such as changing the value of the `expires` field to a later date. Then, TiUP changes the `version` field from `N` to `N+1` and saves the file. After the file is saved, TiUP starts a temporary http server and waits for all mirror administrators to sign the file. + +For how mirror administrators sign files, refer to [the `sign` command](/tiup/tiup-command-mirror-sign.md). + +## Options + +### --addr + +- Specifies the listening address of the temporary server. You need to make sure that the address is accessible to other mirror administrators so that they can use [the `sign` command](/tiup/tiup-command-mirror-sign.md) to sign the file. +- Data type: `STRING` +- If this option is not specified in the command, TiUP listens to `0.0.0.0:8080` by default. + +## Outputs + +The current signature status of each mirror administrator. diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md new file mode 100644 index 0000000000000..7bd6bdc086a17 --- /dev/null +++ b/tiup/tiup-component-cluster-patch.md @@ -0,0 +1,84 @@ +--- +title: tiup cluster patch +--- + +# tiup cluster patch + +If you need to dynamically replace the binaries of a service while the cluster is running (namely, keep the cluster available during the replacement process), you can use the `tiup cluster patch` command. After the command is executed, TiUP does the following things: + +- Upload the binary package for replacement to the target machine. +- If the target service is a storage service such as TiKV, TiFlash, or TiDB Binlog, TiUP first takes the related nodes offline via the API. +- Stop the target service. +- Unpack the binary package and replace the service. +- Start the target service. + +## Syntax + +```shell +tiup cluster patch [flags] +``` + +- ``: The name of the cluster to be operated. +- ``: The path to the binary package used for replacement. The steps to generate the package are as follows: + - Determine the name `${component}` of the component to be replaced (tidb, tikv, pd...), the `${version}` of the component (v4.0.0, v4.0.1 ...), and the operating system `${os}` and platform `${arch}` on which the component runs. + - Download the current component package using the command `wget https://tiup-mirrors.pingcap.com/${component}-${version}-${os}-${arch}.tar.gz -O /tmp/${component}-${version}-${os}-${arch}.tar.gz`. + - Run `mkdir -p /tmp/package && cd /tmp/package` to create a temporary directory to pack files. + - Run `tar xf /tmp/${component}-${version}-${os}-${arch}.tar.gz` to unpack the original binary package. + - Run `find .` to view the file structure in the temporary package directory. + - Copy the binary files or configuration files to the corresponding locations in the temporary directory. + - Run `tar czf /tmp/${component}-hotfix-${os}-${arch}.tar.gz *` to pack the files in the temporary directory. + - Finally, you can use `/tmp/${component}-hotfix-${os}-${arch}.tar.gz` as the `` in the `tiup cluster patch` command. + +## Options + +### --overwrite（boolean，默认 false） + +- After you patch a certain component (such as TiDB or TiKV), when the tiup cluster scales out the component, TiUP uses the original component version by default. To use the version that you patch when the cluster scales out in the future, you need to specified the option `--overwrite` in the command. +- Data type: `BOOLEAN` +- Default: false. If this option is not specified in the command, TiUP uses the original component version when scaling out the cluster component. + +### --transfer-timeout + +- When restarting the PD or TiKV service, TiUP first migrates the leader of the node to be restarted to another node. Because the migration process takes some time, you can use the option `--transfer-timeout` to set the maximum waiting time (in seconds). After the timeout, TiUP directly restarts the service. +- Data type: `UINT` +- If this option is not specified, TiUP directly restarts the service after waiting for `300` seconds. + +> **Note:** +> +> If TiUP directly restarts the service after the timeout, the service performance may jitter. + +### -N, --node + +- Specifies nodes to be replaced. The value of this option is a comma-separated list of node IDs. You can get the node ID from the first column of the [cluster status table](/tiup/tiup-component-cluster-display.md). +- Data type: `STRINGS` +- If this option is not specified, TiUP does not select any nodes to replace by default. + +> **Note:** +> +> If the option `-R, --role` is specified at the same time, TiUP then replaces service nodes that match both the requirements of `-N, --node` and `-R, --role`. + +### -R, --role + +- Specified roles to be replaced. The value of this option is a comma-separated list of the roles of the nodes. You can get the roles of the nodes from the second column of the [cluster status table](/tiup/tiup-component-cluster-display.md). +- Data type: `STRINGS` +- If this option is not specified, TiUP does not select any roles to replace by default. + +> **Note:** +> +> If the option `-N, --node` is specified at the same time, TiUP then replaces service nodes that match both the requirements of `-N, --node` and `-R, --role`. + +## --offline + +- Declares that the current cluster is not running. When the option is specified, TiUP does not migrate service leader to another node or restart the service, but only replaces the binary files of cluster components +- Data type: `BOOLEAN` +- Default: false. If this option is not specified in the command, then the cluster is running. + +### -h, --help + +- Outputs help information. +- Data type: `BOOLEAN` +- Default: false. If this option is not specified in the command, TiUP does not output help information. + +## Outputs + +The execution log of the tiup cluster. \ No newline at end of file From 1afd76334f7fb8ea7c94d2fc256ef7d198c8a302 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Tue, 13 Apr 2021 16:53:09 +0800 Subject: [PATCH 2/9] fix some issues --- tiup/tiup-command-completion.md | 2 +- tiup/tiup-command-list.md | 2 +- tiup/tiup-command-mirror-clone.md | 2 +- tiup/tiup-component-cluster-patch.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tiup/tiup-command-completion.md b/tiup/tiup-command-completion.md index 22155f5dca0df..cdb1befddc53e 100644 --- a/tiup/tiup-command-completion.md +++ b/tiup/tiup-command-completion.md @@ -13,7 +13,7 @@ If you want to complete `bash` commands, you need to install `bash-completion` f ## Syntax -```sh +```shell tiup completion ``` diff --git a/tiup/tiup-command-list.md b/tiup/tiup-command-list.md index 4c352cb35d781..9a79bfa7e0f26 100644 --- a/tiup/tiup-command-list.md +++ b/tiup/tiup-command-list.md @@ -8,7 +8,7 @@ The command `tiup list` is used to get the list of available components of a mir ## Syntax -```sh +```shell tiup list [component] [flags] ``` diff --git a/tiup/tiup-command-mirror-clone.md b/tiup/tiup-command-mirror-clone.md index 2af806c724c61..3c71837888abd 100644 --- a/tiup/tiup-command-mirror-clone.md +++ b/tiup/tiup-command-mirror-clone.md @@ -8,7 +8,7 @@ The command `tiup mirror clone` is used to clone an existing mirror or clone som ## Syntax -```sh +```shell tiup mirror clone [global version] [flags] ``` diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md index 7bd6bdc086a17..54c59dfa28770 100644 --- a/tiup/tiup-component-cluster-patch.md +++ b/tiup/tiup-component-cluster-patch.md @@ -31,7 +31,7 @@ tiup cluster patch [flags] ## Options -### --overwrite（boolean，默认 false） +### --overwrite - After you patch a certain component (such as TiDB or TiKV), when the tiup cluster scales out the component, TiUP uses the original component version by default. To use the version that you patch when the cluster scales out in the future, you need to specified the option `--overwrite` in the command. - Data type: `BOOLEAN` From d8cf295b441d68d18637b024e108a14f3fe2e3d2 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Tue, 13 Apr 2021 17:01:42 +0800 Subject: [PATCH 3/9] refine expressions --- tiup/tiup-component-cluster-patch.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md index 54c59dfa28770..bbd083f1dfddf 100644 --- a/tiup/tiup-component-cluster-patch.md +++ b/tiup/tiup-component-cluster-patch.md @@ -35,7 +35,7 @@ tiup cluster patch [flags] - After you patch a certain component (such as TiDB or TiKV), when the tiup cluster scales out the component, TiUP uses the original component version by default. To use the version that you patch when the cluster scales out in the future, you need to specified the option `--overwrite` in the command. - Data type: `BOOLEAN` -- Default: false. If this option is not specified in the command, TiUP uses the original component version when scaling out the cluster component. +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ### --transfer-timeout @@ -71,13 +71,13 @@ tiup cluster patch [flags] - Declares that the current cluster is not running. When the option is specified, TiUP does not migrate service leader to another node or restart the service, but only replaces the binary files of cluster components - Data type: `BOOLEAN` -- Default: false. If this option is not specified in the command, then the cluster is running. +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ### -h, --help - Outputs help information. - Data type: `BOOLEAN` -- Default: false. If this option is not specified in the command, TiUP does not output help information. +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ## Outputs From 9364b0ae282d377b88fc2e1e511547c7f1b9cad4 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Wed, 14 Apr 2021 13:56:09 +0800 Subject: [PATCH 4/9] refine expression --- tiup/tiup-component-cluster-patch.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md index bbd083f1dfddf..7f2f8f66741dd 100644 --- a/tiup/tiup-component-cluster-patch.md +++ b/tiup/tiup-component-cluster-patch.md @@ -6,11 +6,11 @@ title: tiup cluster patch If you need to dynamically replace the binaries of a service while the cluster is running (namely, keep the cluster available during the replacement process), you can use the `tiup cluster patch` command. After the command is executed, TiUP does the following things: -- Upload the binary package for replacement to the target machine. +- Uploads the binary package for replacement to the target machine. - If the target service is a storage service such as TiKV, TiFlash, or TiDB Binlog, TiUP first takes the related nodes offline via the API. -- Stop the target service. -- Unpack the binary package and replace the service. -- Start the target service. +- Stops the target service. +- Unpacks the binary package and replace the service. +- Starts the target service. ## Syntax @@ -81,4 +81,4 @@ tiup cluster patch [flags] ## Outputs -The execution log of the tiup cluster. \ No newline at end of file +The execution log of the tiup-cluster. \ No newline at end of file From d850975a9d36691d68f5c6fc22dc33707e6e4deb Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Wed, 14 Apr 2021 14:19:03 +0800 Subject: [PATCH 5/9] Update tiup-component-cluster-patch.md --- tiup/tiup-component-cluster-patch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md index 7f2f8f66741dd..8b952712a89a1 100644 --- a/tiup/tiup-component-cluster-patch.md +++ b/tiup/tiup-component-cluster-patch.md @@ -75,7 +75,7 @@ tiup cluster patch [flags] ### -h, --help -- Outputs help information. +- Prints help information. - Data type: `BOOLEAN` - This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. From 2f0b2f6ba7e7a3bb1296089ca9994837b149b762 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Wed, 14 Apr 2021 17:25:50 +0800 Subject: [PATCH 6/9] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-command-mirror-rotate.md | 16 ++++++++-------- tiup/tiup-component-cluster-patch.md | 10 +++++----- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/tiup/tiup-command-mirror-rotate.md b/tiup/tiup-command-mirror-rotate.md index ae9d664f5f6e8..57e4f68408717 100644 --- a/tiup/tiup-command-mirror-rotate.md +++ b/tiup/tiup-command-mirror-rotate.md @@ -6,7 +6,7 @@ title: tiup mirror rotate `root.json` is an important file in a TiUP mirror. It stores the public keys needed for the entire system and is the basis of the chain of trust in TiUP. It mainly contains the following parts: -- Signatures of mirror administrators. For an official mirror, there are five signatures. For a default initialized mirror, there are three signatures. +- Signatures of mirror administrators. For an official mirror, there are five signatures. For an initialized mirror, there are three signatures by default. - The public keys used to verify the following files: - root.json - index.json @@ -21,7 +21,7 @@ You need to update `root.json` in the following cases: - Replace the key of the mirror. - Update the expiration date of certificate files. -After the content of `root.json` is updated, the file must be re-signed by all administrators, or the client rejects the file. The update process is as follows: +After the content of `root.json` is updated, the file must be re-signed by all administrators; otherwise, the client rejects the file. The update process is as follows: 1. Update the content of `root.json`. 2. All administrators sign the new `root.json` file. @@ -34,8 +34,8 @@ TiUP uses the command `tiup mirror rotate` to automate the above process. > **Note:** > -> + In TiUP versions earlier than v1.3.0, running this command does not returns a correct new `root.json` file. See [#983](https://github.com/pingcap/tiup/issues/983). -> + Before using this command, make sure that all TiUP clients are upgraded to v1.3.0 or later versions. +> + For TiUP versions earlier than v1.3.0, running this command does not returns a correct new `root.json` file. See [#983](https://github.com/pingcap/tiup/issues/983). +> + Before using this command, make sure that all TiUP clients are upgraded to v1.3.0 or a later version. ## Syntax @@ -43,17 +43,17 @@ TiUP uses the command `tiup mirror rotate` to automate the above process. tiup mirror rotate [flags] ``` -After executing this command, TiUP starts an editor to modify the file content to target value, such as changing the value of the `expires` field to a later date. Then, TiUP changes the `version` field from `N` to `N+1` and saves the file. After the file is saved, TiUP starts a temporary http server and waits for all mirror administrators to sign the file. +After executing this command, TiUP starts an editor to modify the file content to the target value, such as changing the value of the `expires` field to a later date. Then, TiUP changes the `version` field from `N` to `N+1` and saves the file. After the file is saved, TiUP starts a temporary HTTP server and waits for all mirror administrators to sign the file. -For how mirror administrators sign files, refer to [the `sign` command](/tiup/tiup-command-mirror-sign.md). +For how mirror administrators sign files, refer to the [`sign` command](/tiup/tiup-command-mirror-sign.md). ## Options ### --addr -- Specifies the listening address of the temporary server. You need to make sure that the address is accessible to other mirror administrators so that they can use [the `sign` command](/tiup/tiup-command-mirror-sign.md) to sign the file. +- Specifies the listening address of the temporary server. You need to make sure that the address is accessible to other mirror administrators so that they can use the [`sign` command](/tiup/tiup-command-mirror-sign.md) to sign the file. - Data type: `STRING` -- If this option is not specified in the command, TiUP listens to `0.0.0.0:8080` by default. +- If this option is not specified in the command, TiUP listens on `0.0.0.0:8080` by default. ## Outputs diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md index 8b952712a89a1..6e25298ddfe1a 100644 --- a/tiup/tiup-component-cluster-patch.md +++ b/tiup/tiup-component-cluster-patch.md @@ -20,7 +20,7 @@ tiup cluster patch [flags] - ``: The name of the cluster to be operated. - ``: The path to the binary package used for replacement. The steps to generate the package are as follows: - - Determine the name `${component}` of the component to be replaced (tidb, tikv, pd...), the `${version}` of the component (v4.0.0, v4.0.1 ...), and the operating system `${os}` and platform `${arch}` on which the component runs. + - Determine the name `${component}` of the component to be replaced (tidb, tikv, pd...), the `${version}` of the component (v4.0.0, v4.0.1 ...), and the operating system `${os}` (`linux`) and platform `${arch}` on which the component runs. - Download the current component package using the command `wget https://tiup-mirrors.pingcap.com/${component}-${version}-${os}-${arch}.tar.gz -O /tmp/${component}-${version}-${os}-${arch}.tar.gz`. - Run `mkdir -p /tmp/package && cd /tmp/package` to create a temporary directory to pack files. - Run `tar xf /tmp/${component}-${version}-${os}-${arch}.tar.gz` to unpack the original binary package. @@ -49,7 +49,7 @@ tiup cluster patch [flags] ### -N, --node -- Specifies nodes to be replaced. The value of this option is a comma-separated list of node IDs. You can get the node ID from the first column of the [cluster status table](/tiup/tiup-component-cluster-display.md). +- Specifies nodes to be replaced. The value of this option is a comma-separated list of node IDs. You can get the node ID from the first column of the [cluster status table](/tiup/tiup-component-cluster-display.md) returned by the `tiup cluster display` command. - Data type: `STRINGS` - If this option is not specified, TiUP does not select any nodes to replace by default. @@ -59,7 +59,7 @@ tiup cluster patch [flags] ### -R, --role -- Specified roles to be replaced. The value of this option is a comma-separated list of the roles of the nodes. You can get the roles of the nodes from the second column of the [cluster status table](/tiup/tiup-component-cluster-display.md). +- Specifies the roles to be replaced. The value of this option is a comma-separated list of the roles of the nodes. You can get the role deployed on a node from the second column of the [cluster status table](/tiup/tiup-component-cluster-display.md) returned by the `tiup cluster display` command. - Data type: `STRINGS` - If this option is not specified, TiUP does not select any roles to replace by default. @@ -69,7 +69,7 @@ tiup cluster patch [flags] ## --offline -- Declares that the current cluster is not running. When the option is specified, TiUP does not migrate service leader to another node or restart the service, but only replaces the binary files of cluster components +- Declares that the current cluster is not running. When the option is specified, TiUP does not migrate the service leader to another node or restart the service, but only replaces the binary files of cluster components. - Data type: `BOOLEAN` - This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. @@ -81,4 +81,4 @@ tiup cluster patch [flags] ## Outputs -The execution log of the tiup-cluster. \ No newline at end of file +The execution log of the tiup-cluster. From d8fcd4982cad3ae1eac2095aea6a1fca343f9f9c Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Thu, 15 Apr 2021 14:09:27 +0800 Subject: [PATCH 7/9] Apply suggestions from code review Co-authored-by: SIGSEGV --- tiup/tiup-command-mirror-init.md | 2 +- tiup/tiup-command-mirror-rotate.md | 14 +++++++------- tiup/tiup-component-cluster-patch.md | 4 ++-- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/tiup/tiup-command-mirror-init.md b/tiup/tiup-command-mirror-init.md index 0a41f3b9def19..a549e13ffabdc 100644 --- a/tiup/tiup-command-mirror-init.md +++ b/tiup/tiup-command-mirror-init.md @@ -27,7 +27,7 @@ For the specific usage and content format of the above files, refer to [TiUP Mir tiup mirror init [flags] ``` -`` is used to specify a local directory where TiUP generates and stores mirror files. The local directory can be a relative path. If the specified directory already exists, it must be empty; if it does not exist, TiUP creates it automatically. +`` is used to specify a local directory where TiUP generates and stores mirror files. The local directory can be a relative path. If the specified directory already exists, it must be empty; if it does not exist, TiUP creates it automatically. ## Options diff --git a/tiup/tiup-command-mirror-rotate.md b/tiup/tiup-command-mirror-rotate.md index 57e4f68408717..7dbabf047df05 100644 --- a/tiup/tiup-command-mirror-rotate.md +++ b/tiup/tiup-command-mirror-rotate.md @@ -6,13 +6,13 @@ title: tiup mirror rotate `root.json` is an important file in a TiUP mirror. It stores the public keys needed for the entire system and is the basis of the chain of trust in TiUP. It mainly contains the following parts: -- Signatures of mirror administrators. For an official mirror, there are five signatures. For an initialized mirror, there are three signatures by default. +- Signatures of mirror administrators. For the official mirror, there are five signatures. For an initialized mirror, there are three signatures by default. - The public keys used to verify the following files: - root.json - index.json - snapshot.json - timestamp.json -- Expiration date of `root.json`. For an official mirror, the expiration date is one year later than the creation date of `root.json`. +- Expiration date of `root.json`. For the official mirror, the expiration date is one year later than the creation date of `root.json`. For detailed description of TiUP mirror, see [TiUP Mirror Reference](/tiup/tiup-mirror-reference.md). @@ -25,10 +25,10 @@ After the content of `root.json` is updated, the file must be re-signed by all a 1. Update the content of `root.json`. 2. All administrators sign the new `root.json` file. -3. Update `snapshot.json` to record the version of the new `root.json` file. -4. All administrators sign the new `snapshot.json` file. -5. Update `timestamp.json` to record the hash value of the new `snapshot.json` file. -6. All administrators sign the new `timestamp.json` file. +3. tiup-server updates `snapshot.json` to record the version of the new `root.json` file. +4. tiup-server signs the new `snapshot.json` file. +5. tiup-server updates `timestamp.json` to record the hash value of the new `snapshot.json` file. +6. tiup-server signs the new `timestamp.json` file. TiUP uses the command `tiup mirror rotate` to automate the above process. @@ -43,7 +43,7 @@ TiUP uses the command `tiup mirror rotate` to automate the above process. tiup mirror rotate [flags] ``` -After executing this command, TiUP starts an editor to modify the file content to the target value, such as changing the value of the `expires` field to a later date. Then, TiUP changes the `version` field from `N` to `N+1` and saves the file. After the file is saved, TiUP starts a temporary HTTP server and waits for all mirror administrators to sign the file. +After executing this command, TiUP starts an editor for the user to modify the file content to the target value, such as changing the value of the `expires` field to a later date. Then, TiUP changes the `version` field from `N` to `N+1` and saves the file. After the file is saved, TiUP starts a temporary HTTP server and waits for all mirror administrators to sign the file. For how mirror administrators sign files, refer to the [`sign` command](/tiup/tiup-command-mirror-sign.md). diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md index 6e25298ddfe1a..6f70627ca96c6 100644 --- a/tiup/tiup-component-cluster-patch.md +++ b/tiup/tiup-component-cluster-patch.md @@ -39,13 +39,13 @@ tiup cluster patch [flags] ### --transfer-timeout -- When restarting the PD or TiKV service, TiUP first migrates the leader of the node to be restarted to another node. Because the migration process takes some time, you can use the option `--transfer-timeout` to set the maximum waiting time (in seconds). After the timeout, TiUP directly restarts the service. +- When restarting the PD or TiKV service, TiKV/PD first transfers the leader of the node to be restarted to another node. Because the transfer process takes some time, you can use the option `--transfer-timeout` to set the maximum waiting time (in seconds). After the timeout, TiUP directly restarts the service. - Data type: `UINT` - If this option is not specified, TiUP directly restarts the service after waiting for `300` seconds. > **Note:** > -> If TiUP directly restarts the service after the timeout, the service performance may jitter. +> If TiUP directly restarts the service after the timeout, the service performance might jitter. ### -N, --node From 0cabef0c52a37a4b9f142923f6e88f898e57a7f0 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Thu, 15 Apr 2021 14:17:44 +0800 Subject: [PATCH 8/9] Update tiup-component-cluster-patch.md --- tiup/tiup-component-cluster-patch.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md index 6f70627ca96c6..f282a9d9e2135 100644 --- a/tiup/tiup-component-cluster-patch.md +++ b/tiup/tiup-component-cluster-patch.md @@ -19,15 +19,20 @@ tiup cluster patch [flags] ``` - ``: The name of the cluster to be operated. -- ``: The path to the binary package used for replacement. The steps to generate the package are as follows: - - Determine the name `${component}` of the component to be replaced (tidb, tikv, pd...), the `${version}` of the component (v4.0.0, v4.0.1 ...), and the operating system `${os}` (`linux`) and platform `${arch}` on which the component runs. - - Download the current component package using the command `wget https://tiup-mirrors.pingcap.com/${component}-${version}-${os}-${arch}.tar.gz -O /tmp/${component}-${version}-${os}-${arch}.tar.gz`. - - Run `mkdir -p /tmp/package && cd /tmp/package` to create a temporary directory to pack files. - - Run `tar xf /tmp/${component}-${version}-${os}-${arch}.tar.gz` to unpack the original binary package. - - Run `find .` to view the file structure in the temporary package directory. - - Copy the binary files or configuration files to the corresponding locations in the temporary directory. - - Run `tar czf /tmp/${component}-hotfix-${os}-${arch}.tar.gz *` to pack the files in the temporary directory. - - Finally, you can use `/tmp/${component}-hotfix-${os}-${arch}.tar.gz` as the `` in the `tiup cluster patch` command. +- ``: The path to the binary package used for replacement. + +### Preparation + +You need to pack the binary package required for this command in advance according to the following steps: + +- Determine the name `${component}` of the component to be replaced (tidb, tikv, pd...), the `${version}` of the component (v4.0.0, v4.0.1 ...), and the operating system `${os}` (`linux`) and platform `${arch}` on which the component runs. +- Download the current component package using the command `wget https://tiup-mirrors.pingcap.com/${component}-${version}-${os}-${arch}.tar.gz -O /tmp/${component}-${version}-${os}-${arch}.tar.gz`. +- Run `mkdir -p /tmp/package && cd /tmp/package` to create a temporary directory to pack files. +- Run `tar xf /tmp/${component}-${version}-${os}-${arch}.tar.gz` to unpack the original binary package. +- Run `find .` to view the file structure in the temporary package directory. +- Copy the binary files or configuration files to the corresponding locations in the temporary directory. +- Run `tar czf /tmp/${component}-hotfix-${os}-${arch}.tar.gz *` to pack the files in the temporary directory. +- Finally, you can use `/tmp/${component}-hotfix-${os}-${arch}.tar.gz` as the `` in the `tiup cluster patch` command. ## Options From 005794792f9ff53587a61c09ea9e80e8416fa0b7 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Thu, 15 Apr 2021 14:38:24 +0800 Subject: [PATCH 9/9] temporarily change dead links to html comments --- tiup/tiup-command-mirror-rotate.md | 6 +++--- tiup/tiup-component-cluster-patch.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tiup/tiup-command-mirror-rotate.md b/tiup/tiup-command-mirror-rotate.md index 7dbabf047df05..212516e86d03d 100644 --- a/tiup/tiup-command-mirror-rotate.md +++ b/tiup/tiup-command-mirror-rotate.md @@ -23,7 +23,7 @@ You need to update `root.json` in the following cases: After the content of `root.json` is updated, the file must be re-signed by all administrators; otherwise, the client rejects the file. The update process is as follows: -1. Update the content of `root.json`. +1. The user (client) updates the content of `root.json`. 2. All administrators sign the new `root.json` file. 3. tiup-server updates `snapshot.json` to record the version of the new `root.json` file. 4. tiup-server signs the new `snapshot.json` file. @@ -45,13 +45,13 @@ tiup mirror rotate [flags] After executing this command, TiUP starts an editor for the user to modify the file content to the target value, such as changing the value of the `expires` field to a later date. Then, TiUP changes the `version` field from `N` to `N+1` and saves the file. After the file is saved, TiUP starts a temporary HTTP server and waits for all mirror administrators to sign the file. -For how mirror administrators sign files, refer to the [`sign` command](/tiup/tiup-command-mirror-sign.md). +For how mirror administrators sign files, refer to the `sign` command. ## Options ### --addr -- Specifies the listening address of the temporary server. You need to make sure that the address is accessible to other mirror administrators so that they can use the [`sign` command](/tiup/tiup-command-mirror-sign.md) to sign the file. +- Specifies the listening address of the temporary server. You need to make sure that the address is accessible to other mirror administrators so that they can use the `sign` command to sign the file. - Data type: `STRING` - If this option is not specified in the command, TiUP listens on `0.0.0.0:8080` by default. diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md index f282a9d9e2135..5b329c64fbe24 100644 --- a/tiup/tiup-component-cluster-patch.md +++ b/tiup/tiup-component-cluster-patch.md @@ -54,7 +54,7 @@ You need to pack the binary package required for this command in advance accordi ### -N, --node -- Specifies nodes to be replaced. The value of this option is a comma-separated list of node IDs. You can get the node ID from the first column of the [cluster status table](/tiup/tiup-component-cluster-display.md) returned by the `tiup cluster display` command. +- Specifies nodes to be replaced. The value of this option is a comma-separated list of node IDs. You can get the node ID from the first column of the cluster status table returned by the `tiup cluster display` command. - Data type: `STRINGS` - If this option is not specified, TiUP does not select any nodes to replace by default. @@ -64,7 +64,7 @@ You need to pack the binary package required for this command in advance accordi ### -R, --role -- Specifies the roles to be replaced. The value of this option is a comma-separated list of the roles of the nodes. You can get the role deployed on a node from the second column of the [cluster status table](/tiup/tiup-component-cluster-display.md) returned by the `tiup cluster display` command. +- Specifies the roles to be replaced. The value of this option is a comma-separated list of the roles of the nodes. You can get the role deployed on a node from the second column of the cluster status table returned by the `tiup cluster display` command. - Data type: `STRINGS` - If this option is not specified, TiUP does not select any roles to replace by default.