=head1 ntred

ntred - controller/hub/client interface to a cluster of btred servers

=head1 SYNOPSIS

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

=head1 DESCRIPTION

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 C<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 C<--logdir>, NTRED_LOGDIR or TMP or TEMP environment variable
and defaults to /tmp if none of the previous exists).

=head1 CONFIG FILE

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 --.

=head1 OPTIONS

=head2 QUERY MODE OPTIONS

  ntred [-m macro-file] [-e code] [--hub hub] [--port port]
        [-N|-H] [-T] [--key-file file] -- script-arguments

=over 8

=item B<--execute|-e> code

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
C<--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..

=item B<--macro-file|-m> filename

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
C<--execute>.

Note that servers already have the set of macros they obtained on
startup (i.e. B<--init>): it is namely either the default set of
macros (C<tred.mac>) or the set specified via B<--macro-file>, and beside one of
these also the set specified via B<--include-macro-file>.

=item B<--include-macro-file|-I> filename

A file containing additional set of macros to be sent to the servers.
In query mode, this option behaves just like C<--macro-file> and is
only provided for compatibility with C<btred>. If both these options
are used, both sets of macros are loaded.

=item B<--hub> hostname

The hostname of the hub to connect to (defaults to localhost).

=item B<--port> port

The port on which the hub is listening (defaults to 1500).

=item B<--all-trees|-T>

Run the query code on all trees (wrapping the code into a
C<if ($root) { do {{ CODE }} while TredMacro::NextTree() }> loop).

=item B<--all-nodes|-N>

Run the query code on all nodes (you still must use --all-trees or -T
to process all trees) (wrapping the code into a
C<while ($this) { CODE ; $this=$this->following }";> loop).

=item B<--all-nonhidden-nodes|-H>

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
C<while ($this) { CODE ; $this=$this->following_visible(FS()) }";> loop).

=item B<--listed-files|-L>

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 I<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.

=item B<--regexp-files|-R> regular-expression

Run the query code only on files whose filenames match a given regular
expression.

=item B<--filelist|-l> filename

Like C<--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.

=item B<--key-file>

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'.

=back

=head2 HUB AND SERVER MODE OPTIONS

  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 [...]]

=over 8

=item B<--servers> list of hosts

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 C<--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
C<--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.

=item B<--serverlist> filename

This provides more convenient way to specify servers by providing a
file containing a list of servers, one per line. If neither
C<--servers> nor C<--serverlist> is
provided, then the list of servers is read from ~/.ntred_serverlist.

=item B<--filelist> filename

A list of files to distribute between servers (one filename per line).
Additional files may be given as command-line arguments.

=item B<--no-secondary-files>

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).

=item B<--allow-no-trees|-0>

Allow files with no trees (normaly such files are considered broken).
Note: the short flag is -zero.

=item B<--max-servers> number

Limit number of servers to start even if the list of servers contains
more of them.

=item B<--max-retries> number

Specifies how many times the hub tries to connect to a btred server
before it gives up.

=item B<--no-server-check>

Skip an initial check for server hosts availability (a dummy attempt
for SSH connection).

=item B<--no-server-start>

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.

=item B<--no-hub-start>

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.

=item B<--safe-mode|-F>

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

=item B<--server-debug>

Run btred server with -D flag for some more debugging information.

=item B<--macro-file|-m> filename

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.

=item B<--include-macro-file|-I> filename

A file containing additional set of macros to be prepared on btred
servers. This option is typically used instead of C<--macro-file> to
load macros from B<both> C<filename> B<and> the default macro set from
(C<tred.mac>). C<--macro-file> can still be used in combination with
B<--include-macro-file> to supply a replacement for C<tred.mac>.

=item B<--enable-extensions> list

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 C<--init> or C<--reload-macros>.

=item B<--disable-extensions> list

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 C<--init> or C<--reload-macros>.

=item B<--key-file>

Allows to specify a file where the the session-key for a client's
authentication will be stored. It defaults to ~/.ntred_session_key.

=item B<--terminal-encoding|-d> encoding

Automatically applies a given character encoding to all stdout output
operations on the servers and command-line arguments.
Only works with Perl >= 5.8.

=item B<--hub> hostname

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).

=item B<--port> port

The port number the hub will be listening on (defaults to 1500).

=item B<--preload-module|-M> module-name

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.

=item B<--old-dist-method>

Use old benchmark-based distribution method.

=back

=head2 HUB CONTROL OPTIONS

  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


=over 8

=item B<--init|-i>

Start remote btred servers and a hub. See L</HUB AND SERVER MODE OPTIONS>.

=item B<--keep-empty-servers|-E>

Keep alive those servers which do not get any file during the initial
file distribution (by default, unused servers are automatically
closed).

=item B<--quit>

Sends the hub and all the servers a command to quit.

