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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
.. -*- mode: rst -*-
.. _development-plugins:
Bcfg2 Plugin development
========================
While the Bcfg2 server provides a good interface for representing
general system configurations, its plugin interface offers the ability
to implement configuration interfaces and representation tailored to
problems encountered by a particular site. This chapter describes what
plugins are good for, what they can do, and how to implement them.
Bcfg2 Plugins
-------------
Bcfg2 plugins are loadable python modules that the Bcfg2 server loads at
initialization time. These plugins can contribute to the functions already
offered by the Bcfg2 server or can extend its functionality. In general,
plugins will provide some portion of the configuration for clients, with a
data representation that is tuned for a set of common tasks. Much of the
core functionality of Bcfg2 is implemented by several plugins, however,
they are not special in any way; new plugins could easily supplant one
or all of them.
Server Plugin Types
-------------------
A plugin must implement at least one of the interfaces described
below. Each interface is available as a class in
:mod:``Bcfg2.Server.Plugin``. In most cases, a plugin must also
inherit from :class:`Bcfg2.Server.Plugin.Plugin`, which is the base
Plugin object (described below). Some of the interfaces listed below
are themselves Plugin objects, so your custom plugin would only need
to inherit from the plugin type.
Plugin
^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.Plugin
:inherited-members:
:show-inheritance:
.. automethod:: Bcfg2.Server.Plugin.Plugin.__init__
With the exceptions of :class:`Bcfg2.Server.Plugin.Statistics` and
:class:`Bcfg2.Server.Plugin.ThreadedStatistics`, the plugin interfaces
listed below do **not** inherit from Plugin; they simply provide
interfaces that a given plugin may or must implement.
Generator
^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.Generator
Examples are :ref:`server-plugins-generators-cfg` and
:ref:`server-plugins-generators-sshbase`.
Structure
^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.Structure
:ref:`server-plugins-structures-bundler-index` is a Structure plugin.
Metadata
^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.Metadata
:ref:`server-plugins-grouping-metadata` is a Metadata plugin.
Connector
^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.Connector
Connector plugins include
:ref:`server-plugins-grouping-grouppatterns`,
:ref:`server-plugins-connectors-properties`, and
:ref:`server-plugins-probes-index`.
Probing
^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.Probing
Examples include :ref:`server-plugins-probes-index` and
:ref:`server-plugins-probes-fileprobes`.
Statistics
^^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.Statistics
The Statistics object is itself a :class:`Bcfg2.Server.Plugin.Plugin`
object, so objects that inherit from Statistics do not have to also
inherit from Plugin.
ThreadedStatistics
^^^^^^^^^^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.ThreadedStatistics
:ref:`server-plugins-statistics-dbstats` is an example of a
ThreadedStatistics plugin.
The ThreadedStatistics object is itself a
:class:`Bcfg2.Server.Plugin.Plugin` object, so objects that inherit
from ThreadedStatistics do not have to also inherit from Plugin.
PullSource
^^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.PullSource
:ref:`server-plugins-statistics-dbstats` is an example of a plugin
that implements the PullSource interface
PullTarget
^^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.PullTarget
:ref:`server-plugins-generators-sshbase` is an example of a plugin
that implements the PullTarget interface
Decision
^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.Decision
:ref:`server-plugins-generators-decisions` is an example of a Decision
plugin, and has much more information about how decisions are used.
StructureValidator
^^^^^^^^^^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.StructureValidator
Examples are :ref:`server-plugins-structures-defaults` and
:ref:`server-plugins-structures-deps`.
GoalValidator
^^^^^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.GoalValidator
An example of a GoalValidator plugin would be the ServiceCompat plugin
that is used to provide old-style Service tag attributes to older
clients from a Bcfg2 1.3.0 server. As a final stage of configuration
generation, it translates the new "restart" and "install" attributes
into the older "mode" attribute.
Version
^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.Version
Examples include :ref:`server-plugins-version-git` and
:ref:`server-plugins-version-svn2`.
ClientRunHooks
^^^^^^^^^^^^^^
.. autoclass:: Bcfg2.Server.Plugin.ClientRunHooks
Examples are :ref:`server-plugins-misc-trigger` and
:ref:`server-plugins-connectors-puppetenc`.
Exposing XML-RPC Functions
--------------------------
Plugins can expose XML-RPC functions that can then be called with
:ref:`bcfg2-admin xcmd <server-admin-xcmd>`. Note that there is
absolutely no access control beyond the initial authentication, so
take care to not expose any data or behavior via XML-RPC that you
would not want all of your clients to be able to see or use.
To expose a function, simply add its name to the ``__rmi__`` class
attribute. (RMI stands for "Remote Method Invocation.") Consider
this example from the :ref:`server-plugins-generators-packages`
plugin:
.. code-block:: python
class Packages(Bcfg2.Server.Plugin.Plugin,
Bcfg2.Server.Plugin.StructureValidator,
Bcfg2.Server.Plugin.Generator,
Bcfg2.Server.Plugin.Connector,
Bcfg2.Server.Plugin.ClientRunHooks):
name = 'Packages'
conflicts = ['Pkgmgr']
__rmi__ = Bcfg2.Server.Plugin.Plugin.__rmi__ + ['Refresh', 'Reload']
def Refresh(self):
self._load_config(force_update=True)
return True
def Reload(self):
self._load_config()
return True
This exposes two functions, ``Refresh`` and ``Reload``, in addition to
any default methods that are already exposed. To call one of these
functions, you could run::
bcfg2-admin xcmd Packages.Refresh
Plugin Helper Classes
---------------------
.. autoclass:: Bcfg2.Server.Plugin.Debuggable
Plugin Exceptions
-----------------
.. autoexception:: Bcfg2.Server.Plugin.ValidationError
.. autoexception:: Bcfg2.Server.Plugin.PluginInitError
.. autoexception:: Bcfg2.Server.Plugin.PluginExecutionError
.. autoexception:: Bcfg2.Server.Plugin.MetadataConsistencyError
.. autoexception:: Bcfg2.Server.Plugin.MetadataRuntimeError
|
