Merge branch 'master' of git.mcs.anl.gov:bcfg2

1 files changed, 76 insertions, 36 deletions

diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt
index 88a0febc5..5fe1500f4 100644
--- a/doc/help/troubleshooting.txt
+++ b/doc/help/troubleshooting.txt
@@ -81,101 +81,138 @@ Type `help` in bcfg2-info for more information.
 Error Messages
 ==============
 
-This page describes error messages produced by Bcfg2 and steps that can
+The tables below describe error messages produced by Bcfg2 and steps that can
 be taken to remedy them.
 
+Client Errors
+-------------
+
 +------------------------------+----------+---------------------+--------------+
 | Error                        | Location | Meaning             | Repair       |
 +==============================+==========+=====================+==============+
-| Incomplete information for   | Client   | The described entry | [1]_         |
+| Incomplete information for   | Client   | The described entry | [c1]_        |
 | 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]_         |
+| Incomplete information for   | Client   | The described entry | [c1]_        |
 | 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]_         |
+| The following entries are    | Client   | The client cannot   | [c2]_        |
 | not handled by any tool:     |          | figure out how to   |              |
 | <EntryTag>:<EntryName>       |          | handle this entry.  |              |
 +------------------------------+----------+---------------------+--------------+
-| No ca is specified. Cannot   | Client   | The client is       | [3]_         |
+| No ca is specified. Cannot   | Client   | The client is       | [c3]_        |
 | authenticate the server with |          | unable to verify    |              |
 | SSL.                         |          | the server          |              |
 +------------------------------+----------+---------------------+--------------+
-| Failed to bind entry:        | Server   | The server was      | [4]_         |
+| GID normalization failed for | Client   | The client is       | [c4]_        |
+| FILENAME. Does group GROUP   |          | unable to convert   |              |
+| exist?                       |          | the group GROUP to  |              |
+|                              |          | a usable GID        |              |
++------------------------------+----------+---------------------+--------------+
+| UID normalization failed for | Client   | The client is       | [c5]_        |
+| FILENAME. Does owner OWNER   |          | unable to convert   |              |
+| exist?                       |          | the owner OWNER to  |              |
+|                              |          | a usable UID        |              |
++------------------------------+----------+---------------------+--------------+
+
+
+.. [c1] This entry is not being bound. Ensure that a version of this
+        entry applies to this client.
+.. [c2] It is possible that the type attribute for this generator entry
+        is undefined. You may need to add the appropriate type attribute
+        in the literal entry specification.
+.. [c3] Copy the Bcfg2 server's CA certificate to the client and specify it
+        using the **ca** option in the [communication] section of
+        ``bcfg2.conf``
+.. [c4] If the group doesn't exist, you need to specify the correct one
+        in an :ref:`info.xml <server-info>` file or set the default group
+        appropriately.
+.. [c5] If the owner doesn't exist, you need to specify the correct one
+        in an :ref:`info.xml <server-info>` file or set the default owner
+        appropriately.
+
+Server Errors
+-------------
+
++------------------------------+----------+---------------------+--------------+
+| Error                        | Location | Meaning             | Repair       |
++==============================+==========+=====================+==============+
+| Failed to bind entry:        | Server   | The server was      | [s1]_        |
 | <EntryTag> <EntryName>       |          | unable to find a    |              |
 |                              |          | suitable version of |              |
 |                              |          | entry for client.   |              |
 +------------------------------+----------+---------------------+--------------+
-| Failed to bind to socket     | Server   | The server was      | [5]_         |
+| Failed to bind to socket     | Server   | The server was      | [s2]_        |
 |                              |          | unable to bind to   |              |
 |                              |          | the tcp server      |              |
 |                              |          | socket.             |              |
 +------------------------------+----------+---------------------+--------------+
-| Failed to load               | Server   | The server was      | [6]_         |
+| Failed to load               | Server   | The server was      | [s3]_        |
 | ssl key <path>               |          | unable to read and  |              |
 |                              |          | process the ssl key.|              |
 +------------------------------+----------+---------------------+--------------+
-| Failed to read file <path>   | Server   | The server failed   | [7]_         |
+| Failed to read file <path>   | Server   | The server failed   | [s4]_        |
 |                              |          | to read the         |              |
 |                              |          | specified file      |              |
 +------------------------------+----------+---------------------+--------------+
