diff options
author | Narayan Desai <desai@mcs.anl.gov> | 2010-12-08 21:38:29 -0600 |
---|---|---|
committer | Narayan Desai <desai@mcs.anl.gov> | 2010-12-08 21:38:29 -0600 |
commit | dfcabfcbfc6970c526c80e6f688744966e532c66 (patch) | |
tree | 7994cc2d40fcb4bbc4e3c3a508d8f4c26a13ce30 /doc/help | |
parent | 19dd6674fe58f3f83a5fa85d2f8ebacf2bfd5e13 (diff) | |
parent | d08c7ba3ca269639edd8e7696558c74bc06fb487 (diff) | |
download | bcfg2-dfcabfcbfc6970c526c80e6f688744966e532c66.tar.gz bcfg2-dfcabfcbfc6970c526c80e6f688744966e532c66.tar.bz2 bcfg2-dfcabfcbfc6970c526c80e6f688744966e532c66.zip |
Merge branch 'master' of git.mcs.anl.gov:bcfg2
Diffstat (limited to 'doc/help')
-rw-r--r-- | doc/help/faq/client.txt | 16 | ||||
-rw-r--r-- | doc/help/faq/general.txt | 56 | ||||
-rw-r--r-- | doc/help/faq/index.txt | 17 | ||||
-rw-r--r-- | doc/help/index.txt | 33 | ||||
-rw-r--r-- | doc/help/irc.txt | 24 | ||||
-rw-r--r-- | doc/help/troubleshooting.txt | 184 |
6 files changed, 306 insertions, 24 deletions
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 +<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 index bc713bcbe..63c2ca350 100644 --- a/doc/help/index.txt +++ b/doc/help/index.txt @@ -8,26 +8,35 @@ Getting Help with Bcfg2 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>`. +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` channel. +* Visit our :ref:`help-irc`, or search the `IRC logs`_. -.. _report-a-bug: +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`_. -.. _Bcfg2 mailing list archives: http://trac.mcs.anl.gov/projects/bcfg2/wiki/MailingList -.. _Trac ticket tracker: http://trac.mcs.anl.gov/projects/bcfg2/wiki - -Other ways to get in touch -========================== - .. toctree:: - :maxdepth: 2 + :hidden: - irc mailinglist + irc + faq/index + troubleshooting diff --git a/doc/help/irc.txt b/doc/help/irc.txt index 37d2099d3..303c39e68 100644 --- a/doc/help/irc.txt +++ b/doc/help/irc.txt @@ -1,18 +1,19 @@ .. -*- mode: rst -*- -.. _help-irc: +.. _Freenode: http://chat.freenode.net +.. _#bcfg2: irc://chat.freenode.net/bcfg2 -=== -IRC -=== +.. _help-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. +=========== +IRC Channel +=========== -.. _#bcfg2 on chat.freenode.net: irc://chat.freenode.net/bcfg2 +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. +Archives are available at: http://colabti.org/irclogger/irclogger_logs/bcfg2 .. raw:: html @@ -38,8 +39,7 @@ 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 :-) +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/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. |