Merge remote branch 'upstream/master'

7 files changed, 394 insertions, 0 deletions

diff --git a/doc/help/faq/client.txt b/doc/help/faq/client.txt
new file mode 100644
index 000000000..746b0201d
--- /dev/null
+++ b/doc/help/faq/client.txt
@@ -0,0 +1,26 @@
+.. -*- mode: rst -*-
+
+.. _faq-client:
+
+FAQ: Client
+===========
+
+**No ca is specified. Cannot authenticate the server with SSL.**
+
+This means that the client does not have a copy of the CA for the server,
+so it can't verify that it is talking to the right server. To fix this
+issue, copy ``/etc/bcfg2.crt`` from the server to ``/etc/bcfg2.ca``
+on the client. Then add the following on the client.::
+
+    [communication]
+    ca = /etc/bcfg2.ca
+
+**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/help/faq/general.txt b/doc/help/faq/general.txt
new file mode 100644
index 000000000..0534e72d2
--- /dev/null
+++ b/doc/help/faq/general.txt
@@ -0,0 +1,56 @@
+.. -*- mode: rst -*-
+
+.. _faq-general:
+
+FAQ: General
+============
+
+**What does Bcfg2 stand for?**
+
+Initially, Bcfg stood for the bundle configuration system. Bcfg2 is the
+second major revision. At this point, the acronym is meaningless, but
+the name has stuck. Luckily, Bcfg2 googles better than Bcfg does. No,
+seriously. Try it. All I know is that I have no interest in a billion
+cubic feet of gas.
+
+**What architectures does Bcfg2 support?**
+
+Bcfg2 should run on any POSIX compatible operating system, however direct
+support for an operating system's package and service formats are limited
+by the currently available :ref:`client-tools-index` (although new client
+tools are pretty easy to add). The following is an incomplete but more
+exact list of platforms on which Bcfg2 works.
+
+* GNU/Linux deb based distros
+* GNU/Linux rpm based distros
+* Solaris pkg based
+* Gentoo portage based
+* OSX (POSIX/launchd support)
+
+**What pre-requisites are needed to run Bcfg2?**
+
+Please visit the :ref:`prerequisites` section in the manual.
+
+**Why won't bcfg2-server start?**
+
+If your server doesn't seem to be starting and you see no error
+messages in your server logs, try running it in the foreground to
+see why.
+
+**Why am I getting a traceback?**
+
+If you get a traceback, please let us know. You can file a `ticket
+<https://trac.mcs.anl.gov/projects/bcfg2/newticket>`_, send the traceback
+to the :ref:`help-mailinglist`, or hop on the :ref:`help-irc` and let
+us know.
+
+**Where are the server log messages?**
+
+The bcfg2-server process logs to syslog facility LOG_DAEMON. The server produces a series of messages upon a variety of events and errors.
+
+**Is there a way to check if all repository XML files conform to schemas?**
+
+Bcfg2 comes with XML schemas describing all of the XML formats used in
+the server repository. A validation command ``bcfg2-repo-validate`` is
+included with the source distribution and all packages. Run it with
+the ``-v`` flag to see each file and the results if its validation.
diff --git a/doc/help/faq/index.txt b/doc/help/faq/index.txt
new file mode 100644
index 000000000..ee418d84d
--- /dev/null
+++ b/doc/help/faq/index.txt
@@ -0,0 +1,17 @@
+.. -*- mode: rst -*-
+
+.. _faq-index:
+
+===
+FAQ
+===
+
+The Frequently Asked Questions (FAQ) answers the most common questions
+about Bcfg2.  At the moment the FAQ is splitted into a general
+and a client specfic section.
+
+.. toctree::
+   :maxdepth: 2
+
+   general
+   client
diff --git a/doc/help/index.txt b/doc/help/index.txt
new file mode 100644
index 000000000..63c2ca350
--- /dev/null
+++ b/doc/help/index.txt
@@ -0,0 +1,42 @@
+.. -*- mode: rst -*-
+
+.. _help-index:
+
+=======================
+Getting Help with Bcfg2
+=======================
+
+Having trouble? We'd like to help!
+
+There are several ways to get in touch with the Bcfg2 community.
+
+* Try the :ref:`FAQ <faq-index>` -- it's got answers to many common
+  questions.
+* Check the :ref:`help-troubleshooting` page to see if you can narrow
+  down the cause of your issue.
+* Looking for specific information? Try the :ref:`genindex`,
+  :ref:`modindex`, or the :ref:`detailed table of contents <contents>`.
+* Search for information in the :ref:`help-mailinglist`.
+* Visit our :ref:`help-irc`, or search the `IRC logs`_.
+
+Note that the IRC channel tends to be much busier than the mailing
+list; use whichever seems most appropriate for your query, but don't
+let the lack of mailing list activity make you think the project isn't
+active.
+
+.. _IRC logs: http://colabti.org/irclogger/irclogger_logs/bcfg2
+.. _Bcfg2 mailing list archives: http://trac.mcs.anl.gov/projects/bcfg2/wiki/MailingList
+.. _Trac ticket tracker: http://trac.mcs.anl.gov/projects/bcfg2/wiki
+
+Report A Bug
+============
+
+Report bugs with Bcfg2 on the `Trac ticket tracker`_.
+
+.. toctree::
+   :hidden:
+
+   mailinglist
+   irc
+   faq/index
+   troubleshooting
diff --git a/doc/help/irc.txt b/doc/help/irc.txt
new file mode 100644
index 000000000..303c39e68
--- /dev/null
+++ b/doc/help/irc.txt
@@ -0,0 +1,45 @@
+.. -*- mode: rst -*-
+
+.. _Freenode: http://chat.freenode.net
+.. _#bcfg2: irc://chat.freenode.net/bcfg2
+
+.. _help-irc:
+
+===========
+IRC Channel
+===========
+
+The Bcfg2 IRC channel is `#bcfg2`_ on `Freenode`_. It is home to both
+support and development discussions. If you have a question, suggestion,
+or just want to know about Bcfg2, please drop in and say hi.
+
+Archives are available at: http://colabti.org/irclogger/irclogger_logs/bcfg2
+
+.. raw:: html
+
+    <form method="get" action="http://colabti.org/irclogger/irclogger_log_search/bcfg2">
+      <input type=text name=search value='' size=48>
+      <input type=submit value="Search #bcfg2 irc logs">
+      <input type=hidden name=action value=search> <br>
+      in the timespan
+      <input type=text name=timespan value='' size=17>
+      (yyyymmdd-yyyymmdd)
+    <p>Options:<br>
+     <label><input type=checkbox name=nick value="checked">Search in the nick field</label><br>
+     <label><input type=checkbox name=text checked value="checked">Search in the text field</label><br>
+    </form>
+
+Administrative Note
+===================
+
+If the IRC logging stops working for a while, coordinate on #bcfg2 and
+then bug **feb** on #irclogger (freenode), and stick around on that
+channel until you get an answer (**feb** is great, but busy and in a
+non-US time zone). Actually as long as **ilogger2** is logged in you
+should be okay (**feb** looks at the logs).
+
+If you have private logs for the period of time **ilogger2** was off the
+channel, you can convert them to the will incorporate them into the online
+logs. Be sure to strip out any private messages in your logs first :-)
+
+.. _format shown here: http://colabti.org/irclogger/irclogger_log/bcfg2?date=2008-03-21,Fri;raw=on
diff --git a/doc/help/mailinglist.txt b/doc/help/mailinglist.txt
new file mode 100644
index 000000000..c77caa0c4
--- /dev/null
+++ b/doc/help/mailinglist.txt
@@ -0,0 +1,24 @@
+.. -*- mode: rst -*-
+
+.. _help-mailinglist:
+
+============
+Mailing List
+============
+
+To subscribe to the mailing list for Bcfg2 please visit the `bcfg-dev
+mailman page`_
+
+`Searchable archives`_ are available from Gmane. You can also read the
+mailing list from any NNTP client via Gmane.
+
+.. _bcfg-dev mailman page: https://lists.mcs.anl.gov/mailman/listinfo/bcfg-dev
+.. _Searchable archives: http://dir.gmane.org/gmane.comp.sysutils.bcfg2.devel
+
+.. raw:: html
+
+    <form method="get" action="http://search.gmane.org/">
+    <input type="text" name="query">
+    <input type="hidden" name="group" value="gmane.comp.sysutils.bcfg2.devel">
+    <input type="submit" value="Search gmane.comp.sysutils.bcfg2.devel">
+    </form>
diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt
new file mode 100644
index 000000000..0892587aa
--- /dev/null
+++ b/doc/help/troubleshooting.txt
@@ -0,0 +1,184 @@
+.. -*- mode: rst -*-
+
+.. _help-troubleshooting:
+
+===============
+Troubleshooting
+===============
+
+From time to time, Bcfg2 produces results that the user finds surprising.
+This can happen either due to bugs or user error. This page describes
+several techniques to gain visibility into the bcfg2 client and server
+and understand what is going on.
+
+
+Figure out if error is client or server side
+============================================
+
+* Cache a copy of the client configuration using ``bcfg2 -qnc /tmp/config.xml``
+* Look in the file and search for the entry of interest
+* If it looks correct, then there is a client issue
+* If not, it is time to inspect things on the server
+
+This file contains all aspects of client configuration. It is structured
+as a series of bundles and base entries.
+
+.. note::
+
+    Most often the entry is not correct and the issue lies in
+    the specification.
+
+Review server log messages
+==========================
+
+The bcfg2-server process logs to syslog facility LOG_DAEMON. The server
+produces a series of messages upon a variety of events and errors.
+
+Check if all repository XML files conform to schemas
+====================================================
+
+Bcfg2 comes with XML schemas describing all of the XML formats used in
+the server repository. A validation command ``bcfg2-repo-validate`` is
+included with the source distribution and all packages. Run it with the
+-v flag to see each file and the results if its validation.
+
+If the bcfg2 server is not reflecting recent changes, try restarting the bcfg2-server process
+=============================================================================================
+
+If this fixes the problem, it is either a bug in the
+underlying file monitoring system (fam or gamin) or a bug in
+Bcfg2's file monitoring code. In either case, file a `ticket
+<https://trac.mcs.anl.gov/projects/bcfg2/newticket>`_ in the tracking
+system. In the ticket, include:
+
+* filesystem monitoring system (fam or gamin)
+* kernel version (if on linux)
+* if any messages of the form "Handled N events in M
+  seconds" appeared between the modification event and the client
+  configuration generation request appeared in the server log
+* which plugin handled the file in the repostiory (Cfg, Rules, Packages,
+  TCheetah, TGenshi, Metadata)
+* if a touch of the file after the modification causes the problem to
+  go away
+
+bcfg2-info
+==========
+
+Bcfg2 server operations can be simulated using the ``bcfg2-info`` command.
+The command is interactive, and has commands to allow several useful
+operations
+
+* clients - Current client metadata (profile and group) settings
+* groups - Current group metadata values
+* mappings - Configuration entries provided by plugins
+* buildfile <filename> <hostname> - Build a config file for a client
+* showentries <client> <type> - Build the abstract configuration (list
+  of entries) for a client
+* build <hostname> <output-file> - Build the complete configuration
+  for a client
+
+Type `help` in bcfg2-info for more information.
+
+Error Messages
+==============
+
+This page describes error messages produced by Bcfg2 and steps that can
+be taken to remedy them.
+
++------------------------------+----------+---------------------+--------------+
+| Error                        | Location | Meaning             | Repair       |
++==============================+==========+=====================+==============+
+| Incomplete information for   | Client   | The described entry | [1]_         |
+| entry <EntryTag>:<EntryName> |          | is not fully        |              |
+| cannot verify                |          | specified by the    |              |
+|                              |          | server, so no       |              |
+|                              |          | verification can be |              |
+|                              |          | performed.          |              |
++------------------------------+----------+---------------------+--------------+
+| Incomplete information for   | Client   | The described entry | [1]_         |
+| entry <EntryTag>:<EntryName> |          | is not fully        |              |
+| cannot install               |          | specified by the    |              |
+|                              |          | server, so no       |              |
+|                              |          | verification can be |              |
+|                              |          | performed.          |              |
++------------------------------+----------+---------------------+--------------+
+| The following entries are    | Client   | The client cannot   | [2]_         |
+| not handled by any tool:     |          | figure out how to   |              |
+| <EntryTag>:<EntryName>       |          | handle this entry.  |              |
++------------------------------+----------+---------------------+--------------+
+| No ca is specified. Cannot   | Client   | The client is       | [3]_         |
+| authenticate the server with |          | unable to verify    |              |
+| SSL.                         |          | the server          |              |
++------------------------------+----------+---------------------+--------------+
+| Failed to bind entry:        | Server   | The server was      | [4]_         |
+| <EntryTag> <EntryName>       |          | unable to find a    |              |
+|                              |          | suitable version of |              |
+|                              |          | entry for client.   |              |
++------------------------------+----------+---------------------+--------------+
+| Failed to bind to socket     | Server   | The server was      | [5]_         |
+|                              |          | unable to bind to   |              |
+|                              |          | the tcp server      |              |
+|                              |          | socket.             |              |
++------------------------------+----------+---------------------+--------------+
+| Failed to load               | Server   | The server was      | [6]_         |
+| ssl key <path>               |          | unable to read and  |              |
+|                              |          | process the ssl key.|              |
++------------------------------+----------+---------------------+--------------+
+| Failed to read file <path>   | Server   | The server failed   | [7]_         |
+|                              |          | to read the         |              |
+|                              |          | specified file      |              |
++------------------------------+----------+---------------------+--------------+
+| Failed to parse file <path>  | Server   | The server failed   | [8]_         |
+|                              |          | to parse the        |              |
+|                              |          | specified XML file  |              |
++------------------------------+----------+---------------------+--------------+
+| Client metadata resolution   | Server   | The server cannot   | [9]_         |
+| error for <IP>               |          | resolve the client  |              |
+|                              |          | hostname or the     |              |
+|                              |          | client is           |              |
+|                              |          | associated with a   |              |
+|                              |          | non-profile group.  |              |
++------------------------------+----------+---------------------+--------------+
+
+
+.. [1] This entry is not being bound. Ensure that a version of this
+       entry applies to this client.
+.. [2] Add a type to the generator definition for this entry
+.. [3] Copy the Bcfg2 server's CA certificate to the client and specify it
+       using the **ca** option in the [communication] section of
+       ``bcfg2.conf``
+.. [4] This entry is not being bound. Ensure that a version of this
+       entry applies to this client.
+.. [5] Ensure that another instance of the daemon (or any other process)
+       is not listening on the same port.
+.. [6] Ensure that the key is readable by the user running the daemon
+       and that it is well-formed.
+.. [7] Ensure that this file still exists; a frequent cause is the
+       deletion of a temp file.
+.. [8] Ensure that the file is properly formed XML.
+.. [9] Fix hostname resolution for the client or ensure that the profile
+       group is properly setup.
+
+FAQs
+====
+
+Why won't bcfg2-server start?
+-----------------------------
+
+If your server doesn't seem to be starting and you see no error
+messages in your server logs, try running it in the foreground to see
+why.
+
+Why am I getting a traceback?
+-----------------------------
+
+If you get a traceback, please let us know by :ref:`reporting it
+<report-a-bug>` on Trac, via the mailing list, or on IRC. Your best bet
+to get a quick response will be to jump on IRC during the daytime (CST).
+
+What is the most common cause of "The following entries are not handled by any tool"?
+-------------------------------------------------------------------------------------
+
+Often it corresponds to entries that aren't bound by the server (for which
+you'll get error messages on the server). You should try inspecting the
+logs on the server to see what may be the cause.