tiup: add 4 docs mirror-mirror/merge/modify/sign.md (#5285)

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]
 ```
 

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 <shell>
 ```
 
@@ -25,7 +25,7 @@ tiup completion <shell>
 
 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"
 ```

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]
 ```
 

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 <component1>[:version] [component2...N] [flags]
 ```
 

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]
 ```
 

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 <target-dir> [global version] [flags]
 ```
 

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, the following conditions must be met:
+
+- 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
+
+```shell
+tiup mirror merge <mirror-dir-1> [mirror-dir-N] [flags]
+```
+
+- `<mirror-dir-1>`: 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 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.

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 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
+
+```shell
+tiup mirror modify <component>[:version] [flags]
+```
+
+Each parameter is explained as follows:
+
+- `<component>`: the component name
+- `[version]`: the component version to modify. If it is not specified, the entire component is modified.
+
+## Options
+
+### -k, --key
+
+- Specifies the component owner's private key used for signing the component information (`{component}.json`).
+- Data type: `STRING`
+- 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 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 <component>` 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 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 the `true` value or do not pass any value.
+
+> **Note:**
+>
+> This option can only be applied to the component, not to the component version.
+
+### --standalone
+
+- 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 the `true` value or do not pass any value.
+
+> **Note:**
+>
+> This option can only be applied to the component, not to the component version.
+
+## 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`.

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 <mirror-addr> [flags]
 ```
 

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 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
+
+```shell
+tiup mirror sign <manifest-file> [flags]
+```
+
+`<manifest-file>` is the address of the file to be signed, which has two forms:
+
+- 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 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.
+
+## Options
+
+### -k, --key
+
+- Specifies the location of the private key used for signing the `{component}.json` file.
+- Data type: `STRING`
+- - If this option is not specified in the command, `"${TIUP_HOME}/keys/private.json"` is used by default.
+
+### --timeout
+
+- Specifies the access timeout time for signing through the network. The unit is in seconds.
+- Data type: `INT`
+- Default: 10
+
+> **Note:**
+>
+> This option is valid only when `<manifest-file>` 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`.

tiup/tiup-command-mirror.md

@@ -0,0 +1,37 @@
+---
+title: tiup mirror
+---
+
+# tiup mirror
+
+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 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 ways to create mirrors, distribute components, and manage keys.
+
+## Syntax
+
+```shell
+tiup mirror <command> [flags]
+```
+
+`<command>` stands for sub-commands. For the list of supported sub-commands, refer to the [command list](#command-list) below.
+
+## Option
+
+None
+
+## Command list
+
+- [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 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