From ab55897eb3bbcfc6095c5a3ec2604cf31e097144 Mon Sep 17 00:00:00 2001 From: Joyinqin Date: Mon, 12 Apr 2021 14:49:54 +0800 Subject: [PATCH 01/12] add 4 docs --- tiup/tiup-command-clean.md | 2 +- tiup/tiup-command-completion.md | 6 +-- tiup/tiup-command-env.md | 2 +- tiup/tiup-command-help.md | 2 +- tiup/tiup-command-install.md | 2 +- tiup/tiup-command-list.md | 2 +- tiup/tiup-command-mirror-clone.md | 2 +- tiup/tiup-command-mirror-merge.md | 30 +++++++++++++++ tiup/tiup-command-mirror-modify.md | 62 ++++++++++++++++++++++++++++++ tiup/tiup-command-mirror-set.md | 2 +- tiup/tiup-command-mirror-sign.md | 47 ++++++++++++++++++++++ tiup/tiup-command-mirror.md | 37 ++++++++++++++++++ 12 files changed, 186 insertions(+), 10 deletions(-) create mode 100644 tiup/tiup-command-mirror-merge.md create mode 100644 tiup/tiup-command-mirror-modify.md create mode 100644 tiup/tiup-command-mirror-sign.md create mode 100644 tiup/tiup-command-mirror.md diff --git a/tiup/tiup-command-clean.md b/tiup/tiup-command-clean.md index e849216d3635d..fd61ec22b021f 100644 --- a/tiup/tiup-command-clean.md +++ b/tiup/tiup-command-clean.md @@ -8,7 +8,7 @@ The `tiup clean` command is used to clear the data generated during component op ## Syntax -```sh +```shell tiup clean [name] [flags] ``` diff --git a/tiup/tiup-command-completion.md b/tiup/tiup-command-completion.md index 22155f5dca0df..2157fabc1580a 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 ``` @@ -25,7 +25,7 @@ tiup completion Write the `tiup completion bash` command into a file and source the file in `.bash_profile`. See the following example: -```sh +```shell tiup completion bash > ~/.tiup.completion.bash printf " @@ -38,6 +38,6 @@ source $HOME/.bash_profile ### zsh -```sh +```shell tiup completion zsh > "${fpath[1]}/_tiup" ``` diff --git a/tiup/tiup-command-env.md b/tiup/tiup-command-env.md index 0e84aa3c17cda..6810f4ebac679 100644 --- a/tiup/tiup-command-env.md +++ b/tiup/tiup-command-env.md @@ -8,7 +8,7 @@ TiUP provides users with flexible and customized interfaces, some of which are i ## Syntax -```sh +```shell tiup env [name1...N] ``` diff --git a/tiup/tiup-command-help.md b/tiup/tiup-command-help.md index c67b9332eab9b..ea59b6bdd4733 100644 --- a/tiup/tiup-command-help.md +++ b/tiup/tiup-command-help.md @@ -8,7 +8,7 @@ The TiUP command-line interface provides users with a wealth of help information ## Syntax -```sh +```shell tiup help [command] ``` diff --git a/tiup/tiup-command-install.md b/tiup/tiup-command-install.md index acf5570708e6a..7d4fc71e060d0 100644 --- a/tiup/tiup-command-install.md +++ b/tiup/tiup-command-install.md @@ -8,7 +8,7 @@ The `tiup install` command is used for component installation. It downloads the ## Syntax -```sh +```shell tiup install [:version] [component2...N] [flags] ``` 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-command-mirror-merge.md b/tiup/tiup-command-mirror-merge.md new file mode 100644 index 0000000000000..2e290effaff5f --- /dev/null +++ b/tiup/tiup-command-mirror-merge.md @@ -0,0 +1,30 @@ +--- +title: tiup mirror merge +--- + +# tiup mirror merge + +The `tiup mirror merge` command is used to merge one or more mirrors to the current mirror. + +To execute this command, you need to meet the following conditions: + +-The owner IDs of all components of the target mirror must exist in the current mirror. +-The user's `${TIUP_HOME}/keys` directory has all the private keys corresponding to the above owner ID in the current mirror (you can use the command [`tiup mirror set`](/tiup/tiup-command-mirror-set.md) to switch the current mirror to the mirror that is currently authorized to modify). + +## Syntax + +```shell +tiup mirror merge [mirror-dir-N] [flags] +``` + +- ``: the first mirror to be merged into the current mirror +- `[mirror-dir-N]`: the Nth mirror to be merged into the current mirror + +## Option + +None + +## Outputs + +- If the command is executed successfully, there is no output. +- If the current mirror is missing the component owner of the target mirror, or `${TIUP_HOME}/keys` is missing the administrator's private key, TiUP reports the `Error: missing owner keys for owner %s on component %s` error. \ No newline at end of file diff --git a/tiup/tiup-command-mirror-modify.md b/tiup/tiup-command-mirror-modify.md new file mode 100644 index 0000000000000..d1220029c407a --- /dev/null +++ b/tiup/tiup-command-mirror-modify.md @@ -0,0 +1,62 @@ +--- +title: tiup mirror modify +--- + +# tiup mirror modify + +The `tiup mirror modify` command is used to modify published components. Only legitimate component administrators can modify components, and only their own published components can be modified. For the component publishing method, refer to [`publish` command](/tiup/tiup-command-mirror-publish.md). + +## Syntax + +```shell +tiup mirror modify [:version] [flags] +``` + +Each parameter is explained as follows: + +- ``: the component name +- `[version]`: the version you want to modify. If not specified, the entire component is modified. + +## Options + +### -k, --key + +- Specifies the location of the private key used for signing the `{component}.json` files. +- Data type: `STRING` +- Default: "${TIUP_HOME}/keys/private.json" + +### --yank + +Mark the specified component or version as unavailable. + +- After marking the component as unavailable, `tiup list` cannot see the component, nor can the new version of the component be installed. +- After marking the component as unavailable, `tiup list ` cannot see the version, nor can this version be installed. +- Data type: `BOOLEAN` +- Default: false + +### --hide + +- Specifies whether the component is hidden. If it is a hidden component, it can be seen in the result list of `tiup list -all`, but not in that of `tiup list`. +- Data type: `STRING` +- Default: NULL + +> **Note:** +> +> This option can only be applied to the component, not to the version of the component. + +### --standalone + +- Controls whether the component can run standalone. This option is currently **NOT available**. +- Data type: `BOOLEAN` +- Default: false + +> **Note:** +> +> This option can only be applied to the component, not to the version of the component. + +## Outputs + +- If the command is executed successfully, there is no output. +- If the component owner is not authorized to modify the target component: + - If the mirror is a remote mirror, TiUP reports the error `Error: The server refused, make sure you have access to this component`. + - If the mirror is a local mirror, TiUP reports the error `Error: the signature is not correct`. \ No newline at end of file diff --git a/tiup/tiup-command-mirror-set.md b/tiup/tiup-command-mirror-set.md index 9e570af1133fe..241fb4db86e18 100644 --- a/tiup/tiup-command-mirror-set.md +++ b/tiup/tiup-command-mirror-set.md @@ -10,7 +10,7 @@ The address of the official mirror is `https://tiup-mirrors.pingcap.com`. ## Syntax -```sh +```shell tiup mirror set [flags] ``` diff --git a/tiup/tiup-command-mirror-sign.md b/tiup/tiup-command-mirror-sign.md new file mode 100644 index 0000000000000..883725811b832 --- /dev/null +++ b/tiup/tiup-command-mirror-sign.md @@ -0,0 +1,47 @@ +--- +title: tiup mirror sign +--- + +# tiup mirror sign + +The `tiup mirror sign` command is used to sign the meta-information files (*.json）defined in TiUP [mirror](/tiup/tiup-mirror-reference.md). These meta-information files might be stored on the local file system or remotely stored using the http protocol to provide a signature entry. + +## Syntax + +```shell +tiup mirror sign [flags] +``` + +`` is the address of the signed file, which has two forms: + +- Network address: start with http or https, such as `http://172.16.5.5:8080/rotate/root.json` +- Local file path: relative path or absolute path + +If it is a network address, the address must provide the following functions: + +-Support access with `http get`, at this time the complete content of the signed file (including the signatures field) should be returned +-Support access with `http post`, the client adds this signature to the signatures field of the content returned by `http get` and POST to this address + +## Options + +### -k, --key + +- Specifies the location of the private key used for signing the `{component}.json` files. +- Data type: `STRING` +- Default: "${TIUP_HOME}/keys/private.json" + +### --timeout + +- Specifies the access timeout of the network when signing through the network. The unit is seconds. +- Data type: `int` +- Default: 10 + +> **Note:** +> +> This option is valid only when `` is a network address. + +## Output + +- If the command is executed successfully, there is no output. +- If the file has been signed by the specified key, TiUP reports the error `Error: this manifest file has already been signed by specified key`. +- If the file is not a valid manifest, TiUP reports the error `Error: unmarshal manifest: %s`. \ No newline at end of file diff --git a/tiup/tiup-command-mirror.md b/tiup/tiup-command-mirror.md new file mode 100644 index 0000000000000..f21eb6feb3f3a --- /dev/null +++ b/tiup/tiup-command-mirror.md @@ -0,0 +1,37 @@ +--- +title: tiup mirror +--- + +# tiup mirror + +TiUP [mirror](/tiup/tiup-mirror-reference.md) is a very important concept, and it currently supports two forms of mirroring: + +- Local mirror: the TiUP client and mirror are on the same machine, and the client accesses the mirror through the file system +- Remote mirror: the TiUP client and the mirror are not on the same machine, and the client accesses the mirror through the network + +The `tiup mirror` command is used to manage mirrors and provides various functions such as mirror creation, component distribution, key management. + +## Syntax + +```shell +tiup mirror [flags] +``` + +`` stands for sub-commands. For the list of supported sub-commands, refer to the command list below. + +## Option + +None + +## Command list + +- [genkey](/tiup/tiup-command-mirror-genkey.md): generates a private key file +- [sign](/tiup/tiup-command-mirror-sign.md): signs a specific file with a private key file +- [init](/tiup/tiup-command-mirror-init.md): creates an empty mirror +- [set](/tiup/tiup-command-mirror-set.md): sets the current mirror +- [grant](/tiup/tiup-command-mirror-grant.md): introduces a new component owner for the current mirror +- [publish](/tiup/tiup-command-mirror-publish.md): pushes new components to the current mirror +- [modify](/tiup/tiup-command-mirror-modify.md): modifies the properties of the components in the current mirror +- [rotate](/tiup/tiup-command-mirror-rotate.md): updates the root certificate in the current mirror +- [clone](/tiup/tiup-command-mirror-rotate.md): clones a new mirror from an existing one +- [merge](/tiup/tiup-command-mirror-merge.md): merges mirrors \ No newline at end of file From af351e6ccce134cfc617f0e41f595b9ef15b142f Mon Sep 17 00:00:00 2001 From: Joyinqin Date: Mon, 12 Apr 2021 15:05:50 +0800 Subject: [PATCH 02/12] Update tiup-command-mirror-merge.md --- tiup/tiup-command-mirror-merge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tiup/tiup-command-mirror-merge.md b/tiup/tiup-command-mirror-merge.md index 2e290effaff5f..12f5de8f0975d 100644 --- a/tiup/tiup-command-mirror-merge.md +++ b/tiup/tiup-command-mirror-merge.md @@ -8,8 +8,8 @@ The `tiup mirror merge` command is used to merge one or more mirrors to the curr To execute this command, you need to meet the following conditions: --The owner IDs of all components of the target mirror must exist in the current mirror. --The user's `${TIUP_HOME}/keys` directory has all the private keys corresponding to the above owner ID in the current mirror (you can use the command [`tiup mirror set`](/tiup/tiup-command-mirror-set.md) to switch the current mirror to the mirror that is currently authorized to modify). +- The owner IDs of all components of the target mirror must exist in the current mirror. +- The user's `${TIUP_HOME}/keys` directory has all the private keys corresponding to the above owner ID in the current mirror (you can use the command [`tiup mirror set`](/tiup/tiup-command-mirror-set.md) to switch the current mirror to the mirror that is currently authorized to modify). ## Syntax From c178518cdaabb773c9d54e534043698dc5128f57 Mon Sep 17 00:00:00 2001 From: Joyinqin Date: Mon, 12 Apr 2021 15:14:18 +0800 Subject: [PATCH 03/12] Update tiup-command-mirror.md --- tiup/tiup-command-mirror.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-command-mirror.md b/tiup/tiup-command-mirror.md index f21eb6feb3f3a..fc31818ee1d10 100644 --- a/tiup/tiup-command-mirror.md +++ b/tiup/tiup-command-mirror.md @@ -33,5 +33,5 @@ None - [publish](/tiup/tiup-command-mirror-publish.md): pushes new components to the current mirror - [modify](/tiup/tiup-command-mirror-modify.md): modifies the properties of the components in the current mirror - [rotate](/tiup/tiup-command-mirror-rotate.md): updates the root certificate in the current mirror -- [clone](/tiup/tiup-command-mirror-rotate.md): clones a new mirror from an existing one +- [clone](/tiup/tiup-command-mirror-clone.md): clones a new mirror from an existing one - [merge](/tiup/tiup-command-mirror-merge.md): merges mirrors \ No newline at end of file From acdb3da298c76f8e402bcd1b28fa13b94da22fca Mon Sep 17 00:00:00 2001 From: Joyinqin Date: Mon, 12 Apr 2021 16:24:43 +0800 Subject: [PATCH 04/12] Update tiup-command-mirror-sign.md --- tiup/tiup-command-mirror-sign.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tiup/tiup-command-mirror-sign.md b/tiup/tiup-command-mirror-sign.md index 883725811b832..865e925bb2ae2 100644 --- a/tiup/tiup-command-mirror-sign.md +++ b/tiup/tiup-command-mirror-sign.md @@ -19,8 +19,8 @@ tiup mirror sign [flags] If it is a network address, the address must provide the following functions: --Support access with `http get`, at this time the complete content of the signed file (including the signatures field) should be returned --Support access with `http post`, the client adds this signature to the signatures field of the content returned by `http get` and POST to this address +- Support access with `http get`, at this time the complete content of the signed file (including the signatures field) should be returned +- Support access with `http post`, the client adds this signature to the signatures field of the content returned by `http get` and POST to this address ## Options From 9e457438689be2383bf4ad47cfccd7649a78b688 Mon Sep 17 00:00:00 2001 From: Joyinqin Date: Tue, 13 Apr 2021 18:16:26 +0800 Subject: [PATCH 05/12] update 2 docs --- tiup/tiup-command-mirror-merge.md | 4 ++-- tiup/tiup-command-mirror-modify.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tiup/tiup-command-mirror-merge.md b/tiup/tiup-command-mirror-merge.md index 12f5de8f0975d..a50eb48f1e0e2 100644 --- a/tiup/tiup-command-mirror-merge.md +++ b/tiup/tiup-command-mirror-merge.md @@ -9,7 +9,7 @@ The `tiup mirror merge` command is used to merge one or more mirrors to the curr To execute this command, you need to meet the following conditions: - The owner IDs of all components of the target mirror must exist in the current mirror. -- The user's `${TIUP_HOME}/keys` directory has all the private keys corresponding to the above owner ID in the current mirror (you can use the command [`tiup mirror set`](/tiup/tiup-command-mirror-set.md) to switch the current mirror to the mirror that is currently authorized to modify). +- The `${TIUP_HOME}/keys` directory of the user executing this command contains all the private keys corresponding to the above owner ID in the current mirror (you can use the command [`tiup mirror set`](/tiup/tiup-command-mirror-set.md) to switch the current mirror to the mirror that is currently authorized to modify). ## Syntax @@ -27,4 +27,4 @@ None ## Outputs - If the command is executed successfully, there is no output. -- If the current mirror is missing the component owner of the target mirror, or `${TIUP_HOME}/keys` is missing the administrator's private key, TiUP reports the `Error: missing owner keys for owner %s on component %s` error. \ No newline at end of file +- If the current mirror does not have the component owner of the target mirror, or `${TIUP_HOME}/keys` does not have the owner's private key, TiUP reports the `Error: missing owner keys for owner %s on component %s` error. \ No newline at end of file diff --git a/tiup/tiup-command-mirror-modify.md b/tiup/tiup-command-mirror-modify.md index d1220029c407a..0e987db933938 100644 --- a/tiup/tiup-command-mirror-modify.md +++ b/tiup/tiup-command-mirror-modify.md @@ -4,7 +4,7 @@ title: tiup mirror modify # tiup mirror modify -The `tiup mirror modify` command is used to modify published components. Only legitimate component administrators can modify components, and only their own published components can be modified. For the component publishing method, refer to [`publish` command](/tiup/tiup-command-mirror-publish.md). +The `tiup mirror modify` command is used to modify published components. Only authorized component owners can modify components, and only modify their own published components. For the component publishing method, refer to the [`publish` command](/tiup/tiup-command-mirror-publish.md). ## Syntax @@ -29,8 +29,8 @@ Each parameter is explained as follows: Mark the specified component or version as unavailable. -- After marking the component as unavailable, `tiup list` cannot see the component, nor can the new version of the component be installed. -- After marking the component as unavailable, `tiup list ` cannot see the version, nor can this version be installed. +- After marking the component as unavailable, the component cannot be seen in the `tiup list`, nor can the new version of the component be installed. +- After marking the component as unavailable, the version cannot be seen in the `tiup list `, nor can this version be installed. - Data type: `BOOLEAN` - Default: false From 32e86c9ced6cebb90ae88516075e4dd600ab8d5c Mon Sep 17 00:00:00 2001 From: Joyinqin Date: Wed, 14 Apr 2021 11:04:26 +0800 Subject: [PATCH 06/12] refine the docs --- tiup/tiup-command-mirror-modify.md | 8 ++++---- tiup/tiup-command-mirror-sign.md | 10 +++++----- tiup/tiup-command-mirror.md | 8 ++++---- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/tiup/tiup-command-mirror-modify.md b/tiup/tiup-command-mirror-modify.md index 0e987db933938..cfc90cd65d54f 100644 --- a/tiup/tiup-command-mirror-modify.md +++ b/tiup/tiup-command-mirror-modify.md @@ -4,7 +4,7 @@ title: tiup mirror modify # tiup mirror modify -The `tiup mirror modify` command is used to modify published components. Only authorized component owners can modify components, and only modify their own published components. For the component publishing method, refer to the [`publish` command](/tiup/tiup-command-mirror-publish.md). +The `tiup mirror modify` command is used to modify published components. Only valid component owners can modify components, and only modify their own published components. For the component publishing method, refer to the [`publish` command](/tiup/tiup-command-mirror-publish.md). ## Syntax @@ -27,10 +27,10 @@ Each parameter is explained as follows: ### --yank -Mark the specified component or version as unavailable. +Marks the specified component or version as unavailable. -- After marking the component as unavailable, the component cannot be seen in the `tiup list`, nor can the new version of the component be installed. -- After marking the component as unavailable, the version cannot be seen in the `tiup list `, nor can this version be installed. +- After you mark the component as unavailable, the component cannot be seen in the `tiup list`, nor can the new version of the component be installed. +- After you mark the component as unavailable, the version cannot be seen in the `tiup list `, nor can this version be installed. - Data type: `BOOLEAN` - Default: false diff --git a/tiup/tiup-command-mirror-sign.md b/tiup/tiup-command-mirror-sign.md index 865e925bb2ae2..227e10a59c615 100644 --- a/tiup/tiup-command-mirror-sign.md +++ b/tiup/tiup-command-mirror-sign.md @@ -4,7 +4,7 @@ title: tiup mirror sign # tiup mirror sign -The `tiup mirror sign` command is used to sign the meta-information files (*.json）defined in TiUP [mirror](/tiup/tiup-mirror-reference.md). These meta-information files might be stored on the local file system or remotely stored using the http protocol to provide a signature entry. +The `tiup mirror sign` command is used to sign the metadata files (*.json）defined in TiUP [mirror](/tiup/tiup-mirror-reference.md). These metadata files might be stored on the local file system or remotely stored using the http protocol to provide a signature entry. ## Syntax @@ -17,10 +17,10 @@ tiup mirror sign [flags] - Network address: start with http or https, such as `http://172.16.5.5:8080/rotate/root.json` - Local file path: relative path or absolute path -If it is a network address, the address must provide the following functions: +If it is a network address, this address must provide the following functions: -- Support access with `http get`, at this time the complete content of the signed file (including the signatures field) should be returned -- Support access with `http post`, the client adds this signature to the signatures field of the content returned by `http get` and POST to this address +- Supports access with `http get`, at this time the complete content of the signed file (including the signatures field) should be returned +- Supports access with `http post`, the client adds this signature to the signatures field of the content that is returned by `http get` and POST to this address ## Options @@ -32,7 +32,7 @@ If it is a network address, the address must provide the following functions: ### --timeout -- Specifies the access timeout of the network when signing through the network. The unit is seconds. +- Specifies the access timeout of the network when signing through the network. The unit is in seconds. - Data type: `int` - Default: 10 diff --git a/tiup/tiup-command-mirror.md b/tiup/tiup-command-mirror.md index fc31818ee1d10..592319956990b 100644 --- a/tiup/tiup-command-mirror.md +++ b/tiup/tiup-command-mirror.md @@ -4,7 +4,7 @@ title: tiup mirror # tiup mirror -TiUP [mirror](/tiup/tiup-mirror-reference.md) is a very important concept, and it currently supports two forms of mirroring: +TiUP [mirror](/tiup/tiup-mirror-reference.md) is a very important concept, and TiUP currently supports two forms of mirroring: - Local mirror: the TiUP client and mirror are on the same machine, and the client accesses the mirror through the file system - Remote mirror: the TiUP client and the mirror are not on the same machine, and the client accesses the mirror through the network @@ -27,10 +27,10 @@ None - [genkey](/tiup/tiup-command-mirror-genkey.md): generates a private key file - [sign](/tiup/tiup-command-mirror-sign.md): signs a specific file with a private key file -- [init](/tiup/tiup-command-mirror-init.md): creates an empty mirror +- [init](/tiup/tiup-command-mirror-init.md): initiates an empty mirror - [set](/tiup/tiup-command-mirror-set.md): sets the current mirror -- [grant](/tiup/tiup-command-mirror-grant.md): introduces a new component owner for the current mirror -- [publish](/tiup/tiup-command-mirror-publish.md): pushes new components to the current mirror +- [grant](/tiup/tiup-command-mirror-grant.md): grants a new component owner for the current mirror +- [publish](/tiup/tiup-command-mirror-publish.md): publishes new components to the current mirror - [modify](/tiup/tiup-command-mirror-modify.md): modifies the properties of the components in the current mirror - [rotate](/tiup/tiup-command-mirror-rotate.md): updates the root certificate in the current mirror - [clone](/tiup/tiup-command-mirror-clone.md): clones a new mirror from an existing one From 759798abee523820c919d73606a5bf9fbc6eb08e Mon Sep 17 00:00:00 2001 From: JoyinQ <56883733+Joyinqin@users.noreply.github.com> Date: Wed, 14 Apr 2021 16:07:07 +0800 Subject: [PATCH 07/12] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-command-mirror-merge.md | 8 ++++---- tiup/tiup-command-mirror-modify.md | 24 ++++++++++++------------ tiup/tiup-command-mirror-sign.md | 20 ++++++++++---------- tiup/tiup-command-mirror.md | 18 +++++++++--------- 4 files changed, 35 insertions(+), 35 deletions(-) diff --git a/tiup/tiup-command-mirror-merge.md b/tiup/tiup-command-mirror-merge.md index a50eb48f1e0e2..6e93d3a2330b5 100644 --- a/tiup/tiup-command-mirror-merge.md +++ b/tiup/tiup-command-mirror-merge.md @@ -6,10 +6,10 @@ title: tiup mirror merge The `tiup mirror merge` command is used to merge one or more mirrors to the current mirror. -To execute this command, you need to meet the following conditions: +To execute this command, the following conditions must be met: -- The owner IDs of all components of the target mirror must exist in the current mirror. -- The `${TIUP_HOME}/keys` directory of the user executing this command contains all the private keys corresponding to the above owner ID in the current mirror (you can use the command [`tiup mirror set`](/tiup/tiup-command-mirror-set.md) to switch the current mirror to the mirror that is currently authorized to modify). +- The owner IDs of all components of the target mirror exist in the current mirror. +- The `${TIUP_HOME}/keys` directory of the user who executes this command contains all the private keys corresponding to the above owner IDs in the current mirror (you can use the command [`tiup mirror set`](/tiup/tiup-command-mirror-set.md) to switch the current mirror to the mirror that is currently authorized to modify). ## Syntax @@ -27,4 +27,4 @@ None ## Outputs - If the command is executed successfully, there is no output. -- If the current mirror does not have the component owner of the target mirror, or `${TIUP_HOME}/keys` does not have the owner's private key, TiUP reports the `Error: missing owner keys for owner %s on component %s` error. \ No newline at end of file +- If the current mirror does not have a component owner of the target mirror, or if `${TIUP_HOME}/keys` does not have the owner's private key, TiUP reports the `Error: missing owner keys for owner %s on component %s` error. diff --git a/tiup/tiup-command-mirror-modify.md b/tiup/tiup-command-mirror-modify.md index cfc90cd65d54f..ad02150795788 100644 --- a/tiup/tiup-command-mirror-modify.md +++ b/tiup/tiup-command-mirror-modify.md @@ -4,7 +4,7 @@ title: tiup mirror modify # tiup mirror modify -The `tiup mirror modify` command is used to modify published components. Only valid component owners can modify components, and only modify their own published components. For the component publishing method, refer to the [`publish` command](/tiup/tiup-command-mirror-publish.md). +The `tiup mirror modify` command is used to modify published components. Only valid component owners can modify the components that they have published on their own. For the method to publish a component, refer to the [`publish` command](/tiup/tiup-command-mirror-publish.md). ## Syntax @@ -15,30 +15,30 @@ tiup mirror modify [:version] [flags] Each parameter is explained as follows: - ``: the component name -- `[version]`: the version you want to modify. If not specified, the entire component is modified. +- `[version]`: the component version to modify. If it is not specified, the entire component is modified. ## Options ### -k, --key -- Specifies the location of the private key used for signing the `{component}.json` files. +- Specifies the component owner's private key used for signing the component information (`{component}.json`). - Data type: `STRING` -- Default: "${TIUP_HOME}/keys/private.json" +- If this option is not specified in the command, `"${TIUP_HOME}/keys/private.json"` is used by default to sign the component information. ### --yank -Marks the specified component or version as unavailable. +Marks a specified component or version as unavailable. -- After you mark the component as unavailable, the component cannot be seen in the `tiup list`, nor can the new version of the component be installed. -- After you mark the component as unavailable, the version cannot be seen in the `tiup list `, nor can this version be installed. +- After the component is marked as unavailable, you can neither see it in the result list of `tiup list` nor install the new version of the component. +- After a component version is marked as unavailable, you can neither see it in the result list of `tiup list ` nor install this version. - Data type: `BOOLEAN` - Default: false ### --hide -- Specifies whether the component is hidden. If it is a hidden component, it can be seen in the result list of `tiup list -all`, but not in that of `tiup list`. -- Data type: `STRING` -- Default: NULL +- Specifies whether to hide the component. If a component is hidden, you cannot see it in the result list of `tiup list`. To see the hidden component, you can use `tiup list --all`. +- Data type: `BOOLEAN` +- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command and pass in the `true` value or no value. > **Note:** > @@ -48,7 +48,7 @@ Marks the specified component or version as unavailable. - Controls whether the component can run standalone. This option is currently **NOT available**. - Data type: `BOOLEAN` -- Default: false +- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command and pass in the `true` value or no value. > **Note:** > @@ -59,4 +59,4 @@ Marks the specified component or version as unavailable. - If the command is executed successfully, there is no output. - If the component owner is not authorized to modify the target component: - If the mirror is a remote mirror, TiUP reports the error `Error: The server refused, make sure you have access to this component`. - - If the mirror is a local mirror, TiUP reports the error `Error: the signature is not correct`. \ No newline at end of file + - If the mirror is a local mirror, TiUP reports the error `Error: the signature is not correct`. diff --git a/tiup/tiup-command-mirror-sign.md b/tiup/tiup-command-mirror-sign.md index 227e10a59c615..881e8628529d8 100644 --- a/tiup/tiup-command-mirror-sign.md +++ b/tiup/tiup-command-mirror-sign.md @@ -4,7 +4,7 @@ title: tiup mirror sign # tiup mirror sign -The `tiup mirror sign` command is used to sign the metadata files (*.json）defined in TiUP [mirror](/tiup/tiup-mirror-reference.md). These metadata files might be stored on the local file system or remotely stored using the http protocol to provide a signature entry. +The `tiup mirror sign` command is used to sign the metadata files (*.json）defined in TiUP [mirror](/tiup/tiup-mirror-reference.md). These metadata files might be stored on the local file system or remotely stored using the HTTP protocol to provide a signature entry. ## Syntax @@ -12,28 +12,28 @@ The `tiup mirror sign` command is used to sign the metadata files (*.json）defi tiup mirror sign [flags] ``` -`` is the address of the signed file, which has two forms: +`` is the address of the file to be signed, which has two forms: -- Network address: start with http or https, such as `http://172.16.5.5:8080/rotate/root.json` -- Local file path: relative path or absolute path +- Network address, which starts with HTTP or HTTPS, such as `http://172.16.5.5:8080/rotate/root.json` +- Local file path, which is a relative path or an absolute path If it is a network address, this address must provide the following functions: -- Supports access with `http get`, at this time the complete content of the signed file (including the signatures field) should be returned -- Supports access with `http post`, the client adds this signature to the signatures field of the content that is returned by `http get` and POST to this address +- Supports the access via `http get` that returns the complete content of the signed file (including the `signatures` field). +- Supports the access via `http post`. The client adds the signature to the `signatures` field of the content that is returned by `http get` and posts to this network address. ## Options ### -k, --key -- Specifies the location of the private key used for signing the `{component}.json` files. +- Specifies the location of the private key used for signing the `{component}.json` file. - Data type: `STRING` -- Default: "${TIUP_HOME}/keys/private.json" +- - If this option is not specified in the command, `"${TIUP_HOME}/keys/private.json"` is used by default. ### --timeout - Specifies the access timeout of the network when signing through the network. The unit is in seconds. -- Data type: `int` +- Data type: `INT` - Default: 10 > **Note:** @@ -44,4 +44,4 @@ If it is a network address, this address must provide the following functions: - If the command is executed successfully, there is no output. - If the file has been signed by the specified key, TiUP reports the error `Error: this manifest file has already been signed by specified key`. -- If the file is not a valid manifest, TiUP reports the error `Error: unmarshal manifest: %s`. \ No newline at end of file +- If the file is not a valid manifest, TiUP reports the error `Error: unmarshal manifest: %s`. diff --git a/tiup/tiup-command-mirror.md b/tiup/tiup-command-mirror.md index 592319956990b..22277aafe1ab3 100644 --- a/tiup/tiup-command-mirror.md +++ b/tiup/tiup-command-mirror.md @@ -4,12 +4,12 @@ title: tiup mirror # tiup mirror -TiUP [mirror](/tiup/tiup-mirror-reference.md) is a very important concept, and TiUP currently supports two forms of mirroring: +In TiUP, [mirror](/tiup/tiup-mirror-reference.md) is an important concept. TiUP currently supports two forms of mirroring: -- Local mirror: the TiUP client and mirror are on the same machine, and the client accesses the mirror through the file system -- Remote mirror: the TiUP client and the mirror are not on the same machine, and the client accesses the mirror through the network +- Local mirror: the TiUP client and the mirror are on the same machine, and the client accesses the mirror through the file system. +- Remote mirror: the TiUP client and the mirror are not on the same machine, and the client accesses the mirror through network. -The `tiup mirror` command is used to manage mirrors and provides various functions such as mirror creation, component distribution, key management. +The `tiup mirror` command is used to manage mirrors and provides ways to create mirrors, distribute components, and manage keys. ## Syntax @@ -17,7 +17,7 @@ The `tiup mirror` command is used to manage mirrors and provides various functio tiup mirror [flags] ``` -`` stands for sub-commands. For the list of supported sub-commands, refer to the command list below. +`` stands for sub-commands. For the list of supported sub-commands, refer to the [command list](#command-list) below. ## Option @@ -25,13 +25,13 @@ None ## Command list -- [genkey](/tiup/tiup-command-mirror-genkey.md): generates a private key file -- [sign](/tiup/tiup-command-mirror-sign.md): signs a specific file with a private key file +- [genkey](/tiup/tiup-command-mirror-genkey.md): generates the private key file +- [sign](/tiup/tiup-command-mirror-sign.md): signs a specific file using a private key file - [init](/tiup/tiup-command-mirror-init.md): initiates an empty mirror - [set](/tiup/tiup-command-mirror-set.md): sets the current mirror - [grant](/tiup/tiup-command-mirror-grant.md): grants a new component owner for the current mirror - [publish](/tiup/tiup-command-mirror-publish.md): publishes new components to the current mirror -- [modify](/tiup/tiup-command-mirror-modify.md): modifies the properties of the components in the current mirror +- [modify](/tiup/tiup-command-mirror-modify.md): modifies the attributes of the components in the current mirror - [rotate](/tiup/tiup-command-mirror-rotate.md): updates the root certificate in the current mirror - [clone](/tiup/tiup-command-mirror-clone.md): clones a new mirror from an existing one -- [merge](/tiup/tiup-command-mirror-merge.md): merges mirrors \ No newline at end of file +- [merge](/tiup/tiup-command-mirror-merge.md): merges mirrors From 827f7f13bf998ebf2e585b003b8c984db2c2c9f0 Mon Sep 17 00:00:00 2001 From: JoyinQ <56883733+Joyinqin@users.noreply.github.com> Date: Wed, 14 Apr 2021 16:09:47 +0800 Subject: [PATCH 08/12] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-command-mirror-modify.md | 4 ++-- tiup/tiup-command-mirror-sign.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tiup/tiup-command-mirror-modify.md b/tiup/tiup-command-mirror-modify.md index ad02150795788..6bd858bc03051 100644 --- a/tiup/tiup-command-mirror-modify.md +++ b/tiup/tiup-command-mirror-modify.md @@ -32,7 +32,7 @@ Marks a specified component or version as unavailable. - After the component is marked as unavailable, you can neither see it in the result list of `tiup list` nor install the new version of the component. - After a component version is marked as unavailable, you can neither see it in the result list of `tiup list ` nor install this version. - Data type: `BOOLEAN` -- Default: false +- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command and pass in the `true` value or no value. ### --hide @@ -42,7 +42,7 @@ Marks a specified component or version as unavailable. > **Note:** > -> This option can only be applied to the component, not to the version of the component. +> This option can only be applied to the component, not to the component version. ### --standalone diff --git a/tiup/tiup-command-mirror-sign.md b/tiup/tiup-command-mirror-sign.md index 881e8628529d8..397d07cefe660 100644 --- a/tiup/tiup-command-mirror-sign.md +++ b/tiup/tiup-command-mirror-sign.md @@ -17,7 +17,7 @@ tiup mirror sign [flags] - Network address, which starts with HTTP or HTTPS, such as `http://172.16.5.5:8080/rotate/root.json` - Local file path, which is a relative path or an absolute path -If it is a network address, this address must provide the following functions: +If it is a network address, this address must provide the following features: - Supports the access via `http get` that returns the complete content of the signed file (including the `signatures` field). - Supports the access via `http post`. The client adds the signature to the `signatures` field of the content that is returned by `http get` and posts to this network address. @@ -32,7 +32,7 @@ If it is a network address, this address must provide the following functions: ### --timeout -- Specifies the access timeout of the network when signing through the network. The unit is in seconds. +- Specifies the access timeout time for signing through the network. The unit is in seconds. - Data type: `INT` - Default: 10 From 1281316bac95f58de86709d82c075c2b50c8800b Mon Sep 17 00:00:00 2001 From: Joyinqin Date: Wed, 14 Apr 2021 17:02:06 +0800 Subject: [PATCH 09/12] Update tiup-command-mirror-modify.md --- tiup/tiup-command-mirror-modify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-command-mirror-modify.md b/tiup/tiup-command-mirror-modify.md index 6bd858bc03051..3a4ab48b3efb9 100644 --- a/tiup/tiup-command-mirror-modify.md +++ b/tiup/tiup-command-mirror-modify.md @@ -52,7 +52,7 @@ Marks a specified component or version as unavailable. > **Note:** > -> This option can only be applied to the component, not to the version of the component. +> This option can only be applied to the component, not to the component version. ## Outputs From 78dd99b60948760ef86a179b3d2c0b0c274fd41d Mon Sep 17 00:00:00 2001 From: Joyinqin Date: Wed, 14 Apr 2021 17:34:22 +0800 Subject: [PATCH 10/12] hide the links --- tiup/tiup-command-mirror.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tiup/tiup-command-mirror.md b/tiup/tiup-command-mirror.md index 22277aafe1ab3..22cff91987ff2 100644 --- a/tiup/tiup-command-mirror.md +++ b/tiup/tiup-command-mirror.md @@ -27,11 +27,11 @@ None - [genkey](/tiup/tiup-command-mirror-genkey.md): generates the private key file - [sign](/tiup/tiup-command-mirror-sign.md): signs a specific file using a private key file -- [init](/tiup/tiup-command-mirror-init.md): initiates an empty mirror +- [init]: initiates an empty mirror - [set](/tiup/tiup-command-mirror-set.md): sets the current mirror - [grant](/tiup/tiup-command-mirror-grant.md): grants a new component owner for the current mirror - [publish](/tiup/tiup-command-mirror-publish.md): publishes new components to the current mirror - [modify](/tiup/tiup-command-mirror-modify.md): modifies the attributes of the components in the current mirror -- [rotate](/tiup/tiup-command-mirror-rotate.md): updates the root certificate in the current mirror +- [rotate]: updates the root certificate in the current mirror - [clone](/tiup/tiup-command-mirror-clone.md): clones a new mirror from an existing one - [merge](/tiup/tiup-command-mirror-merge.md): merges mirrors From bfd3eb39a115814bd08e7a6442e3948281188d93 Mon Sep 17 00:00:00 2001 From: JoyinQ <56883733+Joyinqin@users.noreply.github.com> Date: Thu, 15 Apr 2021 14:22:13 +0800 Subject: [PATCH 11/12] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-command-mirror-modify.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tiup/tiup-command-mirror-modify.md b/tiup/tiup-command-mirror-modify.md index 3a4ab48b3efb9..9e5fe1e9b5da3 100644 --- a/tiup/tiup-command-mirror-modify.md +++ b/tiup/tiup-command-mirror-modify.md @@ -32,13 +32,13 @@ Marks a specified component or version as unavailable. - After the component is marked as unavailable, you can neither see it in the result list of `tiup list` nor install the new version of the component. - After a component version is marked as unavailable, you can neither see it in the result list of `tiup list ` nor install this version. - Data type: `BOOLEAN` -- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command and pass in the `true` value or no value. +- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value. ### --hide - Specifies whether to hide the component. If a component is hidden, you cannot see it in the result list of `tiup list`. To see the hidden component, you can use `tiup list --all`. - Data type: `BOOLEAN` -- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command and pass in the `true` value or no value. +- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value. > **Note:** > @@ -48,7 +48,7 @@ Marks a specified component or version as unavailable. - Controls whether the component can run standalone. This option is currently **NOT available**. - Data type: `BOOLEAN` -- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command and pass in the `true` value or no value. +- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value. > **Note:** > From 7102d90dd33c3879d6f5e13d794446b273ffef7e Mon Sep 17 00:00:00 2001 From: JoyinQ <56883733+Joyinqin@users.noreply.github.com> Date: Thu, 15 Apr 2021 14:43:32 +0800 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-command-mirror.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tiup/tiup-command-mirror.md b/tiup/tiup-command-mirror.md index 22cff91987ff2..61394d6e6b4c1 100644 --- a/tiup/tiup-command-mirror.md +++ b/tiup/tiup-command-mirror.md @@ -27,11 +27,11 @@ None - [genkey](/tiup/tiup-command-mirror-genkey.md): generates the private key file - [sign](/tiup/tiup-command-mirror-sign.md): signs a specific file using a private key file -- [init]: initiates an empty mirror +- init: initiates an empty mirror - [set](/tiup/tiup-command-mirror-set.md): sets the current mirror - [grant](/tiup/tiup-command-mirror-grant.md): grants a new component owner for the current mirror - [publish](/tiup/tiup-command-mirror-publish.md): publishes new components to the current mirror - [modify](/tiup/tiup-command-mirror-modify.md): modifies the attributes of the components in the current mirror -- [rotate]: updates the root certificate in the current mirror +- rotate: updates the root certificate in the current mirror - [clone](/tiup/tiup-command-mirror-clone.md): clones a new mirror from an existing one - [merge](/tiup/tiup-command-mirror-merge.md): merges mirrors