timmy/doc/source/usage.rst

Usage

The easiest way to launch timmy would be running the timmy.py script. However, you need to configure </configuration> it first.

Basically, the timmy.py is a simple wrapper that launches cli.py. Full reference </cli> for command line interface

Basic parameters:

• --only-logs only collect logs (skip files, filelists, commands and scripts)
• -l, --logs also collect logs (logs are not collected by default due to their size)
• -e, --env filter by environment ID
• -R, --role filter by role
• -c, --config use custom configuration file to overwrite defaults. See config.yaml as an example
• -j, --nodes-json use json file instead of polling Fuel (to generate json file use fuel node --json) - speeds up initialization
• -o, --dest-file the name/path for output archive, default is general.tar.gz and put into /tmp/timmy/archives.
• -v, --verbose verbose(INFO) logging
• -d, --debug debug(DEBUG) logging

Shell Mode - a mode of execution which makes the following changes:

• rqfile (rq.yaml by default) is skipped
• Fuel node is skipped
• outputs of commands (specified with -C options) and scripts (specified with -S) are printed on screen
• any actions (cmds, scripts, files, filelists, put, except logs) and Parameter Based configuration defined in config are ignored.

The following parameters ("actions") are available, the usage of any of them enables Shell Mode:

• -C <command> - Bash command (string) to execute on nodes. Using multiple -C statements will produce the same result as using one with several commands separated by ; (traditional Shell syntax), but for each -C statement a new SSH connection is established
• -S <script> - name of the Bash script file to execute on nodes (if you do not have a path separator in the filename, you need to put the file into scripts folder inside a path specified by rqdir config parameter, defaults to rq. If a path separator is present, the given filename will be used directly as provided)
• -P <file/path> <dest> - upload local data to nodes (wildcards supported). You must specify 2 values for each -P switch.
• -G <file/path> - download (collect) data from nodes

Examples

• timmy - run according to the default configuration and default actions. Default actions are defined in rq.yaml (/usr/share/timmy/rq.yaml). Logs are not collected.
• timmy -l - run default actions and also collect logs (default log setup applied - defaults are hardcoded in timmy/conf.py). Such execution is similar to Fuel's "diagnostic snapshot" action, but will finish faster and collect less logs.
• timmy --only-logs - only collect logs, no actions performed (default log setup, as above)
• timmy -C 'uptime; free -m' - check uptime and memory on all nodes
• timmy -G /etc/nova/nova.conf - get nova.conf from all nodes
• timmy -R controller -P package.deb '' -C 'dpkg -i package.deb' -C 'rm package.deb' -C 'dpkg -l | grep [p]ackage' - push a package to all nodes, install it, remove the file and check that it is installed
• timmy -с myconf.yaml - use a custom config file and run the program according to it. Custom config can specify any actions, log setup, and other settings. See configuration doc for more details.

Using custom configuration file

If you want to perform a set of actions on the nodes without writing a long command line (or if you want to use the options only available in config), you may want to set up config file instead. An example config structure would be:

rqdir: './pacemaker-debug' # a folder which should contain any filelists and/or scripts if they are defined later, should contain folders 'filelists' and/or 'scripts' 
rqfile: null # explicitly undefine rqfile to skip default filelists and scripts
hard_filter:
  roles: # only execute on Fuel and controllers
    - fuel
    - controller 
cmds: # some commands to run on all nodes (after filtering). cmds syntax is {name: value, ...}. cmds are executed in alphabetical order.
  01-my-first-command: 'uptime'
  02-disk-check: 'df -h'
  and-also-ram: 'free -m'
logs:
  exclude: '.*' # exclude all logs by default
by_roles:
  controller:
    scripts: # I use script here to not overwrite the cmds we have already defined for all nodes 
      - pacemaker-debug.sh # the name of the file inside 'scripts' folder inside 'rqdir' path, which will be executed (by default) on all nodes
    files:
      - '/etc/coros*' # get all files from /etc/coros* wildcard path
  fuel:
    logs:
      include: 'crmd|lrmd|corosync|pacemaker' # only get logs which names match (re.search is used) this regexp

Then you would run timmy -l -c my-config.yaml to execute timmy with such config.

Instead of putting all structure in a config file you can move actions (cmds, files, filelists, scripts, logs) to an rqfile, and specify rqfile path in config (although in this example the config-way is more compact). rqfile structure is a bit different:

cmds: # top-level elements are node parameters, __default will be assigned to all nodes
  __default:
    - 01-my-first-command: 'uptime'
    - 02-disk-check: 'df -h'
    - and-also-ram: 'free -m'
scripts:
  by_roles: # all non "__default" keys should match, "by_<parameter>"
    controller: 
      - pacemaker-debug.sh
files:
  by_roles:
    controller:
      - '/etc/coros*'
logs:
  by_roles:
    fuel:
      include: 'crmd|lrmd|corosync|pacemaker'
  __default:
      exclude: '.*'

Then the config should look like this:

rqdir: './pacemaker-debug'
rqfile: './pacemaker-rq.yaml'
hard_filter:
  roles:
    - fuel
    - controller

And you run timmy -l -c my-config.yaml.

Back to Index </index>.