Writing A Client Tool Driver

This page describes the step-by-step process of writing a client tool driver for a configuration element type. The included example describes an existing driver, and the process that was used to create it.

1. Pick a name for the driver. In this case, we picked the name RPM.
2. Create a file in src/lib/Client/Tools with the same name (RPM.py)
3. Create a class in this file with the same name (class RPM)
   • If it handles Package entries, subclass Bcfg2.Client.Tools.PkgTool (from here referenced as branch [P])
   • If it handles Service entries, subclass Bcfg2.Client.Tools.SvcTool (from here referenced as branch [S])
   • Otherwise, subclass Bcfg2.Client.Tools.Tool (from here referenced as branch [T])
4. Set name to “RPM”
5. Add any required executable programs to __execs__
6. Set __handles__ to a list of (entry.tag, entry.get(‘type’)) tuples. This determines which entries the Tool module can be used on. In this case, we set __handles__ = [('Package', 'rpm')].
7. Add verification. This method should return True/False depending on current entry installation status.
   • [T] Add a Verify<entry.tag> method.
   • [P] Add a VerifyPackage method.
   • [S] Add a VerifyService method.
   • In the failure path, the current state of failing entry attributes should be set in the entry, to aid in auditing. (For example, if a file should be mode 644, and is currently mode 600, then set attribute current_perms=‘600’ in the input entry)
8. Add installation support. This method should return True/False depending on the results of the installation process.
   • [T,S] Add an Install<entry.tag> method.
   • [P] The PkgTool baseclass has a generic mechanism for performing all-at-once installations, followed, in the case of failures, by single installations. To enable this support, set the pkgtype attribute to the package type handled by this driver. Set the pkgtool to a tuple (“command string %s”, (“per-package string format”, [list of package entry fields])). For RPM, we have setup pkgtool =  ("rpm --oldpackage --replacepkgs --quiet -U %s", ("%s", ["url"]))
9. Implement entry removal
   • [T,S] Implement a Remove method that removes all specified entries (prototype Remove(self, entries))
   • [P] Implement a RemovePackages that removes all specified entries (same prototype as Remove)
10. Add a FindExtra method that locates entries not included in the configuration. This may or may not be required, certain drivers do not have the capability to find extra entries.
11. [P] Package drivers require a RefreshPackages method that updates the internal representation of the package database.

Writing Tool Driver Methods

1. Programs can be run using self.cmd.run. This function returns a (return code, stdout list) tuple.
2. The configuration is available as self.config
3. Runtime options are available in a dictionary as self.setup
4. Informational, error, and debug messages can be produced by running self.logger.info/error/debug.