--- name: "cephadm" section: "8" platform: "linux" package: "cephadm" version: "18.2.7+ds-1+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/cephadm" --- # cephadm(8) manage the local cephadm host ## NAME cephadm - manage the local cephadm host ## 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 **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. **cephadm** is not required on all hosts, but useful when investigating a particular daemon. ## OPTIONS - **--image IMAGE** container image. Can also be set via the "CEPHADM\_IMAGE" env var (default: None) - **--docker** use docker instead of podman (default: False) - **--data-dir DATA\_DIR** base directory for daemon data (default: /var/lib/ceph) - **--log-dir LOG\_DIR** base directory for daemon logs (default: /var/log/ceph) - **--logrotate-dir LOGROTATE\_DIR** location of logrotate configuration files (default: /etc/logrotate.d) - **--unit-dir UNIT\_DIR** base directory for systemd units (default: /etc/systemd/system) - **--verbose, -v** Show debug-level log messages (default: False) - **--timeout TIMEOUT** timeout in seconds (default: None) - **--retry RETRY** max number of retries (default: 10) - **--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/\/\/config**) - 3\. **/var/lib/ceph/\/config/ceph.conf** if it exists - 4\. The config file for a **mon** daemon (**/var/lib/ceph/\/mon.\/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 ... ``` 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 **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 [*ceph-volume*(8)](/ceph-volume/8.md), ## COPYRIGHT 2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)