ceph-volume

package: ceph-volume

title: ceph-volume(8)

summary: Ceph OSD deployment and inspection tool

text:
# ceph-volume(8)

## NAME
ceph-volume - Ceph OSD deployment and inspection tool

## SYNOPSIS
ceph-volume [-h] [--cluster CLUSTER] [--log-level LOG_LEVEL] [--log-path LOG_PATH]

ceph-volume inventory

ceph-volume lvm [ trigger | create | activate | prepare | zap | list | batch | new-wal | new-db | migrate ]

ceph-volume simple [ trigger | scan | activate ]

## DESCRIPTION
ceph-volume is a single purpose command line tool to deploy logical volumes as OSDs, trying to maintain a similar API to ceph-disk when preparing, activating, and creating OSDs.

It deviates from ceph-disk by not interacting or relying on the udev rules that come installed for Ceph. These rules allow automatic detection of previously setup devices that are in turn fed into ceph-disk to activate them.

## COMMANDS

### inventory
This subcommand provides information about a host's physical disc inventory and reports metadata about these discs. Among this metadata one can find disc specific data items (like model, size, rotational or solid state) as well as data items specific to ceph using a device, such as if it is available for use with ceph or if logical volumes are present.

Examples:

```
ceph-volume inventory
ceph-volume inventory /dev/sda
ceph-volume inventory --format json-pretty
```

Optional arguments:

-h, --help

show the help message and exit

--format

report format, valid values are plain (default), json and json-pretty

### lvm
By making use of LVM tags, the lvm sub-command is able to store and later re-discover and query devices associated with OSDs so that they can later activated.

Subcommands:

### batch
Creates OSDs from a list of devices using a bluestore (default) setup. It will create all necessary volume groups and logical volumes required to have a working OSD.

Example usage with three devices:

```
ceph-volume lvm batch --bluestore /dev/sda /dev/sdb /dev/sdc
```

Optional arguments:

-h, --help

show the help message and exit

--bluestore

Use the bluestore objectstore (default)

--yes

Skip the report and prompt to continue provisioning

--prepare

Only prepare OSDs, do not activate

--dmcrypt

Enable encryption for the underlying OSD devices

--crush-device-class

Define a CRUSH device class to assign the OSD to

--no-systemd

Do not enable or create any systemd units

--osds-per-device

Provision more than 1 (the default) OSD per device

--report

Report what the potential outcome would be for the current input (requires devices to be passed in)

--format

Output format when reporting (used along with --report), can be one of 'pretty' (default) or 'json'

--block-db-size

Set (or override) the "bluestore_block_db_size" value, in bytes

--journal-size

Override the "osd_journal_size" value, in megabytes

Required positional arguments:

<DEVICE>

Full path to a raw device, like /dev/sda. Multiple <DEVICE> paths can be passed in.

### activate
Enables a systemd unit that persists the OSD ID and its UUID (also called fsid in Ceph CLI tools), so that at boot time it can understand what OSD is enabled and needs to be mounted.

Usage:

```
ceph-volume lvm activate --bluestore <osd id> <osd fsid>
```

Optional Arguments:

-h, --help

show the help message and exit

--auto-detect-objectstore

Automatically detect the objectstore by inspecting the OSD

--bluestore

bluestore objectstore (default)

--all

Activate all OSDs found in the system

--no-systemd

Skip creating and enabling systemd units and starting of OSD services

Multiple OSDs can be activated at once by using the (idempotent) --all flag:

```
ceph-volume lvm activate --all
```

### prepare
Prepares a logical volume to be used as an OSD and journal using a bluestore (default) setup. It will not create or modify the logical volumes except for adding extra metadata.

Usage:

```
ceph-volume lvm prepare --bluestore --data <data lv> --journal <journal device>
```

Optional arguments:

-h, --help

show the help message and exit

--journal JOURNAL

logical group name, path to a logical volume, or path to a device

--bluestore

Use the bluestore objectstore (default)

--block.wal

Path to a bluestore block.wal logical volume or partition

--block.db

Path to a bluestore block.db logical volume or partition

--dmcrypt

Enable encryption for the underlying OSD devices

--osd-id OSD_ID

Reuse an existing OSD id

--osd-fsid OSD_FSID

Reuse an existing OSD fsid

--crush-device-class

Define a CRUSH device class to assign the OSD to

Required arguments:

--data

A logical group name or a path to a logical volume

For encrypting an OSD, the --dmcrypt flag must be added when preparing (also supported in the create sub-command).

### create
Wraps the two-step process to provision a new osd (calling prepare first and then activate) into a single one. The reason to prefer prepare and then activate is to gradually introduce new OSDs into a cluster, and avoiding large amounts of data being rebalanced.

The single-call process unifies exactly what prepare and activate do, with the convenience of doing it all at once. Flags and general usage are equivalent to those of the prepare and activate subcommand.

### trigger
This subcommand is not meant to be used directly, and it is used by systemd so that it proxies input to ceph-volume lvm activate by parsing the input from systemd, detecting the UUID and ID associated with an OSD.

Usage:

```
ceph-volume lvm trigger <SYSTEMD-DATA>
```

The systemd "data" is expected to be in the format of:

```
<OSD ID>-<OSD UUID>
```

The lvs associated with the OSD need to have been prepared previously, so that all needed tags and metadata exist.

Positional arguments:

<SYSTEMD_DATA>

Data from a systemd unit containing ID and UUID of the OSD.

### list
List devices or logical volumes associated with Ceph. An association is determined if a device has information relating to an OSD. This is verified by querying LVM's metadata and correlating it with devices.

The lvs associated with the OSD need to have been prepared previously by ceph-volume so that all needed tags and metadata exist.

Usage:

```
ceph-volume lvm list
```

List a particular device, reporting all metadata about it:

```
ceph-volume lvm list /dev/sda1
```

List a logical volume, along with all its metadata (vg is a volume group, and lv the logical volume name):

```
ceph-volume lvm list {vg/lv}
```

Positional arguments:

<DEVICE>

Either in the form of vg/lv for logical volumes, /path/to/sda1 or /path/to/sda for regular devices.

### zap
Zaps the given logical volume or partition. If given a path to a logical volume it must be in the format of vg/lv. Any file systems present on the given lv or partition will be removed and all data will be purged.

However, the lv or partition will be kept intact.

Usage, for logical volumes:

```
ceph-volume lvm zap {vg/lv}
```

Usage, for logical partitions:

```
ceph-volume lvm zap /dev/sdc1
```

For full removal of the device use the --destroy flag (allowed for all device types):

```
ceph-volume lvm zap --destroy /dev/sdc1
```

Multiple devices can be removed by specifying the OSD ID and/or the OSD FSID:

```
ceph-volume lvm zap --destroy --osd-id 1
ceph-volume lvm zap --destroy --osd-id 1 --osd-fsid C9605912-8395-4D76-AFC0-7DFDAC315D59
```

Positional arguments:

<DEVICE>

Either in the form of vg/lv for logical volumes, /path/to/sda1 or /path/to/sda for regular devices.

### new-wal
Attaches the given logical volume to OSD as a WAL. Logical volume name format is vg/lv. Fails if OSD has already got attached WAL.

Usage:

```
ceph-volume lvm new-wal --osd-id OSD_ID --osd-fsid OSD_FSID --target <target lv>
```

Optional arguments:

-h, --help

show the help message and exit

--no-systemd

Skip checking OSD systemd unit

Required arguments:

--target

logical volume name to attach as WAL

### new-db
Attaches the given logical volume to OSD as a DB. Logical volume name format is vg/lv. Fails if OSD has already got attached DB.

Usage:

```
ceph-volume lvm new-db --osd-id OSD_ID --osd-fsid OSD_FSID --target <target lv>
```

Optional arguments:

-h, --help

show the help message and exit

--no-systemd

Skip checking OSD systemd unit

Required arguments:

--target

logical volume name to attach as DB

### migrate
Moves BlueFS data from source volume(s) to the target one, source volumes (except the main, i.e. data or block one) are removed on success. LVM volumes are permitted for Target only, both already attached or new one. In the latter case it is attached to the OSD replacing one of the source devices. Following replacement rules apply (in the order of precedence, stop on the first match):

- if source list has DB volume - target device replaces it.

- if source list has WAL volume - target device replace it.

- if source list has slow volume only - operation is not permitted, requires explicit allocation via new-db/new-wal command.

Usage:

```
ceph-volume lvm migrate --osd-id OSD_ID --osd-fsid OSD_FSID --target <target lv> --from {data|db|wal} [{data|db|wal} ...]
```

Optional arguments:

-h, --help

show the help message and exit

--no-systemd

Skip checking OSD systemd unit

Required arguments:

--from

list of source device type names

--target

logical volume to move data to

### simple
Scan legacy OSD directories or data devices that may have been created by ceph-disk, or manually.

Subcommands:

### activate
Enables a systemd unit that persists the OSD ID and its UUID (also called fsid in Ceph CLI tools), so that at boot time it can understand what OSD is enabled and needs to be mounted, while reading information that was previously created and persisted at /etc/ceph/osd/ in JSON format.

Usage:

```
ceph-volume simple activate --bluestore <osd id> <osd fsid>
```

Optional Arguments:

-h, --help

show the help message and exit

--bluestore

bluestore objectstore (default)

NOTE:

It requires a matching JSON file with the following format:

```
/etc/ceph/osd/<osd id>-<osd fsid>.json
```

### scan
Scan a running OSD or data device for an OSD for metadata that can later be used to activate and manage the OSD with ceph-volume. The scan method will create a JSON file with the required information plus anything found in the OSD directory as well.

