Merge pull request #4412 from tchaikov/wip-add-man-page

doc: add man page for ceph-create-keys

Reviewed-by: Loic Dachary <ldachary@redhat.com>

ceph.spec.in

@@ -653,6 +653,7 @@ fi
 %{_mandir}/man8/ceph-deploy.8*
 %{_mandir}/man8/ceph-detect-init.8*
 %{_mandir}/man8/ceph-disk.8*
+%{_mandir}/man8/ceph-create-keys.8*
 %{_mandir}/man8/ceph-mon.8*
 %{_mandir}/man8/ceph-mds.8*
 %{_mandir}/man8/ceph-osd.8*

debian/ceph.install

@@ -25,6 +25,7 @@ usr/libexec/ceph/ceph-osd-prestart.sh
 usr/share/doc/ceph/sample.ceph.conf
 usr/share/doc/ceph/sample.fetch_config
 usr/share/man/man8/ceph-clsinfo.8
+usr/share/man/man8/ceph-create-keys.8
 usr/share/man/man8/ceph-debugpack.8
 usr/share/man/man8/ceph-deploy.8
 usr/share/man/man8/ceph-detect-init.8

doc/man/8/ceph-conf.rst

@@ -13,7 +13,7 @@ Synopsis
 | **ceph-conf** -c *conffile* -L
 | **ceph-conf** -c *conffile* -l *prefix*
 | **ceph-conf** *key* -s *section1* ...
-| **ceph-conf** [-s *section* ] --lookup *key*
+| **ceph-conf** [-s *section* ] [-r] --lookup *key*
 | **ceph-conf** [-s *section* ] *key*
 
 
@@ -28,30 +28,59 @@ Ceph configuration file to use with the ``-c`` flag.
 Actions
 =======
 
-.. TODO format this like a proper man page
+**ceph-conf** performs one of the following actions:
 
-**ceph-conf** will perform one of the following actions:
+.. option:: -L, --list-all-sections
 
---list-all-sections or -L prints out a list of all the section names in the configuration
-file.
+   list all sections in the configuration file.
 
---list-sections or -l prints out a list of all the sections that begin
-with a given prefix. For example, --list-sections mon would list all
-sections beginning with mon.
+.. option:: -l, --list-sections *prefix*
 
---lookup will search the configuration for a given value.  By default, the sections  that
-are searched are determined by the Ceph name that we are using. The Ceph name defaults to
-client.admin. It can be specified with --name.
+   list the sections with the given *prefix*. For example, ``--list-sections mon``
+   would list all sections beginning with ``mon``.
 
-For example, if we specify  --name  osd.0,  the  following  sections  will  be  searched:
-[osd.0], [osd], [global]
+.. option:: --lookup *key*
 
-You  can  specify  additional  sections to search with --section or -s.  These additional
-sections will be searched before the sections that would normally be searched. As always,
-the first matching entry we find will be returned.
+   search and print the specified configuration setting. Note:  ``--lookup`` is
+   the default action. If no other actions are given on the command line, we will
+   default to doing a lookup.
 
-Note:  --lookup is the default action. If no other actions are given on the command line,
-we will default to doing a lookup.
+.. option:: -h, --help
+
+   print a summary of usage.
+
+
+Options
+=======
+
+.. option:: -c *conffile*
+
+   the Ceph configuration file.
+
+.. option:: --filter-key *key*
+
+   filter section list to only include sections with given *key* defined.
+
+.. option:: --filter-key-value *key* ``=`` *value*
+
+   filter section list to only include sections with given *key*/*value* pair.
+
+.. option:: --name *type.id*
+
+   the Ceph name in which the sections are searched (default 'client.admin').
+   For example, if we specify ``--name osd.0``, the following sections will be
+   searched: [osd.0], [osd], [global]
+
+.. option:: -r, --resolve-search
+
+   search for the first file that exists and can be opened in the resulted
+   comma delimited search list.
+
+.. option:: -s, --section
+
+   additional sections to search.  These additional sections will be searched
+   before the sections that would normally be searched. As always, the first
+   matching entry we find will be returned.
 
 
 Examples
@@ -65,7 +94,7 @@ To find out what value will mds a use for the "log file" option::
 
         ceph-conf -c foo.conf  --name mds.a "log file"
 
-To list all sections that begin with osd::
+To list all sections that begin with "osd"::
 
         ceph-conf -c foo.conf -l osd
 
@@ -73,6 +102,18 @@ To list all sections::
 
         ceph-conf -c foo.conf -L
 
+To print the path of the "keyring" used by "client.0"::
+
+       ceph-conf --name client.0 -r -l keyring
+
+
+Files
+=====
+
+``/etc/ceph/$cluster.conf``, ``~/.ceph/$cluster.conf``, ``$cluster.conf``
+
+the Ceph configuration files to use if not specified.
+
 
 Availability
 ============

doc/man/8/ceph-create-keys.rst

@@ -0,0 +1,63 @@
+:orphan:
+
+===============================================
+ceph-create-keys -- ceph keyring generate tool
+===============================================
+
+.. program:: ceph-create-keys
+
+Synopsis
+========
+
+| **ceph-create-keys** [-h] [-v] [--cluster *name*] --id *id*
+
+
+Description
+===========
+
+:program:`ceph-create-keys` is a utility to generate bootstrap keyrings using
+the given monitor when it is ready.
+
+it creates following auth entities (or users)
+
+``client.admin``
+
+    and its key for your client host.
+
+``client.bootstrap-{osd, rgw, mds}``
+
+    and their keys for bootstrapping corresponding services
+
+To list all users in cluster::
+
+    ceph auth list
+
+
+Options
+=======
+
+.. option:: --cluster
+
+   name of the cluster (default 'ceph').
+
+.. option:: -i, --id
+
+   id of a ceph-mon that is coming up. **ceph-create-keys** will wait until it joins quorum.
+
+.. option:: -v, --verbose
+
+   be more verbose.
+
+
+Availability
+============
+
+**ceph-create-keys** is part of Ceph, a massively scalable, open-source, distributed storage system.  Please refer
+to the Ceph documentation at http://ceph.com/docs for more
+information.
+
+
+See also
+========
+
+:doc:`ceph <ceph>`\(8)

man/CMakeLists.txt

@@ -11,6 +11,7 @@ install(FILES
 	ceph-run.8
 	ceph.8
 	mount.ceph.8
+	ceph-create-keys.8
 	radosgw.8
 	radosgw-admin.8
 	ceph-authtool.8

man/Makefile-server.am

@@ -3,6 +3,7 @@ dist_man_MANS += \
 	crushtool.8 \
 	ceph-run.8 \
 	mount.ceph.8 \
+	ceph-create-keys.8 \
 	ceph-rest-api.8 \
 	ceph-debugpack.8