-| Failed to parse file <path>  | Server   | The server failed   | [8]_         |
+| Failed to parse file <path>  | Server   | The server failed   | [s5]_        |
 |                              |          | to parse the        |              |
 |                              |          | specified XML file  |              |
 +------------------------------+----------+---------------------+--------------+
-| Client metadata resolution   | Server   | The server cannot   | [9]_         |
+| Client metadata resolution   | Server   | The server cannot   | [s6]_        |
 | error for <IP>               |          | resolve the client  |              |
 |                              |          | hostname or the     |              |
 |                              |          | client is           |              |
 |                              |          | associated with a   |              |
 |                              |          | non-profile group.  |              |
 +------------------------------+----------+---------------------+--------------+
-| Failed to decode <filename>  | Server   | The encoding being  | [10]_        |
+| Failed to decode <filename>  | Server   | The encoding being  | [s7]_        |
 | Please verify you are using  |          | used is unable to   |              |
 | the proper encoding          |          | decode the          |              |
 |                              |          | character present   |              |
 |                              |          | in this file.       |              |
 +------------------------------+----------+---------------------+--------------+
-| Got unknown entries          | Server   | The Packages plugin | [11]_        |
+| Got unknown entries          | Server   | The Packages plugin | [s8]_        |
 | [list of unknown entries]    |          | has no knowledge of |              |
 |                              |          | the listed entries  |              |
 +------------------------------+----------+---------------------+--------------+
-| Failed to import lxml        | Server   | The server cannot   | [12]_        |
+| Failed to import lxml        | Server   | The server cannot   | [s9]_        |
 | dependency. Shutting         |          | import lxml         |              |
 | down server.                 |          |                     |              |
 +------------------------------+----------+---------------------+--------------+
+| You need to specify base64   | Server   | The server cannot   | [s10]_       |
+| encoding for <path>          |          | send the file as    |              |
+|                              |          | ascii text          |              |
++------------------------------+----------+---------------------+--------------+
+| ERROR: Error reading file    | Server   | The server cannot   | [s11]_       |
+| '/path/to/schema': failed to |          | find the schema     |              |
+| load external entity         |          | file                |              |
+| "/path/to/schema"            |          |                     |              |
++------------------------------+----------+---------------------+--------------+
 
 
-.. [1] This entry is not being bound. Ensure that a version of this
-       entry applies to this client.
-.. [2] It is possible that the type attribute for this generator entry
-       is undefined. You may need to add the appropriate type attribute
-       in the literal entry specification.
-.. [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.
-.. [10] Ensure the correct encoding is specified in the [components]
+.. [s1] This entry is not being bound. Ensure that a version of this
+        entry applies to this client.
+.. [s2] Ensure that another instance of the daemon (or any other process)
+        is not listening on the same port.
+.. [s3] Ensure that the key is readable by the user running the daemon
+        and that it is well-formed.
+.. [s4] Ensure that this file still exists; a frequent cause is the
+        deletion of a temp file.
+.. [s5] Ensure that the file is properly formed XML.
+.. [s6] Fix hostname resolution for the client or ensure that the profile
+        group is properly setup.
+.. [s7] Ensure the correct encoding is specified in the [components]
         section of ``bcfg2.conf``.
-.. [11] For packages listed other than **gpg-pubkey**, this error means
+.. [s8] For packages listed other than **gpg-pubkey**, this error means
         that the Packages plugin is unable to find the package in any of
         the sources listed in ``Packages/config.xml``. The issue often
         arises when the client is not in one of the groups necessary for
@@ -183,8 +220,11 @@ be taken to remedy them.
         ignore the message as the Packages plugin has no knowledge of
         these packages (however, note that this package is most often
         specified as a BoundPackage entry).
-.. [12] Ensure that you have installed all the necessary
+.. [s9] Ensure that you have installed all the necessary
         :ref:`installation-prerequisites`.
+.. [s10] You likely need to specify a base64 encoding using an
+         :ref:`server-info` file for this entry.
+.. [s11] Verify that you have the proper prefix set in bcfg2.conf.
 
 FAQs
 ====