Provided by: taktuk_3.6.1-1_all bug

NAME

       TakTuk - a tool for large scale remote execution deployment

SYNOPSIS

       taktuk [-hinsvP] [-c connector] [-d limit] [-f filename] [-g duration]
       [-l login] [-m hostname [-[ args ... -]]] [-o stream=template] [-t
       timeout] [-w size] [-C separators] [-E character] [-F filename] [-L
       hostname] [-O separators] [-R stream=descriptor] [-S files] [-T
       command] [-W scheme] [commands ... ]

DESCRIPTION

       TakTuk is a tool for broadcasting the remote execution of one ore more
       commands to a set of one or more distant machines. TakTuk combines
       local parallelization (using concurrent deployment processes) and work
       distribution (using an adaptive work-stealing algorithm) to achieve
       both scalability and efficiency.

       TakTuk is especially suited to interactive tasks involving several
       distant machines and parallel remote executions. This is the case of
       clusters administration and parallel program debugging.

       TakTuk also provides a basic communication layer to programs it
       executes.  This communication layer uses the communication
       infrastructure set up by TakTuk during its deployment. It is available
       both for the Perl and the C langages and is described in taktukcomm(3).

OPTIONS

       Caution, in TakTuk options are parsed in the order given on the comand
       line.  This means that TakTuk is not POSIX compliant regarding options
       order.  This is important as some of the options change the behavior of
       following ones (and only these ones - e.g. -l applies to following -m
       options). The defaults settings of TakTuk can be obtained by using the
       "--print-defaults" option.  The following options are given by category
       in alphabetical order.

