diff options
Diffstat (limited to 'doc/help/troubleshooting.txt')
| -rw-r--r-- | doc/help/troubleshooting.txt | 184 |
1 files changed, 184 insertions, 0 deletions
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. |