Login credentials

rex edit

This command starts the editor defined by the VISUAL (or, if unset, EDITOR) environment variable. Upon exit from the editor, it compares the new content with the existing one. If changed, the user is prompted whether they wish to save the changes.

The database is a dictionary of key-value pairs. A key identifies the credential (e.g. user, for username, or pass, for password). Unless prefixed with one or more qualifiers, it is valid for all servers in all hostgroups. Qualifiers limit the scope of a key to a given hostgroup or server.

In general, the syntax for a key is:

[[GROUP:][HOST]:]KEYWORD

When looking for a key, the most qualified match is preferred, so the lookup order is:

For example, to determine the login name for the given host, rex looks up for the keyword user. If no matching key is found and the the -u (--user) option is given, its value is used. Otherwise, the name of the value of the environment variable USER is used.

Similarly, the password to use is determined by the following look-ups:

If none of these keys is found, the value of the -p (--password) option is used. If this option is not supplied either, passwordless account is assumed.

Configuration files

/usr/local/etc/rex/rc

System-wide configuration file.

~/.rex/rc

User-specific configuration file.

These files are not required to exist. If they do the user settings override the system-wide ones.

These files are sourced as regular TCL code. Normally, they modify the rex settings by using a st of commands provided for that purpose:

host HOSTNAME [HOSTNAME...]

Adds the listed hostnames to the list of hosts.

hostname IP NAME

Registers NAME in DNS cache as a hostname for the IPv4 address IP. This is useful if IP has no PTR record, or its PTR record is deemed unsuitable for some reason.

ifmode { mode body [mode body...] }

Matches the current mode against each of mode arguments. As soon as the match is found, the corresponding body is evaluated. Similarly to the switch(n) command, a dash in place of body means that the body for the next mode should also be used as the body for this one. If the next mode has a body of "-", than the body after that is used, etc.) The mode should be one of the following: run, copy-to, copy-from, login, list, and edit. If the last mode used is the word default, it will match any mode not explicitly listed before.

The ifmode pattern allows for selecting different settings depending on the running mode. For example, it is common to set the TERM environment variable to dumb for run mode. However, it is undesirable in login and edit modes, and has no effect on the remaining modes. To make sure it is set only for run mode, the following statement is normally used:

ifmode {
  run { environ TERM=dump }
}

option OPTNAME VALUE [VALUE...]

Sets or unsets a rex option. OPTNAME is the long name of the option without the leading two dashes. For example, setting

option jobs 25

option no-resolve true

timeout [NUMBER]

Sets the timeout for expecting reply from the remote commands. NUMBER is the timeout value in seconds. When used without arguments, returns the current timeout value.

environ [-set] NAME=VALUE [NAME=VALUE...]

Sets environment variables.

environ -unset NAME [NAME...]

Unsets environment variables.

earlycmd [-clear] COMMAND [COMMAND...]

Defines the sequence of shell commands that will be sent as soon as the secure connection to the remote host is established, before waiting for the command line prompt. For an example of its use, see the note about ZSH, below.

shrc [-clear] COMMAND [COMMAND...]

Defines the sequence of shell commands that will be sent after receiving the first command line prompt from the remote server.

Hostgroups

The hostgroup rc file should use the host and/or hostgroup commands (see the subsection Configuration files above) to define the list of hosts in the hostgroup.

Debugging

Additional information is provided by the -l (--log) option, which enables logging of the send/expect dialog to stdout.

If you wish to get even more information and are familiar with expect(1) internals, set the EXPECT_DEBUG environment variable prior to invoking rex. The value of this variable is the name of a file where to output additional information (as well as showing it on the standard error). Overall effect is equivalent to setting exp_internal in expect.

When rex encounters an error in one of its rc files, it prints the location where the error occurred and a short diagnostic message describing the nature of the error. If you wish to obtain full trace of TCL calls for such errors, use the --tcl-trace option. Normally, this option is only useful for rex developers.

Sequential and parallel execution

The --no-host-header option disables printing of that header line. The -P (--prefix) option further modifies the output by prefixing each line with the hostname, a greater than sign, and a space character.

When operating on a big number of hosts, the operation can be sped up by running command on several hosts at once. This parallel operation is enabled by the -jN (--jobs=N) option. The N parameter is the number of hosts to be processed in a batch.

The -j option implies --prefix --no-host-header to make it clear which host produced which line. However, if the command produces multiple lines of output, they become intermixed when running in parallel. To further improve readability of the output, the -b (--buffer-output) option is provided.

This option instructs rex to buffer output from each host in the batch and to output it only after the host closes connection. This way, output from each host appears on screen as a contiguous text.

The -b option cancels the implied --prefix --no-host-header settings.

Transferring data prior to execution

To transfer multiple files, repeat the -D option for each of them.

The files supplied with the -D options will be copied to a temporary directory created in /tmp on each target host. That directory will become current working directory when invoking the PROGRAM.