Optionally, the JSON blob can be sent to stdout for further inspection.

Usage on all running OSDs:

```
ceph-volume simple scan
```

Usage on data devices:

```
ceph-volume simple scan <data device>
```

Running OSD directories:

```
ceph-volume simple scan <path to osd dir>
```

Optional arguments:

-h, --help

show the help message and exit

--stdout

Send the JSON blob to stdout

--force

If the JSON file exists at destination, overwrite it

Optional Positional arguments:

<DATA DEVICE or OSD DIR>

Actual data partition or a path to the running OSD

### trigger
This subcommand is not meant to be used directly, and it is used by systemd so that it proxies input to ceph-volume simple activate by parsing the input from systemd, detecting the UUID and ID associated with an OSD.

Usage:

```
ceph-volume simple trigger <SYSTEMD-DATA>
```

The systemd "data" is expected to be in the format of:

```
<OSD ID>-<OSD UUID>
```

The JSON file associated with the OSD need to have been persisted previously by a scan (or manually), so that all needed metadata can be used.

Positional arguments:

<SYSTEMD_DATA>

Data from a systemd unit containing ID and UUID of the OSD.

## AVAILABILITY
ceph-volume 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-osd(8),

## COPYRIGHT
2010-2025, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)


ceph-volume-systemd

title: ceph-volume-systemd(8)

summary: systemd ceph-volume helper tool

text:
# ceph-volume-systemd(8)

## NAME
ceph-volume-systemd - systemd ceph-volume helper tool

## SYNOPSIS

```
ceph-volume-systemd systemd instance name
```

## DESCRIPTION
ceph-volume-systemd is a systemd helper tool that receives input from (dynamically created) systemd units so that activation of OSDs can proceed.

It translates the input into a system call to ceph-volume for activation purposes only.

## EXAMPLES
Its input is the systemd instance name (represented by %i in a systemd unit), and it should be in the following format:

```
<ceph-volume subcommand>-<extra metadata>
```

In the case of lvm a call could look like:

```
/usr/bin/ceph-volume-systemd lvm-0-8715BEB4-15C5-49DE-BA6F-401086EC7B41
```

Which in turn will call ceph-volume in the following way:

```
ceph-volume lvm trigger  0-8715BEB4-15C5-49DE-BA6F-401086EC7B41
```

Any other subcommand will need to have implemented a trigger command that can consume the extra metadata in this format.

## AVAILABILITY
ceph-volume-systemd 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-osd(8),

## COPYRIGHT
2010-2025, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)


cephadm

package: cephadm

title: cephadm(8)

summary: manage the local cephadm host

text:
# cephadm(8)

## 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/<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
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),

## COPYRIGHT
2010-2025, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)


cephfs-mirror

package: cephfs-mirror

title: cephfs-mirror(8)

text:
# cephfs-mirror(8)

## NAME
cephfs-mirror - Ceph daemon for mirroring CephFS snapshots

## SYNOPSIS

```
cephfs-mirror
```

## DESCRIPTION
cephfs-mirror is a daemon for asynchronous mirroring of Ceph Filesystem snapshots among Ceph clusters.

It connects to remote clusters via libcephfs, relying on default search paths to find ceph.conf files, i.e. /etc/ceph/$cluster.conf where $cluster is the human-friendly name of the cluster.

## OPTIONS
--mon-host monaddress[:port]

Connect to specified monitor (instead of looking through ceph.conf).

--keyring=<path-to-keyring>

Provide path to keyring; useful when it's absent in standard locations.

--log-file=<logfile>

file to log debug output

--debug-cephfs-mirror=<log-level>/<memory-level>

set cephfs-mirror debug level

-c ceph.conf, --conf=ceph.conf

Use ceph.conf configuration file instead of the default /etc/ceph/ceph.conf to determine monitor addresses during startup.

-i ID, --id ID

Set the ID portion of name for cephfs-mirror

-n TYPE.ID, --name TYPE.ID

Set the rados user name (eg. client.mirror)

--cluster NAME

Set the cluster name (default: ceph)

-d

Run in foreground, log to stderr

-f

Run in foreground, log to usual location

## AVAILABILITY
cephfs-mirror is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to the Ceph documentation at https://docs.ceph.com for more information.

## SEE ALSO
ceph(8)

## COPYRIGHT
2010-2025, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)


cephfs-shell

package: cephfs-shell

title: cephfs-shell(8)

summary: Shell-like tool talking with CephFS

text:
# cephfs-shell(8)

## NAME
cephfs-shell - Shell-like tool talking with CephFS

## SYNOPSIS

```
cephfs-shell [options] [command]
cephfs-shell [options] -- [command, command,...]
```

## DESCRIPTION
CephFS Shell provides shell-like commands that directly interact with the Ceph File System.

This tool can be used in interactive mode as well as in non-interactive mode. In former mode, cephfs-shell opens a shell session and after the given command is finished, it prints the prompt string and waits indefinitely. When the shell session is finished, cephfs-shell quits with the return value of last executed command. In non-interactive mode, cephfs-shell issues a command and exits right after the command's execution is complete with the command's return value.

Behaviour of CephFS Shell can be tweaked using cephfs-shell.conf. Refer to CephFS Shell Configuration File for details.

## OPTIONS
-b, --batch FILE

Path to batch file.

-c, --config FILE

Path to cephfs-shell.conf

-f, --fs FS

Name of filesystem to mount.

-t, --test FILE

Path to transcript(s) in FILE for testing

NOTE:

Latest version of the cmd2 module is required for running cephfs-shell. If CephFS is installed through source, execute cephfs-shell in the build directory. It can also be executed as following using virtualenv:

```
[build]$ python3 -m venv venv && source venv/bin/activate && pip3 install cmd2 colorama
[build]$ source vstart_environment.sh && source venv/bin/activate && python3 ../src/tools/cephfs/shell/cephfs-shell
```

## COMMANDS
NOTE:

Apart from Ceph File System, CephFS Shell commands can also interact directly with the local file system. To achieve this, ! (an exclamation point) must precede the CephFS Shell command. Usage :

!<cephfs_shell_command>

For example,

```
CephFS:~/>>> !ls # Lists the local file system directory contents.
CephFS:~/>>> ls  # Lists the Ceph File System directory contents.
```

### mkdir
Create the directory(ies), if they do not already exist.

Usage :

mkdir [-option] <directory>...

•

directory - name of the directory to be created.

Options :

-m MODE

Sets the access mode for the new directory.

-p, --parent

Create parent directories as necessary. When this option is specified, no error is reported if a directory already exists.

### put
Copy a file/directory to Ceph File System from Local File System.

Usage :

put [options] <source_path> <target_path>

•

source_path - local file/directory path to be copied to cephfs.

- if . copies all the file/directories in the local working directory.

- if - Reads the input from stdin.

•

target_path - remote directory path where the files/directories are to be copied to.

•

if . files/directories are copied to the remote working directory.

Options :

-f, --force

Overwrites the destination if it already exists.

### get
Copy a file from Ceph File System to Local File System.

Usage :

get [options] <source_path> <target_path>

•

source_path - remote file/directory path which is to be copied to local file system.

•

if . copies all the file/directories in the remote working directory.

•

target_path - local directory path where the files/directories are to be copied to.

- if . files/directories are copied to the local working directory.

- if - Writes output to stdout.

Options:

-f, --force

Overwrites the destination if it already exists.

### ls
List all the files and directories in the current working directory.

Usage :

ls [option] [directory]...

•

directory - name of directory whose files/directories are to be listed.

•

By default current working directory's files/directories are listed.

Options:

-l, --long

list with long format - show permissions

-r, --reverse

reverse sort

-H

human readable

-a,-all

ignore entries starting with .

-S

Sort by file_size

### cat
Concatenate files and print on the standard output

Usage :

cat <file>....

•

file - name of the file

### ln
Add a hard link to an existing file or create a symbolic link to an existing file or directory.

Usage:

ln [options] <target> [link_name]

- target - file/directory to which a link is to be created

- link_name - link to target with the name link_name

Options:

-s, --symbolic

Create symbolic link

-v, --verbose

Print name of each linked file

-f, --force

Force create link/symbolic link

### cd
Change current working directory.

Usage :

cd [directory]

•

directory - path/directory name. If no directory is mentioned it is changed to the root directory.

•

If '.' moves to the parent directory of the current directory.

### cwd
Get current working directory.

Usage :

cwd

### quit/Ctrl + D
Close the shell.

### chmod
Change the permissions of file/directory.

Usage :

chmod <mode> <file/directory>

### mv
Moves files/Directory from source to destination.

Usage :

mv <source_path> <destination_path>

### rmdir
Delete a directory(ies).

Usage :

rmdir <directory_name>.....

### rm
Remove a file(es).

Usage :

rm <file_name/pattern>...

### write
Create and Write a file.

Usage :

write <file_name> <Enter Data> Ctrl+D Exit.

### lls
Lists all files and directories in the specified directory.Current local directory files and directories are listed if no path is mentioned

Usage:

lls <path>.....

### lcd
Moves into the given local directory.

Usage :

lcd <path>

### lpwd
Prints the absolute path of the current local directory.

Usage :

lpwd

### umask
Set and get the file mode creation mask

Usage :

umask [mode]

### alias
Define or display aliases

Usage:

alias [name] | [<name> <value>]

- name - name of the alias being looked up, added, or replaced

- value - what the alias will be resolved to (if adding or replacing) this can contain spaces and does not need to be quoted

