tiup: add documents of publish, grant, and genkey (#5184)

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.

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 <id> [flags]
+```
+
+`<id>` 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, `<id>` is used as the component owner's name.
+- Data type: `STRING`
+- Default: `<id>`
+
+### 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`.

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 <comp-name> <version> <tarball> <entry> [flags]
+```
+
+The meaning of each parameter is as follows:
+
+- `<comp-name>`: 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}$`.
+- `<version>`: The version of the component to be published. The version number needs to follow the requirements of [Semantic Versioning](https://semver.org/).
+- `<tarball>`: 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.
+- `<entry>`: The location of the component's executable file in `<tarball>`.
+
+## 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 `<tarball>` can run. For a single `<tarball>` 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 `<tarball>` can run. For a single `<tarball>` 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`.