tiup
tiup copied to clipboard
pingcap
Man pages
Feature Request
The commands in TiUP do not currently have any man pages. Typically all commands in a Linux/Unix system have man pages, which can be browsed on the command-line e.g. man tiup or via websites such as https://dyn.manpages.debian.org/ or https://manpages.ubuntu.com/.
This feature request was motivated by Lintian nagging about https://lintian.debian.org/tags/no-manual-page.html in Debian:
W: tiup: no-manual-page [usr/bin/client]
N:
N: Each binary in /usr/bin, /usr/sbin, /bin, /sbin or /usr/games should have
N: a manual page
N:
N: Note that though the man program has the capability to check for several
N: program names in the NAMES section, each of these programs should have its
N: own manual page (a symbolic link to the appropriate manual page is
N: sufficient) because other manual page viewers such as xman or tkman don't
N: support this.
N:
N: If the name of the manual page differs from the binary by case, man may be
N: able to find it anyway; however, it is still best practice to match the
N: exact capitalization of the executable in the manual page.
N:
N: If the manual pages are provided by another package on which this package
N: depends, Lintian may not be able to determine that manual pages are
N: available. In this case, after confirming that all binaries do have manual
N: pages after this package and its dependencies are installed, please add a
N: Lintian override.
N:
N: Please refer to Manual pages (Section 12.1) in the Debian Policy Manual
N: for details.
N:
N: Visibility: warning
N: Show-Always: no
N: Check: documentation/manual
N: Renamed from: binary-without-manpage
N:
N:
W: tiup: no-manual-page [usr/bin/cluster]
N:
W: tiup: no-manual-page [usr/bin/ctl]
N:
W: tiup: no-manual-page [usr/bin/dm]
N:
W: tiup: no-manual-page [usr/bin/package]
N:
W: tiup: no-manual-page [usr/bin/playground]
N:
W: tiup: no-manual-page [usr/bin/server]
N:
W: tiup: no-manual-page [usr/bin/tiup]
Related: #2508 #2507
Hi @ottok,
One option I discussed with @dveeden was to create a high-level static content with link(s) to TiUP docs pages.
Having a manpage for tiup would be good. And also for tiup-playground (used as tiup playground, somewhat similar to the git-commit manpage for git commit).
The output shows usr/bin/playground, while I would expect tiup-playground. And that binary should be called by tiup and not directly by users, so it should probably not bin in usr/bin, right?
.TH TIUP 1 "April 2025" "TiUP v8.4" "User Commands"
.SH NAME
tiup \- A package manager for the TiDB ecosystem
.SH SYNOPSIS
.B tiup
[\fIflags\fR] <\fIcommand\fR> [\fIargs...\fR]
.br
.B tiup
[\fIflags\fR] <\fIcomponent\fR> [\fIargs...\fR]
.SH DESCRIPTION
TiUP is a command-line tool that serves as the package manager for the TiDB ecosystem. It manages components such as TiDB, PD, and TiKV, and supports various commands for installation, updating, and management of these components. TiUP also facilitates the management of TiDB clusters and TiDB Data Migration (DM) clusters.
.SH OPTIONS
.TP
.B \-\-binary
Prints the path of the specified binary file. If no version is specified, the latest stable version installed is used. This option is only applicable in the format \fBtiup [flags] <component> [args...]\fR.
.TP
.B \-\-binpath
Specifies the path of the component to be executed, allowing the use of a custom binary file path instead of the default TiUP mirror.
.TP
.B \-T, \-\-tag
Specifies a tag for the component to be started, allowing TiUP to allocate a fixed directory for disk storage during execution.
.TP
.B \-v, \-\-version
Prints the version of TiUP.
.TP
.B \-\-help
Displays help information for TiUP commands and components.
.SH EXAMPLES
.TP
To install a specific version of a component:
.B
tiup install <component>[:version]
.TP
To update all installed components to the latest version:
.B
tiup update \-\-all
.TP
To start a TiDB cluster locally using the playground component:
.B
tiup playground
.TP
To list the available TiDB components or versions:
.B
tiup list
.SH SEE ALSO
For more detailed information, visit the official documentation at:
https://docs.pingcap.com/tidb/v8.4/tiup-overview
https://docs.pingcap.com/tidb/v8.4/tiup-reference
https://tidb.ai/c/01966405-45a0-72f9-8ded-07bb1573ffa7
In https://github.com/xo/usql/pull/521 I submitted a man page for usql that would be included in the upstream repository directory man. Could the same pattern apply here, could tiup carry manpage stubs in man/ and the https://github.com/pingcap/tiup/blob/master/install.sh script install them on target system at /usr/local/share/man/man1 or similar?
Output of commands currently:
/usr/bin/client --help
Connect a TiDB cluster in your local host
Usage:
tiup client [flags]
Flags:
-h, --help help for tiup
/usr/bin/cluster --help
Deploy a TiDB cluster for production
Usage:
cluster [command]
Available Commands:
check Perform preflight checks for the cluster.
deploy Deploy a cluster for production
start Start a TiDB cluster
stop Stop a TiDB cluster
restart Restart a TiDB cluster
scale-in Scale in a TiDB cluster
scale-out Scale out a TiDB cluster
destroy Destroy a specified cluster
clean (EXPERIMENTAL) Cleanup a specified cluster
upgrade Upgrade a specified TiDB cluster
display Display information of a TiDB cluster
prune Destroy and remove instances that is in tombstone state
list List all clusters
audit Show audit log of cluster operation
import Import an exist TiDB cluster from TiDB-Ansible
edit-config Edit TiDB cluster config
show-config Show TiDB cluster config
reload Reload a TiDB cluster's config and restart if needed
patch Replace the remote package with a specified package and restart the service
rename Rename the cluster
enable Enable a TiDB cluster automatically at boot
disable Disable automatic enabling of TiDB clusters at boot
replay Replay previous operation and skip successed steps
template Print topology template
tls Enable/Disable TLS between TiDB components
meta backup/restore meta information
rotatessh rotate ssh keys on all nodes
help Help about any command
completion Generate the autocompletion script for the specified shell
Flags:
-c, --concurrency int max number of parallel tasks allowed (default 5)
--format string (EXPERIMENTAL) The format of output, available values are [default, json] (default "default")
-h, --help help for cluster
--ssh string (EXPERIMENTAL) The executor type: 'builtin', 'system', 'none'.
--ssh-timeout uint Timeout in seconds to connect host via SSH, ignored for operations that don't need an SSH connection. (default 5)
-v, --version version for cluster
--wait-timeout uint Timeout in seconds to wait for an operation to complete, ignored for operations that don't fit. (default 120)
-y, --yes Skip all confirmations and assumes 'yes'
Use "cluster help [command]" for more information about a command.
/usr/bin/ctl --help
(no output)
/usr/bin/dm --help
EXPERIMENTAL: This is an experimental feature, things may or may not work,
please backup your data before process.
Usage:
dm [command]
Available Commands:
deploy Deploy a DM cluster for production
start Start a DM cluster
stop Stop a DM cluster
restart Restart a DM cluster
list List all clusters
destroy Destroy a specified DM cluster
audit Show audit log of cluster operation
edit-config Edit DM cluster config
display Display information of a DM cluster
prune Clear etcd info
reload Reload a DM cluster's config and restart if needed
upgrade Upgrade a specified DM cluster
patch Replace the remote package with a specified package and restart the service
scale-out Scale out a DM cluster
scale-in Scale in a DM cluster
import Import an exist DM 1.0 cluster from dm-ansible and re-deploy 2.0 version
enable Enable a DM cluster automatically at boot
disable Disable automatic enabling of DM clusters at boot
replay Replay previous operation and skip successed steps
template Print topology template
meta backup/restore meta information
rotatessh rotate ssh keys on all nodes
help Help about any command
completion Generate the autocompletion script for the specified shell
Flags:
-c, --concurrency int max number of parallel tasks allowed (default 5)
--format string (EXPERIMENTAL) The format of output, available values are [default, json] (default "default")
-h, --help help for dm
--ssh string The executor type: 'builtin', 'system', 'none'
--ssh-timeout uint Timeout in seconds to connect host via SSH, ignored for operations that don't need an SSH connection. (default 5)
-v, --version version for dm
--wait-timeout uint Timeout in seconds to wait for an operation to complete, ignored for operations that don't fit. (default 120)
-y, --yes Skip all confirmations and assumes 'yes'
Use "dm help [command]" for more information about a command.
/usr/bin/package --help
Package a tiup component and generate package directory
Usage:
tiup package target [flags]
Flags:
-C, -- string Change directory before compress
--arch string Target ARCH of the package (default "amd64")
--desc string (deprecated) Description of the package
--entry string (deprecated) Entry point of the package
-h, --help help for tiup
--hide tiup list (deprecated) Don't show the component in tiup list
--name string Name of the package (required)
--os string Target OS of the package (default "linux")
--release string Version of the package (required)
--standalone (deprecated) Can the component run standalone
/usr/bin/playground --help
Bootstrap a TiDB cluster in your local host, the latest release version will be chosen
if you don't specified a version.
Examples:
$ tiup playground nightly # Start a TiDB nightly version local cluster
$ tiup playground v5.0.1 --db 3 --pd 3 --kv 3 # Start a local cluster with 10 nodes
$ tiup playground nightly --without-monitor # Start a local cluster and disable monitor system
$ tiup playground --pd.config ~/config/pd.toml # Start a local cluster with specified configuration file
$ tiup playground --db.binpath /xx/tidb-server # Start a local cluster with component binary path
$ tiup playground --tag xx # Start a local cluster with data dir named 'xx' and uncleaned after exit
$ tiup playground --mode tikv-slim # Start a local tikv only cluster (No TiDB or TiFlash Available)
$ tiup playground --mode tikv-slim --kv 3 --pd 3 # Start a local tikv only cluster with 6 nodes
Usage:
tiup playground [version] [flags]
tiup [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
display
help Help about any command
scale-in
scale-out
Flags:
--cse.access_key string Object store access key for --mode=tidb-cse or --mode=tiflash-disagg (default "minioadmin")
--cse.bucket string Object store bucket for --mode=tidb-cse or --mode=tiflash-disagg (default "tiflash")
--cse.s3_endpoint string Object store URL for --mode=tidb-cse or --mode=tiflash-disagg (default "http://127.0.0.1:9000")
--cse.secret_key string Object store secret key for --mode=tidb-cse or --mode=tiflash-disagg (default "minioadmin")
--db int TiDB instance number
--db.binpath string TiDB instance binary path
--db.config string TiDB instance configuration file
--db.host host Playground TiDB host. If not provided, TiDB will still use host flag as its host
--db.port int Playground TiDB port. If not provided, TiDB will use 4000 as its port. Or 6000 if TiProxy is enabled.
--db.timeout int TiDB max wait time in seconds for starting, 0 means no limit (default 60)
--dm-master int DM-master instance number
--dm-master.binpath string DM-master instance binary path
--dm-master.config string DM-master instance configuration file
--dm-master.host string DM-master instance host
--dm-master.port int DM-master instance port (default 8261)
--dm-worker int DM-worker instance number
--dm-worker.binpath string DM-worker instance binary path
--dm-worker.config string DM-worker instance configuration file
--dm-worker.host string DM-worker instance host
--dm-worker.port int DM-worker instance port (default 8262)
--drainer int Drainer instance number
--drainer.binpath string Drainer instance binary path
--drainer.config string Drainer instance configuration file
--grafana.port int grafana port. If not provided, grafana will use 3000 as its port. (default 3000)
-h, --help help for tiup
--host string Playground cluster host (default "127.0.0.1")
--kv int TiKV instance number
--kv.binpath string TiKV instance binary path
--kv.config string TiKV instance configuration file
--kv.host host Playground TiKV host. If not provided, TiKV will still use host flag as its host
--kv.port int Playground TiKV port. If not provided, TiKV will use 20160 as its port
--kvcdc int TiKV-CDC instance number
--kvcdc.binpath string TiKV-CDC instance binary path
--kvcdc.config string TiKV-CDC instance configuration file
--kvcdc.version string TiKV-CDC instance version
--mode string TiUP playground mode: 'tidb', 'tidb-cse', 'tiflash-disagg', 'tikv-slim' (default "tidb")
--pd int PD instance number
--pd.binpath string PD instance binary path
--pd.config string PD instance configuration file
--pd.host host Playground PD host. If not provided, PD will still use host flag as its host
--pd.mode string PD mode: 'pd', 'ms' (default "pd")
--pd.port int Playground PD port. If not provided, PD will use 2379 as its port
--port-offset int If specified, all components will use default_port+port_offset as the port. This argument is useful when you want to start multiple playgrounds on the same host. Recommend to set to 10000, 20000, etc.
--pump int Pump instance number
--pump.binpath string Pump instance binary path
--pump.config string Pump instance configuration file
--scheduling int Scheduling instance number
--scheduling.binpath string Scheduling instance binary path
--scheduling.config string Scheduling instance configuration file
-T, --tag string Specify a tag for playground, data dir of this tag will not be removed after exit
--ticdc int TiCDC instance number
--ticdc.binpath string TiCDC instance binary path
--ticdc.config string TiCDC instance configuration file
--ticdc.host host Playground TiCDC host. If not provided, TiDB will still use host flag as its host
--ticdc.port int Playground TiCDC port. If not provided, TiCDC will use 8300 as its port
--tiflash int TiFlash instance number, when --mode=tidb-cse or --mode=tiflash-disagg this will set instance number for both Write Node and Compute Node
--tiflash.binpath string TiFlash instance binary path, when --mode=tidb-cse or --mode=tiflash-disagg this will set binary path for both Write Node and Compute Node
--tiflash.compute int TiFlash Compute instance number, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash
--tiflash.compute.binpath string TiFlash Compute instance binary path, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash.binpath
--tiflash.compute.config string TiFlash Compute instance configuration file, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash.config
--tiflash.config string TiFlash instance configuration file, when --mode=tidb-cse or --mode=tiflash-disagg this will set config file for both Write Node and Compute Node
--tiflash.timeout int TiFlash max wait time in seconds for starting, 0 means no limit (default 120)
--tiflash.write int TiFlash Write instance number, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash
--tiflash.write.binpath string TiFlash Write instance binary path, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash.binpath
--tiflash.write.config string TiFlash Write instance configuration file, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash.config
--tiproxy int TiProxy instance number
--tiproxy.binpath string TiProxy instance binary path
--tiproxy.config string TiProxy instance configuration file
--tiproxy.host host Playground TiProxy host. If not provided, TiProxy will still use host flag as its host
--tiproxy.port int Playground TiProxy port. If not provided, TiProxy will use 6000 as its port
--tiproxy.timeout int TiProxy max wait time in seconds for starting, 0 means no limit (default 60)
--tiproxy.version string TiProxy instance version
--tso int TSO instance number
--tso.binpath string TSO instance binary path
--tso.config string TSO instance configuration file
-v, --version version for tiup
--without-monitor Don't start prometheus and grafana component
Use "tiup [command] --help" for more information about a command.
/usr/bin/server --help
bootstrap a mirror server
Usage:
/usr/bin/server <root-dir> [flags]
Flags:
--addr string addr to listen (default "0.0.0.0:8989")
-h, --help help for /usr/bin/server
--key-dir string specify the directory where stores the private keys
--upstream string specify the upstream mirror (default "https://tiup-mirrors.pingcap.com")
-v, --version version for /usr/bin/server
/usr/bin/tiup --help
Please check for root manifest file, you may download one from the repository mirror, or try `tiup mirror set` to force reset it.
Error: initial repository from mirror(https://tiup-mirrors.pingcap.com/) failed: error loading manifest root.json: open /root/.tiup/bin/root.json: no such file or directory
The tiup command is giving an error as https://tiup-mirrors.pingcap.com/ currently yields 'access denied' in the XML response file.
Are the Markdown pages at https://github.com/pingcap/tiup/tree/master/doc/user automatically published somewhere? At least not at https://docs.pingcap.com/, since that site seems to be generated out of https://github.com/pingcap/docs? On a quick glance it looks like the Overview page at https://docs.pingcap.com/tidb/stable/tiup-overview/ is not the same text as https://github.com/pingcap/tiup/blob/master/doc/user/overview.md. The latter one hasn't been updated for past 5 years based on git history.
It seems to me that the page https://docs.pingcap.com/tidb/stable/quick-start-with-tidb/ should be the primary documentation for anybody starting to use tiup, and maybe the subpages of https://docs.pingcap.com/tidb/stable/tiup-reference/ when looking up what individual commands do (although that reference isn't complete, e.g. 'tiup client' is missing).
Perhaps both the Markdown files and future man pages should be just short stubs with that suggest users to visit the relevant page in the docs portal? For example man tiup should tell the user about https://docs.pingcap.com/tidb/stable/tiup-reference/.
At least git commit log at https://github.com/pingcap/docs/commits/master/tiup shows it is actively maintained, so probably most up-to-date docs there.