document sections and repositories

Signed-off-by: Alfredo Deza <alfredo.deza@inktank.com>

diff --git a/docs/source/conf.rst b/docs/source/conf.rst
index 33869cf881ec8958a5d3425ff833700f9ecdb180..7644a07624b663d9fe7944b6935a456c6e69457d 100644 (file)
--- a/docs/source/conf.rst
+++ b/docs/source/conf.rst
@@ -54,4 +54,90 @@ This is how a default configuration file would look like::
     # gpgkey=https://ceph.com/git/?p=ceph.git;a=blob_plain;f=keys/autobuild.asc
 
 
+.. conf_sections:
 
+Sections
+--------
+To work with ceph-deploy configurations, it is important to note that all
+sections that relate to ceph-deploy's flags and state are prefixed with
+``ceph-deploy-`` followed by the subcommand or by ``global`` if it is something
+that belongs to the global flags.
+
+Any other section that is not prefixed with ``ceph-deploy-`` is considered
+a repository.
+
+Repositories can be very complex to describe and most of the time (specially
+for yum repositories) they can be very verbose too.
+
+Repository Sections
+-------------------
+Keys will depend on the type of package manager that will use it. Certain keys
+for yum are required (like ``baseurl``) and some others like ``gpgcheck`` are
+optional.
+
+yum
+---
+For yum these would be all the required keys in a repository section:
+
+* baseurl
+* gpgkey
+
+If a required key is not present ceph-deploy will abort the installation
+process with an error identifying the section and key what was missing.
+
+The repository name is taken from the section, so if the section is ``[foo]``,
+then the name of the repository will be ``foo repo`` and the filename written
+to ``/etc/yum.repos.d/`` will be ``foo.repo``.
+
+Optional values
+---------------
+**name**:  A descriptive name for the repository. If not provided ``{repo
+section} repo`` is used
+
+**enabled**: Defaults to ``1``
+
+**gpgcheck**: Defaults to ``1``
+
+**type**: Defaults to ``rpm-md``
+
+**gpgcheck**: Defaults to ``1``
+
+
+Default Repository
+------------------
+For installations where a default repository is needed a key can be added to
+that section to indicate it is the default one::
+
+    [myrepo]
+    default = true
+
+When a default repository is detected it is mentioned in the log output and
+ceph will get install from that one repository at the end.
+
+Extra Repositories
+------------------
+If other repositories need to be installed aside from the main one, a key
+should be added to represent that need with a comma separated value with the
+name of the sections of the other repositories (just like the example
+configuration file demonstrates)::
+
+    [myrepo]
+    baseurl = https://user:pass@example.org/rhel6
+    gpgurl = https://example.org/keys/release.asc
+    default = True
+    extra-repos = cephrepo  # will install the cephrepo file too
+
+    [cephrepo]
+    name=ceph repo noarch packages
+    baseurl=http://ceph.com/rpm-emperor/el6/noarch
+    enabled=1
+    gpgcheck=1
+    type=rpm-md
+    gpgkey=https://ceph.com/git/?p=ceph.git;a=blob_plain;f=keys/autobuild.asc
+
+In this case, the repository called ``myrepo`` defines the ``extra-repos`` key
+with just one extra one: ``cephrepo``.
+
+This extra repository must exist as a section in the configuration file. After
+the main one is added all the extra ones defined will follow. Installation of
+Ceph will only happen with the main repository.