From 62b0414db9866ab3b3d4dacb8dbb411cc4705693 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Fri, 9 Apr 2021 11:50:33 +0800 Subject: [PATCH] tiup: add documents of publish, grant, and genkey (#5184) --- tiup/tiup-command-mirror-genkey.md | 53 ++++++++++++++++++ tiup/tiup-command-mirror-grant.md | 42 +++++++++++++++ tiup/tiup-command-mirror-publish.md | 83 +++++++++++++++++++++++++++++ 3 files changed, 178 insertions(+) create mode 100644 tiup/tiup-command-mirror-genkey.md create mode 100644 tiup/tiup-command-mirror-grant.md create mode 100644 tiup/tiup-command-mirror-publish.md diff --git a/tiup/tiup-command-mirror-genkey.md b/tiup/tiup-command-mirror-genkey.md new file mode 100644 index 0000000000000..3f41ef43a0e7b --- /dev/null +++ b/tiup/tiup-command-mirror-genkey.md @@ -0,0 +1,53 @@ +--- +title: tiup mirror genkey +--- + +# tiup mirror genkey + +TiUP [mirror](/tiup/tiup-mirror-reference.md), according its definition, has three roles of users: + +- Mirror administrators: They have the permission to modify `root.json`, `index.json`, `snapshot.json`, and `timestamp.json`. +- Component owners: They have the permission to modify the corresponding component. +- Normal users: They can download and use the components. + + Because TiUP requires the signature of the corresponding owner/administrator to modify a file, owners/administrators must have his or her own private key. The command `tiup mirror genkey` is used to generate a private key. + +> **Warning:** +> +> **DO NOT** transmit private keys over the Internet. + +## Syntax + +```shell +tiup mirror genkey [flags] +``` + +## Options + +### -n, --name + +- Specifies the name of the key, which also determines the name of the final generated file. The path of the generated private key file is `${TIUP_HOME}/keys/{name}.json`. `TIUP_HOME` refers to the home directory of TiUP, which is `$HOME/.tiup` by default. `name` refers to the private key name that `-n/--name` specifies. +- Data type: `STRING` +- Default: "private" + +### -p, --public + +- Shows the corresponding public key of the private key specified in the option `-n/--name`. +- TiUP does not create a new private key when `-p/--public` is specified. If the private key specified in `-n/--name` does not exist, TiUP returns an error. +- Data type: `BOOLEAN` +- Default: false + +### --save + +- Saves the information of the public key as a file in the current directory. The file name is `{hash-prefix}-public.json`. `hash-prefix` is the first 16 bits of the key ID. +- Data type: `BOOLEAN` +- Default: false + +## Outputs + +- If `-p/--public` is not specified: + - If the private key specified in `-n/--name` exists: TiUP outputs `Key already exists, skipped`. + - If the private key specified in `-n/--name` does not exist: TiUP outputs `private key have been write to ${TIUP_HOME}/keys/{name}.json`. +- If `-p/--public` is specified: + - If the private key specified in `-n/--name` does not exist: TiUP reports the error `Error: open ${TIUP_HOME}/keys/{name}.json: no such file or directory`. + - If the private key specified in `-n/--name` exists: TiUP outputs the content of the corresponding public key. diff --git a/tiup/tiup-command-mirror-grant.md b/tiup/tiup-command-mirror-grant.md new file mode 100644 index 0000000000000..a759f699734e5 --- /dev/null +++ b/tiup/tiup-command-mirror-grant.md @@ -0,0 +1,42 @@ +--- +title: tiup mirror grant +--- + +# tiup mirror grant + +The `tiup mirror grant` command is used to introduce a component owner to the current mirror. + +Component owners can use their keys to publish new components or to modify components they previously published. Before adding a new component owner, the component owner to be added needs to send his or her own public key to the mirror administrator. + +> **Note:** +> +> This command is only supported when the current mirror is a local mirror. + +## Syntax + +```shell +tiup mirror grant [flags] +``` + +`` stands for the component owner's ID, which must be unique in the whole mirror. It is recommended to use an ID that matches the regular expression `^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$`. + +## Options + +### -k, --key + +- Specifies the key of the introduced component owner. This key can either be public or private. If it is a private key, TiUP converts it to the corresponding public key before storing it in the mirror. +- A key can be used by only one component owner. +- Data type: `STRING` +- Default: "${TIUP_HOME}/keys/private.json" + +### -n, --name + +- Specifies the name of the component owner. The name is displayed on the `Owner` field of the component list. If `-n/--name` is not specified, `` is used as the component owner's name. +- Data type: `STRING` +- Default: `` + +### Outputs + +- If the command is executed successfully, there is no output. +- If the component owner's ID is duplicated, TiUP reports the error `Error: owner %s exists`. +- If the key is used by another component owner, TiUP reports the error `Error: key %s exists`. diff --git a/tiup/tiup-command-mirror-publish.md b/tiup/tiup-command-mirror-publish.md new file mode 100644 index 0000000000000..1011c379ecce4 --- /dev/null +++ b/tiup/tiup-command-mirror-publish.md @@ -0,0 +1,83 @@ +--- +title: tiup mirror publish +--- + +# tiup mirror publish + +The command `tiup mirror publish` is used to publish a new component or a new version of an existing component. Only component owner that has the access to the target component can publish it. To add a new component owner, see the usage of the [`grant` command](/tiup/tiup-command-mirror-grant.md). + +## Syntax + +```shell +tiup mirror publish [flags] +``` + +The meaning of each parameter is as follows: + +- ``: The name of the components, such as `tidb`. It is recommended to use a string that matches the regular expression `^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$`. +- ``: The version of the component to be published. The version number needs to follow the requirements of [Semantic Versioning](https://semver.org/). +- ``: The local directory of the `.tar.gz` package. You need to put dependencies and the executable file of the component in this package. TiUP uploads this package to the mirror. +- ``: The location of the component's executable file in ``. + +## Options + +### -k, --key + +- Specifies the component owner's private key. The client uses the private key to sign `{component}.json` files. +- Data type: `STRING` +- Default: "${TIUP_HOME}/keys/private.json" + +### --arch + +- Specifies the platform on which the binary files in `` can run. For a single `` package, you can only choose the platform from the following options: + + - `amd64`: Indicates that the files run on AMD64 machines. + - `arm64`: Indicates that the files run on ARM64 machines. + - `any`: Indicates that the files, such as scripts, run on both AMD64 and ARM64 machines. + +- Data type: `STRING` +- Default: "${GOARCH}" + +> **Note:** +> +> If `--arch` is set to `any`, then `--os` must be set to `any` as well. + +### --os + +- Specifies the operating system on which the binary files in `` can run. For a single `` package, you can only choose the operating system from the following options: + + - `linux`: Indicates that the files run on the Linux operating system. + - `darwin`: Indicates that the files run on the Darwin operating system. + - `any`: Indicates that the files, such as scripts, run on both the Linux and Darwin operating systems. + +- Data type: `STRING` +- Default: "${GOOS}" + +> **Note:** +> +> If `--os` is set to `any`, then `--arch` must be set to `any` as well. + +### --desc + +- Specifies the description of the component. +- Data type: `String` +- Default: NULL + +### --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 + +### --standalone + +- Controls whether the component can run standalone. This option is currently **NOT available**. +- Data type: `BOOLEAN` +- Default: false + +## 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`.