### run_pyscript
Runs a python script file inside the console

Usage:

run_pyscript <script_path> [script_arguments]

•

Console commands can be executed inside this script with cmd ("your command") However, you cannot run nested "py" or "pyscript" commands from within this script. Paths or arguments that contain spaces must be enclosed in quotes

NOTE:

This command is available as pyscript for cmd2 versions 0.9.13 or less.

### py
Invoke python command, shell, or script

Usage :

py <command>: Executes a Python command. py: Enters interactive Python mode.

### shortcuts
Lists shortcuts (aliases) available

Usage :

shortcuts

### history
View, run, edit, and save previously entered commands.

Usage :

history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]

Options:

-h

show this help message and exit

-r

run selected history items

-e

edit and then run selected history items

-s

script format; no separation lines

-o FILE

output commands to a script file

-t TRANSCRIPT

output commands and results to a transcript file

### unalias
Unsets aliases

Usage :

unalias [-a] name [name ...]

•

name - name of the alias being unset

Options:

-a

remove all alias definitions

### set
Sets a settable parameter or shows current settings of parameters.

Usage :

set [-h] [-a] [-l] [settable [settable ...]]

•

Call without arguments for a list of settable parameters with their values.

Options :

-h

show this help message and exit

-a

display read-only settings as well

-l

describe function of parameter

### edit
Edit a file in a text editor.

Usage:

edit [file_path]

•

file_path - path to a file to open in editor

### run_script
Runs commands in script file that is encoded as either ASCII or UTF-8 text. Each command in the script should be separated by a newline.

Usage:

run_script <file_path>

•

file_path - a file path pointing to a script

NOTE:

This command is available as load for cmd2 versions 0.9.13 or less.

### shell
Execute a command as if at the OS prompt.

Usage:

shell <command> [arguments]

### locate
Find an item in File System

Usage:

locate [options] <name>

Options :

-c

Count number of items found

-i

Ignore case

### stat
Display file status.

Usage :

stat [-h] <file_name> [file_name ...]

Options :

-h

Shows the help message

### snap
Create or Delete Snapshot

Usage:

snap {create|delete} <snap_name> <dir_name>

- snap_name - Snapshot name to be created or deleted

- dir_name - directory under which snapshot should be created or deleted

### setxattr
Set extended attribute for a file

Usage :

setxattr [-h] <path> <name> <value>

- path - Path to the file

- name - Extended attribute name to get or set

- value - Extended attribute value to be set

Options:

-h, --help

Shows the help message

### getxattr
Get extended attribute value for the name associated with the path

Usage :

getxattr [-h] <path> <name>

- path - Path to the file

- name - Extended attribute name to get or set

Options:

-h, --help

Shows the help message

### listxattr
List extended attribute names associated with the path

Usage :

listxattr [-h] <path>

•

path - Path to the file

Options:

-h, --help

Shows the help message

### df
Display amount of available disk space

Usage :

df [-h] [file [file ...]]

•

file - name of the file

Options:

-h, --help

Shows the help message

### du
Show disk usage of a directory

Usage :

du [-h] [-r] [paths [paths ...]]

•

paths - name of the directory

Options:

-h, --help

Shows the help message

-r

Recursive Disk usage of all directories

### quota
Quota management for a Directory

Usage :

quota [-h] [--max_bytes [MAX_BYTES]] [--max_files [MAX_FILES]] {get,set} path

- {get,set} - quota operation type.

- path - name of the directory.

Options :

-h, --help

Shows the help message

--max_bytes MAX_BYTES

Set max cumulative size of the data under this directory

--max_files MAX_FILES

Set total number of files under this directory tree

## CEPHFS SHELL CONFIGURATION FILE
By default, CephFS Shell looks for cephfs-shell.conf in the path provided by the environment variable CEPHFS_SHELL_CONF and then in user's home directory (~/.cephfs-shell.conf).

Right now, CephFS Shell inherits all its options from its dependency cmd2. Therefore, these options might vary with the version of cmd2 installed on your system. Refer to cmd2 docs for a description of these options.

Following is a sample cephfs-shell.conf

```
[cephfs-shell]
prompt = CephFS:~/>>>
continuation_prompt = >
quiet = False
timing = False
colors = True
debug = False
abbrev = False
autorun_on_edit = False
echo = False
editor = vim
feedback_to_output = False
locals_in_py = True
```

## EXIT CODE
Following exit codes are returned by cephfs shell

Error Type

Exit Code

Miscellaneous

1

Keyboard Interrupt

2

Operation not permitted

3

Permission denied

4

No such file or directory

5

I/O error

6

No space left on device

7

File exists

8

No data available

9

Invalid argument

10

Operation not supported on transport endpoint

11

Range error

12

Operation would block

13

Directory not empty

14

Not a directory

15

Disk quota exceeded

16

Broken pipe

17

Cannot send after transport endpoint shutdown

18

Connection aborted

19

Connection refused

20

Connection reset

21

Interrupted function call

22

## FILES
~/.cephfs-shell.conf

## COPYRIGHT
2010-2025, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)


cephfs-top

package: cephfs-top

title: cephfs-top(8)

summary: Ceph Filesystem Top Utility

text:
# cephfs-top(8)

## NAME
cephfs-top - Ceph Filesystem Top Utility

## SYNOPSIS

```
cephfs-top [flags]
```

## DESCRIPTION
cephfs-top provides top(1) like functionality for Ceph Filesystem. Various client metrics are displayed and updated in realtime.

Ceph Metadata Servers periodically send client metrics to Ceph Manager. Stats plugin in Ceph Manager provides an interface to fetch these metrics.

## OPTIONS
--cluster

Cluster: Ceph cluster to connect. Defaults to ceph.

--id

Id: Client used to connect to Ceph cluster. Defaults to fstop.

--selftest

Perform a selftest. This mode performs a sanity check of stats module.

--conffile [CONFFILE]

Path to cluster configuration file

-d [DELAY], --delay [DELAY]

Refresh interval in seconds (default: 1)

--dump

Dump the metrics to stdout

--dumpfs <fs_name>

Dump the metrics of the given filesystem to stdout

## DESCRIPTIONS OF FIELDS
chit

cap hit rate

dlease

dentry lease rate

ofiles

number of opened files

oicaps

number of pinned caps

oinodes

number of opened inodes

rtio

total size of read IOs

wtio

total size of write IOs

raio

average size of read IOs

waio

average size of write IOs

rsp

speed of read IOs compared with the last refresh

wsp

speed of write IOs compared with the last refresh

rlatavg

average read latency

rlatsd

standard deviation (variance) for read latency

wlatavg

average write latency

wlatsd

standard deviation (variance) for write latency

mlatavg

average metadata latency

mlatsd

standard deviation (variance) for metadata latency

## AVAILABILITY
cephfs-top is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to the Ceph documentation at http://ceph.com/ for more information.

## SEE ALSO
ceph(8), ceph-mds(8)

## COPYRIGHT
2010-2025, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)


certmonger

package: certmonger

title: certmonger(8)

text:
# certmonger(8)

## NAME
certmonger

## SYNOPSIS
certmonger [-s|-S] [-L|-l] [-P PATH] [-b TIMEOUT|-B] [-n|-f] [-d LEVEL] [-p FILE] [-F] [-c command] [-v]

## DESCRIPTION
The certmonger daemon monitors certificates for impending expiration, and can optionally refresh soon-to-be-expired certificates with the help of a CA. If told to, it can drive the entire enrollment process from key generation through enrollment and refresh.

The daemon provides a control interface via the org.fedorahosted.certmonger service, with which client tools such as getcert(1) interact.

## OPTIONS
-s, --session

Listen on the session bus rather than the system bus.

-S, --system

Listen on the system bus rather than the session bus. This is the default.

-l, --listening-socket

Also listen on a private socket for connections from clients running under the same UID.

-L, --only-listening-socket

Listen only on a private socket for connections from clients running under the same UID, and skip connecting to a bus.

-P PATH, --listening-socket-path=PATH

Specify a location for the private listening socket. If the location beings with a '/' character, it will be prefixed with 'unix:path=', otherwise it will be prefixed with 'unix:'. If this option is not specified, the listening socket, if one is created, will be placed in the abstract namespace.

-b TIMEOUT, --bus-activation-timeout=TIMEOUT

Behave as a bus-activated service: if there are no certificates to be monitored or obtained, and no requests are received within TIMEOUT seconds, exit. Not compatible with the -c option.

-B, --no-bus-activation-timeout

Don't behave as a bus-activated service. This is the default.

-n, --nofork

Don't fork, and log messages to stderr rather than syslog.

-f, --fork

Do fork, and log messages to syslog rather than stderr. This is the default.

-d LEVEL, --debug-level=LEVEL

Set debugging level. Higher values produce more debugging output. Implies -n.

-p FILE, pidfile=FILE

Store the daemon's process ID in the named file.

-F, --fips

Force NSS to be initialized in FIPS mode. The default behavior is to heed the setting stored in /proc/sys/crypto/fips_enabled.

-c COMMAND, --command=COMMAND

After the service has initialized, run the specified command, then shut down the service after the command exits. If the -l or -L option was also specified, the command will be run with the CERTMONGER_PVT_ADDRESS environment variable set to the listening socket's location. Not compatible with the -b option.

-v, --version

Print version information and exit.

## FILES
The set of certificates being monitored or signed is tracked using files stored under /var/lib/certmonger/requests, or in a directory named by the CERTMONGER_REQUESTS_DIR environment variable.

