ntred - controller/hub/client interface to a cluster of btred servers
To query the servers:
ntred [-m|-I macro-file] [-e code] [--hub hub] [--port port] [-N|-H] [-T] [--key-file file] [--filelist file-list ] [-L files] -- script-arguments
To start remote servers and a hub:
ntred -i [--servers server[,server,...]] [--serverlist server-list] [--filelist file-list] [--max-servers num] [--allow-no-trees] [--no-secondary-files] [--no-server-check] [--no-server-start] [--no-hub-start] [--old-dist-method] [--safe-mode] [--server-debug] [-m|-I macro-file] [--disable-extensions list] [--enable-extensions list] [-M module] [--btred path-to-btred] [--ssh ssh-command] [--local] [--key-file] [--hub hub] [--port port] [file [...]]
To close all remote servers and a hub:
ntred --quit|--ps-quit
To kill all remote servers and a hub:
ntred --kill|--ps-kill
To manage files on the servers:
ntred --list-files|--list-changed-files ntred --reload-files [--disable-extensions list] [--enable-extensions list] ntred --reload-macros [-m macro-file] ntred --load-files [--filelist file-list] [file [...]] ntred --close-files ntred --save-files|--save-changed-files [-s strip-sfx] [-a append-sfx] [-p strip-prefix] [-r add-prefix] [-f out-fmt] ntred --dump-files [--filelist file-list] [file [...]] ntred --upload-file filename < fs-file
Get help:
ntred -u for usage (synopsis) ntred -h for help ntred --man for the manual page
This program is able to start one or more btred servers on a set of
host machines over SSH, create a proxy hub to provide the
communication between the servers and a client, distribute given files
over the servers (provided the servers are able to load the files from
given filenames (eg. they share the files over NFS), query the servers
using a btred-macro and collect the answers. It is highly recommended
to use some password-free authentication method for SSH (e.g. Kerberos
or ssh-agent
), so that password input is not required each time the
SSH connection is made (at least two per-host).
In the client mode, the standard output of the macro is printed to
STDOUT of the client. STDERR is reserved for debugging and information
messages as well as error messages caused by the macros on the
servers. The rest of the error output from a server is stored in a
file <logdir>/ntred-server-<host>.log (where <logdir> can be specified
using --logdir
, NTRED_LOGDIR or TMP or TEMP environment variable
and defaults to /tmp if none of the previous exists).
Options for ntred can be specified on the command line or in a config file (default is ~/.ntredrc, but --ntred-config-file option can be use to set a custom config file). The format of this file is simple: each non-empty line should be of the form:
option = value
with leading and trailing white-space ignored and with all characters following a '#' ignored. Option names for the config file are the same as command-line options, but without leading - or --.
ntred [-m macro-file] [-e code] [--hub hub] [--port port] [-N|-H] [-T] [--key-file file] -- script-arguments
This is the query to be executed on the remote servers. It usually
either of a name of the macro defined in the file given as
--macro-file
or some Perl one-liner. If omitted, it defaults to
'autostart()' and a macro with this name must be defined in
the macro file provided..
A file containing macros that are to be sent to the servers and
preloaded on the servers before the particular query code is
evaluated. The query code to be evaluated must be specified in
--execute
.
Note that servers already have the set of macros they obtained on
startup (i.e. --init): it is namely either the default set of
macros (tred.mac
) or the set specified via --macro-file, and beside one of
these also the set specified via --include-macro-file.
A file containing additional set of macros to be sent to the servers.
In query mode, this option behaves just like --macro-file
and is
only provided for compatibility with btred
. If both these options
are used, both sets of macros are loaded.
The hostname of the hub to connect to (defaults to localhost).
The port on which the hub is listening (defaults to 1500).
Run the query code on all trees (wrapping the code into a
if ($root) { do {{ CODE }} while TredMacro::NextTree() }
loop).
Run the query code on all nodes (you still must use --all-trees or -T
to process all trees) (wrapping the code into a
while ($this) { CODE ; $this=$this-
following }";> loop).
Run the query code on all nodes that are not hidden (you still must
use --all-trees or -T to process all trees). This wraps
the code into a
while ($this) { CODE ; $this=$this-
following_visible(FS()) }";> loop).
Run the query code only on files specified on the command line (provided they are already present on some server, i.e. this option does not make servers load files they don't already have). Filenames may contain ordinary TrEd suffixes of the form ##tree or ##tree.node to indicate that the processing should apply only on a single tree (use in combination with -N) or a single node (use without -T and -N). NTrEd URIs of the form ntred:// are also allowed. Relative file-names are expanded according to the current working directory before they are sent to ntred servers.
Run the query code only on files whose filenames match a given regular expression.
Like --listed-files|-L
but this time the files to be processed are
listed in the given file rather than on the command line. Both options
may be used together in which case the file-lists are joined.
This option may be used to provide a file with a session-key which is necessary for the authentication to the running hub. This defaults to `~/.ntred_session_key'.
ntred -i [--servers server[,server,...]] [--serverlist server-list] [--filelist file-list] [--max-servers num] [--no-secondary-files] [--no-server-check] [--no-server-start] [--no-hub-start] [--old-dist-method] [--safe-mode] [--server-debug] [--max-retries num] [-m macro-file] [-M module] [--btred path-to-btred] [--ssh ssh-command] [--local] [--key-file file] [--hub hub] [--port port] [file [...]]
A comma separated list of hosts to run btred servers. The hostname may
be optionally followed by a comma and a port number thus making it
possible to run several btred servers on one host. If the port number
is omitted, it defaults to 1600. See also --serverlist
.
Ports may be given as a range, e.g. 1600-1800; in this case btred server will use the first port from the range that is free.
Special syntax can be used to start btred servers over SGE cluster using the task queue (qsub and qdel commands must be in PATH):
qsub://<job_prefix>:<port_range>
In this case ntred schedules one btred server task on the SGE queue
for each port in the range. It waits at most two seconds times
--max-retries
for the first server to start. Tasks of the servers
that are not running by that time are abandoned and deleted from the
queue.
This provides more convenient way to specify servers by providing a
file containing a list of servers, one per line. If neither
--servers
nor --serverlist
is
provided, then the list of servers is read from ~/.ntred_serverlist.
A list of files to distribute between servers (one filename per line). Additional files may be given as command-line arguments.
Don't load "secondary" files along with normal files (a file may require other - secondary - file to load along with it; this is typical for stand-off annotation where one tree is built upon another).
Allow files with no trees (normaly such files are considered broken). Note: the short flag is -zero.
Limit number of servers to start even if the list of servers contains more of them.
Specifies how many times the hub tries to connect to a btred server before it gives up.
Skip an initial check for server hosts availability (a dummy attempt for SSH connection).
Don't start new btred servers on the remote hosts. Instead, start a hub and try to connect to the btred servers already running. This requires a server-session key to be given on the standard input.
Start servers on the remote hosts but don't start a hub. The server session key required for authentication to the servers will be printed on the standard output.
Run btred servers in safe mode in which all macros are processed in a Safe compartment whith some security restrictions. This mode seems to be likely to cause btred servers to suffer from memory leaks.
In the safe mode, only the following opcodes and opcode-sets are allowed (see documentation for the Opcode Perl module):
:base_core :base_mem :base_loop :base_math entereval caller dofile print entertry leavetry tie untie bless sprintf localtime gmtime sort require
plus :base_orig, but the following opcodes (which are forbidden):
getppid getpgrp setpgrp getpriority setpriority pipe_op sselect select dbmopen dbmclose tie untie
Run btred server with -D flag for some more debugging information.
A file containing the default set of macros to be prepared on btred servers. The file (with exactly the same path) must be visible from all server hosts.
A file containing additional set of macros to be prepared on btred
servers. This option is typically used instead of --macro-file
to
load macros from both filename
and the default macro set from
(tred.mac
). --macro-file
can still be used in combination with
--include-macro-file to supply a replacement for tred.mac
.
Give a comma-separated list of installed TrEd extension names to temporarily enable if disabled in the extension configuration. Use '*' to enable all currently enabled extensions.
This option can only be used with --init
or --reload-macros
.
Give a comma-separated list of installed TrEd extension names to temporarily disable if enabled in the extension configuration. Use '*' to disable all currently enabled extensions.
This option can only be used with --init
or --reload-macros
.
Allows to specify a file where the the session-key for a client's authentication will be stored. It defaults to ~/.ntred_session_key.
Automatically applies a given character encoding to all stdout output operations on the servers and command-line arguments. Only works with Perl >= 5.8.
The hostname of the local machine the hub will listen on (defaults to localhost but a machine's hostname may be given to allow remote access to the hub).
The port number the hub will be listening on (defaults to 1500).
This option is passed to the btred command line when starting a btred server. It makes btred preload a given Perl module at btred startup so as it is available to all macros (DOES NOT WORK WITH RESTRICTED MODE). This option may be specified more than once with different modules.
Use old benchmark-based distribution method.
ntred --list-files|--list-changed-files ntred --reload-files [-filelist file-list] [--listed-files file [...]] ntred --reload-changed-files ntred --reload-macros [-m macro_file] ntred --load-files [--filelist file-list] [file [...]] ntred --close-files ntred --save-files|--save-changed-files [-s strip-sfx] [-a append-sfx] [-p strip-prefix] [-r add-prefix] [-f out-fmt] [--knit] ntred --quit ntred --kill|--ps-kill [--servers server[,server,...]] [--serverlist server-list] ntred --break|--ps-break ntred --dump-files [--filelist file-list] [file [...]] ntred --upload-file filename < fs-file
Start remote btred servers and a hub. See HUB AND SERVER MODE OPTIONS.
Keep alive those servers which do not get any file during the initial file distribution (by default, unused servers are automatically closed).
Sends the hub and all the servers a command to quit.
Tells ntred nub to send USR1 a signal to all running btred servers. Upon receiving that signal, the servers should stop current processing and return to the request awaiting state.
Similar to --break
but tries to identify btred server processes by
looking at the output of the system command ps x -o pid,command
. This may help if
killall -USR1 btred
doesn't work.
Runs killall -9 ntred
on the local machine and and killall -9 btred
on
the server hosts listed with --servers, --serverlist, or in
~/.ntred_serverlist.
Similar to --kill
but tries to identify btred server processes by
looking at the output of the system command ps x -o pid,command
. This may help if
killall -TERM btred
doesn't work.
List all files currently open on servers.
List all files that have been changed by some macro. Note, that a macro
has to claim that the file was changed by setting
$TredMacro::FileChanged
variable to 1, otherwise the btred server
would never notice.
Apply request only on listed files (currently only works for queries
and --reload-files
request).
Query number of files open on each server.
Send a command to the btred servers to reload all open files. If
--filelist
or --listed-files
options are given, reload only
files occuring in the given lists (all other files remain intact in
servers' memory).
Send a command to the btred servers to reload files that have been modified since (re)loaded.
Send command to the btred servers to reload the initial macro file.
If -m
(--macro-file
) is specified, the servers use the given
macro-file instead of the original one (specified when initializing
btred servers). Note, that the file (with exactly the same path) must
be visible from all server hosts.
Options --disable-extensions
and --enable-extensions
can be used
to define a set of extensions to use.
Send a command to the hub to distribute files given on the
command-line or those specified using --filelist
of in
~/.ntred_filelist to the servers.
Warning: Do not load files already in servers' memory, otherwise you
may get duplicates (depending on to which server the files get
distributed). Use --list-files
to see which files are already loaded.
See also --reload-files
.
Send a command to the btred servers to close all open files.
Send a command to the servers to save all open files. The filenames
of the saved files may be modified using
--add-prefix
, --strip-prefix
,
--strip-suffix
,
--append-suffix
.
Same as --save-files
except that only files that have been changed
by some macro will be saved. Note, that a macro has to claim that the
file was changed by setting $TredMacro::FileChanged
variable to 1,
otherwise the btred server would never notice. See also
--list-changed-files
.
If a file is saved, save/update also listed types of reffiles the file
pulled data from. For the moment, this only makes sense with the
PML
backend which supports so called knitting, i.e. a method to
pull certain data from external resources and push it back (with all
changes) to the original position in the resource when saving the
file. This option allows to list the types of resources (in PML the
types are the reference names listed in the PML schema) which should
be saved. Default is NONE
. This type of resources doesn't include
so called secondary files.
Dumps given files or trees to standard output in FS format as they are
in memory of the btred servers. Individual dumps are separated with
`//FSEND' preceded and followed by two newline characters. To output
a single tree, follow the filename with ##n
suffix where n
is
the absolute position of the tree in the file (starting from one).
The following example shows how csplit
command can be used to
save individual dumps into separate files:
ntred --dump <files> | csplit -z -f out -b '%d.fs' - '/\/\/FSEND/+2' '{*}'
To merge these separate files into one huge FS file, use
any2any -m hugeout.fs out*.fs
This command is kind of a reverse to dump. It takes a filename from
the first command line argument and a FS file from the standard input
and sends them to the btred servers. The server possessing the file
with the given filename replaces its own in-memory copy of the file
with the one provided on the standard input. To update a single tree,
follow the filename with ##n
suffix where n
is the absolute
position of the tree in the file (starting from one).
Ignore "secondary" files even if loaded. This only affects some commands, such as --list-changed, in which particular case is means that a file, whose secondary file was changed, is not reported as changed unless the (primary) file itself was marked as changed.
Allow files with no trees (normaly such files are considered broken). Note: the short flag is -zero.
Remove strings matching given regexp from the beginning of filenames before saving.
Prepend output filenames with the given prefix when saving.
Strip strings matching given regexp from the end of filenames when saving.
Append given suffix to the filenames when saving.
Format to use for files being saved.
Don't save "secondary" files (not even if changed). Normally, secondary files (if loaded) are saved along with their primary files (the exactly same file-name prefix/suffix processing and format apply to both the primary and secondary files).
Apply Perl glob
function on the filename patterns given on the
command-line. This expands possible wild-card patterns on each of the
filename command-line argument as the standard Unix shell /bin/csh
would do. This can not only help in a situation where the shell used
doesn't support wildcard expansion, but can also be used to reduce the
number of the command-line arguments passed to the process in cases
where the argument list would after the shell-expansion exceed a
system limit. Note, that currently expansion is performed on the
client regardless of the type of request. This may change in the
future versions.
Print a brief help message on usage and exits.
Prints the help page and exits.
Displays the help as manual page.
Suppress all NTRED-CLIENT/NTRED-HUB messages on error output.
Redirect all std error output to /dev/null.
This option may be used to specify the ssh/rsh command to use to connect to remote servers. Default value is `ssh -o ConnectTimeout=10'.
Run btred servers locally. It ignores all non-local entries in the .ntred_serverlist (i.e. entries not matching local machine's hostname). There still may be more BTrEd instances, provided they use different ports. In this case, SSH is not used.
Use --servers localhost:XY (where XY is port number) if you wish to run a single server on the loopback interface.
This option may be used to specify the command to use to start a btred server on a remote host. The command must accept any btred parameters.
USE AT YOUR OWN RISK. IF SECURITY IS A CRITICAL ISSUE OR IF IN DOUBT, DON'T USE IT AT ALL.
Why is security an issue here? Because btred servers execute almost
arbitrary Perl code provided by the client. In the --unrestricted
mode such code may contain arbitrary commands such as system() or
open(). It is therefore desirable that the servers are not open for
all parties.
The following precautions have been taken to lower the potential security risks:
1) Both btred servers and hub require an authorization based on verification of a MD5 signature of a random data block (generated by the server in case of the hub-to-btred-server communication and by the hub in case of the client-to-hub communication) xor-ed with an authorization key known to both parties. Although the communication is unencrypted, the client must with each request send a MD5 checksum of the request XORed with the secret authorization key. Only requests whose signature is verified by the server, are responded to.
2) There may be only one connection from a hub to a server. As soon as it is closed, the server terminates.
3) If the servers are started by the hub itself (using --init
) the
authorization key is created by the hub and is passed to the btred
server via a ssh encrypted pipe.
4) For the client's disposal, the authorization key is stored in
user's home directory as ~/.ntred_session_key
with permissions
set to 600 (only user can read or write). This theoretically
(depending on the general security of the system) limits the access
to the hub (and thus to the servers) to the user running the hub
only. It may, though, be obviously abused from the local root
account to execute arbitrary perl code on all btred server
hosts. This might especially be undesirable if the hub runs on a
machine whose administrator would normaly have no user access to
the machines running btred servers. Another possible security issue
might arise if user's home directory is on a remote NFS server, so
that NFS intervenes accessing the key file. Since NFS uses an
unencrypted protocol, network sniffing techniques may be used to
obtain the authorization key and hence run arbitrary code on btred
hosts. If such situations are likely to happen (e.g. in a large
network) it is advisable to use a different location for the
authorization key (see --key-file
), e.g. /tmp
.
5) It is possible to restrict Perl code evaluated on the servers to a
safer compartment, where some critical Perl commands are disabled.
In some cases, these restrictions may not be sufficient, in other
they may be too strict. Some memory leaks can appear when Safe
compartment is used. See --safe-mode
above for more discussion.
6) Unless --hub
option is used, the hub runs on localhost and as
such is not (under normal circumstances) open for connections from
the outside world. If you are considering making the hub listen on
a non-local interface, note that it is a much better option to
configure a secure SSH tunnel.
~/.ntred_serverlist
- default list of servers to use
~/.ntred_filelist
- default list of files to load on servers
~/.ntred_session_key
- client/hub session key
This software is distributed under GPL - The General Public Licence. Full text of the GPL can be found in the LICENSE file distributed with this program and also on-line at http://www.gnu.org/copyleft/gpl.html.
Petr Pajas <pajas@matfyz.cz>
Zdenek Zabokrtsky <zabokrtsky@ufal.mff.cuni.cz>
Copyright 2003-2008 Petr Pajas and Zdenek Zabokrtsky, All rights reserved.