.. -*- 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'
            build='true|false'/>

.. xml:type:: ActionType

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'.

Actions may be completely defined inside of a bundle with the use of
:ref:`server-configurationentries`, much like Packages, Services or Paths.
The Rules plugin can also 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>
      ...
      <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.

It is also possible to do this in one step in the bundle itself with a
``BoundAction`` tag, e.g.:

.. code-block:: xml

    <Bundle>
      <BoundAction timing='post' when='modified' name='action_name'
                   command='/path/to/command arg1 arg2' status='ignore'/>
    </Rules>

Example Action (add APT keys)
=============================

This example will add the '0C5A2783' for aptitude. It is useful to run
this during the client bootstrap process so that the proper keys are
installed prior to the bcfg2 client trying to install a package which
requires this key.

.. code-block:: xml

    <Rules priority='0'>
      <Group name='ubuntu'>
        <Action timing='post' name='apt-key-update' command='apt-key adv --recv-keys --keyserver hkp://pgp.mit.edu 0C5A2783' when='modified' status='check'/>
      </Group>
    </Rules>

Example BoundAction (add RPM GPG keys)
======================================

This example will add the RPM-GPG-KEY-redhat-release key to the RPM
GPG keyring **before** Package entries are handled on the client run.

.. code-block:: xml

    <Bundle name="rpm-gpg-keys">
      <Group name='rhel'>
        <Path name="/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release"/>
        <BoundAction timing="pre" name="install rpm key" command="rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release" when="modified" status="check"/>
      </Group>
    </Bundle>