The set of known CAs is tracked using files stored under /var/lib/certmonger/cas, or in a directory named by the CERTMONGER_CAS_DIR environment variable.

Temporary files will be stored in "/run/certmonger", or in the directory named by the CERTMONGER_TMPDIR environment variable if that value was not given at compile time.

## BUGS
Please file tickets for any that you find at https://fedorahosted.org/certmonger/

## SEE ALSO
getcert(1) getcert-add-ca(1) getcert-add-scep-ca(1) getcert-list-cas(1) getcert-list(1) getcert-modify-ca(1) getcert-refresh-ca(1) getcert-refresh(1) getcert-rekey(1) getcert-remove-ca(1) getcert-request(1) getcert-resubmit(1) getcert-start-tracking(1) getcert-status(1) getcert-stop-tracking(1) certmonger-certmaster-submit(8) certmonger-dogtag-ipa-renew-agent-submit(8) certmonger-dogtag-submit(8) certmonger-ipa-submit(8) certmonger-local-submit(8) certmonger-scep-submit(8) certmonger_selinux(8)


summary: ipa\-renew\-agent\-submit

text:
# certmonger-dogtag-ipa-renew-agent-submit(8)

## NAME
dogtag-ipa-renew-agent-submit

## SYNOPSIS
dogtag-ipa-renew-agent-submit [options] [csrfile]

## DESCRIPTION
dogtag-ipa-renew-agent-submit is the helper which certmonger uses to make certificate renewal requests to Dogtag instances running on IPA servers. It is not normally run interactively, but it can be for troubleshooting purposes.

The preferred option is to request a renewal of an already-issued certificate, using its serial number, which can be read from a PEM-formatted certificate provided in the CERTMONGER_CERTIFICATE environment variable, or via the -s or -D option on the command line. If no serial number is provided, then the client will attempt to obtain a new certificate by submitting a signing request to the CA.

The signing request which is to be submitted should either be in a file whose name is given as an argument, or fed into dogtag-ipa-renew-agent-submit via stdin.

certmonger does not yet support retrieving trust information from Dogtag CAs.

## OPTIONS
-E EE-URL, --ee-url=EE-URL

The top-level URL for the end-entity interface provided by the CA. In IPA installations, this is typically http://SERVER:EEPORT/ca/ee/ca. If no URL is specified, the host named in the [global] section in the /etc/ipa/default.conf file is used as the value of SERVER, and the value of EEPORT will be inferred based on the value of the dogtag_version in the [global] section in the /etc/ipa/default.conf file: if dogtag_version is set to 10 or more, EEPORT will be set to 8090. Otherwise it will be 9180.

-A AGENT-URL, --agent-url=AGENT-URL

The top-level URL for the agent interface provided by the CA. In IPA installations, this is typically https://SERVER:AGENTPORT/ca/agent/ca. If no URL is specified, the host named in the [global] section in the /etc/ipa/default.conf file is used as the value of SERVER, and the value of AGENTPORT will be inferred based on the value of the dogtag_version in the [global] section in the /etc/ipa/default.conf file: if dogtag_version is set to 10 or more, AGENTPORT will be set to 8443. Otherwise it will be 9443.

-i FILE, --cafile=PATH

The location of a file containing a copy of the CA's certificate, against which the CA server's certificate will be verified. The default is /etc/ipa/ca.crt.

-C DIR, --capath=DIR

The location of a directory containing a copy of the CA's certificate, against which the CA server's certificate will be verified.

-d DIR, --dbdir=DIR

The NSS database that contains credentials to authenticate to the CA.

-n NAME, --nickname=NAME

The nickname of the certificate used for authentication.

-c FILENAME, --certfile=FILENAME

The certificate in PEM format used for authentication.

-k FILENAME, --keyfile=FILENAME

The private key for the certificate in PEM format used for authentication. It may be encrypted.

-p FILENAME, --sslpinfile=FILENAME

A file that contains the pin for the private key file or NSS database.

-P STRING, --sslpin=STRING

The pin for the private key file or NSS database.

-s NUMBER, --hex-serial=NUMBER

The serial number of an already-issued certificate for which the client should attempt to obtain a new certificate, in hexidecimal form, if one can not be read from the CERTMONGER_CERTIFICATE environment variable.

-D NUMBER, --serial=NUMBER

The serial number of an already-issued certificate for which the client should attempt to obtain a new certificate, in decimal form, if one can not be read from the CERTMONGER_CERTIFICATE environment variable.

-S STATE-VALUE, --state=STATE-VALUE

A cookie value provided by a previous instance of this helper, if the helper is being asked to continue a multi-step enrollment process. If the CERTMONGER_COOKIE environment variable is set, its value is used.

-T NAME, --profile=NAME

The name of the type of certificate which the client should request from the CA if it is not renewing a certificate (per the -s option above). If the CERTMONGER_CA_PROFILE environment variable is set, its value is used. Otherwise, the default value is caServerCert.

-t, --profile-list

Instead of attempting to obtain a new certificate, query the server for a list of the enabled enrollment profiles.

-O param=value, --approval-option=param=value

An additional parameter to pass to the server when approving the signing request using the agent's credentials. By default, any server-supplied default settings are applied. This option can be used either to override a server-supplied default setting, or to supply one which would otherwise have not been used.

-N, --force-new

Even if an already-issued certificate is available in the CERTMONGER_CERTIFICATE environment variable, or a serial number has been provided, don't attempt to renew a certificate using its serial number. Instead, attempt to obtain a new certificate using the signing request. The default behavior is to request a renewal if possible.

-R, --force-renew

Negates the effect of the -N flag.

-o param=value, --submit-option=param=value

When initially submitting a request to the CA, add the specified parameter and value along with any request parameters which would otherwise be sent. This option is not typically used.

-a, --agent-submit

Use agent credentials, specified using some combination of the -d, -n, -c, and -k flags, to authenticate to the CA when initially submitting a request to the CA or retrieving the list of enabled enrollment profiles. This is typically required when the enrollment profile being used uses AgentCertAuth-based authentication, and requires that the URL specified using the -E flag be an HTTPS URL, or when the URL specified using the -E flag is an HTTPS URL.

-u username, --uid=username

When initially submitting a request to the CA, supply the specified value as a user name. This is typically required when the enrollment profile being used uses UidPwdDirAuth-based or NISAuth-based authentication..TP -U userdn, --upn=userdn When initially submitting a request to the CA, supply the specified value as the DN (distinguished name) of the user's entry in a directory server which the CA is configured to use for checking the user's password. This is typically required when the enrollment profile being used uses UdnPwdDirAuth-based authentication.

-W PASSWORD, --userpwd=PASSWORD

When initially submitting a request to the CA, supply the specified value as the password for the user whose name is specified with the -u option, or whose DN is specified with the -U option. This is typically only required when the enrollment profile being used uses UidPwdDirAuth-based, UserPwdDirAuth-based, or NISAuth-based authentication. If the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.

-w FILE, --userpwdfile=FILE

When initially submitting a request to the CA, read from the specified file a password to supply for the user whose name is specified with the -u option, or whose DN is specified with the -U option. This is typically only required when the enrollment profile being used uses UidPwdDirAuth-based, UserPwdDirAuth-based, or NISAuth-based authentication. If the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.

-Y PIN, --userpin=PIN

When initially submitting a request to the CA, supply the specified value as the PIN for the user whose name is specified with the -u option, or whose DN is specified with the -U option. This is typically only required when the enrollment profile being used uses UidPwdPinDirAuth-based authentication. If the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted. -y FILE, --userpinfile=FILE When initially submitting a request to the CA, read from the specified file a PIN to supply for the user whose name is specified with the -u option, or whose DN is specified with the -U option. This is typically only required when the enrollment profile being used uses UidPwdPinDirAuth-based authentication. If the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.

-v, --verbose

Increases the logging level. Use twice for more logging. This option is mainly useful for troubleshooting.

## AGENT KEY AND CERTIFICATE OPTIONS
Options that provide the location for the private key and public certificate which the client should use to authenticate to the CA's agent interface. The values to use depend on which cryptography library your copy of libcurl was linked with.

The location of the certificate used for authentication to the CA needs to be provided in either a combination of PEM files using --certfile and --keyfile or an NSS database using--dbdir and --nickname. The default for --cafile is /etc/ipa/ca.crt.

-d dbdir, --dbdir=dbdir

Use an NSS database in the specified directory for this certificate and key. Only valid with -n.

-n NAME, --nickname=NAME

Use the NSS key with this nickname. Only valid with -d.

-c FILE, --certfile=FILE

The PEM file that contains the public certificate. Only valid with -k.

-k FILE, --keyfile=FILE

The PEM file that contains the private certificate. Only valid with -c.

-p FILE, --sslpinfile=FILE

The name of a file which contains a PIN/password which will be needed in order to make use of the agent credentials.

-P PIN, --sslpin=PIN

The name of a file which contains a PIN/password which will be needed in order to make use of the agent credentials.

## EXIT STATUS
0

if the certificate was issued. The certificate will be printed.

1

if the CA is still thinking. A cookie (state) value will be printed.

2

if the CA rejected the request. An error message may be printed.

3

if the CA was unreachable. An error message may be printed.

4

if critical configuration information is missing. An error message may be printed.

5

if the CA is still thinking. A suggested poll delay (specified in seconds) and a cookie (state) value will be printed.

17

if the CA indicates that the client needs to attempt enrollment using a new key pair.

## FILES
/etc/ipa/default.conf

