summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/appendix/guides/fedora.txt97
-rw-r--r--doc/client/index.txt17
-rw-r--r--doc/client/tools.txt (renamed from doc/client/tools/index.txt)8
-rw-r--r--doc/help/faq/client.txt10
-rw-r--r--doc/installation/distributions.txt2
-rw-r--r--doc/server/admin/backup.txt17
-rw-r--r--doc/server/admin/bundle.txt30
-rw-r--r--doc/server/admin/client.txt31
-rw-r--r--doc/server/admin/compare.txt16
-rw-r--r--doc/server/admin/index.txt92
-rw-r--r--doc/server/admin/init.txt47
-rw-r--r--doc/server/admin/minestruct.txt14
-rw-r--r--doc/server/admin/perf.txt18
-rw-r--r--doc/server/admin/pull.txt24
-rw-r--r--doc/server/admin/query.txt15
-rw-r--r--doc/server/admin/snapshots.txt8
-rw-r--r--doc/server/admin/tidy.txt8
-rw-r--r--doc/server/admin/viz.txt18
-rw-r--r--doc/server/admin/xcmd.txt27
-rw-r--r--doc/server/bcfg2-info.txt (renamed from doc/appendix/guides/using-bcfg2-info.txt)2
-rw-r--r--doc/server/index.txt14
-rw-r--r--doc/server/plugins/grouping/metadata.txt10
22 files changed, 385 insertions, 140 deletions
diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt
index d8d3b1b34..1dd4f6db0 100644
--- a/doc/appendix/guides/fedora.txt
+++ b/doc/appendix/guides/fedora.txt
@@ -12,22 +12,33 @@ This guide is work in progess.
This is a complete getting started guide for Fedora. With this
-document you should be able to install a Bcfg2 server, a Bcfg2 client,
+document you should be able to install a Bcfg2 server, a Bcfg2 client,
and change the ``/etc/motd`` file on the client.
+Prerequisites
+=============
+
+To setup a configuration management system based on Bcfg2 only a few
+prerequisites need to be fullfilled.
+
+* A server machine that can host the Bcfg2
+* Internet access for the installation process
+* A working network with DNS
+
+
Install Bcfg2 From RPM
======================
-The fastest way to get Bcfg2 onto your system is to use ``yum``
-or PackageKit. ``
-um`` will pull all dependencies of Bcfg2
+The fastest way to get Bcfg2 onto your system is to use ``yum``
+or PackageKit. ``yum`` will pull all dependencies of Bcfg2
automatically in. ::
$ su -c 'yum install bcfg2-server bcfg2'
-Your system should now have the necessary software to use Bcfg2.
+Your system should now have the necessary software to use Bcfg2.
The next step is to set up your Bcfg2 :term:`repository`.
+
Initialize your repository
==========================
@@ -38,14 +49,14 @@ is a tool which allows you to automate this:
.. code-block:: sh
# bcfg2-admin init
- Store bcfg2 configuration in [/etc/bcfg2.conf]:
- Location of bcfg2 repository [/var/lib/bcfg2]:
+ Store bcfg2 configuration in [/etc/bcfg2.conf]:
+ Location of bcfg2 repository [/var/lib/bcfg2]:
Directory /var/lib/bcfg2 exists. Overwrite? [y/N]:y
- Input password used for communication verification (without echoing; leave blank for a random):
+ Input password used for communication verification (without echoing; leave blank for a random):
What is the server's hostname: [config01.local.net]
- Input the server location [https://config01.local.net:6789]:
+ Input the server location [https://config01.local.net:6789]:
Input base Operating System for clients:
- 1: Redhat/Fedora/RHEL/RHAS/Centos
+ 1: Red Hat/Fedora/RHEL/RHAS/Centos
2: SUSE/SLES
3: Mandrake
4: Debian
@@ -68,7 +79,7 @@ Change responses as necessary.
Start the server
================
-You are now ready to start your bcfg2 server for the first time::
+You are now ready to start your Bcfg2 server for the first time::
$ su -c '/etc/init.d/bcfg2-server start'
Starting Configuration Management Server: bcfg2-server [ OK ]
@@ -90,12 +101,12 @@ Run ``bcfg2`` to be sure you are able to communicate with the server:
.. code-block:: sh
$ su -c 'bcfg2 -vqne'
-
+
/usr/lib/python2.6/site-packages/Bcfg2/Client/Tools/rpmtools.py:23: DeprecationWarning: the md5 module is deprecated; use hashlib instead
import md5
Loaded plugins: presto, refresh-packagekit
Loaded tool drivers:
- Action Chkconfig POSIX YUMng
+ Action Chkconfig POSIX YUMng
Extra Package imsettings-libs 0.108.0-2.fc13.i686.
Extra Package PackageKit-device-rebind 0.6.4-1.fc13.i686.
...
@@ -114,11 +125,11 @@ Run ``bcfg2`` to be sure you are able to communicate with the server:
Incorrect entries: 0
Total managed entries: 0
Unmanaged entries: 1314
- Package:ConsoleKit Package:jasper-libs Package:pcsc-lite-libs
- Package:ConsoleKit-libs Package:java-1.5.0-gcj Package:perf
- ...
- Package:iw Package:pcre Service:sshd
- Package:jack-audio-connection-kit Package:pcsc-lite Service:udev-post
+ Package:ConsoleKit Package:jasper-libs Package:pcsc-lite-libs
+ Package:ConsoleKit-libs Package:java-1.5.0-gcj Package:perf
+ ...
+ Package:iw Package:pcre Service:sshd
+ Package:jack-audio-connection-kit Package:pcsc-lite Service:udev-post
The ``bcfg2.conf`` file contains only standard plugins so far.
@@ -161,17 +172,17 @@ The ``bcfg2.conf`` file contains only standard plugins so far.
Add the machines to Bcfg2
-------------------------
-``bcfg2-admin`` can be used to add a machine to Bcfg2 easily. You
+``bcfg2-admin`` can be used to add a machine to Bcfg2 easily. You
need to know the Fully Qualified Domain Name (FQDN) of ever system
-you want to control through Bcfg2. ::
+you want to control through Bcfg2. ::
- bcfg2-admin client add <FQDN machine>
+ bcfg2-admin client add <FQDN machine>
Bring your first machine under Bcfg2 control
--------------------------------------------
-Now it is time to get the first machine's configuration into the
-Bcfg2 repository. The server will be the first machine. It's
+Now it is time to get the first machine's configuration into the
+Bcfg2 repository. The server will be the first machine. It's
already in the ``Metadata/client.xml``.
@@ -181,13 +192,13 @@ Setup the `Packages`_ plugin
.. _Packages: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages
First, replace **Pkgmgr** with **Packages** in the plugins
-line of ``bcfg2.conf``. Then create `Packages/` directory in
+line of ``bcfg2.conf``. Then create `Packages/` directory in
``/var/lib/bcfg2`` ::
$ su -c 'mkdir /var/lib/bcfg2/Packages'
-Create a ``config.xml`` file for the packages in
-``/var/lib/bcfg2/Packages`` with the following content. Choose a
+Create a ``config.xml`` file for the packages in
+``/var/lib/bcfg2/Packages`` with the following content. Choose a
mirror near your location according the `Mirror list`_ .
.. _Mirror list: http://mirrors.fedoraproject.org/publiclist/
@@ -229,11 +240,11 @@ something like this
<Group name='suse'/>
<Group name='mandrake'/>
<Group name='solaris'/>
- </Groups>
+ </Groups>
.. note::
- When editing your xml files by hand, it is useful to occasionally
- run ``bcfg2-repo-validate`` to ensure that your xml validates
+ When editing your xml files by hand, it is useful to occasionally
+ run ``bcfg2-repo-validate`` to ensure that your xml validates
properly.
Add a probe
@@ -241,7 +252,7 @@ Add a probe
The next step for the client will be to have the proper
arch group membership. For this, we will make use of the
-:ref:`server-plugins-grouping-dynamic_groups` capabilities of
+:ref:`server-plugins-grouping-dynamic_groups` capabilities of
the Probes plugin. Add **Probes** to your plugins line in ``bcfg2.conf``
and create the Probe:
@@ -271,7 +282,7 @@ Start managing packages
+++++++++++++++++++++++
Add a base-packages bundle. Let's see what happens when we just populate
-it with the *yum* package. Create the ``base-packages.xml`` in your
+it with the *yum* package. Create the ``base-packages.xml`` in your
``Bundler/`` directory with a entry for ``yum``.
.. code-block:: xml
@@ -295,22 +306,22 @@ Now if we run the client, we can see what this has done for us.::
output
-As you can see, the Packages plugin has generated the dependencies
-required for the yum package automatically. The ultimate goal should
-be to move all the packages from the **Unmanaged** entries section
-to the **Managed** entries section. So, what exactly *are* those
+As you can see, the Packages plugin has generated the dependencies
+required for the yum package automatically. The ultimate goal should
+be to move all the packages from the **Unmanaged** entries section
+to the **Managed** entries section. So, what exactly *are* those
Unmanaged entries?::
output
-Now you can go through these and continue adding the packages you
-want to your Bundle. After a while, I ended up with a minimal bundle
+Now you can go through these and continue adding the packages you
+want to your Bundle. After a while, I ended up with a minimal bundle
that looks like this
.. code-block:: xml
<Bundle name='base-packages'>
-
+
</Bundle>
Now when I run the client, you can see I have only one unmanaged
@@ -319,8 +330,8 @@ package::
outout
The gpg-pubkey packages are special in that they are not really
-packages. Currently, the way to manage them is using
-:ref:`BoundEntries <boundentries>`. So, after adding them, our
+packages. Currently, the way to manage them is using
+:ref:`BoundEntries <boundentries>`. So, after adding them, our
Bundle now looks like this
.. note:: This does not actually control the contents of the files,
@@ -352,7 +363,7 @@ Bundle now looks like this
To actually push the gpg keys out via Bcfg2, you will need to manage
the files as well. This can be done by adding Path entries for each
-of the gpg keys you want to manage
+of the gpg keys you want to manage
.. code-block:: xml
@@ -452,12 +463,12 @@ Git
.. _Git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
Adding the :ref:`server-plugins-version-git` plugins can preserve
-versioning information. The first step is to add *Git* to your
+versioning information. The first step is to add *Git* to your
plugin line::
plugins = Base,Bundler,Cfg,...,Git
-For tracking the configuration files in the ``/var/lib/bcfg2``
+For tracking the configuration files in the ``/var/lib/bcfg2``
directory a git repository need to be established::
git init
diff --git a/doc/client/index.txt b/doc/client/index.txt
index 5e6551387..e232d8084 100644
--- a/doc/client/index.txt
+++ b/doc/client/index.txt
@@ -23,22 +23,11 @@ client, for a few reasons:
deployment engine that can be driven by anything that writes a
compatible configuration description.
-Available client tools
-----------------------
-
-.. toctree::
- :maxdepth: 2
- :glob:
-
- tools/*
-
-Other client-related documentation
-----------------------------------
-
.. toctree::
:maxdepth: 2
+ modes
+ tools
+ metadata
agent
debugging
- metadata
- modes
diff --git a/doc/client/tools/index.txt b/doc/client/tools.txt
index 9bec46316..676feb175 100644
--- a/doc/client/tools/index.txt
+++ b/doc/client/tools.txt
@@ -1,6 +1,6 @@
.. -*- mode: rst -*-
-.. _client-tools-index:
+.. _client-tools:
Client Tool Drivers
===================
@@ -26,6 +26,12 @@ the system.
Currently these are the tool drivers that are distributed with Bcfg2:
+.. toctree::
+ :maxdepth: 2
+ :glob:
+
+ tools/*
+
Action
------
diff --git a/doc/help/faq/client.txt b/doc/help/faq/client.txt
index 8eb04e620..636d318ad 100644
--- a/doc/help/faq/client.txt
+++ b/doc/help/faq/client.txt
@@ -14,3 +14,13 @@ on the client. Then add the following on the client.::
[communication]
ca = /etc/bcfg2.ca
+
+.. FIXME: What is the solution for this?
+.. **Server failure**
+..
+.. On Fedora 14 and above it can happen that no connection is possible.
+..
+.. # bcfg2 -vqne
+.. Server failure: Protocol Error: 401 Unauthorized
+.. Failed to download probes from bcfg2
+.. Server Failure
diff --git a/doc/installation/distributions.txt b/doc/installation/distributions.txt
index 38b34f14d..a4ce9fb5d 100644
--- a/doc/installation/distributions.txt
+++ b/doc/installation/distributions.txt
@@ -38,7 +38,7 @@ at `CustomDebianRepository`_.
Fedora
======
-The fastest way to get Bcfg2 Packages_ onto your Fedora_ system is to
+The fastest way to get Bcfg2 packages onto your Fedora_ system is to
use `yum` or PackageKit. Yum will pull in all dependencies of Bcfg2
automatically. ::
diff --git a/doc/server/admin/backup.txt b/doc/server/admin/backup.txt
new file mode 100644
index 000000000..0c4758bda
--- /dev/null
+++ b/doc/server/admin/backup.txt
@@ -0,0 +1,17 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-backup-index:
+
+backup
+======
+
+.. _Samples repository: https://github.com/solj/bcfg2-repo
+
+Create an archive of the whole Bcfg2 :term:`repository`. The archive is stored
+directly in your Bcfg2 repository (e.g. ``/var/lib/bcfg2/``) and named with
+the current date and time::
+
+ bcfg2-admin backup
+
+A backup is recommanded before you start using the `Samples repository`_ of
+Bcfg2.
diff --git a/doc/server/admin/bundle.txt b/doc/server/admin/bundle.txt
new file mode 100644
index 000000000..101666bb9
--- /dev/null
+++ b/doc/server/admin/bundle.txt
@@ -0,0 +1,30 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-bundle:
+
+bundle
+======
+
+For a list of all available xml bundles use ``list-xml``. ``list-genshi``
+will list all available genshi bundles.::
+
+ # bcfg2-admin bundle list-xml
+ # bcfg2-admin bundle list-genshi
+
+``show`` provides an interactive dialog to get details about the available
+bundles.::
+
+ # bcfg2-admin bundle show
+ Available bundles (Number of bundles: 4)
+ ----------------------------------------
+ [0] motd.xml
+ [1] snmpd.xml
+ [2] bcfg2.xml
+ [3] ntp.xml
+ Enter the line number of a bundle for details: 3
+ Details for the "ntp" bundle:
+ Package: xntp
+ Path: /etc/sysconfig/xntp
+ Path: /etc/sysconfig/clock
+ Path: /etc/ntp.conf
+ Service: xntpd
diff --git a/doc/server/admin/client.txt b/doc/server/admin/client.txt
new file mode 100644
index 000000000..02b46bda1
--- /dev/null
+++ b/doc/server/admin/client.txt
@@ -0,0 +1,31 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-client:
+
+client
+======
+
+Create, delete, list, or modify client entries. ::
+
+ bcfg2-admin client add <client> attr1=val1 attr2=val2
+
+Allowed attributes are *profile*, *uuid*, *password*, *location*, *secure*,
+and *address*.
+
+A full example is shown below::
+
+ bcfg2-admin client add laptop02.example.com profile="basic"
+
+For more details please refer to the
+:ref:`Metadata section <server-plugins-grouping-metadata>`.
+
+With ``list`` the file ``clients.xml`` is parsed and all entries are shown::
+
+ bcfg2-admin client list
+ server01.example.com
+ laptop02.example.com
+
+This is useful for a quick check after adding an entry. If you want more
+in-depth information about a client, ``bcfg2-info clients`` can provide
+that. Please refer to the :ref:`bcfg2-info <server-bcfg2-info>`
+section for further details.
diff --git a/doc/server/admin/compare.txt b/doc/server/admin/compare.txt
new file mode 100644
index 000000000..6a770055e
--- /dev/null
+++ b/doc/server/admin/compare.txt
@@ -0,0 +1,16 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-compare:
+
+compare
+=======
+
+Determine differences between files or directories of client
+specification instances.::
+
+ bcfg2-admin compare <file1> <file2>
+
+If you want to compare two directories recursively then use ``-r`` as an
+option. ::
+
+ bcfg2-admin compare -r <dir1> <dir2>
diff --git a/doc/server/admin/index.txt b/doc/server/admin/index.txt
index e850d9df0..ee03cedda 100644
--- a/doc/server/admin/index.txt
+++ b/doc/server/admin/index.txt
@@ -7,82 +7,24 @@ Admin
=====
The ``bcfg2-admin`` command provides you an interface which allows you
-to interact with your Bcfg2 repository in an administrative fashion. To
+to interact with your Bcfg2 :term:`repository` in an administrative fashion. To
get started, run ``bcfg2-admin help``. You will be presented with a list
of different *modes* which each provide various administrative
functionality. Available modes are listed below.
-FIXME: Need examples for each command listed below.
-
-client
-======
-
-Create, delete, or modify client entries.
-
-compare
-=======
-
-Determine differences between files or directories of client
-specification instances.
-
-init
-====
-
-Interactively initialize a new repository.
-
-minestruct
-==========
-
-Extract extra entry lists from statistics.
-
-perf
-====
-
-Query server for performance data.
-
-pull
-====
-
-Integrate configuration information from clients into the server
-repository.
-
-query
-=====
-
-Query clients.
-
-The default result format is suitable for consumption by `pdsh`_.
-This example queries the server for all clients in the *ubuntu* group::
-
- bcfg2-admin query g=ubuntu
-
-.. _pdsh: http://sourceforge.net/projects/pdsh/
-
-snapshots
-=========
-
-Interact with the Snapshots system.
-
-tidy
-====
-
-Clean up useless files in the repo.
-
-viz
-===
-
-Produce graphviz diagrams of metadata structures.
-
-The following command will produce a graphviz image which includes hosts,
-bundles, and a key::
-
- bcfg2-admin viz -H -b -k -o ~/bcfg2.png
-
-.. note:: The graphviz package available via DAG/RPMforge has been known
- to have dependency issues. We recommend installing the package
- from EPEL.
-
-xcmd
-====
-
-XML-RPC Command Interface.
+.. toctree::
+ :maxdepth: 1
+
+ backup
+ bundle
+ client
+ compare
+ init
+ minestruct
+ perf
+ pull
+ query
+ snapshots
+ tidy
+ viz
+ xcmd
diff --git a/doc/server/admin/init.txt b/doc/server/admin/init.txt
new file mode 100644
index 000000000..0e8b3afd3
--- /dev/null
+++ b/doc/server/admin/init.txt
@@ -0,0 +1,47 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-init:
+
+init
+====
+
+Interactively initialize a new repository. Most values are automatically
+detected or a default value is provided. ::
+
+ bcfg2-admin init
+ Store bcfg2 configuration in [/etc/bcfg2.conf]:
+ Location of bcfg2 repository [/var/lib/bcfg2]:
+ Input password used for communication verification (without echoing; leave blank for a random):
+ What is the server's hostname [conf01.example.com]:
+ Input the server location [https://conf01.example.com:6789]:
+ Input base Operating System for clients:
+ 1: Red Hat/Fedora/RHEL/RHAS/Centos
+ 2: SUSE/SLES
+ 3: Mandrake
+ 4: Debian
+ 5: Ubuntu
+ 6: Gentoo
+ 7: FreeBSD
+ : 1
+
+ Generating a 2048 bit RSA private key
+ .....................+++
+ .....................+++
+ writing new private key to '/etc/bcfg2.key'
+ -----
+ Signature ok
+ subject=/C=US/ST=Illinois/L=Argonne/CN=conf01.example.com
+ Getting Private key
+
+A toplevel repository structure was created under the provided path. ::
+
+ /var/lib/bcfg2
+ |-- Base
+ |-- Bundler
+ |-- Cfg
+ |-- etc
+ |-- Metadata
+ |-- Pkgmgr
+ |-- Rules
+ `-- SSHbase
+
diff --git a/doc/server/admin/minestruct.txt b/doc/server/admin/minestruct.txt
new file mode 100644
index 000000000..d1de72426
--- /dev/null
+++ b/doc/server/admin/minestruct.txt
@@ -0,0 +1,14 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-minestruct:
+
+minestruct
+==========
+
+Extract extra entry lists from statistics.::
+
+ bcfg2-admin minestruct <client> [-f xml-file] [-g groups]
+
+Hierarchy of groups in which to place the extra entries in can be
+determined with ``-g <groups>``. The ``-f <xml-output-file>`` option
+specifies the xml file in which to write the extra entries.
diff --git a/doc/server/admin/perf.txt b/doc/server/admin/perf.txt
new file mode 100644
index 000000000..9a126ec71
--- /dev/null
+++ b/doc/server/admin/perf.txt
@@ -0,0 +1,18 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-perf:
+
+perf
+====
+
+Query server for performance data.::
+
+ bcfg2-admin perf
+ ================ ========== ========== ========== =======
+ Name Min Max Mean Count
+ ================ ========== ========== ========== =======
+ RecvStats 0.000378 0.001716 0.001367 5
+ GetConfig 0.018624 0.039495 0.023589 5
+ component_lock 0.000002 0.000057 0.000016 20
+ GetProbes 0.000523 0.000666 0.000591 5
+ RecvProbeData 0.002260 0.004550 0.002979
diff --git a/doc/server/admin/pull.txt b/doc/server/admin/pull.txt
new file mode 100644
index 000000000..e19485d53
--- /dev/null
+++ b/doc/server/admin/pull.txt
@@ -0,0 +1,24 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-pull:
+
+pull
+====
+
+Integrate configuration information from clients into the server
+repository. ::
+
+ bcfg2-admin pull [-v] [-f][-I] [-s] <client> <entry type> <entry name>
+
+The following options are available:
+
+
+``-v`` verbose
+``-f`` force
+``-I`` interactive
+``-s`` stdin
+
+.. FIXME: No example yet
+.. A full example is shown below. ::
+
+.. bcfg2-admin pull
diff --git a/doc/server/admin/query.txt b/doc/server/admin/query.txt
new file mode 100644
index 000000000..65851a43d
--- /dev/null
+++ b/doc/server/admin/query.txt
@@ -0,0 +1,15 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-query:
+
+query
+=====
+
+Query clients.
+
+The default result format is suitable for consumption by `pdsh`_.
+This example queries the server for all clients in the *ubuntu* group::
+
+ bcfg2-admin query g=ubuntu
+
+.. _pdsh: http://sourceforge.net/projects/pdsh/
diff --git a/doc/server/admin/snapshots.txt b/doc/server/admin/snapshots.txt
new file mode 100644
index 000000000..25a7286c2
--- /dev/null
+++ b/doc/server/admin/snapshots.txt
@@ -0,0 +1,8 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-snapshots:
+
+snapshots
+=========
+
+Interact with the Snapshots system.
diff --git a/doc/server/admin/tidy.txt b/doc/server/admin/tidy.txt
new file mode 100644
index 000000000..816d6cdb3
--- /dev/null
+++ b/doc/server/admin/tidy.txt
@@ -0,0 +1,8 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-tidy:
+
+tidy
+====
+
+Clean up useless files in the repo.
diff --git a/doc/server/admin/viz.txt b/doc/server/admin/viz.txt
new file mode 100644
index 000000000..1e7712ef9
--- /dev/null
+++ b/doc/server/admin/viz.txt
@@ -0,0 +1,18 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-viz:
+
+viz
+===
+
+Produce graphviz diagrams of metadata structures. Make sure that the
+graphviz package is installed.
+
+The following command will produce a graphviz image which includes hosts,
+bundles, and a key::
+
+ bcfg2-admin viz -H -b -k -o ~/bcfg2.png
+
+.. note:: The graphviz package available via DAG/RPMforge has been known
+ to have dependency issues. We recommend installing the package
+ from EPEL.
diff --git a/doc/server/admin/xcmd.txt b/doc/server/admin/xcmd.txt
new file mode 100644
index 000000000..fc40f1243
--- /dev/null
+++ b/doc/server/admin/xcmd.txt
@@ -0,0 +1,27 @@
+.. -*- mode: rst -*-
+
+.. _server-admin-xcmd:
+
+xcmd
+====
+
+XML-RPC Command Interface.::
+
+ xcmd <xmlrpc method> <optional arguments>
+
+For debbuging the following command can help::
+
+ bcfg2-admin xcmd Metadata.toggle_debug
+
+Those two examples can alos be found in the
+:ref:`Package section <server-plugins-generators-packages>`.
+
+To rebuild the packages plugin cache::
+
+ bcfg2-admin xcmd Packages.Refresh
+
+To perform a soft reload to reread the configuration file and
+download only missing sources.::
+
+ bcfg2-admin xcmd Packages.Reload
+
diff --git a/doc/appendix/guides/using-bcfg2-info.txt b/doc/server/bcfg2-info.txt
index b2354652f..35d176e96 100644
--- a/doc/appendix/guides/using-bcfg2-info.txt
+++ b/doc/server/bcfg2-info.txt
@@ -1,6 +1,6 @@
.. -*- mode: rst -*-
-.. _appendix-guides-using_bcfg2_info:
+.. _server-bcfg2-info:
================
Using bcfg2-info
diff --git a/doc/server/index.txt b/doc/server/index.txt
index 0de02c400..9c427a0f4 100644
--- a/doc/server/index.txt
+++ b/doc/server/index.txt
@@ -6,6 +6,19 @@
The Bcfg2 Server
================
+The Bcfg2 server is responsible for taking a comprehensive infrastructure
+description and turning it into a series of configuration specifications
+for particular clients. It also manages probed data and tracks statistics
+for clients.
+
+The Bcfg2 server takes information from two sources when generating client
+configuration specifications. The first is a pool of metadata that describes
+clients as members of an aspect-based classing system. That is, clients are
+defined in terms of aspects of their behavior. The other is a file system
+repository that contains mappings from metadata to literal configuration.
+These are combined to form the literal configuration specifications for
+clients.
+
.. toctree::
:maxdepth: 2
@@ -14,3 +27,4 @@ The Bcfg2 Server
configurationentries
info
snapshots/index
+ bcfg2-info
diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt
index fc452eb2f..071d4239d 100644
--- a/doc/server/plugins/grouping/metadata.txt
+++ b/doc/server/plugins/grouping/metadata.txt
@@ -10,8 +10,8 @@ The metadata mechanism has two types of information, client metadata and
group metadata. The client metadata describes which top level group a
client is associated with.The group metadata describes groups in terms
of what bundles and other groups they include. Each aspect grouping
-and clients' memberships are reflected in the Metadata/groups.xml and
-Metadata/clients.xml files, respectively.
+and clients' memberships are reflected in the ``Metadata/groups.xml`` and
+``Metadata/clients.xml`` files, respectively.
Usage of Groups in Metadata
===========================
@@ -22,13 +22,13 @@ groups. Client membership of all other groups is by those groups being
associated with the profile or public groups. This file can be indirectly
modified from clients through use of the -p flag to bcfg2.
-Clients are associated with profile groups in Metadata/clients.xml as
+Clients are associated with profile groups in ``Metadata/clients.xml`` as
shown below.
Metadata/clients.xml
====================
-The Metadata/clients.xml file contains the mappings of Profile Groups
+The ``Metadata/clients.xml`` file contains the mappings of Profile Groups
to clients. The file is just a series of <Client /> tags, each of which
describe one host. A sample file is below:
@@ -58,7 +58,7 @@ The Clients tag has the following possible attributes:
Client Tag
----------
-Each entry in clients.xml **must** have the following properties:
+Each entry in ``clients.xml`` **must** have the following properties:
+---------+---------------------------------------+--------+
| Name | Description | Values |
generated by cgit v1.2.3-1-g7c22 (git 2.25.1) at 2024-07-20 23:17:44 +0000