Provided by: kanif_1.2.1-1_all bug

NAME

       kanif - a TakTuk wrapper for cluster management

SYNOPSIS

       kash|kaget|kaput [-aHhimsV] [-f conf-file] [-l login] [-M
       machines-list] [-n|-w nodes] [-o options] [-p level] [-r command] [-T
       options] [-t timeout] [-u timeout] [-x nodes] [machines specifications]
       [command body]

DESCRIPTION

       kanif is a tool for cluster management and administration. It combines
       main features of well known cluster management tools such as c3, pdsh
       and dsh and mimics their syntax. For the effective cluster management
       it relies on TakTuk, a tool for large scale remote execution
       deployment.

       For simple parallel tasks that have to be executed on regular machines
       such as clusters, TakTuk syntax is too complicated.  The goal of kanif
       is to provide an easier and familiar syntax to cluster administrators
       while still taking advantage of TakTuk characteristics and features
       (adaptivity, scalability, portability, autopropagation and informations
       redirection).

       To work, kanif needs to find the "taktuk" command (version 3.3 and
       above) in the user path. The other requirements are the same as TakTuk:
       it requires, on all the nodes of the cluster, a working Perl
       interpreter (version 5.8 and above) and a command to log without
       password (such as "ssh" with proper rsa keys installed).

       kanif provides three simple commands for clusters administration and
       management:

       kash: runs the same command on multiple nodes
       kaput: broadcasts the copy of files or directories to several nodes
       kaget: gathers several remote files or directories

       kanif combines the advantages of several cluster management tools.  Its
       main features can be summarized as follows:

       ·   C3-style configuration file for static clusters setups

       ·   pdsh-like options such as nodes ranges and timeouts

       ·   dshbak-like gathering, sorting and merging of output

       As with "pdsh", kanif deployment can be monitored and controlled by
       signals.  When kanif receives a SIGINT (usually sent by typing Ctrl-C),
       it displays a brief summary of its deployment state and commands
       execution progress. After this first SIGINT, if kanif receives a second
       signal within one second:

       ·   it terminates its execution (cancelling any ongoing task) if this
           is a SIGINT

       ·   it cancels any ongoing connections and start executions on the
           already deployed nodes if this is a SIGTSTP (usually sent by typing
           Ctrl-Z)

       At the end of executions, kanif also reports a quick summary of
       failures: connections and commands execution.