The arguments to PROGRAM can refer to the files transferred via the -D option using the syntax {N}, where N is the number of the -D option occurrence (1-based). The {N} is expanded to the file name part of the argument to the corresponding -D option. For example,

rex run -D prefix.txt -D repl sed -f {2} {1} /etc/passwd

will result in running the following command in a temporary directory on each target host:

sed -f repl prefix.txt /etc/passwd

Note, that the {N} notation expands to a file name relative to the current working directory on the remote host. This means that

rex run -D /tmp/prefix.txt -D repl sed -f {2} {1} /etc/passwd

will result in exactly the same command as the example above: the expansion of {1} will throw away the directory part from the file name.

Similarly, the token {} expands to a space-separated list of file names passed with all -D options, in the same order they appear on the command line.

The PROGRAM itself can be an interpreted script that needs to be copied on each host for execution. The --copy option instructs rex to create a temporary directory on the remote host, copy PROGRAM there, and then select the interpreter to run by analyzing the first line from it. If this line starts with characters #!, the rest of line is taken as the interpreter pathname and initial arguments. For example, assuming that file /libexec/foo is a shell script beginning with #!/bin/ksh, the following command:

rex run --copy /libexec/foo /home

will first copy the file /libexec/foo to a temporary directory on the remote host, and then invoke it as

/bin/ksh foo /home

If the file does not begin with #!, the default interpreter,
/bin/sh, will be used.  The default interpreter can be changed
using the --interpreter option, as in the following example:

rex run --copy --interpreter="/bin/env perl" test.pl

Scripting

The default library search path is:

If the -g GROUP (--group=GROUP) option is given, the path is modified as follows:

The following functions from the hostproc namespace are used by rex:

proc prologue {}

Called at the very beginning of rex invocation, after analyzing the command line options, but before parsing the remaining command line arguments.

This function can be used to initialize internal variables. It is also allowed to modify the global config array (see the section CONFIG ARRAY, below).

In the following example, prologue is used to set up the command line:

proc prologue {} {
    global config
    set config(argv) {ls -ld /home}
}    

proc epilogue {}

Called after processing all hosts.

It an be used for application-specific cleanup.

proc transition {host state}

Called when the session for $host is switched to the state $state. Currently implemented states are:

proc transition {host state} {
    if {$state == "INIT"} {
        puts -nonewline stderr "$host... "
    } elseif {$state == "LOGOUT"} {
        puts "done"
    }
}

proc getline {host line}

Invoked each time a new line of output is received from the host. The host parameter is the name of the host. The $line parameter is the line received from the host (with trailing CRLF characters).

proc finish {host refname status}

The finish function is called when EOF has been received from the host. The refname parameter is a name of the variable keeping the entire text received from that host during the session. This variable exists only if rex has been instructed to buffer host output (see the -b option). If it exists, the output text is stored as a list of lines. The status parameter is the exit status of the command.

REX RUN OPTIONS

-b, --buffer-output

Output from servers is buffered and printed only when the job is finished. When running several jobs in parallel (see --jobs option below), output lines from the concurrent jobs are printed as they arrive and can therefore appear on the screen intermixed. This option ensures that output from each server is printed as a contiguous block of text instead.

--copy

copy PROGRAM to each host before executing

-D, --data-file=FILE

Declares FILE as a data file which will be used by COMMAND. The file will be copied to each host prior to running the command on it.

Multiple files can be specified by repeating the -D option as many times as needed.

If -D FILE option is given, the string {} passed as one of the ARGS is replaced by FILE on the target machine. If several -D options are given, {} is replaced by their arguments. For example, the command rex run -D a -D b proc {} copies files a and b to the target machine and then runs the command proc a b.

-g, --group=NAME

Select host group.

-h, --help

Display short help summary.

-H, --host=HOST[,NAME...]

Add HOST to the list. Multiple hosts can be specified as a comma-delimited list (no whitespace around commas, please).

-i, --ignore-hosts

Ignore the list of hosts read from the hostgroup file. Operate only on hosts supplied in the command line (see the --host option, above). This is useful to preserve the settings from the hostgroup file while running the command on the hosts defined on the command line.

-I, --interactive

Interactively ask for missing usernames and passwords.

--interpreter=COMMAND

Use COMMAND as interpreter for running PROGRAM. This option implies --copy. By default, rex deduces the interpreter to use from the first line of PROGRAM.

-j, --jobs=N

Run N jobs at once. Implies --no-host-header --prefix.

--no-host-header

Don't print hostname before output from the host.

-p, --password=PWD

Set default password (unsafe!)

-P, --prefix

Prefix each output line with the host name or IP.

-s, --source=NAME

Source .rex/NAME.tcl after reading configuration files.

--sudo

Run the command via sudo(1).

-u, --user=NAME

Set default user name.

-w, --confirm

Prompt and wait for confirmation before each host.

-X, --exclude-host=HOST[,NAME...]

Remove HOST from the list. Multiple hosts can be specified as a comma-delimited list (no whitespace around commas, please).

-Z, --zsh-quirk

Try to cope with hosts running zsh(1).