is the IPA client configuration file. This file is consulted to determine the URL for the Dogtag server's end-entity and agent interfaces if they are not supplied as arguments.

## BUGS
Please file tickets for any that you find at https://fedorahosted.org/certmonger/

## SEE ALSO
certmonger(8) getcert(1) getcert-add-ca(1) getcert-add-scep-ca(1) getcert-list-cas(1) getcert-list(1) getcert-modify-ca(1) getcert-refresh-ca(1) getcert-refresh(1) getcert-rekey(1) getcert-remove-ca(1) getcert-resubmit(1) getcert-start-tracking(1) getcert-status(1) getcert-stop-tracking(1) certmonger-certmaster-submit(8) certmonger-dogtag-submit(8) certmonger-ipa-submit(8) certmonger-local-submit(8) certmonger-scep-submit(8) certmonger_selinux(8)


certmonger-dogtag-submit

title: certmonger-dogtag-submit(8)

summary: submit

text:
# certmonger-dogtag-submit(8)

## NAME
dogtag-submit

## SYNOPSIS
dogtag-submit -E EE-URL -A AGENT-URL [-d DIR] [-n NAME] [-i FILE] [-C DIR] [-c FILE] [-k FILE] [-p FILE] [-P PIN] [-s serial (hex)] [-D serial (decimal)] [-S state] [-T profile] [-O param=value] [-N | -R] [-t] [-o option=value] [-a] [-u username] [-U userdn] [-W PASSWORD] [-w FILE] [-Y PIN] [-y FILE] [-v] [csrfile]

## DESCRIPTION
dogtag-submit is the helper which certmonger can use to make certificate enrollment and renewal requests to Dogtag servers. It is not normally run interactively, but it can be for troubleshooting purposes.

The preferred option is to request a renewal of an already-issued certificate, using its serial number, which can be read from a PEM-formatted certificate provided in the CERTMONGER_CERTIFICATE environment variable, or via the -s or -D option on the command line. If no serial number is provided, then the client will attempt to obtain a new certificate by submitting a signing request to the CA.

The signing request which is to be submitted should either be in a file whose name is given as an argument, or fed into dogtag-submit via stdin.

certmonger does not yet support retrieving trust information from Dogtag CAs.

## OPTIONS
-E EE-URL, --ee-url=EE-URL

The top-level URL for the end-entity interface provided by the CA, through which the initial enrollment request will be submitted. This is typically http://SERVER:EEPORT/ca/ee/ca.

-A AGENT-URL, --agent-url=AGENT-URL

The top-level URL for the agent interface provided by the CA, through which the request can be approved using agent credentials. This is typically https://SERVER:AGENTPORT/ca/agent/ca.

-i FILE, --cafile=FILE

The location of a file containing a copy of the CA's certificate, against which the CA server's certificate will be verified.

-C DIR, --capath=DIR

The location of a directory containing a copy of the CA's certificate(s), against which the CA server's certificate will be verified.

-D SERIAL, --serial=SERIAL

The serial number of an already-issued certificate for which the client should attempt to obtain a new certificate, in decimal form, if one can not be read from the CERTMONGER_CERTIFICATE environment variable.

-s SERIAL, --hex-serial=SERIAL

The serial number of an already-issued certificate for which the client should attempt to obtain a new certificate, in hexadecimal form, if one can not be read from the CERTMONGER_CERTIFICATE environment variable.

-S STATE, --state=STATE

A cookie value provided by a previous instance of this helper, if the helper is being asked to continue a multi-step enrollment process. If the CERTMONGER_COOKIE environment variable is set, its value is used.

-T NAME, --profile=NAME

The name of the type of certificate which the client should request from the CA if it is not renewing a certificate (per the -s option above). If the CERTMONGER_CA_PROFILE environment variable is set, its value is used. Otherwise, the default value is caServerCert.

-O param=value, --approval-options=param=value

An additional parameter to pass to the server when approving the signing request using agent credentials. By default, any server-supplied default settings are applied. This option can be used either to override a server-supplied default setting, or to supply one which would otherwise have not been used. Requires the -A option.

-N, --force-new

Even if an already-issued certificate is available in the CERTMONGER_CERTIFICATE environment variable, or a serial number has been provided, don't attempt to renew a certificate using its serial number. Instead, attempt to obtain a new certificate using the signing request. The default behavior is to request a renewal if possible.

-R, --force-renew

Negates the effect of the -N flag.

-t, --profile-list

Instead of attempting to obtain a new certificate, query the server for a list of the enabled enrollment profiles.

-o param=value, --submit-option=param=value

When initially submitting a request to the CA, add the specified parameter and value along with any request parameters which would otherwise be sent.

-a, --agent-submit

Use agent credentials, specified using some combination of the -d, -n, -c, and -k flags, to authenticate to the CA when initially submitting a request to the CA or retrieving the list of enabled enrollment profiles. This is typically required when the enrollment profile being used uses AgentCertAuth-based authentication, and requires that the URL specified using the -E flag be an HTTPS URL, or when the URL specified using the -E flag is an HTTPS URL.

-u username, --uid=username

When initially submitting a request to the CA, supply the specified value as a user name. This is typically required when the enrollment profile being used uses UidPwdDirAuth-based or NISAuth-based authentication.

-U userdn, --upn=userdn

When initially submitting a request to the CA, supply the specified value as the DN (distinguished name) of the user's entry in a directory server which the CA is configured to use for checking the user's password. This is typically required when the enrollment profile being used uses UdnPwdDirAuth-based authentication.

-W PASSWORD, --userpwd=PASSWORD

When initially submitting a request to the CA, supply the specified value as the password for the user whose name is specified with the -u option, or whose DN is specified with the -U option. This is typically only required when the enrollment profile being used uses UidPwdDirAuth-based, UserPwdDirAuth-based, or NISAuth-based authentication. If the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.

-w FILE, --userpwdfile=FILE

When initially submitting a request to the CA, read from the specified file a password to supply for the user whose name is specified with the -u option, or whose DN is specified with the -U option. This is typically only required when the enrollment profile being used uses UidPwdDirAuth-based, UserPwdDirAuth-based, or NISAuth-based authentication. If the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.

-Y PIN, --userpin=PIN

When initially submitting a request to the CA, supply the specified value as the PIN for the user whose name is specified with the -u option, or whose DN is specified with the -U option. This is typically only required when the enrollment profile being used uses UidPwdPinDirAuth-based authentication. If the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.

-y FILE, --userpinfile=FILE

When initially submitting a request to the CA, read from the specified file a PIN to supply for the user whose name is specified with the -u option, or whose DN is specified with the -U option. This is typically only required when the enrollment profile being used uses UidPwdPinDirAuth-based authentication. If the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.

-v, --verbose

Increases the logging level. Use twice for more logging. This option is mainly useful for troubleshooting.

## AGENT KEY AND CERTIFICATE OPTIONS
Options that provide the location for the private key and public certificate which the client should use to authenticate to the CA's agent interface. The values to use depend on which cryptography library your copy of libcurl was linked with.

-d DIR, --dbdir=DIR

Use an NSS database in the specified directory for this certificate and key. Only valid with -n.

-n NAME, --nickname=NAME

Use the NSS key with this nickname. Only valid with -d.

-c FILE, --certfile=FILE

The PEM file that contains the public certificate. Only valid with -k.

-k FILE, --keyfile=FILE

The PEM file that contains the private certificate. Only valid with -c.

-p FILE, --sslpinfile=FILE

The name of a file which contains a PIN/password which will be needed in order to make use of the agent credentials.

-P PIN, --sslpin=PIN

The name of a file which contains a PIN/password which will be needed in order to make use of the agent credentials.

## EXIT STATUS
0

if the certificate was issued. The certificate will be printed.

1

if the CA is still thinking. A cookie (state) value will be printed.

2

if the CA rejected the request. An error message may be printed.

3

if the CA was unreachable. An error message may be printed.

4

if critical configuration information is missing. An error message may be printed.

5

if the CA is still thinking. A suggested poll delay (specified in seconds) and a cookie (state) value will be printed.

17

if the CA indicates that the client needs to attempt enrollment using a new key pair.

## BUGS
Please file tickets for any that you find at https://fedorahosted.org/certmonger/

## SEE ALSO
certmonger(8) getcert(1) getcert-add-ca(1) getcert-add-scep-ca(1) getcert-list-cas(1) getcert-list(1) getcert-modify-ca(1) getcert-refresh-ca(1) getcert-refresh(1) getcert-rekey(1) getcert-remove-ca(1) getcert-resubmit(1) getcert-start-tracking(1) getcert-status(1) getcert-stop-tracking(1) certmonger-certmaster-submit(8) certmonger-dogtag-ipa-renew-agent-submit(8) certmonger-ipa-submit(8) certmonger-local-submit(8) certmonger-scep-submit(8) certmonger_selinux(8)


certmonger-ipa-submit

title: certmonger-ipa-submit(8)

summary: submit

text:
# certmonger-ipa-submit(8)

## NAME
ipa-submit

## SYNOPSIS
ipa-submit [-h serverHost] [-H serverURL] [-d domain] [-L ldapurl] [-b basedn] [-c cafile] [-C capath] [[-K] | [-t keytab] [-k submitterPrincipal]] [-u UID] [-W PASSWORD] [-w FILE] [-P principalOfRequest] [-T profile] [-X issuer] [csrfile]

## DESCRIPTION
ipa-submit is the helper which certmonger uses to make requests to IPA-based CAs. It is not normally run interactively, but it can be for troubleshooting purposes. The signing request which is to be submitted should either be in a file whose name is given as an argument, or fed into ipa-submit via stdin.

