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-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..6e93d3a2330b5 --- /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, 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-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 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 new file mode 100644 index 0000000000000..9e5fe1e9b5da3 --- /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 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 [:version] [flags] +``` + +Each parameter is explained as follows: + +- ``: 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 ` 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`. 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..397d07cefe660 --- /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 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 [flags] +``` + +`` 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 `` 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`. diff --git a/tiup/tiup-command-mirror.md b/tiup/tiup-command-mirror.md new file mode 100644 index 0000000000000..61394d6e6b4c1 --- /dev/null +++ b/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 [flags] +``` + +`` 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: 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 +- [clone](/tiup/tiup-command-mirror-clone.md): clones a new mirror from an existing one +- [merge](/tiup/tiup-command-mirror-merge.md): merges mirrors