diff options
Diffstat (limited to 'doc/getting_help/troubleshooting.txt')
| -rw-r--r-- | doc/getting_help/troubleshooting.txt | 184 |
1 files changed, 0 insertions, 184 deletions
diff --git a/doc/getting_help/troubleshooting.txt b/doc/getting_help/troubleshooting.txt deleted file mode 100644 index cce9c3d78..000000000 --- a/doc/getting_help/troubleshooting.txt +++ /dev/null @@ -1,184 +0,0 @@ -.. -*- mode: rst -*- - -.. _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. |