1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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.
|
