table of contents
TAKTUK(1) | TakTuk Deployment Engine | TAKTUK(1) |
NAME¶
TakTuk - a tool for large scale remote execution deploymentSYNOPSIS¶
taktuk [-behinsvzMP] [-c connector] [-d limit] [-f filename] [ -g duration] [-l login] [-m hostname [ -[ args ... -]]] [ -o stream=template] [-t timeout] [ -u limit] [-w size] [ -B parameter=expression] [ -C separators] [-E character] [ -F filename] [ -G hostname [-[ args ... -]]] [-L hostname] [ -I interpreter] [-O separators] [-R stream=filename] [ -S files] [ -T command] [-V path ] [ -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 TakTuk(3) and taktukcomm(3) respectively.OPTIONS¶
Caution, in TakTuk options are parsed in the order given on the command 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¶
- -b
- --begin-group
- begins a new deployment group. A deployment group acts both as a context for most options (options set within a group have no effect outside the group) and as an isolation for deployment tasks scheduling (deployment tasks within a group cannot be stolen by nodes deployed in other groups).
- -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 with positive values on the same command line.
- -e
- --end-group
- ends a deployment group.
- -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.
- -G hostname
- --gateway hostname
- same as -m hostname, except that the deployed node(s) are considered as forward-only nodes: they will not be numbered and will not be targeted by subsequent diffusion commands. As an exception, execution of TakTuk commands on those nodes is still possible by giving them as deployment arguments of the -G option.
- -I command
- --perl-interpreter command
- "command" is the name of the command to use as a Perl interpreter when auto propagating or when using the "taktuk_perl" command.
- -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 (rather use the "put" command to transfer such files). This option should be used to transfer files that are necessary to perform further connections from the remote node. "files" is a comma separated list of pairs "local_file:remote_file". Regarding the transfer itself, 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.
- -V list
- --path-value list
- set the PATH environment variable to the given list (as usual, a colon separated directories list) on remote hosts to which TakTuk connects. This is performed very early and is taken into account even for "taktuk" or "perl" invocations at connection time.
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 information 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 information outputed by executed command to stdout or stderr (respectively). Relevant fields include $host, $command, $pid and others listed below.
- "info" (general information such as help summary or version)
- this stream contains in $line information outputed by taktuk in response to commands such as "help" or "version".
- "message" (messages from running processes)
- each output of this stream contains in $line a message sent with target "output" (through TakTuk out-of-band communications facilities) by some processus started using TakTuk commands. Relevant fields for this stream include $from and $to and others listed below.
- "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 16 - file send failed 17 - Invalid target 18 - No target 19 - Message delivered 20 - Invalid destination 21 - Destination not available anymore 22 - Wait complete 23 - Wait reduce complete
- "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.
- $command (not for "taktuk" nor "info")
- the command line execution that generated output.
- $count
- the total number of TakTuk instances.
- $eol
- 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.
- $from ("message" only)
- the logical number of the TakTuk instance from which the message has been sent.
- $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 $eol).
- $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).
- $peers_given ("state" only)
- a space separated list of remote nodes that has been given to the remote peer for deployment (whatever their deployment state). Each remote node is specified as a colon separated couple made of its hostname and its position on the command line. This variable has only a meaningful value when the event outputed to the stream "state" is a connection loss (event number 5).
- $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()).
- $init_date ("connector" and "state" only)
- the time in seconds since Jan. 1, 1970 at which the remote TakTuk completed its initilization.
- $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).
- $to ("message" only)
- the logical number (or set of such numbers) of the TakTuk instance to which the message has been sent.
- $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.
- -R stream=filename
- --output-redirect stream=filename
- redirect a given stream output to a given file (located at the root node). Notice that the given filename comply with Perl open syntax: for instance, one might redirect to a file descriptor X using the name ">&=X". See "-o" option for more details about streams output.
PERFORMANCE TUNING OPTIONS¶
- -B parameter=expression
- --worksteal-behavior parameter=expression
- caution: this feature should be considered as experimental and could be removed from future releases. Tunes finely the behavior of the work-stealing algorithm by setting some its parameters to Perl expressions. These Perl expressions can use the variables $last_given and $available which are respectively equal to the number of tasks given to a stealer last time it stole and to the total number of remaining deployment tasks. Available parameters are :
- initial
- the number of tasks given to a remote TakTuk instance the first time it send a steal request to the local host.
- growth
- the number of tasks given to a remote TakTuk instance each time it performs a steal to the local host after the first time.
- limit
- an upper bound to the value resulting from the evaluation of "growth".
- -g duration
- --time-granularity duration
- sets to "duration" (in seconds) 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.
- -t timeout
- --timeout timeout
- sets the timeout (in seconds) 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.
- -u limit
- --cache-limit limit
- limits a number of memory bytes TakTuk might use as
an internal write buffer. For most users, setting such a limit is a bad
idea : in some rare situations it might result in a deadlock in
TakTuk (caused by parallel blocking writes between an application
and TakTuk itself). Setting this option to a negative value
disables the limit (default).
- -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 AND TARGETS 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. 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 [ target target ] * data *
- input [ target target ] data * data *
- Sends the given data as input to commands in execution on the local machine as specified by the given target. If no target is given, the data is sent to all commands. For more details about targets, see "SET AND TARGETS SPECIFICATION"
- input [ target target ] close
- Closes the inputs descriptor of executing commands on the local machine as specified by the given target. If no target is given, the inputs of all commands are closed.
- input [ target target ] file * filename *
- Sends the content of a file (which must be local to the
node executing the input file) as input to commands in execution on the
local machine as specified by the given target. If no target is given, the
data is sent to all commands.
- input [ target target ] line * data *
- Sends the given data with an additional newline as input to commands in execution on the local machine as specified by the given target. If no target is given, the data is sent to all commands.
- input [ target target ] pipe * filename *
- Treat the parameter as a file (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. If given, the target specifies to which command the data are to be sent, otherwise it is sent to all commands.
- kill [ target target ] <signal>
- Sends the given signal to local commands processes groups. If no signal is given, sends a TERM signal (signal 15). If given, the target specifies to which command the signal is to be sent, otherwise it is sent to all commands. For more details about targets, see "SET AND TARGETS SPECIFICATION"
- message [ target target ] * data *
- message [ target target ] data * data *
- Sends the given data as a message to commands in execution on the local machine as specified by the given target (see TakTuk(3) and taktukcomm(3) for more details about messages). If no target is given, the data is sent to the first command peforming a receive and not already targeted by another message. For more details about targets, see "SET AND TARGETS SPECIFICATION"
- message [ target target ] file * filename *
- Sends the content of a file (which must be local to the
node executing the message file) as a message to commands in execution on
the local machine as specified by the given target (see TakTuk(3) and
taktukcomm(3) for more details about messages). If no target is given, the
data is sent to the first command peforming a receive and not already
targeted by another message.
- message [ target target ] line * data *
- Sends the given data with an additional newline as a message to commands in execution on the local machine as specified by the given target (see TakTuk(3) and taktukcomm(3) for more details about messages). If no target is given, the data is sent to the first command peforming a receive and not already targeted by another message.
- message [ target target ] 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 a message to commands when available (see TakTuk(3) and taktukcomm(3) for more details about messages). If given, the target specifies to which command the data are to be sent, otherwise it is sent to the first command peforming a receive and not already targeted by another message.
- 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.
- 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 command
- Forces the given command to wait for the completion of deployment, nodes numbering and previous commands before executing. This is useful for global commands like "broadcast" which does not wait for nodes numbering. In contrary, multicast commands (those that use a set specification as a prefix) wait for the nodes numbering and the completion of previous commands. If in doubt, always use "synchronize" before a "broadcast", "downcast" or "wait reduce".
- taktuk_perl * arguments *
- Forks a perl interpreter on the local node just as if the command "exec perl arguments" has 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.
- wait target target
- Waits (suspends the execution of following commands) in the local TakTuk instance for the completion of some local process depending on the given target. This target might be any target specification except "output". For more details about targets, see "SET AND TARGETS SPECIFICATION".
- wait reduce target target
- Can only be used in the root node. Waits (suspends the execution of following commands) for the completion of some processes in all the deployed TakTuk instances depending on the given target. This target might be any target specification except "output". Notice that, contrary to simple "wait" commands, this command is synchronized the same way as "broadcast". Thus, it should be explicitly synchronized if mixed with non broadcasted commands (otherwise it will be executed before them).
EXEC PARAMETERS¶
The TakTuk command "exec" accepts optional parameters. These parameters are used to specify a target id for the command, or 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:- target value
- Attach the (numerical) value as the target id of the
executed command. This target id will be used by any subsequent command
that make use of targets (such as "input", "message",
"kill" or "wait").
- 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).
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.
- 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_TARGET
- Target number of the currently executing process (see "SET AND TARGETS SPECIFICATION" for more details).
- TAKTUK_POSITION
- Host position on the command line.
- TAKTUK_RANK
- The logical rank of the local instance.
- TAKTUK_FATHER
- The logical rank of the taktuk instance that spawned this one.
- TAKTUK_CHILD_MIN
- The logical rank of the lowest numbered descendent from the current taktuk instance (-1 if the local TakTuk instance has no children).
- TAKTUK_CHILD_MAX
- The logical rank of the highest numbered descendent from the current taktuk instance (-1 if the local TakTuk instance has no children).
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 AND TARGETS 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 either made of a single number, two numbers separated by a dash or a single number followed by a plus symbol (this last case match the interval that goes from the number to the highest numbered TakTuk destination). 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 3+ the peers from 3 to the highest numbered 5+/1 the peers from 5 to the highest numbered and the peer 1The target number is a number assigned by TakTuk to all processes it executes (successfully started or not using "exec" or "taktuk_perl" commands). By default, this number starts from 0 and goes to the total number of processes that have been executed since TakTuk launch minus one. Target processes of a "TakTuk::send" or a TakTuk command can be expressed with the same syntax as in the case of sets. Furthermore, TakTuk understands several special targets. The special target "all" targets all processes: this means that the command is applied to all executing local processes (message or input data are duplicated and sent to all of them), this is the default for the "input" and "kill" commands. The special target "any" targets the first eligible process. In the case of a message this is the first process that issues a "TakTuk::recv" and that is not already the target of another message, this is the default for the "message" command. Finally, the special target "output" targets the output stream "message" rather than a process.
EXAMPLES¶
The following examples illustrate the basic use of TakTuk on a few machines and the use of developer 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 ]
taktuk -m toto.nowhere.com
broadcast exec { hostname } Ctrl-D
toto.nowhere.com
taktuk -f machine broadcast exec - hostname -
-f machine
taktuk -F options broadcast exec \( hostname \)
-f machine broadcast exec = hostname =
taktuk -F command_line
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' ]
taktuk -m localhost -E%
b e [ if [ $RANDOM -gt 10000 %];then echo greater;else echo lower;fi ] Ctrl-D
taktuk -m localhost
b e { if [ $RANDOM -gt 10000 ];then echo greater;else echo lower;fi }
Ctrl-D
- 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 ]
taktuk -m localhost broadcast exec timeout 2 kill 9 [ sleep 10 ]
taktuk -m localhost broadcast exec timeout 2 action broadcast exec [ echo hello ] [ sleep 10 ]
taktuk -m localhost b e t 2 a e [ echo hello ] k 30 t 10 k 9 [ sleep 5 ]
- 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.
taktuk -d -1 -m host1 -m host2 -m host3 broadcast exec [ 'echo $$' ]
taktuk -m host1 -[ -m host2 -[ -m host3 -] -] broadcast exec [ 'echo $$' ]
taktuk -d 1 -m host1 -m host2 -m host3 broadcast exec [ 'echo $$' ]
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 enclose the
nodes of each cluster into a separate deployment group:
taktuk -b -m node1.cluster1 -m node2.cluster1 -m node3.cluster1 -m node4.cluster1 -e -b -m node1.cluster2 -m node2.cluster2 -m node3.cluster2 -m node4.cluster2 -e broadcast exec [ hostname ]
- 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
./taktuk -m host1 -m host3 -m host8 1 exec [ hostname ], 2 exec [ id ], 3 exec [ 'echo $TAKTUK_RANK; ls' ]
./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 is straightforward
with TakTuk:
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.
taktuk -s -m host1 -m host2 -m host3 broadcast put [ message.txt ] [ /tmp ] Ctrl-D
taktuk -s -m host1 -m host2 -m host3 broadcast exec [ cat - >/tmp/message.txt ] broadcast input file [ message.txt ] broadcast input close Ctrl-D
taktuk -s -m host1 -m host2 -m host3 broadcast exec [ 'cat - >/tmp/message.txt' ]\;broadcast input file [ message.txt ]
taktuk -s -m host1 -m host2 -m host3 broadcast get [ /tmp/message.txt ] [ message-$rank.txt ] Ctrl-D
- communication
- TakTuk can also be used to establish 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 ($from, $message) = TakTuk::recv(); print "Process $to received $message from $from\n"; }
taktuk -m localhost -m localhost broadcast taktuk_perl [ - ]\;broadcast input file [ communication.pl ]
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
taktuk -m localhost -m localhost broadcast taktuk_perl [ communication.pl ]
- output templates and redirections
- TakTuk is also capable of making each site echo its
rank without command status information:
taktuk -o status -m host1 -m host2 broadcast exec [ 'echo $TAKTUK_RANK' ]
taktuk -o output='"$line\n"' -m host1 -m host2 broadcast exec [ 'echo $TAKTUK_RANK' ]
taktuk -o default='"$type > $line\n"' -m host1 -m host2 broadcast exec [ 'echo $TAKTUK_RANK' ]
taktuk -m host1 -R status=2 -m host2 broadcast exec [ 'echo $TAKTUK_RANK' ]
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.
taktuk -D default=1 -m toto.nowhere.com broadcast exec [ true ]
taktuk -D scheduler=1 -m toto.nowhere.com broadcast exec [ true ]
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
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.
- 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()".
http://taktuk.gforge.inria.fr/Bugs.txtwhere all the temporary bugs are listed version by version.
SEE ALSO¶
taktukcomm(3), TakTuk(3), TakTuk::Pilot(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.2012-06-11 | perl v5.14.2 |