summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSol Jerome <solj@ices.utexas.edu>2010-10-06 00:17:28 +0000
committerSol Jerome <sol.jerome@gmail.com>2010-10-07 17:14:52 -0500
commit4a544fa1a774c4b6dc96782f4e3f29d5c33d12e3 (patch)
treedfd0374ca5546a5f92590b853393b84b50793d9f
parent4b6e7c559454761fa5516e3a7a0527321741fbf6 (diff)
downloadbcfg2-4a544fa1a774c4b6dc96782f4e3f29d5c33d12e3.tar.gz
bcfg2-4a544fa1a774c4b6dc96782f4e3f29d5c33d12e3.tar.bz2
bcfg2-4a544fa1a774c4b6dc96782f4e3f29d5c33d12e3.zip
doc: Add troubleshooting document from trac
Signed-off-by: Sol Jerome <sol.jerome@gmail.com> git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@6086 ce84e21b-d406-0410-9b95-82705330c041
-rw-r--r--doc/contents.txt3
-rw-r--r--doc/troubleshooting.txt184
-rw-r--r--doc/unsorted/index.txt1
3 files changed, 186 insertions, 2 deletions
diff --git a/doc/contents.txt b/doc/contents.txt
index b2d96923f..40128175e 100644
--- a/doc/contents.txt
+++ b/doc/contents.txt
@@ -17,7 +17,8 @@ Welcome to Bcfg2's documentation!
getting_started/index
server/index
client/index
- gettinghelp
+ troubleshooting
+ help/index
bcfg2.conf-options
architecture
development/index
diff --git a/doc/troubleshooting.txt b/doc/troubleshooting.txt
new file mode 100644
index 000000000..72c5f6e14
--- /dev/null
+++ b/doc/troubleshooting.txt
@@ -0,0 +1,184 @@
+.. -*- mode: rst -*-
+
+.. _unsorted-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.
diff --git a/doc/unsorted/index.txt b/doc/unsorted/index.txt
index 3ff8e4c70..90e6b1a9d 100644
--- a/doc/unsorted/index.txt
+++ b/doc/unsorted/index.txt
@@ -21,7 +21,6 @@ list below.
* `SchemaEvolution`
* `SecurityDevPlan`
* `ServerSideOverview`
-* `Troubleshooting`
* `UpgradeTesting`
* `VimSnippetSupport`