CSSH-Range
==========
Introduction
------------
CSSH-range is an avahi-backed cluster-ssh connection tool.
It allows you to connect to a range of hosts with cssh using a short command.
This tool is Useful in applications where clusters of unix-based IoT (Internet
of Things) devices have to be administered.
Usage instructions
------------------
Cssh-range takes a hostname_base as argument, which is translated to a range
of hostnames by appending "-x" where x is an increasing index number.
Cssh-range intelligently resolves ranges of hostnames by polling the detected
avahi names, and only returns those hostnames that actually exist on the
network. This makes it also a useful tool to list the avahi hostnames within a
range that are visible on the network (use the -l option for that).
An example:
cssh-range.py foo
This will find and connect to all devices that announce their hostname via
the AVAHI daemon in range:
foo-1.local foo-2.local foo-3.local ...
This is a common practice with avahi hostnames, where avahi appends an index to
keep hostnames unique.
To get started, configure your devices with a common base hostname (usually in
the file /etc/hostname), for example "foo-1". The "-1" will automatically be
replaced with an incremental index by avahi to identify each device with a
unique hostname.
Note that if you were to store "foo" in the hostname file, instead of "foo-1",
the first device would get the hostname "foo" assigned, the others would get
"foo-1", "foo-2", ... This makes the first unit fall outside of the range.
The tool also includes a ping (--ping, -p) feature that allows pinging missing
hostnames in the range, which helps alleviate problems where the avahi hostname
cache temporarily goes out of sync. Pinging other likely devices in the hostname
range usually solves problems with missing devices. It's sometimes useful to use
the -p switch together with an end argument when the number of devices in the
range is known, as pinging non-existing devices takes a little longer.
To use this tool, you need to have cssh or Cluster ssh and avahi-browse
installed. On debian-based systems these can be installed using:
apt-get install clusterssh avahi-daemon avahi-utils
This software is written in python and relies exclusively on the standard
libraries. A Python2 interpreter is required to run.
Usage:
cssh-range.py [-h] [<username@>]<hostname_base> [<begin>] [<end>]
cssh-range takes a hostname_base as argument, which is translated to a range
of hostnames by appending "-x" where x is an increasing index number.
hostname_base The base hostname to use in the range
username The username to login to SSH with
begin Integer number where the range should begin
end Integer number where the range should stop (inclusive)
When only one number is specified, it's the end index, begin
defaults to 1
Not specifying begin and/or end index will use avahi-browse
to discover the available range and include all
-h, --help Shows this help message
-l, --list List hostnames in range only, do not connect
-c, --clearkeys Clear the ssh known_host keys for the hosts in range
-p, --ping Ping to detect missing hostnames in range
Licensing
---------
This software is written by Jonas Hauquier and is distributed under the GPLv3
license. For more information, see the accompanying COPYING file that comes with
this software.