OPTIONS

       To help administrators in their task, kanif options syntax is as close
       as possible to C3/pdsh/dsh well known tools.

       -a
       --all
           Deploys on all nodes of all configured clusters.

       -f conf-file
       --file conf-file
           Uses "conf-file" as configuration file instead of default. Several
           possibilities are examined for default configuration file, in
           order: "$HOME/.kanif.conf", "/etc/kanif.conf", "/etc/c3.conf".

       -F
       --flat-deployment
           Deploys all remote execution from the root node (which executes
           kanif). Useful when remote nodes cannot log on each other.

       -H
       --head
           Deploys only on clusters "head" node (using local interface) for
           all specified clusters.

       -h
       --help
           Prints a short help text and exits.

       -i
       --interactive
           Ask confirmation before any action. An action is either the
           execution of one command on all the hosts (default) or the
           execution of one command on one host (sequential mode, see -s
           switch).

       -l login
       --login login
           Uses the given "login" to connect to remote hosts.

       -M machines-list
       --list machines-list
           Adds to the remote hosts the names contained in the file named
           "machines-list". kanif accepts as many -M options as you wish.

       -m
       --monitoring
           Makes kanif more verbose about whats happening during deployment
           commands execution.

       -n nodes
       --nodes nodes
           Adds the given "nodes" to the deployment. See section "HOSTNAMES
           SPECIFICATION" for more information about "nodes" syntax.  kanif
           accepts as many -n options as you wish.

       -o options
       --remote-opts options
           Sets additional options to be passed to the remote shell command.

       -p level
       --postprocess level
           Sets the level of output formating made in kanif. The general idea
           is: the higher the level, the more sorted, merged and human
           readable the output. Default is 4, differents levels are:

           0   No processing at all: raw commands output is printed to stdout
               and raw commands error is printed to stderr. Connections and
               executions errors are not reported.

           1   Same as 0 except that the name of the host which produced the
               output is prepended before each line.

           2   Same as 1 except that the output is sorted by command (one
               complete command execution is outputed entirely before another
               one). Connections and executions errors are summarized at the
               end to stderr.

           3   Same as 2 except that the hostname is printed once, formatted
               as a title, before its output.

           4   Same as 3 except that identical output produced by multiple
               nodes is printed once with all the hosts summarized in the
               title.

       -q
       --dry-run
           When this option is given, kanif does nothing and prints its
           configuration, the remote nodes it would have tried to contact and
           the TakTuk command that would have been executed.

       -r command
       --remote-cmd command
           Sets the name of the "command" used to contact remote hosts
           (default is "ssh -o StrictHostKeyChecking=no -o BatchMode=yes").

       -s
       --sequential
           Each command is executed sequentially on remote hosts (using the
           order given on the command line as hosts order).

       -T options
       --taktuk-options options
           Allows power users to pass some options to the TakTuk command
           executed (caution: always include -s which is the default unless
           you really know what you are doing).

       -t timeout
       --timeout timeout
           Gives a timeout value for connection attempts. At expiration,
           connection is canceled and deployment on the remote host is
           aborted.

       -u timeout
       --upper-limit timeout
           Gives a timeout value for commands execution. At expiration the
           command is killed with a TERM signal.

       -V
       --version
           Prints kanif version and exits.

       -w
       -wcoll
           Synonym to -n.

       -x nodes
       --exclude nodes
           Excludes some nodes from the ones given using -n or -w. Applies to
           all hosts sets that do not already contain an exclusion part. Does
           not apply to host given with -M option.

ENVIRONMENT

       Usually all kanif options can be set by environment variables.  The
       rationale is that boolean options have 0/1 value and environment
       settings are overridden by command line switches.

       The name of an environment variable used by kanif is made of the long
       option name capitalized with dashes replaced by underscores and
       "KANIF_" prepended (for instance "KANIF_ALL", "KANIF_HEAD", and so on).
       This rule admits the following exceptions (that have been chosen to
       mimic C3/dsh behavior):

       KANIF_CONF
           Instead of KANIF_FILE for configuration file.

       KANIF_USER
           Instead of KANIF_LOGIN for login name.

       Notice also that the variable KANIF_WCOLL has no meaning to kanif.

HOSTNAMES SPECIFICATION

       Hostnames given to kanif might be simple machine name or complex hosts
       lists specifications. In its general form, an hostname is made of an
       host set and an optional exclusion set separated by a slash.  Each of
       those sets is a comma separated list of host templates. Each of these
       templates is made of constant parts (characters outside brackets) and
       optional range parts (characters inside brackets). Each range part is a
       comma separated list of intervals or single values. Each interval is
       made of two single values separated by a dash. This is true for all
       hostnames given to kanif (both with -M or -n/-w options).

       In other words, the following expressions are valid host
       specifications:
           node1
           node[19]
           node[1-3]
           node[1-3],otherhost/node2
           node[1-3,5]part[a-b]/node[3-5]parta,node1partb

       they respectively expand to:
           node1
           node19
           node1 node2 node3
           node1 node3 otherhost
           node1parta node2parta node2partb node3partb node5partb

       Notice that these list of values are not regular expressions
       ("node[19]" is "node19" and not "node1, node2, ...., node9"). Intervals
       are implemented using the perl magical auto increment feature, thus you
       can use alphanumeric values as interval bounds (see perl documentation,
       operator ++ for limitations of this auto increment).

