Advanced

Advanced Usage

Contents

• Configuration File
• Executing action remotely (ssh)
• Implement a guesser
  • First step: guesser implementation
  • Second step: configure the sequencer
• Reporting
• Chaining: blackbox mode
• Incremental mode
• Dealing with failures

In the following, we consider the sequencer has been installed as a normal user, not as the root user. See Installation for details.

Configuration File

The behavior of the sequencer can be modified through its configuration file called config. This file is searched by the sequencer in:

• /etc/sequencer/ when installed system wide;
• ~/.sequencer/ when installed by the end user.

A configuration file template with default values is packaged within the sequencer. You will find it at:

<python_installation>/sequencer-*/conf/config

Do not modify this file. Instead, copy it to the configuration directory (here, in the user home):

$ cp $(find /usr/lib*/python* ~/.local/lib*/python* -path '*sequencer-*/conf/config' 2>/dev/null) ~/.sequencer/config

and modify the copy:

$ vi ~/.sequencer/config

The packaged config file is self-documented.

Executing action remotely (ssh)

By default, the sequencer executes actions locally. If the command specified in the column action should be executed remotely, prefix it by the symbol '@'. For example:

$ sequencer dbadd uname cmd ALL ALL '@uname -a' NONE NONE 'Remote execution of uname'
$ sequencer  dbshow uname
ruleset | name | types | filter |    action | depsfinder | dependson |                  comments |
---------------------------------------------------------------------------------------------------
  uname |  cmd |   ALL |    ALL | @uname -a |       NONE |      NONE | Remote execution of uname |
$ sequencer uname localhost phobos
phobos#exotic@alien/cmd: [node=phobos] Linux phobos 2.6.36-gentoo-r8 #4 SMP PREEMPT Sat Sep 24 20:20:05 CEST 2011 i686 Intel(R) Atom(TM) CPU D510 @ 1.66GHz GenuineIntel GNU/Linux
localhost#exotic@alien/cmd: [node=localhost] Linux gaia 2.6.32-gentoo-r7 #2 SMP PREEMPT Fri Sep 30 20:43:03 CEST 2011 i686 Genuine Intel(R) CPU T2400 @ 1.83GHz GenuineIntel GNU/Linux
$

Implement a guesser

The default guesser requires that you specify the type and the category of each component names in the input list unless your ruleset does not use type and categorie at all. This might be cumbersome. The solution is to use your own guesser. This is a two steps process:

1. implement the get_guesser(param) function
2. tells the sequencer to use your guesser

First step: guesser implementation

You first have to implement a function called get_guesser(param) in your own module (e.g. myguesser). The sequencer will call this function with a string parameter. This string can be anything you want. For example, it can be a database name, where your guesser will fetch types and categories.

Your function should then return an object that implements (duck typing) the Guesser interface defined in the sequencer API. This is where you will implement your own business logic.

Note: the guesser API documentation is available through pydoc:

$ pydoc sequencer.guesser

A trivial implementation is available here. When one name in the input list is just world, clients or servers, it expands it to world#fake@group, clients#fake@group and servers#fake@group respectively. To test our guesser implementation, do the following:

1. Download the guesser example
2. Store it somewhere, say in /tmp
3. Test with the guesser script using our implementation.

The last step can be done with the following instruction:

$ PYTHONPATH=/tmp guesser --module=myguesser world clients servers host[1-3]
host1#ip@host
host3#ip@host
servers#fake@group
clients#fake@group
world#fake@group
host2#ip@host
$

Second step: configure the sequencer

Once you have implemented your own guesser, you have to configure the sequencer so it will use it instead of the default one. This is done through the configuration file. Follow the following steps:

In the configuration file, modify lines:

guesser.module.name = sequencer.guesser
guesser.factory.params = None

Into:

guesser.module.name = myguesser
guesser.factory.params = None

If your implementation conforms to the guesser API, types and categories should now reflect your owns. Of course, it is mandatory that your implementation is known by python: an easy solution is to update your PYTHONPATH accordingly before the execution of the sequencer:

$ export PYTHONPATH=$PYTHONPATH:~/.local/dev/my_guesser_impl_dir
$ sequencer ...

Reporting

See option '--report' in sequencer man pages seqexec (1) and chain (1).

Chaining: blackbox mode

Chaining means executing all three stages transparently. This is also known as the blackbox mode in opposition to the incremental mode.

Chaining is roughly equivalent to the piping of all stages. For example:

$ sequencer test foo bar

is roughly equivalent to:

$ sequencer depmake test foo bar | sequencer seqmake | sequencer seqexec

See chain (1) man page for details.

Incremental mode

The incremental mode is best used when you need to validate a critical script before being pushed to production. A typical example is an Emergency Power Off (EPO) script.

Workflow suggestion:

# Create rules: dbadd, dbshow, dbupdate, dbremove

• define your actions according to component types and categories
• define depsfinder and adapt dependson column accordingly
• optionnaly implement a guesser

# Create dependency graph: depmake

• check the output by hand if the graph is small
• optionnaly, generate a DOT representation of the dependency graph: --depgraphto
• modify rules
• optionnaly, modify the dependency graph output by hands

# Create the instructions sequence: seqmake

# Simulate the execution of the instructions sequence: seqexec --doexec=n

• Use reporting to check various paramaters: number of components, components that should be filtered in, or filtered out, ...: --report=model
• optionnaly, generate a DOT representation of the actions graph: --actionsgraphto
• optionnaly, modify the instructions sequence by hand

# Push to production the script: seqexec

• optionnaly, generate a report: --report=all
• optionnaly, generate statistics: --dostats=y
• optionnaly, ask for progress report: --progress=10
• optionnaly, specify the maximum number of parallel actions: --fanout 200

Dealing with failures

See option --Force in chain (1) and depmake (1) and seqexec (1) man pages.