Unless special measures are taken, the output produced by zsh is heavily contaminated with special escape sequences, which makes it almost impossible to recognize command line prompts.

The -Z option forces rex to set TERM=dumb. Then, if no command line prompt is seen within the predefined interval, rex will try to disable ZLE option, set PS1 to a dollar sign followed by space and will retry scanning. This allows for properly recognizing command line prompts returned by zsh at the expense of a certain slowdown. See the subsection ZSH below for more efficient ways of handling zsh.

REX COPY OPTIONS

-g, --group=NAME

Select host group.

-h, --help

Display short help summary.

-H, --host=HOST[,NAME...]

Add HOST to the list. Multiple hosts can be specified as a comma-delimited list (no whitespace around commas, please).

-i, --ignore-hosts

Ignore the list of hosts read from the hostgroup file. Operate only on hosts supplied in the command line (see the --host option, above). This is useful to preserve the settings from the hostgroup file while executing the command on the hosts defined on the command line.

-I, --interactive

Interactively ask for missing usernames and passwords.

-j, --jobs=N

Run N jobs at once. Implies --no-host-header --prefix.

-p, --password=PWD

Set default password (unsafe!)

-P, --prefix

Prefix each output line with the host name or IP.

--sudo

Switch to root privileges before copying to DEST. Technically, speaking, the command

rex copy --sudo FILE DEST

is equivalent to

rex run -D FILE sudo cp {} DEST

-u, --user=NAME

Set default user name.

-w, --confirm

Prompt and wait for confirmation before proceeding with each host.

-X, --exclude-host=HOST[,NAME...]

Remove HOST from the list. Multiple hosts can be specified as a comma-delimited list (no whitespace around commas, please).

REX COPY-FROM OPTIONS

-I, --interactive

Interactively ask for missing usernames and passwords.

-p, --password=PWD

Set default password (unsafe!)

-u, --user=NAME

Set default user name.

-h, --help

Display short help summary.

REX LOGIN OPTIONS

-I, --interactive

Interactively ask for missing usernames and passwords.

-p, --password=PWD

Set default password (unsafe!)

-u, --user=NAME

Set default user name.

-Z, --zsh-quirk

Try to cope with hosts running zsh(1). See the description of this option in subsection REX RUN OPTIONS.

-h, --help

Display short help summary.

REX LIST OPTIONS

-h, --help

Display a short help summary.

-H, --host=HOST[,NAME...]

Add HOST to the list. Multiple hosts can be specified as a comma-delimited list (no whitespace around commas, please).

-i, --ignore-hosts

Ignore the list of hosts read from the hostgroup file. Operate only on hosts supplied in the command line (see the --host option, above). This is useful to preserve the settings from the hostgroup file while executing the command on the hosts defined on the command line.

-X, --exclude-host=HOST[,NAME...]

Remove HOST from the list. Multiple hosts can be specified as a comma-delimited list (no whitespace around commas, please).

Additionally, the -h, or --help option displays a short help summary.

Disabling command history

The exact list of commands depends on the shell that the remote uses.

The simplest way, common for bash, ksh, and zsh is:

shrc HISTFILE=/dev/null

Similar setting for csh(1) or tcsh(1) is:

shrc {set histfile=/dev/null}

The drawback of this approach is that the assignment itself and all the built-in commands sent by rex are still retained in history.

A more sophisticated way, suitable for both bash and zsh shells is:

shrc {
     if test -n "$HISTFILE" && test -f "$HISTFILE"; \
     then \
       mv $HISTFILE ${HISTFILE}~; \
       head -n -1 ${HISTFILE}~ > $HISTFILE; \
     fi} \
     {unset HISTFILE}

It removes the most recent line from the history file and unsets the HISTFILE variable, thereby preventing the shell from further updating it.

(The most recent line contains the command stty -echo, sent by rex at the beginning of each session.)

To set history cleaning on a per-host (or per-hostgroup) basis, use the shrc key in the rex database file.

ZSH

An ad-hoc way of coping with hosts running zsh is provided by the -Z (--zsh-quirk) command line option. However, it is convenient only for casual usage, because of the slowdown it imposes.

The proper way of handling zsh hosts is by configuring the earlycmd setting. This configuration setting declares a list of commands that rex is to send as early as it sees the very first line of output from the host.

If all your hosts run zsh, add the following to your rc file:

ifmode {
  run {
    environ TERM=dumb
  }
}  
earlycmd {unsetopt ZLE} {PS1='$ '}

This will disable the zle module, which is the cause of all evil (TM), reset terminal defaults to decent values and set a proper command line prompt.

If only some of your hosts run zsh, you can set the earlycmd option in the rex database file, using the earlycmd key, either for hostgroup or for individual hosts.

The value of that option is a whitespace-separated list of TCL strings.

For example, if the account on host baboo runs zsh, run rex edit and add the following line:

baboo:earlycmd   {unsetopt ZLE} {PS1='$ '}

Notice that you will still need to have

environ TERM=dumb

in your rc file.