MACHINES SPECIFICATIONS

       With kanif, you can specify the remote nodes on which you want to do
       some stuff using the command line switches (-n and -x, pdsh/dsh style),
       using machines specifications (C3 style) or both. Thus, this part of
       the documentation might be ignored if you do not want to use C3 style
       nodes management.

       To use machines specification you must describe your cluster in a
       configuration file (see -f option and kanif.conf(5)).  Machines
       specifications are nodes intervals taken from clusters defined in this
       file.

       A machine specification is an optional cluster name followed by a colon
       and an optional range. The default cluster is taken if no cluster name
       is given.  All the nodes of the cluster are taken if no range is given.
       Notice that if none of -n/-w, -M or machine specification is given on
       the command line, the remote hosts are assumed to be all the nodes of
       the default cluster.

COMMAND BODY

       Depending on the name used to invoke it (kash, kaput or kaget), kanif
       does not perform the same task. Here are its various behavior:

       kash [options] [command line]
           Executes the last part of the command line on all the remote hosts.
           If this last part is empty, enters interactive mode in which kanif
           waits for command (one per line) on stdin. In interactive mode,
           just send an EOF character (Ctrl-D) to exit kash.

       kaput [options] src1 [src2 ...] dest
           Copies one ore more files or directories to all the remote hosts.
           The last argument is the path to the destination file or directory
           on the remote machine.  The other arguments are local files or
           directories to copy. Behavior and limitations are similar to the
           command cp(1).

       kaget [options] src1 [src2 ...] dest
           Download one ore more files or directories from all the remote
           hosts. The last argument is the path to the destination directory
           on the local machine. The other arguments are path to files or
           directories on remote hosts. Each source must be present on all the
           remote hosts. Sources are copied to the destination directory
           having the originating host appended to their name.

       Notice that when using kaget or kaput each file or directory is
       completely copied before proceeding to the next one.

EXAMPLES

       When a configuration file exists on the system or is given on the
       command line (see option -f), remote machines can be specified via
       clusters names. For instance, the simple execution of the command "ls
       -l" on all the nodes of the cluster named "megacluster" can be written:

           kash megacluster: ls -l

       Intervals can also be given. The following command copies the local
       .cshrc file to the login directory of a subset of the default cluster
       and another subset of the "megacluster":

           kaput :3-6 megacluster:2-5 $HOME/.cshrc .

       Finally, one can take advantage of the default behavior to gather a
       file named "results.txt" placed in the "/tmp" directory on all the
       nodes of the default cluster to the local directory "results":

           kaget /tmp/results.txt results

       When a user does not want to write a configuration file or just wants
       to deploy on some other nodes, it is possible to give remote hosts on
       the command line:

           kash -n localhost,supernode uptime

       This last command will just execute "uptime" on "localhost" and
       "supernode".  Giving intervals and exclusion lists is also possible on
       the command line. The following command copie the file
       "/tmp/temporary.txt" to the remote "/tmp" directories of node1 and
       node5:

           kaput -n node[1-6] -x node[2-4],node6 /tmp/temporary.txt /tmp

       Finally, without entering into the details of each option, the final
       command illustrates the -u option. It executes during 5 seconds a
       "ping" to "gateway" from 5 nodes:

           kash -n node[1-2],node[4-6] -u 5 ping gateway

BUGS

       Missing features:

       ·   indirect clusters not supported (see C3 documentation about such
           clusters)

       ·   when there are no machine to deploy and kanif runs in interactive
           mode, kanif still waits for a command (or eof) before exiting

       Performance issues:

       ·   the algorithm used by kaput is not very efficient for transferring
           large files. Although the precise limit depends on the machine, it
           should not scale well above a few hundreds of megabytes.

SEE ALSO

       taktuk(1), kanif.conf(5)

AUTHOR

       The author of kanif and current maintainer of the package is Guillaume
       Huard. Acknowledgements to Lucas Nussbaum for the idea of the name
       "kanif".

COPYRIGHT

       kanif is provided under the terms of the GNU General Public License
       version 2 or later.