certmonger supports retrieving trusted certificates from IPA CAs. See getcert-request(1) and getcert-resubmit(1) for information about specifying where those certificates should be stored on the local system. Trusted certificates are retrieved from the caCertificate attribute of entries present at and below cn=cacert,cn=ipa,cn=etc,$BASE in the IPA LDAP server's directory tree, where $BASE defaults to the value of the basedn setting in /etc/ipa/default.conf.

## OPTIONS
-P PRINCIPAL, --principal-of-request=PRINCIPAL

Identifies the principal name of the service for which the certificate is being issued. This setting is required by IPA and must always be specified.

-X NAME, --issuer=NAME

Requests that the certificate be processed by the specified certificate issuer. By default, if this flag is not specified, and the CERTMONGER_CA_ISSUER variable is set in the environment, then the value of the environment variable will be used. This setting is optional, and if a server returns error 3005, indicating that it does not understand multiple profiles, the request will be re-submitted without specifying an issuer name.

-T NAME, --profile=NAME

Requests that the certificate be processed using the specified certificate profile. By default, if this flag is not specified, and the CERTMONGER_CA_PROFILE variable is set in the environment, then the value of the environment variable will be used. This setting is optional, and if a server returns error 3005, indicating that it does not understand multiple profiles, the request will be re-submitted without specifying a profile.

-h HOSTNAME, --host=HOSTNAME

Submit the request to the IPA server running on the named host. The default is to read the location of the host from /etc/ipa/default.conf. If no server is configured, or the configured server cannot be reached, the client will attempt to use DNS discovery to locate LDAP servers for the IPA domain. If servers are found, they will be searched for entries pointing to IPA masters running the "CA" service, and the client will attempt to contact each of those in turn.

-H URL, --xmlrpc-url=URL

Submit the request to the IPA server at the specified location. The default is to read the location of the host from /etc/ipa/default.conf. If no server is configured, or the configured server cannot be reached, the client will attempt to use DNS discovery to locate LDAP servers for the IPA domain. If servers are found, they will be searched for entries pointing to IPA masters running the "CA" service, and the client will attempt to contact each of those in turn.

-L URL, --ldap-url=URL

Provide the IPA LDAP service location rather than using DNS discovery. The default is to read the location of the host from /etc/ipa/default.conf and use DNS discovery to find the set of _ldap._tcp.DOMAIN values and pick one for use.

-d DOMAIN, --domain=DOMAIN

Use this domain when doing DNS discovery to locate LDAP servers for the IPA installation. The default is to read the location of the host from /etc/ipa/default.conf.

-b BASEDN, --basedn=BASEDN

Use this basedn to search for an IPA installation in LDAP. The default is to read the location of the host from /etc/ipa/default.conf.

-c FILE, --cafile=FILE

The server's certificate was issued by the CA whose certificate is in the named file. The default value is /etc/ipa/ca.crt.

-C PATH, --capath=DIR

Trust the server if its certificate was issued by a CA whose certificate is in a file in the named directory. There is no default for this option, and it is not expected to be necessary.

-t KEYTAB, --keytab=KEYTAB

Authenticate to the IPA server using Kerberos with credentials derived from keys stored in the named keytab. The default value can vary, but it is usually /etc/krb5.keytab. This option conflicts with the -K, -u, -W, and -w options.

-k PRINCIPAL, --submitter-principal=PRINCIPAL

Authenticate to the IPA server using Kerberos with credentials derived from keys stored in the named keytab for this principal name. The default value is the host service for the local host in the local realm. This option conflicts with the -K, -u, -W, and -w options.

-K, --use-ccache-creds

Authenticate to the IPA server using Kerberos with credentials derived from the default credential cache rather than a keytab. This option conflicts with the -k, -u, -W, and -w options.

-u USERNAME, --uid=USERNAME

Authenticate to the IPA server using a user name and password, using the specified value as the user name. This option conflicts with the -k, -K, and -t options.

-W PASSWORD, --pwd=PASSWORD

Authenticate to the IPA server using a user name and password, using the specified value as the password. This option conflicts with the -k, -K, -t, and -w options.

-w FILE, --pwdfile=FILE

Authenticate to the IPA server using a user name and password, reading the password from the specified file. This option conflicts with the -k, -K, -t, and -W options.

## EXIT STATUS
0

if the certificate was issued. The certificate will be printed.

1

if the CA is still thinking. A cookie value will be printed.

2

if the CA rejected the request. An error message may be printed.

3

if the CA was unreachable. An error message may be printed.

4

if critical configuration information is missing. An error message may be printed.

17

if the CA indicates that the client needs to attempt enrollment using a new key pair.

## FILES
/etc/ipa/default.conf

is the IPA client configuration file. This file is consulted to determine the URL for the IPA server's XML-RPC interface.

## BUGS
Please file tickets for any that you find at https://fedorahosted.org/certmonger/

## SEE ALSO
certmonger(8) getcert(1) getcert-add-ca(1) getcert-add-scep-ca(1) getcert-list-cas(1) getcert-list(1) getcert-modify-ca(1) getcert-refresh-ca(1) getcert-refresh(1) getcert-rekey(1) getcert-remove-ca(1) getcert-request(1) getcert-resubmit(1) getcert-start-tracking(1) getcert-status(1) getcert-stop-tracking(1) certmonger-certmaster-submit(8) certmonger-dogtag-ipa-renew-agent-submit(8) certmonger-dogtag-submit(8) certmonger-local-submit(8) certmonger-scep-submit(8) certmonger_selinux(8)


certmonger-local-submit

title: certmonger-local-submit(8)

summary: submit

text:
# certmonger-local-submit(8)

## NAME
local-submit

## SYNOPSIS
local-submit [-d state-directory] [-v] [csrfile]

## DESCRIPTION
local-submit is the helper which certmonger uses to implement its local signer. It is not normally run interactively, but it can be for troubleshooting purposes. The signing request which is to be submitted should either be in a file whose name is given as an argument, or fed into local-submit via stdin.

The local signer is currently hard-coded to generate and use a 2048-bit RSA key and a name and initial serial number based on a UUID, replacing that key and certificate at roughly the midpoint of their useful lifetime.

certmonger supports retrieving the list of current and previously-used local CA certificates. See getcert-request(1) and getcert-resubmit(1) for information about specifying where those certificates should be stored.

## OPTIONS
-d DIR, --ca-data-directory=DIR

Identifies the directory which contains the local signer's private key, certificates, and other data used by the local signer.

-v, --verbose

Increases the verbosity of the tool's diagnostic logging.

## EXIT STATUS
0

if the certificate was issued. The new certificate will be printed.

3

if the helper needs to be called again. An error message may be printed.

4

if critical configuration information is missing. An error message may be printed.

## FILES
creds

is currently a PKCS#12 bundle containing the local signer's current signing key and current and previously-used signer certificates. It should not be modified except by the local signer. A new key is currently generated when ever a new signer certificate is needed.

serial

currently contains the serial number which will be used for the next issued certificate. It should not be modified except by the local signer.

## BUGS
Please file tickets for any that you find at https://fedorahosted.org/certmonger/

## SEE ALSO
certmonger(8) getcert(1) getcert-add-ca(1) getcert-add-scep-ca(1) getcert-list-cas(1) getcert-list(1) getcert-modify-ca(1) getcert-refresh-ca(1) getcert-refresh(1) getcert-rekey(1) getcert-remove-ca(1) getcert-resubmit(1) getcert-start-tracking(1) getcert-status(1) getcert-stop-tracking(1) certmonger-certmaster-submit(8) certmonger-dogtag-ipa-renew-agent-submit(8) certmonger-dogtag-submit(8) certmonger-ipa-submit(8) certmonger-scep-submit(8) certmonger_selinux(8)


certmonger-scep-submit

title: certmonger-scep-submit(8)

summary: submit

text:
# certmonger-scep-submit(8)

## NAME
scep-submit

## SYNOPSIS
scep-submit -u SERVER-URL [-r ra-cert-file] [-R ca-cert-file] [-I other-certs-file] [-N ca-cert-file] [-i ca-identifier] [-v] [-n] [-c|-C|-g|-p] [pkimessage-filename]

## DESCRIPTION
scep-submit is the helper which certmonger can use to transmit certificate enrollment and renewal requests to servers using SCEP. It is not normally run interactively, but it can be for troubleshooting purposes.

The request which is to be submitted should be a PEM-encoded SCEP pkiMessage either in a file whose name is given as an argument, or fed into scep-submit via stdin.

## MODES
-c, --retrieve-ca-capabilities

scep-submit will issue a GetCACaps request to the server and print the results.

-C, --retrieve-ca-certificates

scep-submit will issue a GetCACert request to the server, parse the response, and then print, in order, the RA certificate, the CA certificate, and any additional certificates.

-p, --pki-message

scep-submit will issue a PKIOperation request to the server using the passed-in message as the message content. It will parse the server's response, verify the signature, and if the response includes an issued certificate, it will output the pkcsPKIEnvelope in PEM format. If the response indicates an error, it will print the error.

-g, --get-initial-cert

scep-submit will issue a PKIOperation request to the server using the passed-in message as the message content. It will parse the server's response, verify the signature, and if the response includes an issued certificate, it will output the pkcsPKIEnvelope in PEM format. If the response indicates an error, it will print the error.

## OPTIONS
-u URL, --url=URL

The location of the SCEP interface provided by the CA. This is typically http://SERVER/cgi-bin/PKICLIENT.EXE or http://SERVER/certsrv/mscep/mscep.dll. This option is always required.