DEPLOYMENT OPTIONS

       -c connector
       --connector connector
           defines the connector command used to contact the following remote
           machines.

       -d limit
       --dynamic limit
           turns dynamic mode (work stealing) on or off for the deployment of
           all the following remote machines specifications. If "limit" is
           positive or null, TakTuk uses the dynamic mode with its value as a
           maximal arity (0 = no maximal arity).  A negative value for "limit"
           turns dynamic mode off.  Warning, currently it is a bad idea to use
           several -d options on the same command line.

       -f filename
       --machines-file filename
           "filename" is the name of a file that contains remote machines
           names (equivalent to several "-m" opions). In each line of this
           file, the first word is considered as a machine name and the
           remaining as comments.

       -l login
       --login login
           sets the login name for the following hosts. This assumes that the
           connector command accepts "-l" option (this is the case for ssh,
           the default).

       -m hostname
       --machine hostname
           "hostname" is the name of a remote machine on which TakTuk has to
           be deployed. "hostname" might contain list of values specified
           inside brackets and exclusion lists (see "HOSTNAMES
           SPECIFICATION"). In such case, the depolyment will be performed on
           all the matching hosts.  This option can be followed by any number
           of arguments enclosed between "-[" and "-]" which will be
           transmitted as arguments of the remote TakTuk that will execute on
           all the target hosts.

       -s
       --self-propagate
           propagates the TakTuk executable through the following connectors
           and thus eliminates the need for a TakTuk installation on remote
           machines.

       -z
       --dont-self-propagate
           cancels a preceding -s option.

       -F filename
       --args-file filename
           "filename" is the name of a file that contains additional options
           for TakTuk. The parsing of the file is done when encountering this
           option.

       -L hostname
       --localhost hostname
           changes the name of localhost as viewed by TakTuk.

       -S files
       --send-files files
           gives to TakTuk a list of files to be sent upon successfull remote
           connection. Use with caution as it will slow down deployment (the
           files are transfered before the end of the deployment). The
           intended use is NOT to transfer application data files but rather
           files that are necessary to perform further connections from the
           remote node.  "files" is a comma separated list of pairs
           "local_file:remote_file". It behaves as the "put" command.

       -T command
       --taktuk-command command
           "command" is the name of the TakTuk command (default is $0, the
           name used to launch TakTuk). This is the command used once
           connected to initiate the remote TakTuk engine. Note that the
           effect of this switch is void when using the "-s" option.

COMMAND LINE PARSING OPTIONS

       -C separators set
       --command-separator separators set
           replaces the default set of characters that separates successive
           TakTuk commands.

       -E character
       --escape-character character
           defines an escape character that can be used to protect any
           following character from TakTuk interpretation. This protection
           applies nearly to the whole TakTuk command line.

       -O separators set
       --option-separator separators set
           replaces the default set of characters that separates successive
           words when reading options and commands from a file (using the "-F"
           switch).

I/O OPTIONS

       -o stream=template
       --output-template stream=template
           sets an output template specification for one of output streams
           designed by the given name. When giving only a stream name (without
           template) this disables the stream. Available streams include :

           "connector" (errors from the connector command)
               this stream contains in $line informations outputed to stderr
               by a connector command. Relevant fields include $host, $peer
               and others listed below.

           "error", "output" (error and output of remotely executed commands)
               these streams contain in $line informations outputed by
               executed command to stdout or stderr (respectively). Relevant
               fields include $host, $command, $pid and others listed below.

           "info" (general informations such as help summary or version)
               this stream contains in $line informations outputed by taktuk
               in response to commands such as "help" or "version".

           "state" (internal state of TakTuk instance)
               this stream contains in $line the state change code matching
               some TakTuk events. Codes are the following:

                 0 - TakTuk is ready
                 1 - TakTuk is numbered
                 2 - TakTuk terminated
                 3 - connection failed
                 4 - connection initialized
                 5 - connection lost
                 6 - command started
                 7 - command failed
                 8 - command terminated
                 9 - numbering update failed
                10 - pipe input started
                11 - pipe input failed
                12 - pipe input terminated
                13 - file reception started
                14 - file reception failed
                15 - file reception terminated

               The function event_msg($) can be used in the template to
               translate this code into a string that describes the event.
               Relevant fields include $host, $position, $rank, $count and
               others listed below.

           "status" (commands exit status)
               this stream contains in $line the return code of executed
               commands. Relevant fields include $host, $pid and others listed
               below.

           "taktuk" (internal messages, warnings and errors)
               this stream contains in $line error, warning and debug messages
               outputed by TakTuk itself. Relevant fields include
               $line_number, $package and others listed below.

           a template is a Perl expression that should evaluate to the string
           eventually displayed. Within a specification, some variables might
           be used depending on the concerned stream (notice that
           $father_position and $depth that appeared in 3.2.4 are not
           supported anymore and that $position evolved since 3.2.5):

           $command (not for "taktuk" nor "info")
               the command line execution that generated output.

           $count
               the total number of TakTuk instances.

           $eof
               an empty string or a newline depending on what character ended
               command output.

           $filename ("taktuk" only)
               the file in which a TakTuk diagnostic function has been called.

           $host
               the name of the host executing the current TakTuk instance

           $init_date ("connector" and "state" only)
               the time in seconds since Jan. 1, 1970 at which the remote
               TakTuk instance completed its initialization (including ssh
               connection time and self propagation if any).

           $level ("taktuk" only)
               the level of the diagnostic function called.

           $level_name ("taktuk" only)
               the name associated with the level of the diagnostic function
               called.

           $line
               the raw data outputed by a command or passed to a diagnostic
               function, any trailing newline removed (see $eof).

           $line_number ("taktuk" only)
               the line number at which a TakTuk diagnostic function has been
               called.

           $package ("taktuk" only)
               the package in which a TakTuk diagnostic function has been
               called.

           $peer ("connector" and "state" only)
               the remote machine for which a connector command outputed
               information.

           $peer_position ("connector" and "state" only)
               position on the command line of the remote host. This position
               is expressed as a path in the hierarchy of hosts expressed on
               the command line (dot separated position number at each level
               of imbrication).

           $pid (not for "taktuk" nor "info")
               the pid of the command line executed (that produced output).

           $position
               position on the command line of the current host. This position
               is expressed as a path in the hierarchy of hosts expressed on
               the command line (dot separated position number at each level
               of imbrication).

           $rank
               the logical number of TakTuk instance in which output is
               collected.

           $reply_date ("connector" and "state" only)
               the time in seconds since Jan. 1, 1970 at which the connector
               command replied to the local TakTuk instance (note that this
               does not include the initialization exange occuring before the
               remote TakTuk is considered as functional).

           $start_date ("output", "error", "connector" and "status")
               the time in seconds since Jan. 1, 1970 at which the command
               started (taken just after the call to fork()).

           $stop_date ("connector" and "status" only)
               the time in seconds since Jan. 1, 1970 at which the command
               terminated (after the closing of its stdout).

           $type
               the name of the output stream (connector, error, output, ...).

           $user_scalar
               a scalar, global to the package, initially initialized to
               undef, that the user is free to use for any purpose.

           at the end of the day, the specification is evaluated for each line
           of the concerned stream and the result printed on the root node.
           Note that the newline has to be added explicitely as "\n" in the
           template if needed.

           WARNING: take care of your specification, if the Perl syntax is not
           correct lots of awfull compilation error messages will be displayed
           and TakTuk execution will fail.

       -R stream=descriptor
       --output-redirect stream=descriptor
           redirect a given stream output to a given file descriptor number
           (located at the root node). See "-o" option for more details about
           streams output.

PERFORMANCE TUNING OPTIONS

       -g duration
       --time-granularity duration
           sets to "duration" the maximal interval between timeouts checks
           (usually checks are made more often: at each message received a
           timeouts check is made).

       -n
       --no-numbering
           disables TakTuk logical numbering and the variables "TAKTUK_COUNT"
           and "TAKTUK_RANK" are not defined in executed commands. This has
           the advantage of removing the global synchronization occuring at
           the end of the deployment and making the deployment more efficient.

           WARNING: use this option only before any remote node specification
           ("-m" or "-f") otherwise you might get serious synchronization
           issues in TakTuk.  Using TakTuk point-to-point communication along
           with this option will fail and produce TakTuk warnings.

       -t timeout
       --timeout timeout
           sets the timeout for following connectors (0 = no timeout). Notice
           that this option override the timeout of the connector command
           ("ssh" for instance).  When the delay expires, the connector
           command is simply killed.

       -w size
       --window size
           sets initial window to the given size (= pipeline width).

       -W scheme
       --window-adaptation scheme
           sets the windows adaptation scheme to number (default is 0, 0: no
           adaptation, 1: implementation in progress).

MISCELLANEOUS OPTIONS

       -M
       --my
           makes the next option local (not inherited). This means that the
           next option is set only for the local host and not propagated to
           children TakTuk instances.  Has no effect if the next option is
           already a local one.

       -h
       --help
           prints a short description of TakTuk on the screen.

       -i
       --interactive
           forces TakTuk interactive mode even after some batch commands given
           on the command line.

       -v
       --version
           prints the TakTuk version.

       -P
       --print-defaults
           prints the defaults settings used by TakTuk (environment variables
           taken into account).

INTERNAL OPTIONS

       These option are not useful for most users. They are used either
       internally by TakTuk itself or for development purposes.

       -p packagename
       --print-package packagename
           prints the content of package "packagename" extracted from the
           taktuk code in execution.

       -r
       --not-root
           current TakTuk instance is not the root node. This is an internal
           switch used by spawned TakTuk instances. This is usually not useful
           for most users.

       -D scope=level
       --debug scope=level
           sets debugging level (1..4) for "scope". The "scope" might be a
           TakTuk package name or "default" and the lowest the level the more
           verbose the output.

COMMANDS

       After the options parsing, TakTuk expects some commands either on the
       remaining of the command line (batch mode) or on the standard input
       (interactive mode). These commands are actions to be performed by
       TakTuk using the logical network infrastructure set up during the
       deployment. By default, commands might be separated by ; or newlines.
       For all the commands, any non ambiguous prefix can be used instead of
       their full name.  In interactive mode, TakTuk has support for
       "readline" (history, command line editing) if installed on your system.

       When TakTuk commands accept arguments, they should be enclosed into
       matching delimiters (indicated by * below). In other words, * might be
       replaced either by any non alphanumeric character or by a pair of
       matching braces, brackets or parenthesis.  These delimiters must be
       separated from their content (using the options separator). If the
       argument contains a closing delimiter preceded by a separator, then it
       is probably a good idea to escape it (see -E option) or to protect the
       whole arguments string if given on the command line.

       Taktuk understands the following commands:

       [ set specification ] command
           Sends the execution of command to all the peers belonging to the
           given set. For more details about the set specification, see
           section "SET SPECIFICATION".

       broadcast command
           Broadcasts the execution of command on all the remote peers (not
           including the node initiating the broadcast).

       downcast command
           Spreads the execution of command on all the children of the node
           initiating the downcast (not including itself).

       exec parameters * command line *
           Executes the "command line" on the local machine but has no effect
           on the root node. Inputs/outputs of the execution are multiplexed
           and fowarded to the TakTuk root.

           This command accepts optional parameters that enable the attachment
           of callbacks triggered by timeouts to the execution of the command.
           See section "EXEC PARAMETERS" for more details.

       get * src * * dest *
           Copies (a) remote source(s) (present on the remote node(s)) to a
           destination on the node executing this command.  The type of source
           and destination is quite similar to those accepted by the "cp -r"
           command (that is file or directories). This command also performs
           some kind of magic with its parameters: shell environment variables
           present in the source or destination names are replaced by their
           respective value on the remote and local nodes.  In addition, the
           variables $host, $rank and $position of the remote node (which are
           the same as in -o option) can also be used in both names.

       help
           Prints a very concise TakTuk help.

       input * data *
       input data * data *
           Sends the parameters as input to each command in execution on the
           local machine.

       input close
           Closes the inputs descriptor of all executing commands on the local
           machine.

       input file * filename *
           Sends the content of a file (which must be local to the node
           executing the input file) as input to each command in execution on
           the local machine.

           WARNING: this command is not atomic. If you manage somehow to
           initiate a input file command from two different TakTuk instances,
           data will probably be interleaved. In this case you should
           synchronize the two instances. This is not required when spreading
           files only from the root node.

       input line * data *
           Sends the parameters with an additional newline as input to each
           command in execution on the local machine.

       input pipe * data *
           Treat the parameter as a filename (which must be local to the node
           executing the input pipe) which behavior is the same as a pipe:
           data can arrive continuously. TakTuk add it as one of its input
           channels and send data as input to commands when available.

       kill <signal>
           Sends the given signal to local commands processes groups. If no
           signal is given, sends a TERM signal (signal 15).

       network
       network state
           Prints the current TakTuk deployment tree. Numbers in parenthesis
           match the peer rank in the logical TakTuk numbering and the peer
           ready state. If the deployment is not complete, the printed tree
           will display "connecting ..."  leaves.

       network cancel
           Cancels all ongoing connections. Consequently, this causes
           immediate starting of the possible numbering of TakTuk instances
           and the execution of TakTuk commands.

       network renumber
           Completely recomputes the logical numbering of TakTuk instances.
           This is especially useful when adding new nodes to the deployed
           network after initial numbering.

       network update
           Updates the logical numbering of TakTuk instances without changing
           already existing numbers. Does not always succeed as TakTuk uses a
           depth first scheme for numbering. Sends an event 9 in the stream
           ’state’ for each node of the tree that cannot be updated while
           keeping TakTuk numbering scheme.  This is especially useful when
           adding new nodes to the deployed network after initial numbering.

       option name * value *
       option * line *
           Either changes a single option which name is given (first form) or
           parses an additional options line (second form) on the node(s)
           executing this command.  See TakTuk options for more details, name
           can be either short or long in the first form.

           WARNING: new nodes added to TakTuk network using this command are
           not numbered. Further use of network renumbering or update is
           necessary to get TakTuk logical numbering.

       put * src * * dest *
           Copies a local source (present on the node executing this command)
           to a destination on all the remote nodes given as prefix of the
           command.  The type of source and destination is quite similar to
           those accepted by the "cp -r" command (that is file or
           directories). This command also performs some kind of magic with
           its parameters: shell environment variables present in the source
           or destination names are replaced by their respective value on the
           local and remote nodes.  In addition, the variables $host, $rank
           and $position of the local node (which are the same as in -o
           option) can also be used in both names.

       synchronize
           Forces the given command to wait for the completion of deployment,
           nodes numbering and previous commands before executing. This is
           usefull for commands like "broadcast" which does not wait for nodes
           numbering.

       taktuk_perl * arguments *
           Forks a perl interpreter on the local node just as if the command
           "exec perl arguments" have been used. The difference is that this
           interpreter is previously fetched with the "taktuk" package that
           contains point-to-point communication routines ("taktuk::send" and
           "taktuk::recv", see taktukcomm(3)).  WARNING: due to the
           limitations of the parser that analyses the arguments of this
           command, you have to give arguments (even if empty) and to use ’--’
           if you give any option to the perl interpreter (and even if you
           give it only options).

       version
           prints TakTuk version.

       quit
           Quit the TakTuk engine and shut down the logical communication
           network established during the deployment.

EXEC PARAMETERS

       The TakTuk command "exec" accepts optional parameters. These parameters
       are used to attach actions triggered by timeouts to commands execution.
       An "exec" command accepts any number of parameters. These parameters
       are interpreted from left to right using the following syntax:

       timeout value
           Creates a new timeout specification. At the end of the duration
           expressed by the given value, it will trigger its attached
           callbacks. If it has no attached callback, it will send a TERM
           signal to the command. If the command execution terminates before
           the end of the timeout duration, the timeout is canceled.

       kill value
           Attach a callback to the last defined timeout. This callback send a
           signal, which number is the given value, to the timeouted command.

       action command
           Attach a callback to the last defined timeout. This callback
           executes the given TakTuk command. If it executes some other
           command, it can use the environment variable "TAKTUK_PID" that
           contains the pid of the timeouted command. The given TakTuk command
           can be any valid TakTuk command (without command separator).

       Notice that each timeout can have any number of attached callbacks.
       They will be processed in the order they are given as parameters.

ENVIRONMENT

       Variables that change TakTuk default behavior
           Some of TakTuk defaults settings can be changed on some host using
           environment variables. These settings are propagated as are other
           options.  They are overridden by propagated settings and command
           line options.

           To change some default setting use the variable TAKTUK_NAME where
           NAME is the name of the according long option in upper case and
           with dashes replaced by underscores. For option taking complex
           value (such as "--debug") just add an underscore and the field you
           want to change in upper case at the end of the name.  Using "taktuk
           --print-defaults" will give you examples of names used to change
           default settings.  Note that defining in the environment a default
           setting not used by TakTuk has no effect.

           You can also change some TakTuk default settings locally without
           propagating the change in the deployment tree. To do this, use the
           variable TAKTUK_MY_NAME where name is defined as above. As before,
           these local settings are overridden by propagated settings and
           command line options.

       Variables set by TakTuk in remotely executed commands
           Taktuk sets the following environment variables for all the
           commands it executes :

           TAKTUK_CONTROL_READ, TAKTUK_CONTROL_WRITE
               File descriptors, used internally by TakTuk.

           TAKTUK_COUNT
               The total number of successfully deployed TakTuk instances

           TAKTUK_HOSTNAME
               Local node hostname as given to TakTuk (on the command line)

           TAKTUK_PIDS
               List of pids (separated by spaces) of commands executed by the
               local TakTuk instance.

           TAKTUK_POSITION
               Host position on the command line.

           TAKTUK_RANK
               The logical rank of the local instance

HOSTNAMES SPECIFICATION

       Hostnames given to TakTuk 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 part (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 TakTuk (both with -m or -f 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).

SET SPECIFICATION

       The TakTuk command line and the "taktuk::send" routine accept a set
       specification as destination host(s). A set specification is made of
       interval specifications separated by slashes. An interval specification
       is made of a single number or two numbers separated by a dash. Of
       course the two numbers specifying an interval must be given in
       increasing order.

       The remote peers included in a set specification are all the peer which
       logical number belong to at least one interval of the set. Here are
       some exemples of set specifications :

           1
       the peer numbered 1

           2-7
       the peers numbered 2,3,4,5,6 and 7

           2-4/1/10
       the peers numbered 1,2,3,4 an 10

EXAMPLES

       The following examples illustrate the basic use of TakTuk on a few
       machines and the use of developper options. Notice that TakTuk is
       designed to scale to much more peers than the number involved in these
       examples.

       Basic usage

       simple deployment
           the simplest way to use TakTuk is to make it selfpropagate with
           option "-s". In this case, the basic remote execution of "hostname"
           on the host "toto.nowhere.com" can be written :

               taktuk -s -m toto.nowhere.com broadcast exec [ hostname ]

           In this example, "-s" asks TakTuk to propagate its own code on
           remote hosts. It can be removed by installing the "taktuk"
           executable on "toto.nowhere.com". By the following we will assume
           that TakTuk is installed on all the remote hosts.

           The "-m toto.nowhere.com" describe the set of remote hosts to be
           contacted by TakTuk and "broadcast exec [hostname]" is a command
           that will be executed by the TakTuk interpreter.

           This example can be written in many other ways. In interactive
           mode, the same execution might become:

               taktuk -m toto.nowhere.com

           here TakTuk is blocked waiting for commands from stdin. Thus, we
           just have to type:

               broadcast exec { hostname }
               Ctrl-D

           here you can notice that parameters to the "exec" TakTuk command
           (as all commands parameters) can be enclosed in any reasonable pair
           of delimiters.  We might also write the list of hosts involved in
           the command in a file "machine" that contains:

               toto.nowhere.com

           and the TakTuk command becomes:

               taktuk -f machine broadcast exec - hostname -

           We could also use another file "options" that contains:

               -f machine

           and use it as the options line given to TakTuk:

               taktuk -F options broadcast exec \( hostname \)

           Finally, everything could be stored in a last file "command_line"
           that contains:

               -f machine broadcast exec = hostname =

           and the following command achieve the same result:

               taktuk -F command_line

           All of these variants have the same effect: they execute "hostname"
           on "toto.nowhere.com" and the output of the program is forwarded to
           the localhost. In this case:

               toto.nowhere.com: hostname: somepid: output > toto.nowhere.com

       parameters braces
           notice that braces for command parameters must be separated from
           their content.  Thus, they can contain other braces as long as no
           single closing brace is part of the content:

               taktuk -m localhost broadcast exec [ 'if [ $RANDOM -gt 10000 ];then echo greater;else echo lower;fi' ]

           In this example, quotes are necessary to prevent the shell from
           interpreting the "$" and ";" characters and to prevent the closing
           brace for "if" toe be considered as closing the "exec" command.  In
           this case the variable will be interpolated only on remote hosts.
           This same example can also be expressed using shortcuts and
           intercative mode:

               taktuk -m localhost -E%

           then type:

               b e [ if [ $RANDOM -gt 10000 %];then echo greater;else echo lower;fi ]
               Ctrl-D

           Notice the closing bracket used in the test that should not be
           interpreted as the closing bracket for "exec" arguments. In such
           case, a simpler solution is probably to use another kind of braces

               taktuk -m localhost

           and then:
               b e { if [ $RANDOM -gt 10000 ];then echo greater;else echo
           lower;fi }
               Ctrl-D

           Usually, if you want to be safe, you can quote all commands
           parameters.  Nevertheless, notice that parameters should not be
           quoted in interactive mode as input lines are not interpreted by
           the shell.

       exec parameters
           commands executed by TakTuk can be timeouted using "exec"
           parameters.  For instance if you want to execute some command and
           send it a TERM signal after two seconds, just type:

               taktuk -m localhost broadcast exec timeout 2 [ sleep 10 ]

           the callback executed when a timeout occurs can also be something
           else than a TERM signal. This can be another signal (KILL for
           instance):

               taktuk -m localhost broadcast exec timeout 2 kill 9 [ sleep 10 ]

           or any valid TakTuk command:

               taktuk -m localhost broadcast exec timeout 2 action broadcast exec [ echo hello ] [ sleep 10 ]

           or even several timeouts and several callbacks:

               taktuk -m localhost b e t 2 a e [ echo hello ] k 30 t 10 k 9 [ sleep 5 ]

           in this last example, the command "sleep 5" is executed by TakTuk.
           After 2 seconds, the first timeout will be triggered, it will
           execute the command "echo hello" and send a USR1 signal to the
           first command ("sleep 5"). The second timeout is set to 10 seconds.
           Thus, it will never occur as the "sleep 5" command will be
           terminated before its expiration.

       topology
           Usually, TakTuk deploys itself using a relatively flat tree because
           its default window size is quite large (10 simultaneous ongoing
           connections).  Using a smaller window size will result in a deeper
           tree although it also depends on the local load of the deployment
           nodes.  You can use the TakTuk "network state" command to print the
           tree constructed by TakTuk.

           Notice that it is usually a bad idea to use a too large window as
           it results in too much local load and bad distribution of work
           (something like 10 is often sufficient).

           You can also force TakTuk to use more specific topologies. For
           instance, to execute "echo $$" using a flat-tree as deployment
           topology, just disable work-stealing in TakTuk:

               taktuk -d -1 -m host1 -m host2 -m host3 broadcast exec [ 'echo $$' ]

           and to use a chain-like topology, either encode the topology in
           arguments structure:

               taktuk -m host1 -[ -m host2 -[ -m host3 -] -] broadcast exec [ 'echo $$' ]

           or limits the arity of the dynamic tree to 1:

               taktuk -d 1 -m host1 -m host2 -m host3 broadcast exec [ 'echo $$' ]

           Finally, the default will use a dynamicly constructed topology:

               taktuk -d 0 -m host1 -m host2 -m host3 broadcast exec [ 'echo $$' ]

       lightweight grid deployment
           On a lightweight grid, because of locality issues (ldap cache,
           network topology, ...) it seems interesting to separate the
           deployment of each subcluster. To do this, it is possible to choose
           one node in each subcluster that will be deployed first and from
           which the rest of the cluster will be deployed:

               taktuk -m node1.cluster1 -[ -m node2.cluster1 -m node3.cluster1 -m node4.cluster1 -] -m node1.cluster2 -[ -m node2.cluster2 -m node3.cluster2 -m node4.cluster2 -] broadcast exec [ hostname ]

           This command has the effect of deploying TakTuk on two clusters
           (cluster 1 and 2) made of four nodes (node 1 to 4) using node1 of
           each cluster to deploy the other nodes in the same cluster.
           Finally, once the deployment is complete, it executes the command
           "hostname" on all these nodes.

       executing a distinct command on each host
           each distinct host can be given its own command using arguments:

               ./taktuk -m host1 -[ exec [ hostname ] -] -m host2 -[ exec [ id ] -] -m host3 -[ exec [ 'echo $TAKTUK_RANK; ls' ] -] quit

           but this could also be given using set specification (in this case
           logical number are used for hosts):

               ./taktuk -m host1 -m host3 -m host8 1 exec [ hostname ], 2 exec [ id ], 3 exec [ 'echo $TAKTUK_RANK; ls' ]

           or in interactive mode:

               ./taktuk -m host1 -m host3 -m host8
               1 exec [ hostname ]
               2 exec [ id ]
               3 exec [ echo $TAKTUK_RANK; ls ]
               Ctrl-D

       script diffusion
           spreading and executing a perl script named "essai.pl" on three
           hosts, knowing that "taktuk" and "essai.pl" are only present on the
           root node:

               taktuk -s -m host1 -m host2 -m host3
               broadcast exec [ perl -- - ]
               broadcast input file [ essai.pl ]
               broadcast input close
               Ctrl-D

       files diffusion and collection
           since version 3.4, files transfer is supported directly by TakTuk.
           Notice that this transfer uses the TakTuk network (usually a tree
           composed of ssh connections by default). This network is not
           efficient for the tranfer of large files (both topologically and
           from a protocol point of view), so keep this in mind when using
           this feature.

           copying a file named "message.txt" to the "/tmp" directory of each
           remote host is thus as easy as:

               taktuk -s -m host1 -m host2 -m host3
               broadcast put [ message.txt ] [ /tmp ]
               Ctrl-D

           but the older method still works (and does almost the same as the
           previous command):

               taktuk -s -m host1 -m host2 -m host3
               broadcast exec [ cat - >/tmp/message.txt ]
               broadcast input file [ message.txt ]
               broadcast input close
               Ctrl-D

           although it reuqires to be more careful about shell interpretation
           when typing everything directly on the command line:

               taktuk -s -m host1 -m host2 -m host3  broadcast exec [ 'cat - >/tmp/message.txt' ]\;broadcast input file [ message.txt ]

           notice in this latter command that the "input close" is not
           necessary as TakTuk closes inputs of all spawned commands when
           quiting.

           the "get" command also makes possible things that were previously
           very difficult in TakTuk, files collecting. The following command
           gets the file "/tmp/message.txt" from each remote host and copies
           it locally to "message-number.txt" where "number" is the logical
           rank of the source node:

               taktuk -s -m host1 -m host2 -m host3
               broadcast get [ /tmp/message.txt ] [ message-$rank.txt ]
               Ctrl-D

           finally, it seems important to mention that "put/get" commands can
           copy directories and keep files permissions unchanged.

       communication
           establishing a point-to-point communication. Assume the file
           "communication.pl" contains the following Perl script:

               my $rank = taktuk::get('rank');
               my $count = taktuk::get('count');
               if ($rank == 1)
                 {
                   print "I'm process 1\n";
                   if ($count > 1)
                     {
                       taktuk::send(to=>2, body=>"Hello world");
                     }
                 }
               elsif ($rank == 2)
                 {
                   print "I'm process 2\n";
                   my ($to, $from, $message) = taktuk::recv();
                   print "Process $to received $message from $from\n";
                 }

           then the execution of the following command:

               taktuk -m localhost -m localhost broadcast taktuk_perl [ - ]\;broadcast input file [ communication.pl ]

           would produce an output similar to:

               Astaroth.local: taktuk_perl: 3523: output > I'm process 2
               Astaroth.local: taktuk_perl: 3523: output > Process 2 received Hello world from 1
               Astaroth.local: taktuk_perl: 3523: status > 0
               Astaroth.local: taktuk_perl: 3524: output > I'm process 1
               Astaroth.local: taktuk_perl: 3524: status > 0

           if the file "communication.pl" was placed in the login directory of
           the user, this could have also been executed by the more simple:

               taktuk -m localhost -m localhost broadcast taktuk_perl [ communication.pl ]

       output templates and redirections
           making each site echo its rank without command status information:

               taktuk -o status -m host1 -m host2 broadcast exec [ 'echo $TAKTUK_RANK' ]

           or removing the prompt before each line of output from commands:

               taktuk -o output='"$line\n"' -m host1 -m host2 broadcast exec [ 'echo $TAKTUK_RANK' ]

           or even changing the prompt to make it display only the stream
           type:

               taktuk -o default='"$type > $line\n"' -m host1 -m host2 broadcast exec [ 'echo $TAKTUK_RANK' ]

           and it also possible to redirect the status to file descriptor 2
           only for the second host:

               taktuk -m host1 -R status=2 -m host2 broadcast exec [ 'echo $TAKTUK_RANK' ]

           and so on...

       Developer usage

       debugging TakTuk
           debugging in TakTuk is made using "debug", "warning" and "error"
           functions of the package "diagnostic". These routines, depending on
           the debugging level of the package in which they are called,
           produce an output that is propagated up to the root node and
           printed on screen.

           By default the debugging level of packages is set to 2 (everything
           is printed out except "debug" messages). It might be changed for
           each package using the -D option. For instance the following code
           executes "true" on "toto.nowhere.com" and prints out every bit of
           internal messaging:

               taktuk -D default=1 -m toto.nowhere.com broadcast exec [ true ]

           but one could have executed the same command keeping only messages
           from the "scheduler" package:

               taktuk -D scheduler=1 -m toto.nowhere.com broadcast exec [ true ]

           or ensuring an  execution exempted of any warning or error
           messages:

               taktuk -D default=4 -m toto.nowhere.com broadcast exec [ true ]

       internal messages server
           the internal message server used in TakTuk for the management of
           logical network construction, commands execution and I/O forwarding
           can be exposed using the -r option:

               taktuk -r

           Notice that in this mode the behavior of TakTuk can seem very
           cryptic. This is not intended for ordinary users.

BUGS

       The development of TakTuk is still in progress, so there are propably
       numbers of bugs. For now, the following characteristics (some of them
       are not really bugs) have been identified :

       hanged commands
           currently TakTuk do not quit (even if asked to do so) if some local
           commands do not terminate upon the closing of their standard input.
           Interrupting TakTuk actually terminate the engine but do not kill
           these commands. We still have to decide if this is the appropriate
           behavior.

       command order
           broadcasts and multicast (set specifications) are not synchronized
           the same way in TakTuk. Thus, broadcast commands given after
           multicast commands might be executed before these last ones. Use
           the "synchronize" command to avoid this.

       synchronized network state
           implementation of the "synchronize" command do not allow a proper
           synchronization of the "network state" command. This might change
           in the future but is not in the priority list.

       slow connections
           this is not really a bug : on some clusters, the connections are
           VERY slow when doing a large deployment (over 50 nodes) with self
           propagation.  This result in a total time for the deployment of 50
           nodes that can take several minutes (up to half an hours in some
           cases).  I don’t know what’s the exact cause (ldap ? local load ?
           writes block ?) but it can be fixed by adding connection timeouts
           to connectors.

       fork failures
           this is not really a bug : when a machine is highly loaded, fork
           may fail.  If this happen to a local command, a distributed
           application may deadlock, because the taktuk instances numbering is
           correct but some instance didn’t fork the local command.  The
           simplest fix is to use timeouts on taktuk::recv().

       You might also want to have a look at:

           http://taktuk.gforge.inria.fr/Bugs.txt

       where all the temporary bugs are listed version by version.

SEE ALSO

       taktukcomm(3)

AUTHOR

       The original concept of TakTuk has been proposed by Cyrille Martin in
       his PhD thesis. People involved in this work include Jacques Briat,
       Olivier Richard, Thierry Gautier and Guillaume Huard.

       The author of the version 3 (perl version) and current maintainer of
       the package is Guillaume Huard.

COPYRIGHT

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