=item B<--break>

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.

=item B<--ps-kill>

Similar to C<--break> but tries to identify btred server processes by
looking at the output of the system command C<ps x -o pid,command>. This may help if
C<killall -USR1 btred> doesn't work.


=item B<--kill>

Runs C<killall -9 ntred> on the local machine and and C<killall -9 btred> on
the server hosts listed with --servers, --serverlist, or in
~/.ntred_serverlist.

=item B<--ps-kill>

Similar to C<--kill> but tries to identify btred server processes by
looking at the output of the system command C<ps x -o pid,command>. This may help if
C<killall -TERM btred> doesn't work.

=item B<--list-files>

List all files currently open on servers.

=item B<--list-changed-files>

List all files that have been changed by some macro. Note, that a macro
has to claim that the file was changed by setting
C<$TredMacro::FileChanged> variable to 1, otherwise the btred server
would never notice.

=item B<--listed-files|-L>

Apply request only on listed files (currently only works for queries
and C<--reload-files> request).

=item B<--count-files>

Query number of files open on each server.

=item B<--reload-files>

Send a command to the btred servers to reload all open files.  If
C<--filelist> or C<--listed-files> options are given, reload only
files occuring in the given lists (all other files remain intact in
servers' memory).

=item B<--reload-changed-files>

Send a command to the btred servers to reload files that have been
modified since (re)loaded.

=item B<--reload-macros>

Send command to the btred servers to reload the initial macro file.
If C<-m> (C<--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 C<--disable-extensions> and C<--enable-extensions> can be used
to define a set of extensions to use.

=item B<--load-files>

Send a command to the hub to distribute files given on the
command-line or those specified using C<--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 C<--list-files> to see which files are already loaded.

See also C<--reload-files>.

=item B<--close-files>

Send a command to the btred servers to close all open files.

=item B<--save-files>

Send a command to the servers to save all open files.  The filenames
of the saved files may be modified using
C<--add-prefix>, C<--strip-prefix>,
C<--strip-suffix>,
C<--append-suffix>.

=item B<--save-changed-files>

Same as C<--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 C<$TredMacro::FileChanged> variable to 1,
otherwise the btred server would never notice. See also
C<--list-changed-files>.

=item B<--knit|K> ALL|NONE|name1,name2,...

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
C<PML> backend which supports so called B<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 C<NONE>. This type of resources doesn't include
so called secondary files.

=item B<--dump-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 C<##n> suffix where C<n> is
the absolute position of the tree in the file (starting from one).
The following example shows how C<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

=item B<--upload-file>

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 C<##n> suffix where C<n> is the absolute
position of the tree in the file (starting from one).

=item B<--no-secondary-files>

Ignore "secondary" files even if loaded. This only affects some
commands, such as B<--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.

=item B<--allow-no-trees|-0>

Allow files with no trees (normaly such files are considered broken).
Note: the short flag is -zero.

=back

=head2 SAVING OPTIONS

=over 8

=item B<--strip-prefix|-p> regexp

Remove strings matching given regexp from the beginning of filenames
before saving.

=item B<--add-prefix|-r> prefix

Prepend output filenames with the given prefix when saving.

=item B<--strip-suffix|-s> regexp

Strip strings matching given regexp from the end of filenames
when saving.

=item B<--add-suffix|-a> suffix

Append given suffix to the filenames when saving.

=item B<--output-format|-f> [fs|csts|trxml|tei|storable]

Format to use for files being saved.

=item B<--no-secondary-files>

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).

=back

=head2 GENERAL OPTIONS

=over 8

=item B<--glob|-g>

Apply Perl C<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.

=item B<--usage|-u>

Print a brief help message on usage and exits.

=item B<--help|-h>

Prints the help page and exits.

=item B<--man>

Displays the help as manual page.

=item B<--quiet|-q>

Suppress all NTRED-CLIENT/NTRED-HUB messages on error output.

=item B<--really-quiet|-Q>

Redirect all std error output to /dev/null.


=item B<--ssh> command

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'.

=item B<--local>

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.

=item B<--btred> command

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.

=back

=head1 SECURITY ISSUES

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 C<--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 C<--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 C<~/.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 C<--key-file>), e.g. C</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 C<--safe-mode> above for more discussion.

6) Unless C<--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.

=head1 FILES

C<~/.ntred_serverlist>  - default list of servers to use

C<~/.ntred_filelist>    - default list of files to load on servers

C<~/.ntred_session_key> - client/hub session key

=head1 LICENSE

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.

=head1 AUTHORS

Petr Pajas <pajas@matfyz.cz>

Zdenek Zabokrtsky <zabokrtsky@ufal.mff.cuni.cz>

Copyright 2003-2008 Petr Pajas and Zdenek Zabokrtsky, All rights reserved.