-R FILE, --cacert=FILE

The location of the CA certificate which was used to issue the SCEP web server's certificate in PEM form. If the URL specified with the -u option is an https URL, then this option is required.

-N FILE, --signingca=FILE

The location of a PEM-formatted copy of the SCEP server's CA certificate. A discovered value is normally supplied by the certmonger daemon, but one can be specified for troubleshooting purposes.

-r FILE, --racert=FILE

The location of the SCEP server's RA certificate, which is expected to be used for signing responses sent by the SCEP server back to the client. This option is required when either the -g flag or the -p flag is specified.

-I FILE, --other-certs=FILE

The location of a file containing other PEM-formatted certificates which may be needed in order to properly verify signed responses sent by the SCEP server back to the client. This option may be necessary when either the -g flag or the -p flag is specified.

-i NAME, --ca-identifier=NAME

When called with the -c or -C flag, this option can be used to specify the CA identifier which is passed to the server as part of the client's request. The default is "0".

-n, --non-renewal

The SCEP Renewal feature allows a client with a previously-issued certificate to use that certificate and the associated private key to request a new certificate for a different key pair, and can be used to support certmonger's rekeying feature if the SCEP server advertises support for it. This option forces the scep-submit helper to prefer to issue requests which do not make use of this feature.

-v, --verbose

Increases the logging level. Use twice for more logging. This option is mainly useful for troubleshooting.

## EXIT STATUS
0

if the certificate was issued. The pkcsPKIEnvelope will be printed in PEM-encoded form.

1

if the CA is still thinking. A cookie (state) value will be printed.

2

if the CA rejected the request. An error message may be printed.

3

if the CA was unreachable. An error message may be printed.

4

if critical configuration information is missing. An error message may be printed.

5

if the CA is still thinking. A suggested poll delay (specified in seconds) and a cookie (state) value will be printed.

16

if the helper needs an SCEP pkiMessage, but couldn't read one.

17

if the CA indicates that the client needs to attempt enrollment using a new key pair.

## BUGS
Please file tickets for any that you find at https://fedorahosted.org/certmonger/

## SEE ALSO
certmonger(8) getcert(1) getcert-add-ca(1) getcert-add-scep-ca(1) getcert-list-cas(1) getcert-list(1) getcert-modify-ca(1) getcert-refresh-ca(1) getcert-refresh(1) getcert-rekey(1) getcert-remove-ca(1) getcert-resubmit(1) getcert-start-tracking(1) getcert-status(1) getcert-stop-tracking(1) certmonger-certmaster-submit(8) certmonger-dogtag-ipa-renew-agent-submit(8) certmonger-dogtag-submit(8) certmonger-ipa-submit(8) certmonger-local-submit(8) certmonger_selinux(8)


certspotter

package: certspotter

title: certspotter(8)

text:
# certspotter(8)

## NAME
certspotter - Certificate Transparency Log Monitor

## SYNOPSIS
certspotter [-start_at_end] [-watchlist FILENAME] [-email ADDRESS] ...

## DESCRIPTION
Cert Spotter is a Certificate Transparency log monitor from SSLMate that alerts you when a SSL/TLS certificate is issued for one of your domains. Cert Spotter is easier to use than other open source CT monitors, since it does not require a database. It’s also more robust, since it uses a special certificate parser that ensures it won’t miss certificates.

Cert Spotter is also available as a hosted service by SSLMate, https://sslmate.com/certspotter.

You can use Cert Spotter to detect:

- Certificates issued to attackers who have compromised your DNS and are redirecting your visitors to their malicious site.

- Certificates issued to attackers who have taken over an abandoned sub-domain in order to serve malware under your name.

- Certificates issued to attackers who have compromised a certificate authority and want to impersonate your site.

- Certificates issued in violation of your corporate policy or outside of your centralized certificate procurement process.

## OPTIONS
-batch_size NUMBER

Maximum number of entries to request per call to get-entries. You should not generally need to change this. Defaults to 1000.

-email ADDRESS

Email address to contact when a matching certificate is discovered, or an error occurs. You can specify this option more than once to email multiple addresses. Your system must have a working sendmail(1) command.

Regardless of the -email option, certspotter also emails any address listed in $CERTSPOTTER_CONFIG_DIR/email_recipients file (~/.certspotter/email_recipients by default). (One address per line, blank lines are ignored.) This file is read only at startup, so you must restart certspotter if you change it.

-healthcheck INTERVAL

Perform a health check at the given interval (default: “24h”) as described below. INTERVAL must be a decimal number followed by “h” for hours or “m” for minutes.

-logs ADDRESS

Filename or HTTPS URL of a v2 or v3 JSON log list containing logs to monitor. The schema for this file can be found at https://www.gstatic.com/ct/log_list/v3/log_list_schema.json. Defaults to https://loglist.certspotter.org/monitor.json, which includes the union of active logs recognized by Chrome and Apple. certspotter periodically reloads the log list in case it has changed.

-no_save

Do not save a copy of matching certificates.

-script COMMAND

Command to execute when a matching certificate is found or an error occurs. See certspotter-script(8) for information about the interface to scripts.

Regardless of the -script option, certspotter also executes any executable file in the $CERTSPOTTER_CONFIG_DIR/hooks.d directory (~/.certspotter/hooks.d by default).

-start_at_end

Start monitoring logs from the end rather than the beginning.

WARNING: monitoring from the beginning guarantees detection of all certificates, but requires downloading hundreds of millions of certificates, which takes days.

-state_dir PATH

Directory for storing state. Defaults to $CERTSPOTTER_STATE_DIR, which is “~/.certspotter” by default.

-stdout

Write matching certificates and errors to stdout.

-verbose

Be verbose.

-version

Print version and exit.

-watchlist PATH

File containing DNS names to monitor, one per line. To monitor an entire domain namespace (including the domain itself and all sub-domains) prefix the domain name with a dot (e.g. “.example.com”). To monitor a single DNS name only, do not prefix the name with a dot.

Defaults to $CERTSPOTTER_CONFIG_DIR/watchlist, which is “~/.certspotter/watchlist” by default. Specify - to read the watch list from stdin.

certspotter reads the watch list only when starting up, so you must restart certspotter if you change it.

## NOTIFICATIONS
When certspotter detects a certificate matching your watchlist, or encounters an error that is preventing it from discovering certificates, it notifies you as follows:

- Emails any address specified by the -email command line flag.

- Emails any address listed in the $CERTSPOTTER_CONFIG_DIR/email_recipients file (~/.certspotter/email_recipients by default). (One address per line, blank lines are ignored.) This file is read only at startup, so you must restart certspotter if you change it.

- Executes the script specified by the -script command line flag.

- Executes every executable file in the $CERTSPOTTER_CONFIG_DIR/hooks.d directory (~/.certspotter/hooks.d by default).

- Writes the notification to standard out if the -stdout flag was specified.

Sending email requires a working sendmail(1) command. For details about the script interface, see certspotter-script(8).

## OPERATION
certspotter continuously monitors all browser-recognized Certificate Transparency logs looking for certificates which are valid for any domain on your watch list. When certspotter detects a matching certificate, it emails you, executes a script, and/or writes a report to standard out, as described above.

certspotter also saves a copy of matching certificates in $CERTSPOTTER_STATE_DIR/certs (“~/.certspotter/certs” by default) unless you specify the -no_save option.

When certspotter has not previously monitored a log, it can either start monitoring the log from the beginning, or seek to the end of the log and start monitoring from there. Monitoring from the beginning guarantees detection of all certificates, but requires downloading hundreds of millions of certificates, which takes days. The default behavior is to monitor from the beginning. To start monitoring new logs from the end, specify the -start_at_end option.

If certspotter has previously monitored a log, it resumes monitoring the log from the previous position. This means that if you add a domain to your watch list, certspotter will not detect any certificates that were logged prior to the addition. To detect such certificates, you must delete $CERTSPOTTER_STATE_DIR/logs, which will cause certspotter to restart monitoring from the very beginning of each log (provided -start_at_end is not specified). This will cause certspotter to download hundreds of millions of certificates, which takes days. To find preexisting certificates, it’s faster to use the Cert Spotter service https://sslmate.com/certspotter, SSLMate’s Certificate Transparency Search API https://sslmate.com/ct_search_api, or a CT search engine such as https://crt.sh.

## ERROR HANDLING
When certspotter encounters a problem with the local system (e.g. failure to write a file or execute a script), it prints a message to stderr and exits with a non-zero status.

When certspotter encounters a problem monitoring a log, it prints a message to stderr and continues running. It will try monitoring the log again later; most log errors are transient.

Every 24 hours (unless overridden by -healthcheck), certspotter performs the following health checks:

- Ensure that the log list has been successfully retrieved at least once since the previous health check.

- Ensure that every log has been successfully contacted at least once since the previous health check.

- Ensure that certspotter is not falling behind monitoring any logs.

If any health check fails, certspotter notifies you by email, script, and/or standard out, as described above.

Health check failures should be rare, and you should take them seriously because it means certspotter might not detect all certificates. It might also be an indication of CT log misbehavior. Consult certspotter’s stderr output for details, and if you need help, file an issue at https://github.com/SSLMate/certspotter.

## EXIT STATUS
certspotter exits 0 when it receives SIGTERM or SIGINT, and non-zero when a serious error occurs.

## ENVIRONMENT
CERTSPOTTER_STATE_DIR

Directory for storing state. Overridden by -state_dir. Defaults to ~/.certspotter.

