summaryrefslogtreecommitdiffstats
path: root/doc/client/tools
diff options
context:
space:
mode:
Diffstat (limited to 'doc/client/tools')
-rw-r--r--doc/client/tools/actions.txt68
1 files changed, 68 insertions, 0 deletions
diff --git a/doc/client/tools/actions.txt b/doc/client/tools/actions.txt
new file mode 100644
index 000000000..6b68164e3
--- /dev/null
+++ b/doc/client/tools/actions.txt
@@ -0,0 +1,68 @@
+.. -*- mode: rst -*-
+
+.. _client-tools-actions:
+
+=======
+Actions
+=======
+
+This page describes use of the Action configuration entry. Action entries
+are commands that are executed either before bundle installation,
+after bundle installation or both. If exit status is observed, a
+failing pre-action will cause no modification of the enclosing bundle
+to be performed; all entries in included in that bundle will not be
+modified. Failing actions are reported through Bcfg2's reporting system,
+so they can be centrally observed. Actions look like:
+
+.. code-block:: xml
+
+ <Action timing='pre|post|both'
+ name='name'
+ command='cmd text'
+ when='always|modified'
+ status='ignore|check'/>
+
++-----------+------------------+-------------------------------------------+
+| Attribute | Values | Meaning |
++===========+==================+===========================================+
+| timing | pre, post, both | When the action is run |
++-----------+------------------+-------------------------------------------+
+| name | freeform | action name |
++-----------+------------------+-------------------------------------------+
+| command | freeform | command text |
++-----------+------------------+-------------------------------------------+
+| when | always, modified | If the action is always run, or only when |
+| | | a bundle should be or has been modified |
++-----------+------------------+-------------------------------------------+
+| status | ignore, check | If the return code of the action |
+| | | should be reported or not |
++-----------+------------------+-------------------------------------------+
+
+Note that the status attribute tells the bcfg2 client to ignore
+return status, causing failures to still not be centrally reported. If
+central reporting of action failure is desired, set this attribute to
+'check'. Also note that Action entries included in Base will not be
+executed.
+
+Actions cannot be completely defined inside of a bundle; they are a bound
+entry, much like Packages, Services or Paths. The Rules plugin can bind
+these entries. For example to include the above action in a bundle,
+first the Action entry must be included in the bundle:
+
+.. code-block:: xml
+
+ <Bundle name='bundle_name'>
+ ...
+ <Action name='action_name'/>
+ </Bundle>
+
+Then a corresponding entry must be included in the Rules directory, like:
+
+.. code-block:: xml
+
+ <Rules priority='0'>
+ <Action timing='post' when='modified' name='action_name' command='/path/to/command arg1 arg2' status='ignore'/>
+ </Rules>
+
+This allows different clients to get different actions as a part of the
+same bundle based on group membership.