From 477c0fc85218cba12597cf3daf7728b127b0fd64 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Wed, 8 Dec 2010 19:43:54 -0600 Subject: doc: Finish merging remaining documentation updates Signed-off-by: Sol Jerome --- doc/help/faq/client.txt | 16 ++++ doc/help/faq/general.txt | 56 +++++++++++++ doc/help/faq/index.txt | 17 ++++ doc/help/index.txt | 42 ++++++++++ doc/help/irc.txt | 45 +++++++++++ doc/help/mailinglist.txt | 24 ++++++ doc/help/troubleshooting.txt | 184 +++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 384 insertions(+) create mode 100644 doc/help/faq/client.txt create mode 100644 doc/help/faq/general.txt create mode 100644 doc/help/faq/index.txt create mode 100644 doc/help/index.txt create mode 100644 doc/help/irc.txt create mode 100644 doc/help/mailinglist.txt create mode 100644 doc/help/troubleshooting.txt (limited to 'doc/help') diff --git a/doc/help/faq/client.txt b/doc/help/faq/client.txt new file mode 100644 index 000000000..8eb04e620 --- /dev/null +++ b/doc/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/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 +`_, 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 ` -- 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 `. +* 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 + +
+ + +
+ in the timespan + + (yyyymmdd-yyyymmdd) +

Options:
+
+
+

+ +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 + +
+ + + +
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 +`_ 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 - Build a config file for a client +* showentries - Build the abstract configuration (list + of entries) for a client +* build - 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 : | | is not fully | | +| cannot verify | | specified by the | | +| | | server, so no | | +| | | verification can be | | +| | | performed. | | ++------------------------------+----------+---------------------+--------------+ +| Incomplete information for | Client | The described entry | [1]_ | +| entry : | | 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 | | +| : | | 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]_ | +| | | 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 | | unable to read and | | +| | | process the ssl key.| | ++------------------------------+----------+---------------------+--------------+ +| Failed to read file | Server | The server failed | [7]_ | +| | | to read the | | +| | | specified file | | ++------------------------------+----------+---------------------+--------------+ +| Failed to parse file | Server | The server failed | [8]_ | +| | | to parse the | | +| | | specified XML file | | ++------------------------------+----------+---------------------+--------------+ +| Client metadata resolution | Server | The server cannot | [9]_ | +| error for | | 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 +` 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. -- cgit v1.2.3-1-g7c22