CERTSPOTTER_CONFIG_DIR

Directory from which any configuration, such as the watch list, is read. Defaults to ~/.certspotter.

HTTPS_PROXY

URL of proxy server for making HTTPS requests. http://, https://, and socks5:// URLs are supported. By default, no proxy server is used.

SENDMAIL_PATH

Path to the sendmail binary used for sending emails. Defaults to /usr/sbin/sendmail.

## SEE ALSO
certspotter-script(8)

## COPYRIGHT
Copyright © 2016-2023 Opsmate, Inc.

## BUGS
Report bugs to https://github.com/SSLMate/certspotter.


certspotter-script

title: certspotter-script(8)

text:
# certspotter-script(8)

## NAME
certspotter-script - Certificate Transparency Log Monitor (hook script)

## DESCRIPTION
certspotter-script is any program that is executed by certspotter(8) when it needs to notify you about an event, such as detecting a certificate for a domain on your watch list.

Scripts are placed in the $CERTSPOTTER_CONFIG_DIR/hooks.d directory (~/.certspotter/hooks.d by default), or specified on the command line using the -script argument.

## ENVIRONMENT

### Event information
The following environment variables are set for all types of events:

EVENT

One of the following values, indicating the type of event:

- discovered_cert - certspotter has discovered a certificate for a domain on your watch list.

- malformed_cert - certspotter can’t determine if a certificate matches your watch list because the certificate or the log entry is malformed.

- error - a problem is preventing certspotter from monitoring all logs.

Additional event types may be defined in the future, so your script should be able to handle unknown values.

SUMMARY

A short human-readable string describing the event. This is the same string used in the subject line of emails sent by certspotter.

### Discovered certificate information
The following environment variables are set for discovered_cert events:

WATCH_ITEM

The item from your watch list which matches this certificate. (If more than one item matches, the first one is used.)

LOG_URI

The URI of the log containing the certificate.

ENTRY_INDEX

The index of the log entry containing the certificate.

TBS_SHA256

The hex-encoded SHA-256 digest of the TBSCertificate, as defined in RFC 6962 Section 3.2. Certificates and their corresponding precertificates have the same TBS_SHA256 value.

CERT_SHA256

The hex-encoded SHA-256 digest (sometimes called fingerprint) of the certificate. The digest is computed over the ASN.1 DER encoding.

PUBKEY_SHA256

The hex-encoded SHA-256 digest of the certificate’s Subject Public Key Info.

CERT_FILENAME

Path to a file containing the PEM-encoded certificate chain. Not set if -no_save was used.

JSON_FILENAME

Path to a JSON file containing additional information about the certificate. See below for the format of the JSON file. Not set if -no_save was used.

TEXT_FILENAME

Path to a text file containing information about the certificate. This file contains the same text that certspotter uses in emails. You should not attempt to parse this file because its format may change in the future. Not set if -no_save was used.

NOT_BEFORE, NOT_BEFORE_UNIXTIME, NOT_BEFORE_RFC3339

The not before time of the certificate, in a human-readable format, seconds since the UNIX epoch, and RFC3339, respectively. These variables may be unset if there was a parse error, in which case VALIDITY_PARSE_ERROR is set.

NOT_AFTER, NOT_AFTER_UNIXTIME, NOT_AFTER_RFC3339

The not after (expiration) time of the certificate, in a human-readable format, seconds since the UNIX epoch, and RFC3339, respectively. These variables may be unset if there was a parse error, in which case VALIDITY_PARSE_ERROR is set.

VALIDITY_PARSE_ERROR

Error parsing not before and not after, if any. If this variable is set, then the NOT_BEFORE and NOT_AFTER family of variables are unset.

SUBJECT_DN

The distinguished name of the certificate’s subject. This variable may be unset if there was a parse error, in which case SUBJECT_PARSE_ERROR is set.

SUBJECT_PARSE_ERROR

Error parsing the subject, if any. If this variable is set, then SUBJECT_DN is unset.

ISSUER_DN

The distinguished name of the certificate’s issuer. This variable may be unset if there was a parse error, in which case ISSUER_PARSE_ERROR is set.

ISSUER_PARSE_ERROR

Error parsing the issuer, if any. If this variable is set, then ISSUER_DN is unset.

SERIAL

The hex-encoded serial number of the certificate. Prefixed with a minus (-) sign if negative. This variable may be unset if there was a parse error, in which case SERIAL_PARSE_ERROR is set.

SERIAL_PARSE_ERROR

Error parsing the serial number, if any. If this variable is set, then SERIAL is unset.

### Malformed certificate information
The following environment variables are set for malformed_cert events:

LOG_URI

The URI of the log containing the malformed certificate.

ENTRY_INDEX

The index of the log entry containing the malformed certificate.

LEAF_HASH

The base64-encoded Merkle hash of the leaf containing the malformed certificate.

PARSE_ERROR

A human-readable string describing why the certificate is malformed.

ENTRY_FILENAME

Path to a file containing the JSON log entry. The file contains a JSON object with two fields, leaf_input and extra_data, as described in RFC 6962 Section 4.6.

TEXT_FILENAME

Path to a text file containing a description of the malformed certificate. This file contains the same text that certspotter uses in emails.

### Error information
The following environment variables are set for error events:

TEXT_FILENAME

Path to a text file containing a description of the error. This file contains the same text that certspotter uses in emails.

## JSON FILE FORMAT
Unless -no_save is used, certspotter saves a JSON file for every discovered certificate under $CERTSPOTTER_STATE_DIR, and puts the path to the file in $JSON_FILENAME. Your script can read the JSON file, such as with the jq(1) command, to get additional information about the certificate which isn’t appropriate for environment variables.

The JSON file contains an object with the following fields:

tbs_sha256

A string containing the hex-encoded SHA-256 digest of the TBSCertificate, as defined in RFC 6962 Section 3.2. Certificates and their corresponding precertificates have the same tbs_sha256 value.

pubkey_sha256

A string containing the hex-encoded SHA-256 digest of the certificate’s Subject Public Key Info.

dns_names

An array of strings containing the DNS names for which the certificate is valid, taken from both the DNS subject alternative names (SANs) and the subject common name (CN). Internationalized domain names are encoded in Punycode.

ip_addresses

An array of strings containing the IP addresses for which the certificate is valid, taken from both the IP subject alternative names (SANs) and the subject common name (CN).

not_before

A string containing the not before time of the certificate in RFC3339 format. Null if there was an error parsing the certificate’s validity.

not_after

A string containing the not after (expiration) time of the certificate in RFC3339 format. Null if there was an error parsing the certificate’s validity.

Additional fields will be added in the future based on user feedback. Please open an issue at https://github.com/SSLMate/certspotter if you have a use case for another field.

## EXAMPLES
Example environment variables for a discovered_cert event:

```
CERT_FILENAME=/home/andrew/.certspotter/certs/3c/3cdc83b3932c194fcdf17aa2bf1abc34e8438b293c3d5c70693e175b38ff128a.pem
CERT_SHA256=3cdc83b3932c194fcdf17aa2bf1abc34e8438b293c3d5c70693e175b38ff128a
ENTRY_INDEX=6464843
EVENT=discovered_cert
ISSUER_DN=C=GB, ST=Greater Manchester, L=Salford, O=Sectigo Limited, CN=Sectigo RSA Domain Validation Secure Server CA
JSON_FILENAME=/usr2/andrew/.certspotter/certs/3c/3cdc83b3932c194fcdf17aa2bf1abc34e8438b293c3d5c70693e175b38ff128a.v1.json
LOG_URI=https://ct.cloudflare.com/logs/nimbus2024/
NOT_AFTER='2024-01-26 03:47:26 +0000 UTC'
NOT_AFTER_RFC3339=2024-01-26T03:47:26Z
NOT_AFTER_UNIXTIME=1706240846
NOT_BEFORE='2023-01-31 03:47:26 +0000 UTC'
NOT_BEFORE_RFC3339=2023-01-31T03:47:26Z
NOT_BEFORE_UNIXTIME=1675136846
PUBKEY_SHA256=33ac1d9b9e56005ccac045eac2398b3e9dd6b3f5b66ae6260f2d478c7c0d82c8
SERIAL=c170fbf3bf27481e5c351a4db6f2dc5f
SUBJECT_DN=CN=sslmate.com
SUMMARY='certificate discovered for .sslmate.com'
TBS_SHA256=2388ee81c6f45cffc73e68a35fa8921e839e20acc9a98e8e6dcaea07cbfbdef8
TEXT_FILENAME=/usr2/andrew/.certspotter/certs/3c/3cdc83b3932c194fcdf17aa2bf1abc34e8438b293c3d5c70693e175b38ff128a.txt
WATCH_ITEM=.sslmate.com
```

Example JSON file for a discovered certificate:

```
{

  "dns_names": [

    "sslmate.com",

    "www.sslmate.com"

  ],

  "ip_addresses": [],

  "not_after": "2024-01-26T03:47:26Z",

  "not_before": "2023-01-31T03:47:26Z",

  "pubkey_sha256": "33ac1d9b9e56005ccac045eac2398b3e9dd6b3f5b66ae6260f2d478c7c0d82c8",

  "tbs_sha256": "2388ee81c6f45cffc73e68a35fa8921e839e20acc9a98e8e6dcaea07cbfbdef8"
}
```

## SEE ALSO
certspotter(8)

## COPYRIGHT
Copyright © 2016-2023 Opsmate, Inc.

## BUGS
Report bugs to https://github.com/SSLMate/certspotter.