From 3f6be22f64a5b6840d2f1d0b6e49d1ba12a86c15 Mon Sep 17 00:00:00 2001 From: Nilamdyuti Goswami Date: Wed, 17 Dec 2014 20:08:22 +0530 Subject: [PATCH] doc: Updates man page for ceph-disk. Changes format style to improve readability as html. Signed-off-by: Nilamdyuti Goswami --- doc/man/8/ceph-disk.rst | 192 +++++++++++++++++++++++++--------------- 1 file changed, 122 insertions(+), 70 deletions(-) diff --git a/doc/man/8/ceph-disk.rst b/doc/man/8/ceph-disk.rst index 41e360994cf9e..8a89fab3c32bb 100644 --- a/doc/man/8/ceph-disk.rst +++ b/doc/man/8/ceph-disk.rst @@ -19,104 +19,150 @@ Synopsis Description =========== -**ceph-disk** is a utility that can prepare and activate a disk, partition or -directory as a ceph OSD. It is run directly or triggered by **ceph-deploy** -or udev. +:program:`ceph-disk` is a utility that can prepare and activate a disk, partition or +directory as a Ceph OSD. It is run directly or triggered by :program:`ceph-deploy` +or ``udev``. It can also be triggered by other deployment utilities like ``Chef``, +``Juju``, ``Puppet`` etc. It actually automates the multiple steps involved in manual creation and start of an OSD into 2 steps of preparing and activating the OSD by using the -subcommands **prepare** and **activate**. +subcommands ``prepare`` and ``activate``. Subcommands ============ -**prepare**: Prepare a directory, disk or drive for a ceph OSD. It creates a GPT -partition, marks the partition with ceph type uuid, creates a file system, marks -the file system as ready for ceph consumption, uses entire partition and adds a -new partition to the journal disk. It is run directly or triggered by -**ceph-deploy**. +prepare +-------- -Usage: ceph-disk prepare --cluster [cluster-name] --cluster-uuid [uuid] --fs-type -[ext4|xfs|btrfs] [data-path] [journal-path] +Prepare a directory, disk or drive for a Ceph OSD. It creates a GPT partition, +marks the partition with Ceph type ``uuid``, creates a file system, marks the +file system as ready for Ceph consumption, uses entire partition and adds a new +partition to the journal disk. It is run directly or triggered by +:program:`ceph-deploy`. -Other options like --osd-uuid, --journal-uuid, --zap-disk, --data-dir, --data-dev, ---journal-file, --journal-dev, --dmcrypt and --dmcrypt-key-dir can also be used -with the subcommand. +Usage:: -**activate**: Activate the ceph OSD. It mounts the volume in a temporary -location, allocates an OSD id (if needed), remounts in the correct location -/var/lib/ceph/osd/$cluster-$id and starts ceph-osd. It is triggered by udev -when it sees the OSD GPT partition type or on ceph service start with -'ceph disk activate-all'. It is also run directly or triggered by **ceph-deploy**. + ceph-disk prepare --cluster [cluster-name] --cluster-uuid [uuid] --fs-type + [ext4|xfs|btrfs] [data-path] [journal-path] -Usage: ceph-disk activate [PATH] +Other options like :option:`--osd-uuid`, :option:`--journal-uuid`, +:option:`--zap-disk`, :option:`--data-dir`, :option:`--data-dev`, +:option:`--journal-file`, :option:`--journal-dev`, :option:`--dmcrypt` +and :option:`--dmcrypt-key-dir` can also be used with the subcommand. + +activate +-------- + +Activate the Ceph OSD. It mounts the volume in a temporary location, allocates +an OSD id (if needed), remounts in the correct location +``/var/lib/ceph/osd/$cluster-$id`` and starts ceph-osd. It is triggered by +``udev`` when it sees the OSD GPT partition type or on ceph service start with +``ceph disk activate-all``. It is also run directly or triggered by +:program:`ceph-deploy`. + +Usage:: + + ceph-disk activate [PATH] Here, [PATH] is path to block device or directory. -An additional option [--activate-key PATH] has to be used with this subcommand -when a copy of /var/lib/ceph/bootstrap-osd/{cluster}.keyring isn't present in the -OSD node. +An additional option :option:`--activate-key` has to be used with this +subcommand when a copy of ``/var/lib/ceph/bootstrap-osd/{cluster}.keyring`` +isn't present in the OSD node. + +Usage:: + + ceph-disk activate [PATH] [--activate-key PATH] -Usage: ceph-disk activate [PATH] [--activate-key PATH] +Another option :option:`--mark-init` can also be used with this subcommand. -Another option --mark-init can also be used with this subcommand. +activate-journal +---------------- -**activate-journal**: Activate an OSD via it's journal device. udev triggers -'ceph-disk activate-journal ' based on the partition type. +Activate an OSD via it's journal device. ``udev`` triggers +``ceph-disk activate-journal `` based on the partition type. -Usage: ceph-disk activate-journal [DEV] +Usage:: + + ceph-disk activate-journal [DEV] Here, [DEV] is the path to journal block device. -Others options can also be used with this subcommand like --activate-key and ---mark-init. +Others options like :option:`--activate-key` and :option:`--mark-init` can also +be used with this subcommand. + +Usage:: + + ceph-disk activate-journal [--activate-key PATH] [--mark-init INITSYSTEM] [DEV] + +activate-all +------------ + +Activate all tagged OSD partitions. ``activate-all`` relies on +``/dev/disk/by-parttype-uuid/$typeuuid.$uuid`` to find all partitions. Special +``udev`` rules are installed to create these links. It is triggered on ceph +service start or run directly. -Usage: ceph-disk activate-journal [--activate-key PATH] [--mark-init INITSYSTEM] -[DEV] +Usage:: -**activate-all**: Activate all tagged OSD partitions. activate-all relies on -/dev/disk/by-parttype-uuid/$typeuuid.$uuid to find all partitions. Special udev -rules are installed to create these links. It is triggered on ceph service start -or run directly. + ceph-disk activate-all -Usage: ceph-disk activate-all +Others options like :option:`--activate-key` and :option:`--mark-init` can +also be used with this subcommand. -Others options can also be used with this subcommand like --activate-key and ---mark-init. +Usage:: -Usage: ceph-disk activate-all [--activate-key PATH] [--mark-init INITSYSTEM] + ceph-disk activate-all [--activate-key PATH] [--mark-init INITSYSTEM] -**list**: List disk partitions and ceph OSDs. It is run directly or triggered -by **ceph-deploy**. +list +---- -Usage: ceph-disk list +List disk partitions and Ceph OSDs. It is run directly or triggered by +:program:`ceph-deploy`. -**suppress-activate**: Suppress activate on a device (prefix). -Mark devices that you want to suppress activate with a file like -/var/lib/ceph/tmp/suppress-activate.sdb where the last bit is -the sanitized device name (/dev/X without the /dev/ prefix). A -function is_suppressed() checks for and matches a prefix (/dev/). -It means suppressing sdb will stop activate on sdb1, sdb2, etc. +Usage:: -Usage: ceph-disk suppress-activate [PATH] + ceph-disk list + +suppress-activate +----------------- + +Suppress activate on a device (prefix). Mark devices that you want to suppress +activate with a file like ``/var/lib/ceph/tmp/suppress-activate.sdb`` where the +last bit is the sanitized device name (/dev/X without the /dev/ prefix). A +function ``is_suppressed()`` checks for and matches a prefix (/dev/). It means +suppressing sdb will stop activate on sdb1, sdb2, etc. + +Usage:: + + ceph-disk suppress-activate [PATH] Here, [PATH] is path to block device or directory. -**unsuppress-activate**: Stop suppressing activate on a device (prefix). +unsuppress-activate +------------------- + +Stop suppressing activate on a device (prefix). + +Usage:: -Usage: ceph-disk unsuppress-activate [PATH] + ceph-disk unsuppress-activate [PATH] Here, [PATH] is path to block device or directory. -**zap**: Zap/erase/destroy a device's partition table and contents. -It actually uses 'sgdisk' and it's option '--zap-all' to destroy both -GPT and MBR data structures so that the disk becomes suitable for -repartitioning. 'sgdisk' then uses '--mbrtogpt' to convert the MBR or -BSD disklabel disk to a GPT disk. The **prepare** subcommand can now be -executed which will create a new GPT partition. It is also run directly -or triggered by **ceph-deploy**. +zap +--- -Usage: ceph-disk zap [DEV] +Zap/erase/destroy a device's partition table and contents. It actually uses +``sgdisk`` and it's option ``--zap-all`` to destroy both GPT and MBR data +structures so that the disk becomes suitable for repartitioning. ``sgdisk`` +then uses ``--mbrtogpt`` to convert the MBR or BSD disklabel disk to a GPT +disk. The ``prepare`` subcommand can now be executed which will create a new +GPT partition. It is also run directly or triggered by :program:`ceph-deploy`. + +Usage:: + + ceph-disk zap [DEV] Here, [DEV] is path to block device. @@ -125,15 +171,15 @@ Options .. option:: --prepend-to-path PATH - Prepend PATH to $PATH for backward compatibility (default /usr/bin). + Prepend PATH to $PATH for backward compatibility (default ``/usr/bin``). .. option:: --statedir PATH - Directory in which ceph configuration is preserved (default /usr/lib/ceph). + Directory in which ceph configuration is preserved (default ``/usr/lib/ceph``). .. option:: --sysconfdir PATH - Directory in which ceph configuration files are found (default /etc/ceph). + Directory in which ceph configuration files are found (default ``/etc/ceph``). .. option:: --cluster @@ -145,7 +191,7 @@ Options .. option:: --fs-type - Provide the filesytem type for the OSD. e.g. 'xfs/ext4/btrfs'. + Provide the filesytem type for the OSD. e.g. ``xfs/ext4/btrfs``. .. option:: --osd-uuid @@ -161,11 +207,11 @@ Options .. option:: --data-dir - Verify that [data-path] is of a directory. + Verify that ``[data-path]`` is of a directory. .. option:: --data-dev - Verify that [data-path] is of a block device. + Verify that ``[data-path]`` is of a block device. .. option:: --journal-file @@ -177,15 +223,15 @@ Options .. option:: --dmcrypt - Encrypt [data-path] and/or journal devices with dm-crypt. + Encrypt ``[data-path]`` and/or journal devices with ``dm-crypt``. .. option:: --dmcrypt-key-dir - Directory where dm-crypt keys are stored. + Directory where ``dm-crypt`` keys are stored. .. option:: --activate-key - Use when a copy of /var/lib/ceph/bootstrap-osd/{cluster}.keyring isn't + Use when a copy of ``/var/lib/ceph/bootstrap-osd/{cluster}.keyring`` isn't present in the OSD node. Suffix the option by the path to the keyring. .. option:: --mark-init @@ -195,5 +241,11 @@ Options Availability ============ -**ceph-disk** is a part of the Ceph distributed storage system. Please refer to +:program:`ceph-disk` is a part of the Ceph distributed storage system. Please refer to the Ceph documentation at http://ceph.com/docs for more information. + +See also +======== + +:doc:`ceph-osd `\(8), +:doc:`ceph-deploy `\(8) -- 2.39.5