diff options
Diffstat (limited to 'doc/man/8/cephadm.rst')
| -rw-r--r-- | doc/man/8/cephadm.rst | 540 |
1 files changed, 540 insertions, 0 deletions
diff --git a/doc/man/8/cephadm.rst b/doc/man/8/cephadm.rst new file mode 100644 index 000000000..0847066b6 --- /dev/null +++ b/doc/man/8/cephadm.rst @@ -0,0 +1,540 @@ +:orphan: + +========================================= + cephadm -- manage the local cephadm host +========================================= + +.. program:: cephadm + +Synopsis +======== + +| **cephadm**** [-h] [--image IMAGE] [--docker] [--data-dir DATA_DIR] +| [--log-dir LOG_DIR] [--logrotate-dir LOGROTATE_DIR] +| [--unit-dir UNIT_DIR] [--verbose] [--timeout TIMEOUT] +| [--retry RETRY] [--no-container-init] +| {version,pull,inspect-image,ls,list-networks,adopt,rm-daemon,rm-cluster,run,shell,enter,ceph-volume,unit,logs,bootstrap,deploy,check-host,prepare-host,add-repo,rm-repo,install} +| ... + + +| **cephadm** **pull** + +| **cephadm** --image IMAGE_NAME **inspect-image** + +| **cephadm** **ls** [-h] [--no-detail] [--legacy-dir LEGACY_DIR] + +| **cephadm** **list-networks** + +| **cephadm** **adopt** [-h] --name NAME --style STYLE [--cluster CLUSTER] +| [--legacy-dir LEGACY_DIR] [--config-json CONFIG_JSON] +| [--skip-firewalld] [--skip-pull] + +| **cephadm** **rm-daemon** [-h] --name NAME --fsid FSID [--force] +| [--force-delete-data] + +| **cephadm** **rm-cluster** [-h] --fsid FSID [--force] + +| **cephadm** **run** [-h] --name NAME --fsid FSID + +| **cephadm** **shell** [-h] [--fsid FSID] [--name NAME] [--config CONFIG] + [--keyring KEYRING] --mount [MOUNT [MOUNT ...]] [--env ENV] + [--] [command [command ...]] + +| **cephadm** **enter** [-h] [--fsid FSID] --name NAME [command [command ...]] + +| **cephadm** **ceph-volume** [-h] [--fsid FSID] [--config-json CONFIG_JSON] + [--config CONFIG] [--keyring KEYRING] + command [command ...] + +| **cephadm** **unit** [-h] [--fsid FSID] --name NAME command + +| **cephadm** **logs** [-h] [--fsid FSID] --name NAME [command [command ...]] + +| **cephadm** **bootstrap** [-h] [--config CONFIG] [--mon-id MON_ID] +| [--mon-addrv MON_ADDRV] [--mon-ip MON_IP] +| [--mgr-id MGR_ID] [--fsid FSID] +| [--log-to-file] [--single-host-defaults] +| [--output-dir OUTPUT_DIR] +| [--output-keyring OUTPUT_KEYRING] +| [--output-config OUTPUT_CONFIG] +| [--output-pub-ssh-key OUTPUT_PUB_SSH_KEY] +| [--skip-ssh] +| [--initial-dashboard-user INITIAL_DASHBOARD_USER] +| [--initial-dashboard-password INITIAL_DASHBOARD_PASSWORD] +| [--ssl-dashboard-port SSL_DASHBOARD_PORT] +| [--dashboard-key DASHBOARD_KEY] +| [--dashboard-crt DASHBOARD_CRT] +| [--ssh-config SSH_CONFIG] +| [--ssh-private-key SSH_PRIVATE_KEY] +| [--ssh-public-key SSH_PUBLIC_KEY] +| [--ssh-user SSH_USER] [--skip-mon-network] +| [--skip-dashboard] [--dashboard-password-noupdate] +| [--no-minimize-config] [--skip-ping-check] +| [--skip-pull] [--skip-firewalld] [--allow-overwrite] +| [--allow-fqdn-hostname] [--skip-prepare-host] +| [--orphan-initial-daemons] [--skip-monitoring-stack] +| [--apply-spec APPLY_SPEC] +| [--registry-url REGISTRY_URL] +| [--registry-username REGISTRY_USERNAME] +| [--registry-password REGISTRY_PASSWORD] +| [--registry-json REGISTRY_JSON] + + + +| **cephadm** **deploy** [-h] --name NAME --fsid FSID [--config CONFIG] +| [--config-json CONFIG_JSON] [--keyring KEYRING] +| [--key KEY] [--osd-fsid OSD_FSID] [--skip-firewalld] +| [--tcp-ports TCP_PORTS] [--reconfig] [--allow-ptrace] + +| **cephadm** **check-host** [-h] [--expect-hostname EXPECT_HOSTNAME] + +| **cephadm** **prepare-host** + +| **cephadm** **add-repo** [-h] [--release RELEASE] [--version VERSION] +| [--dev DEV] [--dev-commit DEV_COMMIT] +| [--gpg-url GPG_URL] [--repo-url REPO_URL] + + +| **cephadm** **rm-repo** + +| **cephadm** **install** [-h] [packages [packages ...]] + +| **cephadm** **registry-login** [-h] [--registry-url REGISTRY_URL] +| [--registry-username REGISTRY_USERNAME] +| [--registry-password REGISTRY_PASSWORD] +| [--registry-json REGISTRY_JSON] [--fsid FSID] + + + +Description +=========== + +:program:`cephadm` is a command line tool to manage the local host for the cephadm orchestrator. + +It provides commands to investigate and modify the state of the current host. + +:program:`cephadm` is not required on all hosts, but useful when investigating a particular +daemon. + +Options +======= + +.. option:: --image IMAGE + + container image. Can also be set via the + "CEPHADM_IMAGE" env var (default: None) + +.. option:: --docker + + use docker instead of podman (default: False) + +.. option:: --data-dir DATA_DIR + + base directory for daemon data (default: /var/lib/ceph) + +.. option:: --log-dir LOG_DIR + + base directory for daemon logs (default: /var/log/ceph) + +.. option:: --logrotate-dir LOGROTATE_DIR + + location of logrotate configuration files (default: /etc/logrotate.d) + +.. option:: --unit-dir UNIT_DIR + + base directory for systemd units (default: /etc/systemd/system) + +.. option:: --verbose, -v + + Show debug-level log messages (default: False) + +.. option:: --timeout TIMEOUT + + timeout in seconds (default: None) + +.. option:: --retry RETRY + + max number of retries (default: 10) + +.. option:: --no-container-init + + do not run podman/docker with `--init` (default: False) + + +Commands +======== + +add-repo +-------- + +configure local package repository to also include the ceph repository. + +Arguments: + +* [--release RELEASE] use latest version of a named release (e.g., octopus) +* [--version VERSION] use specific upstream version (x.y.z) +* [--dev DEV] use specified bleeding edge build from git branch or tag +* [--dev-commit DEV_COMMIT] use specified bleeding edge build from git commit +* [--gpg-url GPG_URL] specify alternative GPG key location +* [--repo-url REPO_URL] specify alternative repo location + + +adopt +----- + +Adopt a daemon deployed with a different deployment tool. + +Arguments: + +* [--name NAME, -n NAME] daemon name (type.id) +* [--style STYLE] deployment style (legacy, ...) +* [--cluster CLUSTER] cluster name +* [--legacy-dir LEGACY_DIR] base directory for legacy daemon data +* [--config-json CONFIG_JSON] Additional configuration information in JSON format +* [--skip-firewalld] Do not configure firewalld +* [--skip-pull] do not pull the latest image before adopting + +Configuration: + +When starting the shell, cephadm looks for configuration in the following order. +Only the first values found are used: + +1. An explicit, user provided path to a config file (``-c/--config`` option) +2. Config file for daemon specified with ``--name`` parameter (``/var/lib/ceph/<fsid>/<daemon-name>/config``) +3. ``/var/lib/ceph/<fsid>/config/ceph.conf`` if it exists +4. The config file for a ``mon`` daemon (``/var/lib/ceph/<fsid>/mon.<mon-id>/config``) if it exists +5. Finally: fallback to the default file ``/etc/ceph/ceph.conf`` + + +bootstrap +--------- + +Bootstrap a cluster on the local host. It deploys a MON and a MGR and then also automatically +deploys the monitoring stack on this host (see --skip-monitoring-stack) and calls +``ceph orch host add $(hostname)`` (see --skip-ssh). + +Arguments: + +* [--config CONFIG, -c CONFIG] ceph conf file to incorporate +* [--mon-id MON_ID] mon id (default: local hostname) +* [--mon-addrv MON_ADDRV] mon IPs (e.g., [v2:localipaddr:3300,v1:localipaddr:6789]) +* [--mon-ip MON_IP] mon IP +* [--mgr-id MGR_ID] mgr id (default: randomly generated) +* [--fsid FSID] cluster FSID +* [--log-to-file] configure cluster to log to traditional log files +* [--single-host-defaults] configure cluster to run on a single host +* [--output-dir OUTPUT_DIR] directory to write config, keyring, and pub key files +* [--output-keyring OUTPUT_KEYRING] location to write keyring file with new cluster admin and mon keys +* [--output-config OUTPUT_CONFIG] location to write conf file to connect to new cluster +* [--output-pub-ssh-key OUTPUT_PUB_SSH_KEY] location to write the cluster's public SSH key +* [--skip-ssh skip setup of ssh key on local host +* [--initial-dashboard-user INITIAL_DASHBOARD_USER] Initial user for the dashboard +* [--initial-dashboard-password INITIAL_DASHBOARD_PASSWORD] Initial password for the initial dashboard user +* [--ssl-dashboard-port SSL_DASHBOARD_PORT] Port number used to connect with dashboard using SSL +* [--dashboard-key DASHBOARD_KEY] Dashboard key +* [--dashboard-crt DASHBOARD_CRT] Dashboard certificate +* [--ssh-config SSH_CONFIG] SSH config +* [--ssh-private-key SSH_PRIVATE_KEY] SSH private key +* [--ssh-public-key SSH_PUBLIC_KEY] SSH public key +* [--ssh-user SSH_USER] set user for SSHing to cluster hosts, passwordless sudo will be needed for non-root users' +* [--skip-mon-network] set mon public_network based on bootstrap mon ip +* [--skip-dashboard] do not enable the Ceph Dashboard +* [--dashboard-password-noupdate] stop forced dashboard password change +* [--no-minimize-config] do not assimilate and minimize the config file +* [--skip-ping-check] do not verify that mon IP is pingable +* [--skip-pull] do not pull the latest image before bootstrapping +* [--skip-firewalld] Do not configure firewalld +* [--allow-overwrite] allow overwrite of existing --output-* config/keyring/ssh files +* [--allow-fqdn-hostname] allow hostname that is fully-qualified (contains ".") +* [--skip-prepare-host] Do not prepare host +* [--orphan-initial-daemons] Do not create initial mon, mgr, and crash service specs +* [--skip-monitoring-stack] Do not automatically provision monitoring stack] (prometheus, grafana, alertmanager, node-exporter) +* [--apply-spec APPLY_SPEC] Apply cluster spec after bootstrap (copy ssh key, add hosts and apply services) +* [--registry-url REGISTRY_URL] url of custom registry to login to. e.g. docker.io, quay.io +* [--registry-username REGISTRY_USERNAME] username of account to login to on custom registry +* [--registry-password REGISTRY_PASSWORD] password of account to login to on custom registry +* [--registry-json REGISTRY_JSON] JSON file containing registry login info (see registry-login command documentation) + + +ceph-volume +----------- + +Run ceph-volume inside a container:: + + cephadm ceph-volume inventory + +Positional arguments: +* [command] command + +Arguments: + +* [--fsid FSID] cluster FSID +* [--config-json CONFIG_JSON] JSON file with config and (client.bootstrap-osd) key +* [--config CONFIG, -c CONFIG] ceph conf file +* [--keyring KEYRING, -k KEYRING] ceph.keyring to pass through to the container + + +check-host +---------- + +check host configuration to be suitable for a Ceph cluster. + +Arguments: + +* [--expect-hostname EXPECT_HOSTNAME] Check that hostname matches an expected value + + +deploy +------ + +deploy a daemon on the local host. Used by the orchestrator CLI:: + + cephadm shell -- ceph orch apply <type> ... + +Arguments: + +* [--name NAME] daemon name (type.id) +* [--fsid FSID] cluster FSID +* [--config CONFIG, -c CONFIG] config file for new daemon +* [--config-json CONFIG_JSON] Additional configuration information in JSON format +* [--keyring KEYRING] keyring for new daemon +* [--key KEY] key for new daemon +* [--osd-fsid OSD_FSID] OSD uuid, if creating an OSD container +* [--skip-firewalld] Do not configure firewalld +* [--tcp-ports List of tcp ports to open in the host firewall +* [--reconfig] Reconfigure a previously deployed daemon +* [--allow-ptrace] Allow SYS_PTRACE on daemon container + + +enter +----- + +Run an interactive shell inside a running daemon container:: + + cephadm enter --name mgr.myhost.ysubfo + +Positional arguments: +* [command] command + +Arguments: + +* [--fsid FSID] cluster FSID +* [--name NAME, -n NAME] daemon name (type.id) + +install +------- + +install ceph package(s) + +Positional arguments: + +* [packages] packages + + +inspect-image +------------- + +Inspect local Ceph container image. From Reef onward, requires specifying +the image to inspect with ``--image``:: + + cephadm --image IMAGE_NAME inspect-image + +list-networks +------------- + +list IP networks + + +ls +-- + +list daemon instances known to cephadm on **this** host:: + + $ cephadm ls + [ + { + "style": "cephadm:v1", + "name": "mgr.storage-14b-1.ysubfo", + "fsid": "5110cb22-8332-11ea-9148-0894ef7e8bdc", + "enabled": true, + "state": "running", + "container_id": "8562de72370a3836473ecfff8a22c9ccdd99815386b4692a2b30924fb5493c44", + "container_image_name": "docker.io/ceph/ceph:v15", + "container_image_id": "bc83a388465f0568dab4501fb7684398dca8b50ca12a342a57f21815721723c2", + "version": "15.2.1", + "started": "2020-04-21T01:16:41.831456", + "created": "2020-04-21T01:16:41.775024", + "deployed": "2020-04-21T01:16:41.415021", + "configured": "2020-04-21T01:16:41.775024" + }, + ... + +Arguments: + +* [--no-detail] Do not include daemon status +* [--legacy-dir LEGACY_DIR] Base directory for legacy daemon data + +logs +---- + +print journald logs for a daemon container:: + + cephadm logs --name mgr.myhost.ysubfo + +This is similar to:: + + journalctl -u mgr.myhost.ysubfo + +Can also specify additional journal arguments:: + + cephadm logs --name mgr.myhost.ysubfo -- -n 20 # last 20 lines + cephadm logs --name mgr.myhost.ysubfo -- -f # follow the log + + +Positional arguments: + +* [command] command (optional) + +Arguments: + +* [--fsid FSID] cluster FSID +* [--name NAME, -n NAME] daemon name (type.id) + + +prepare-host +------------ + +prepare a host for cephadm use + +Arguments: + +* [--expect-hostname EXPECT_HOSTNAME] Set hostname + + +pull +---- + +Pull the ceph image:: + + cephadm pull + +registry-login +-------------- + +Give cephadm login information for an authenticated registry (url, username and password). +Cephadm will attempt to log the calling host into that registry:: + + cephadm registry-login --registry-url [REGISTRY_URL] --registry-username [USERNAME] + --registry-password [PASSWORD] + +Can also use a JSON file containing the login info formatted as:: + + { + "url":"REGISTRY_URL", + "username":"REGISTRY_USERNAME", + "password":"REGISTRY_PASSWORD" + } + +and turn it in with command:: + + cephadm registry-login --registry-json [JSON FILE] + +Arguments: + +* [--registry-url REGISTRY_URL] url of registry to login to. e.g. docker.io, quay.io +* [--registry-username REGISTRY_USERNAME] username of account to login to on registry +* [--registry-password REGISTRY_PASSWORD] password of account to login to on registry +* [--registry-json REGISTRY_JSON] JSON file containing login info for custom registry +* [--fsid FSID] cluster FSID + +rm-daemon +--------- + +Remove a specific daemon instance + +Arguments: + +* [--name NAME, -n NAME] daemon name (type.id) +* [--fsid FSID] cluster FSID +* [--force] proceed, even though this may destroy valuable data +* [--force-delete-data] delete valuable daemon data instead of making a backup + + +rm-cluster +---------- + +remove all daemons for a cluster + +Arguments: + +* [--fsid FSID] cluster FSID +* [--force] proceed, even though this may destroy valuable data + +rm-repo +------- + +remove package repository configuration + +run +--- + +run a ceph daemon, in a container, in the foreground + +Arguments: + +* [--name NAME, -n NAME] daemon name (type.id) +* [--fsid FSID] cluster FSID + + +shell +----- + +Run an interactive shell:: + + cephadm shell + +Or one specific command inside a container:: + + cephadm shell -- ceph orch ls + + +Positional arguments: + +* [command] command (optional) + +Arguments: + +* [--fsid FSID] cluster FSID +* [--name NAME, -n NAME] daemon name (type.id) +* [--config CONFIG, -c CONFIG] ceph.conf to pass through to the container +* [--keyring KEYRING, -k KEYRING] ceph.keyring to pass through to the container +* [--mount MOUNT, -m MOUNT] mount a file or directory under /mnt in the container +* [--env ENV, -e ENV] set environment variable + + +unit +---- + +Operate on the daemon's systemd unit. + +Positional arguments: + +* [command] systemd command (start, stop, restart, enable, disable, ...) + +Arguments: + +* [--fsid FSID] cluster FSID +* [--name NAME, -n NAME] daemon name (type.id) + + +Availability +============ + +:program:`cephadm` is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to +the documentation at http://docs.ceph.com/ for more information. + + +See also +======== + +:doc:`ceph-volume <ceph-volume>`\(8), |