16 files changed, 308 insertions, 63 deletions
diff --git a/doc/getting_help/error-messages.txt b/doc/getting_help/error-messages.txt
new file mode 100644
index 000000000..72d1f1f40
--- /dev/null
+++ b/doc/getting_help/error-messages.txt
@@ -0,0 +1,45 @@
+.. -*- mode: rst -*-
+
+.. _error-messages:
+
+==============
+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 entry <EntryTag>:<EntryName>; cannot verify    | Client   | The described entry is not fully specified by the server, so no verification can be performed.      | [#f1]_  |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+| Incomplete information for entry <EntryTag>:<EntryName>; cannot install   | Client   | The described entry is not fully specified by the server, so no verification can be performed.      | [#f2]_  |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+| The following entries are not handled by any tool: <EntryTag>:<EntryName> | Client   | The client cannot figure out how to handle this entry.                                              | [#f3]_  |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+| no server x509 fingerprint; no server verification performed!             | Client   | The client is unable to verify the server                                                           | [#f4]_  |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+| Failed to bind entry: <EntryTag> <EntryName>                              | Server   | The server was unable to find a suitable version of entry for client.                               | [#f5]_  |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+| Failed to bind to socket                                                  | Server   | The server was unable to bind to the tcp server socket.                                             | [#f6]_  |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+| Failed to load ssl key <path>                                             | Server   | The server was unable to read and process the ssl key.                                              | [#f7]_  |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+| Failed to read file <path>                                                | Server   | The server failed to read the specified file                                                        | [#f8]_  |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+| Failed to parse file <path>                                               | Server   | The server failed to parse the specified XML file                                                   | [#f9]_  |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+| Client metadata resolution error for <IP>                                 | Server   | The server cannot resolve the client hostname or the client is associated with a non-profile group. | [#f10]_ |
++---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+
+
+.. [#f1] This entry is not being bound. Ensure that a version of this entry applies to this client.
+.. [#f2] This entry is not being bound. Ensure that a version of this entry applies to this client.
+.. [#f3] Add a type to the generator definition for this entry
+.. [#f4] Run bcfg2-admin fingerprint on the server and add it to the client bcfg2.conf as mentioned here
+.. [#f5] This entry is not being bound. Ensure that a version of this entry applies to this client.
+.. [#f6] Ensure that another instance of the daemon (or any other process) is not listening on the same port.
+.. [#f7] Ensure that the key is readable by the user running the daemon and that it is well-formed.
+.. [#f8] Ensure that this file still exists; a frequent cause is the deletion of a temp file.
+.. [#f9] Ensure that the file is properly formed XML.
+.. [#f10] Fix hostname resolution for the client or ensure that the profile group is properly setup.
diff --git a/doc/getting_help/faq/client.txt b/doc/getting_help/faq/client.txt
new file mode 100644
index 000000000..a230a84bb
--- /dev/null
+++ b/doc/getting_help/faq/client.txt
@@ -0,0 +1,16 @@
+.. -*- 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
diff --git a/doc/getting_help/faq/general.txt b/doc/getting_help/faq/general.txt
new file mode 100644
index 000000000..f08bfb7b2
--- /dev/null
+++ b/doc/getting_help/faq/general.txt
@@ -0,0 +1,72 @@
+.. -*- 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:`mailinglist`, or hop on 
+:ref:`ircchannel` and let us know. 
+
+**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.
+
+**How can I figure out if error is client or server side?**
+
+* Cache a copy of the client using ``bcfg2 -c /tmp/config.xml``
+* Search for the entry of interest
+* If it looks correct, then there is a client issue 
+
+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.
+
+**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/getting_help/faq/index.txt b/doc/getting_help/faq/index.txt
new file mode 100644
index 000000000..27aa5303f
--- /dev/null
+++ b/doc/getting_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/getting_help/index.txt b/doc/getting_help/index.txt
index bc713bcbe..308f31df1 100644
--- a/doc/getting_help/index.txt
+++ b/doc/getting_help/index.txt
@@ -1,33 +1,40 @@
 .. -*- mode: rst -*-
 
-.. _help-index:
+.. _gettinghelp-index:
 
-=======================
-Getting Help with Bcfg2
-=======================
+.. _IRC logs: http://colabti.org/irclogger/irclogger_logs/bcfg2
+
+
+Getting Help
+============
 
 Having trouble? We'd like to help!
 
-* Try the :ref:`FAQ <faq-index>` -- it's got answers to many common questions.
-* 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` channel.
+There are several ways to get in touch with the community around Bcfg2.
 
-.. _report-a-bug:
+* Try the :ref:`FAQ <faq-index>` -- it's got answers to many common
+  questions.
 
-Report A Bug
-============
+* Looking for specific information? Try the :ref:`genindex`, 
+  :ref:`modindex`, or the :ref:`detailed table of contents <contents>`.
+
+* Search for information in the :ref:`mailinglist`.
 
-Report bugs with Bcfg2 on the `Trac ticket tracker`_.
+* Ask a question in the :ref:`ircchannel`, or search the `IRC logs`_ 
+  to see if its been asked before.
 
-.. _Bcfg2 mailing list archives: http://trac.mcs.anl.gov/projects/bcfg2/wiki/MailingList
-.. _Trac ticket tracker: http://trac.mcs.anl.gov/projects/bcfg2/wiki
+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.
 
-Other ways to get in touch
-==========================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   irc
+   reporting
    mailinglist
+   ircchannel
+   faq/index
+   error-messages
+   manpages
diff --git a/doc/getting_help/irc.txt b/doc/getting_help/irc.txt
deleted file mode 100644
index 37d2099d3..000000000
--- a/doc/getting_help/irc.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _help-irc:
-
-===
-IRC
-===
-
-The Bcfg2 IRC channel is `#bcfg2 on chat.freenode.net`_. 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.
-
-.. _#bcfg2 on chat.freenode.net: irc://chat.freenode.net/bcfg2
-
-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 `format shown here`_, and **feb**
-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/getting_help/ircchannel.txt b/doc/getting_help/ircchannel.txt
new file mode 100644
index 000000000..b97e5f6a6
--- /dev/null
+++ b/doc/getting_help/ircchannel.txt
@@ -0,0 +1,28 @@
+.. -*- mode: rst -*-
+
+.. _Freenode: http://chat.freenode.net
+.. _#bcfg2: irc://chat.freenode.net/bcfg2
+
+.. _ircchannel:
+
+===========
+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>
diff --git a/doc/getting_help/manpages.txt b/doc/getting_help/manpages.txt
new file mode 100644
index 000000000..14c22a92e
--- /dev/null
+++ b/doc/getting_help/manpages.txt
@@ -0,0 +1,16 @@
+.. -*- mode: rst -*-
+
+.. _manpages:
+
+============
+Manual pages
+============
+
+These are copies of the bcfg2 manual pages created with man2html.
+The most recent versions of these man pages are always in the `man/`
+directory in the source.
+
+.. toctree::
+   :glob:
+
+   manpages/*
diff --git a/doc/getting_help/manpages/bcfg2-admin.txt b/doc/getting_help/manpages/bcfg2-admin.txt
new file mode 100644
index 000000000..4440c7134
--- /dev/null
+++ b/doc/getting_help/manpages/bcfg2-admin.txt
@@ -0,0 +1,11 @@
+.. -*- mode: rst -*-
+
+.. _manpages-bcfg2-admin:
+
+===========
+bcfg2-admin
+===========
+
+The man page of ``bcfg2-admin``. ::
+
+   man bcfg2-admin
diff --git a/doc/getting_help/manpages/bcfg2-build-reports.txt b/doc/getting_help/manpages/bcfg2-build-reports.txt
new file mode 100644
index 000000000..217c25627
--- /dev/null
+++ b/doc/getting_help/manpages/bcfg2-build-reports.txt
@@ -0,0 +1,11 @@
+.. -*- mode: rst -*-
+
+.. _manpages-bcfg2-build-reports:
+
+===================
+bcfg2-build-reports
+===================
+
+The man page of ``bcfg2-build-reports``. ::
+
+   man bcfg2-build-reports
diff --git a/doc/getting_help/manpages/bcfg2-conf.txt b/doc/getting_help/manpages/bcfg2-conf.txt
new file mode 100644
index 000000000..623521a67
--- /dev/null
+++ b/doc/getting_help/manpages/bcfg2-conf.txt
@@ -0,0 +1,11 @@
+.. -*- mode: rst -*-
+
+.. _manpages-bcfg2.conf:
+
+==========
+bcfg2.conf
+==========
+
+The man page of ``bcfg2.conf``. ::
+
+   man bcfg2.conf
diff --git a/doc/getting_help/manpages/bcfg2-info.txt b/doc/getting_help/manpages/bcfg2-info.txt
new file mode 100644
index 000000000..751905e0b
--- /dev/null
+++ b/doc/getting_help/manpages/bcfg2-info.txt
@@ -0,0 +1,11 @@
+.. -*- mode: rst -*-
+
+.. _manpages-bcfg2-info:
+
+==========
+bcfg2-info
+==========
+
+The man page of ``bcfg2-info``. ::
+
+   man bcfg2-info
diff --git a/doc/getting_help/manpages/bcfg2-repo-validate.txt b/doc/getting_help/manpages/bcfg2-repo-validate.txt
new file mode 100644
index 000000000..b13bd928b
--- /dev/null
+++ b/doc/getting_help/manpages/bcfg2-repo-validate.txt
@@ -0,0 +1,11 @@
+.. -*- mode: rst -*-
+
+.. _manpages-bcfg2-repo-validate:
+
+===================
+bcfg2-repo-validate
+===================
+
+The man page of ``bcfg2-repo-validate``. ::
+
+   man bcfg2-repo-validate
diff --git a/doc/getting_help/manpages/bcfg2-server.txt b/doc/getting_help/manpages/bcfg2-server.txt
new file mode 100644
index 000000000..27002789e
--- /dev/null
+++ b/doc/getting_help/manpages/bcfg2-server.txt
@@ -0,0 +1,11 @@
+.. -*- mode: rst -*-
+
+.. _manpages-bcfg2-server:
+
+============
+bcfg2-server
+============
+
+The man page of ``bcfg2-server``. ::
+
+   man bcfg2-server
diff --git a/doc/getting_help/manpages/bcfg2.txt b/doc/getting_help/manpages/bcfg2.txt
new file mode 100644
index 000000000..4e93ab449
--- /dev/null
+++ b/doc/getting_help/manpages/bcfg2.txt
@@ -0,0 +1,11 @@
+.. -*- mode: rst -*-
+
+.. _manpages-bcfg2:
+
+=====
+bcfg2
+=====
+
+The man page of bcfg2. ::
+
+   man bcfg2
diff --git a/doc/getting_help/reporting.txt b/doc/getting_help/reporting.txt
new file mode 100644
index 000000000..cd53b1206
--- /dev/null
+++ b/doc/getting_help/reporting.txt
@@ -0,0 +1,12 @@
+.. -*- mode: rst -*-
+
+.. _reporting:
+
+.. _tracker: http://trac.mcs.anl.gov/projects/bcfg2/wiki
+
+==============
+Reporting bugs
+==============
+
+Report bugs with Bcfg2 in our `tracker`_.
+