diff options
Diffstat (limited to 'doc/getting_help')
| -rw-r--r-- | doc/getting_help/error-messages.txt | 45 | ||||
| -rw-r--r-- | doc/getting_help/faq/client.txt | 26 | ||||
| -rw-r--r-- | doc/getting_help/faq/general.txt | 72 | ||||
| -rw-r--r-- | doc/getting_help/faq/index.txt | 17 | ||||
| -rw-r--r-- | doc/getting_help/index.txt | 41 | ||||
| -rw-r--r-- | doc/getting_help/ircchannel.txt | 28 | ||||
| -rw-r--r-- | doc/getting_help/mailinglist.txt | 24 | ||||
| -rw-r--r-- | doc/getting_help/manpages.txt | 16 | ||||
| -rw-r--r-- | doc/getting_help/manpages/bcfg2-admin.txt | 11 | ||||
| -rw-r--r-- | doc/getting_help/manpages/bcfg2-build-reports.txt | 11 | ||||
| -rw-r--r-- | doc/getting_help/manpages/bcfg2-conf.txt | 11 | ||||
| -rw-r--r-- | doc/getting_help/manpages/bcfg2-info.txt | 11 | ||||
| -rw-r--r-- | doc/getting_help/manpages/bcfg2-repo-validate.txt | 11 | ||||
| -rw-r--r-- | doc/getting_help/manpages/bcfg2-server.txt | 11 | ||||
| -rw-r--r-- | doc/getting_help/manpages/bcfg2.txt | 11 | ||||
| -rw-r--r-- | doc/getting_help/reporting.txt | 12 | ||||
| -rw-r--r-- | doc/getting_help/troubleshooting.txt | 184 |
17 files changed, 0 insertions, 542 deletions
diff --git a/doc/getting_help/error-messages.txt b/doc/getting_help/error-messages.txt deleted file mode 100644 index 72d1f1f40..000000000 --- a/doc/getting_help/error-messages.txt +++ /dev/null @@ -1,45 +0,0 @@ -.. -*- mode: rst -*- - -.. _error-messages: - -============== -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 entry <EntryTag>:<EntryName>; cannot verify | Client | The described entry is not fully specified by the server, so no verification can be performed. | [#f1]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Incomplete information for entry <EntryTag>:<EntryName>; cannot install | Client | The described entry is not fully specified by the server, so no verification can be performed. | [#f2]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| The following entries are not handled by any tool: <EntryTag>:<EntryName> | Client | The client cannot figure out how to handle this entry. | [#f3]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| no server x509 fingerprint; no server verification performed! | Client | The client is unable to verify the server | [#f4]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to bind entry: <EntryTag> <EntryName> | Server | The server was unable to find a suitable version of entry for client. | [#f5]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to bind to socket | Server | The server was unable to bind to the tcp server socket. | [#f6]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to load ssl key <path> | Server | The server was unable to read and process the ssl key. | [#f7]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to read file <path> | Server | The server failed to read the specified file | [#f8]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to parse file <path> | Server | The server failed to parse the specified XML file | [#f9]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Client metadata resolution error for <IP> | Server | The server cannot resolve the client hostname or the client is associated with a non-profile group. | [#f10]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ - -.. [#f1] This entry is not being bound. Ensure that a version of this entry applies to this client. -.. [#f2] This entry is not being bound. Ensure that a version of this entry applies to this client. -.. [#f3] Add a type to the generator definition for this entry -.. [#f4] Run bcfg2-admin fingerprint on the server and add it to the client bcfg2.conf as mentioned here -.. [#f5] This entry is not being bound. Ensure that a version of this entry applies to this client. -.. [#f6] Ensure that another instance of the daemon (or any other process) is not listening on the same port. -.. [#f7] Ensure that the key is readable by the user running the daemon and that it is well-formed. -.. [#f8] Ensure that this file still exists; a frequent cause is the deletion of a temp file. -.. [#f9] Ensure that the file is properly formed XML. -.. [#f10] Fix hostname resolution for the client or ensure that the profile group is properly setup. diff --git a/doc/getting_help/faq/client.txt b/doc/getting_help/faq/client.txt deleted file mode 100644 index aa9743048..000000000 --- a/doc/getting_help/faq/client.txt +++ /dev/null @@ -1,26 +0,0 @@ -.. -*- 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 - -**Server failure** - -On Fedora 14 and above it can happen that no connection is possible. - - # bcfg2 -vqne - Server failure: Protocol Error: 401 Unauthorized - Failed to download probes from bcfg2 - Server Failure - diff --git a/doc/getting_help/faq/general.txt b/doc/getting_help/faq/general.txt deleted file mode 100644 index f08bfb7b2..000000000 --- a/doc/getting_help/faq/general.txt +++ /dev/null @@ -1,72 +0,0 @@ -.. -*- 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:`mailinglist`, or hop on -:ref:`ircchannel` and let us know. - -**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. - -**How can I figure out if error is client or server side?** - -* Cache a copy of the client using ``bcfg2 -c /tmp/config.xml`` -* Search for the entry of interest -* If it looks correct, then there is a client issue - -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. - -**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/getting_help/faq/index.txt b/doc/getting_help/faq/index.txt deleted file mode 100644 index 27aa5303f..000000000 --- a/doc/getting_help/faq/index.txt +++ /dev/null @@ -1,17 +0,0 @@ -.. -*- 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/getting_help/index.txt b/doc/getting_help/index.txt deleted file mode 100644 index 1060a8f4b..000000000 --- a/doc/getting_help/index.txt +++ /dev/null @@ -1,41 +0,0 @@ -.. -*- mode: rst -*- - -.. _gettinghelp-index: - -.. _IRC logs: http://colabti.org/irclogger/irclogger_logs/bcfg2 - - -Getting Help -============ - -Having trouble? We'd like to help! - -There are several ways to get in touch with the community around Bcfg2. - -* 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>`. - -* Search for information in the :ref:`mailinglist`. - -* Ask a question in the :ref:`ircchannel`, or search the `IRC logs`_ - to see if its been asked before. - -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. - - -.. toctree:: - :maxdepth: 1 - - reporting - mailinglist - ircchannel - faq/index - error-messages - manpages - troubleshooting diff --git a/doc/getting_help/ircchannel.txt b/doc/getting_help/ircchannel.txt deleted file mode 100644 index b97e5f6a6..000000000 --- a/doc/getting_help/ircchannel.txt +++ /dev/null @@ -1,28 +0,0 @@ -.. -*- mode: rst -*- - -.. _Freenode: http://chat.freenode.net -.. _#bcfg2: irc://chat.freenode.net/bcfg2 - -.. _ircchannel: - -=========== -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 - - <form method="get" action="http://colabti.org/irclogger/irclogger_log_search/bcfg2"> - <input type=text name=search value='' size=48> - <input type=submit value="Search #bcfg2 irc logs"> - <input type=hidden name=action value=search> <br> - in the timespan - <input type=text name=timespan value='' size=17> - (yyyymmdd-yyyymmdd) - <p>Options:<br> - <label><input type=checkbox name=nick value="checked">Search in the nick field</label><br> - <label><input type=checkbox name=text checked value="checked">Search in the text field</label><br> - </form> diff --git a/doc/getting_help/mailinglist.txt b/doc/getting_help/mailinglist.txt deleted file mode 100644 index c77caa0c4..000000000 --- a/doc/getting_help/mailinglist.txt +++ /dev/null @@ -1,24 +0,0 @@ -.. -*- 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 - - <form method="get" action="http://search.gmane.org/"> - <input type="text" name="query"> - <input type="hidden" name="group" value="gmane.comp.sysutils.bcfg2.devel"> - <input type="submit" value="Search gmane.comp.sysutils.bcfg2.devel"> - </form> diff --git a/doc/getting_help/manpages.txt b/doc/getting_help/manpages.txt deleted file mode 100644 index 14c22a92e..000000000 --- a/doc/getting_help/manpages.txt +++ /dev/null @@ -1,16 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages: - -============ -Manual pages -============ - -These are copies of the bcfg2 manual pages created with man2html. -The most recent versions of these man pages are always in the `man/` -directory in the source. - -.. toctree:: - :glob: - - manpages/* diff --git a/doc/getting_help/manpages/bcfg2-admin.txt b/doc/getting_help/manpages/bcfg2-admin.txt deleted file mode 100644 index 4440c7134..000000000 --- a/doc/getting_help/manpages/bcfg2-admin.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-admin: - -=========== -bcfg2-admin -=========== - -The man page of ``bcfg2-admin``. :: - - man bcfg2-admin diff --git a/doc/getting_help/manpages/bcfg2-build-reports.txt b/doc/getting_help/manpages/bcfg2-build-reports.txt deleted file mode 100644 index 217c25627..000000000 --- a/doc/getting_help/manpages/bcfg2-build-reports.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-build-reports: - -=================== -bcfg2-build-reports -=================== - -The man page of ``bcfg2-build-reports``. :: - - man bcfg2-build-reports diff --git a/doc/getting_help/manpages/bcfg2-conf.txt b/doc/getting_help/manpages/bcfg2-conf.txt deleted file mode 100644 index 623521a67..000000000 --- a/doc/getting_help/manpages/bcfg2-conf.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2.conf: - -========== -bcfg2.conf -========== - -The man page of ``bcfg2.conf``. :: - - man bcfg2.conf diff --git a/doc/getting_help/manpages/bcfg2-info.txt b/doc/getting_help/manpages/bcfg2-info.txt deleted file mode 100644 index 751905e0b..000000000 --- a/doc/getting_help/manpages/bcfg2-info.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-info: - -========== -bcfg2-info -========== - -The man page of ``bcfg2-info``. :: - - man bcfg2-info diff --git a/doc/getting_help/manpages/bcfg2-repo-validate.txt b/doc/getting_help/manpages/bcfg2-repo-validate.txt deleted file mode 100644 index b13bd928b..000000000 --- a/doc/getting_help/manpages/bcfg2-repo-validate.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-repo-validate: - -=================== -bcfg2-repo-validate -=================== - -The man page of ``bcfg2-repo-validate``. :: - - man bcfg2-repo-validate diff --git a/doc/getting_help/manpages/bcfg2-server.txt b/doc/getting_help/manpages/bcfg2-server.txt deleted file mode 100644 index 27002789e..000000000 --- a/doc/getting_help/manpages/bcfg2-server.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-server: - -============ -bcfg2-server -============ - -The man page of ``bcfg2-server``. :: - - man bcfg2-server diff --git a/doc/getting_help/manpages/bcfg2.txt b/doc/getting_help/manpages/bcfg2.txt deleted file mode 100644 index 4e93ab449..000000000 --- a/doc/getting_help/manpages/bcfg2.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2: - -===== -bcfg2 -===== - -The man page of bcfg2. :: - - man bcfg2 diff --git a/doc/getting_help/reporting.txt b/doc/getting_help/reporting.txt deleted file mode 100644 index cd53b1206..000000000 --- a/doc/getting_help/reporting.txt +++ /dev/null @@ -1,12 +0,0 @@ -.. -*- mode: rst -*- - -.. _reporting: - -.. _tracker: http://trac.mcs.anl.gov/projects/bcfg2/wiki - -============== -Reporting bugs -============== - -Report bugs with Bcfg2 in our `tracker`_. - 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. |