Project

runsible

0.0
No commit activity in last 3 years
No release in over 3 years
Runsible runs remote commands via net-ssh with retries and alerting
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 2.0

Runtime

~> 2.7
~> 1.0
~> 4.0
 Project Readme

Gem Version

Note: this is pre-alpha software and not feature complete. See open Issues.

Runsible

Runsible uses SSH (via net-ssh) to execute remote commands, handling failures with retries and alerting. It captures remote STDOUT and STDERR and outputs them locally. Commands are executed sequentially in a "runlist".

An executable runsible is provided, which looks for a YAML file in the command line arguments. The YAML file defines the runlist and settings, while the command line options for runsible can override the YAML settings.

Features

  • Use SSH for remote transport and execution
    • Use your local ssh_config, keys, agent, etc.
  • Declare runlists and settings in YAML format
  • Robust failure handling including:
  • Runs locally - no additional software or agents to manage on the command target
    • Command target must be running SSH service

Installation

Install the gem:

$ gem install runsible       # sudo as necessary

Or, if using Bundler, add to your Gemfile:

gem 'runsible', '~> 0.1'

Usage

runsible /path/to/file.yaml

$ runsible -h
usage: runsible [options] yaml_file
    -h, --help
    -v, --version  show runsible version
    -u, --user     remote user [rwh]
    -H, --host     remote host [127.0.0.1]
    -p, --port     remote port [22]
    -r, --retries  retry count [0]
    -s, --silent   suppress alerts

YAML Configuration

The top-level YAML structure is a hash. Primary keys are 'settings' and 'runlist', though neither are necessary. Optionally you can define a 'cleanup' section and point to it with on_failure: cleanup in a runlist item.

The minimal YAML file is empty. runsible empty.yaml will use internal defaults to attempt to SSH to 127.0.0.1:22 as the current user.

Real-world Example

settings:
  user: root
  alerts:
    backend: email
    address: alerts@bigco.local

runlist:
  - command: ./setup_fs
  - command: source anaconda/bin/activate graphlab
  - command: python scorer.py
    retries: 5
    on_failure: cleanup

cleanup:
  - command: python wipe_cache.py

Maximal Settings Example

settings:
  silent: no
  retries: 5
  alerts:
    backend: email
    address: alerts@bigco.local
  user: root
  host: bigco.local
  port: 80
  vars: FOO BAR BAZ

All of the above is optional. Note that vars is not behaving as expected and is unsupported at the moment. See net-ssh/net-ssh#236 for details.

Simple Runlist Example

runlist:
  - command: false
    retries: 3
    on_failure: continue
  - command: true
  - command: false
  - command: true

Note that the last - command: true runlist item will never execute. The previous - command: false will exit, since it doesn't have on_failure: continue and the default value is exit.

Empty Runlist

The SSH connection will still be attempted according to defaults and any settings provided. The connection will be closed immediately.

See also the built-in examples.

Commands

  • Commands are executed in the context of a remote shell provided by SSH
  • Commands are executed sequentially within a runlist
  • Shell exit code determines command success or failure
  • On success, execution proceeds to the next command in the runlist
  • On failure, if there are retries configured, the command will be retried after a short delay
  • When retries are exhausted, an alert goes out, and on_failure determines the flow of execution
    • exit is the default, aborting the runlist and causing runsible to exit with non-zero status code
    • continue is used to proceed to the next command in the runlist
    • cleanup proceeds to another runlist keyed by cleanup