DragonFly On-Line Manual Pages
rwreceiver(8) SiLK Tool Suite rwreceiver(8)
NAME
rwreceiver - Accepts files transferred from rwsender(s)
SYNOPSIS
rwreceiver --mode=server --server-port=[HOST:]PORT
--client-ident=IDENT [--client-ident=IDENT ...]
--identifier=IDENT --destination-directory=DIR
[--duplicate-destination=DIR [--duplicate-destination=DIR...]]
[--unique-duplicates] [--freespace-minimum=SIZE]
[--space-maximum-percent=NUM] [--post-command=COMMAND]
[ --tls-ca=PEM_FILE
{ { --tls-cert=PEM_FILE --tls-key=PEM_FILE }
| --tls-pkcs12=DER_FILE } ]
{ --log-destination=DESTINATION
| --log-pathname=FILE_PATH
| --log-directory=DIR_PATH [--log-basename=LOG_BASENAME]
[--log-post-rotate=COMMAND] }
[--log-level=LEVEL] [--log-sysfacility=NUMBER]
[--pidfile=FILE_PATH] [--no-chdir] [--no-daemon]
rwreceiver --mode=client --server-address=IDENT:HOST:PORT
[--server-address=IDENT:HOST:PORT ...]
--identifier=IDENT --destination-directory=DIR
[--duplicate-destination=DIR [--duplicate-destination=DIR...]]
[--unique-duplicates] [--freespace-minimum=SIZE]
[--space-maximum-percent=NUM] [--post-command=COMMAND]
[ --tls-ca=PEM_FILE
{ { --tls-cert=PEM_FILE --tls-key=PEM_FILE }
| --tls-pkcs12=DER_FILE } ]
{ --log-destination=DESTINATION
| --log-pathname=FILE_PATH
| --log-directory=DIR_PATH [--log-basename=LOG_BASENAME]
[--log-post-rotate=COMMAND] }
[--log-level=LEVEL] [--log-sysfacility=NUMBER]
[--pidfile=FILE_PATH] [--no-chdir] [--no-daemon]
rwreceiver --help
rwreceiver --version
DESCRIPTION
rwreceiver is a daemon which accepts files transferred from one or more
rrwwsseennddeerr(8) processes. The received files are stored in a destination
directory.
Either rwsender or rwreceiver may act as the server with the other
acting as the client. That is, an rwsender server may listen for
connections from rwreceiver clients, or an rwsender client may attempt
to connect to one or more rwreceiver servers.
In addition, each rwsender and rwreceiver is configured with an
identifier of its own and the identifier(s) of the rwreceiver(s) or
rwsender(s) that may connect to it. The connection will not
established if the identifier provided by other process is not
recognized.
Every rwsender that communicates with the same rwreceiver must have a
unique identifier; likewise, every rwreceiver that communicates with
the same rwsender must have a unique identifier. Ideally, the
identifier should provide some information about where the rwsender or
rwreceiver program is running and what sort of data it is transferring.
rwreceiver creates multiple copies of the files it receives when one or
more --duplicate-destination switches are specified. If possible, the
duplicate file is created as a hard link to the original file. The
--unique-duplicates switch tells rwreceiver not to use hard links and
forces rwreceiver to create an individual copy of the file in each
duplicate destination directory. Failure to create a file in any of
the duplicate destination directories is noted in rwreceiver's log but
it is not treated as a failure to transfer the file. Only when a file
cannot be created in the destination-directory does rwreceiver consider
the transfer as failed.
Disk Usage
By default, if the disk that rwreceiver writes to becomes full,
rwreceiver prints a message to the log file and exits.
To prevent this, specify the --freespace-minimum and/or
--space-maximum-percent switches, which cause rwreceiver to monitor its
disk usage. These switches were added in SiLK 3.6.
If receiving a file from an rwsender process would violate the limits
specified in those switches, rwreceiver closes the connection to that
rwsender. This causes the connection to be reestablished, and rwsender
tries to transfer the file again. If the filesystem is still full,
rwreceiver closes the connection again. After a delay, the connection
is reestablished. This loop is repeated until the file is successfully
transferred. The delay between each retry starts at five seconds and
grows in five second increments to a maximum of one minute.
When monitoring its disk usage, rwreceiver accounts for one copy of the
number of bytes in the file. rwreceiver does not account for the
filesystem overhead associated with creating a file, and it does not
consider the space required to create multiple copies of the file (cf.,
--duplicate-destination).
File Creation
The following describes the process rwreceiver uses when creating a
file it receives from rwsender. Administrators may find this
information useful when configuring other software to work with
rwreceiver.
1. rwsender sends the name of the file, the size of the file, and the
file's permission bits to rwreceiver.
2. If a file with that name already exists in rwreceiver's destination
directory, rwreceiver checks the file's on-disk size. If the size
is 0 and no other rwreceiver thread is currently handling that
file, rwreceiver assumes it is an aborted attempt to send the file,
and rwreceiver removes the existing file. Otherwise, rwreceiver
tells rwsender that the name represents a duplicate file, at which
point rwsender moves the file to its error directory.
3. When neither --freespace-minimum nor --space-maximum-percent is
specified, processing moves to the next step. Otherwise,
rwreceiver verifies that there is space on the filesystem to hold
one copy of the file. As described in the "Disk Usage" section
above, rwreceiver delays processing the file until space is
available.
4. rwreceiver creates a 0-length placeholder file having the name of
the file being transferred, and rwreceiver closes this file. The
permission bits on this file are all 0.
5. The rwreceiver process creates a second file whose name consists of
a dot (.) followed by the name of the file being transferred. The
permission bits on this file are those sent by rwsender.
6. rwreceiver writes the data it receives from rwsender into the dot
file.
7. Once the transfer is complete, rwreceiver closes the dot file.
8. If any duplicate destination directories have been specified,
rwreceiver copies the dot file to each of those directories (using
a hard link if possible). A failure to copy the file into a
duplicate destination is noted in the log file, but otherwise the
error is ignored.
9. rwreceiver renames the dot file to replace the placeholder file.
10. The rwreceiver process tells the rwsender process that the transfer
was successfully completed.
OPTIONS
Option names may be abbreviated if the abbreviation is unique or is an
exact match for an option. A parameter to an option may be specified
as --arg=param or --arg param, though the first form is required for
options that take optional parameters.
The following set of switches are required:
--identifier=IDENT
Use the name IDENT when establishing a connection with an rwsender
process. The identifier should contain only printable, non-
whitespace characters; the following characters are illegal: colon
(":"), slash ("/" and "\"), period ("."), and comma (",").
--mode=MODE
Specify how the connection between rwsender and rwreceiver(s)
should be established. When MODE is server, rwreceiver will listen
for connections from rwsender clients; when MODE is client,
rwreceiver will attempt to connect to rwsender servers.
--destination-directory=DIR
Place the transferred files into DIR. Note that rwreceiver uses
this as its processing directory; rwreceiver writes an incoming
file to a name beginning with a dot ("."), and moves the file to
its final name once the transfer is complete.
When running in server mode, the following switches are required:
--server-port=[HOST:]PORT
Listen for incoming rwsender client connections on PORT as HOST.
If HOST is omitted, rwreceiver will listen on any address. HOST
may be a name or an IP address; when HOST is an IPv6 address,
enclose it in square brackets.
--client-ident=IDENT
Allow connections from an rwsender client whose identifier is
IDENT. This switch may be repeated to allow multiple rwsender
clients to connect.
When running in client mode, the following switch is required:
--server-address=IDENT:HOST:PORT
Attempt to connect to the rwsender server listening to port number
PORT on the machine HOST. The connection will be dropped unless
the rwsender identifies itself as IDENT. This switch may be
repeated to connect to multiple rwsender servers. HOST may be a
name or an IP address; when HOST is an IPv6 address, it must be
enclosed in brackets.
The following switch is optional in both modes:
--post-command=COMMAND
Run COMMAND on a file once it has been successfully received. The
following "%"-conversions are supported in COMMAND: %s is replaced
with the full path of the transferred file in the destination
directory, %I is replaced with the identifier of the rwsender that
sent the file, and "%%" is replaced with "%". If any other
character follows "%", rwreceiver exits with an error. Note that
COMMAND is only invoked on files in the destination directory;
however, at the time COMMAND is invoked, rwreceiver will have
already copied the file into each of the duplicate destination
directories, if any. See also the rrwwppoolllleexxeecc(8) daemon.
When SiLK is built with the GnuTLS (Transport Layer Security) library,
the following switches are available. Using these switches allows
rwsender and rwreceiver to use an encrypted/authenticated channel for
their communication. Use GnuTLS's cceerrttttooooll(1) program to create the
PEM (Privacy Enhanced Mail) file.
--tls-ca=PEM_FILE
Sets the Certificate Authority file to the given PEM_FILE, thereby
enabling encryption using TLS. This switch must be used in
conjunction with either the --tls-pkcs12 option, or the --tls-cert
and the --tls-key options. Use cceerrttttooooll(1) to create
--tls-cert=PEM_FILE
Sets rwreceiver's encryption certificate for TLS to the given
PEM_FILE. This switch must be used in conjunction with the
--tls-ca and --tls-key options.
--tls-key=PEM_FILE
Sets rwreceiver's encryption key for TLS to the given PEM_FILE.
This switch must be used in conjunction with the --tls-ca and
--tls-cert options.
--tls-pkcs12=DER_FILE
Sets rwreceiver's encryption certificate and key for TLS to the
given DER_FILE. This switch must be used in conjunction with the
--tls-ca option. rwreceiver will use the value in the
RWRECEIVER_TLS_PASSWORD environment variable to decrypt the PKCS#12
file. If this variable is not set, rwreceiver assumes the password
is the empty string.
One of the following logging switches is required:
--log-destination=DESTINATION
Specify the destination where logging messages are written. When
DESTINATION begins with a slash "/", it is treated as a file system
path and all log messages are written to that file; there is no log
rotation. When DESTINATION does not begin with "/", it must be one
of the following strings:
"none"
Messages are not written anywhere.
"stdout"
Messages are written to the standard output.
"stderr"
Messages are written to the standard error.
"syslog"
Messages are written using the ssyysslloogg(3) facility.
"both"
Messages are written to the syslog facility and to the standard
error (this option is not available on all platforms).
--log-directory=DIR_PATH
Use DIR_PATH as the directory where the log files are written.
DIR_PATH must be a complete directory path. The log files have the
form
DIR_PATH/LOG_BASENAME-YYYYMMDD.log
where YYYYMMDD is the current date and LOG_BASENAME is the
application name or the value passed to the --log-basename switch
when provided. The log files are rotated: At midnight local time,
a new log is opened, the previous file is closed, and the command
specified by --log-post-rotate is invoked on the previous day's log
file. (Old log files are not removed by rwreceiver; the
administrator should use another tool to remove them.) When this
switch is provided, a process-ID file (PID) is also written in this
directory unless the --pidfile switch is provided.
--log-pathname=FILE_PATH
Use FILE_PATH as the complete path to the log file. The log file
is not rotated.
The following switches are optional:
--duplicate-destination=DIR
Create a duplicate of each transferred file in the directory DIR.
This option may be specified multiple times to create multiple
duplicates. This duplicate is made by a hard link to the file in
the destination-directory if possible, otherwise a complete copy is
made (see also --unique-duplicates). If there are errors copying
the file to this directory, the error is logged but the process
continues as if the transfer was successful. (rwreceiver considers
a transfer as failed only when the file cannot be created in the
destination-directory.)
--unique-duplicates
Force the duplicate file created in each duplicate-destination
directory to be a complete copy of the file in the destination-
directory instead of a hard link to the file. Using hard links
saves disk space and is faster than making a complete copy;
however, any modification-in-place to one file affects all files.
This switch is ignored when the --duplicate-destination switch is
not provided.
--freespace-minimum=SIZE
Set the minimum amount free space (in bytes) to maintain on the
file system where the --destination-directory is located.
rwreceiver delays processing of any file that would cause it to
violate this limit (see "Disk Usage" above). The default value of
this switch is 0, which tells rwreceiver not to monitor its disk
usage. See also --space-maximum-percent.
SIZE may be given as an ordinary integer, or as a real number
followed by a suffix "K", "M", "G", or "T", which represents the
numerical value multiplied by 1,024 (kilo), 1,048,576 (mega),
1,073,741,824 (giga), and 1,099,511,627,776 (tera), respectively.
For example, 1.5K represents 1,536 bytes, or one and one-half
kilobytes.
--space-maximum-percent=NUM
Use no more than this percentage of the file system containing the
--destination-directory. The default is to use all of the file
system (100%). rwreceiver delays processing of files that would
cause it to violate this limit. The NUM parameter does not need to
be an integer. See also --freespace-minimum and "Disk Usage".
--log-level=LEVEL
Set the severity of messages that will be logged. The levels from
most severe to least are: "emerg", "alert", "crit", "err",
"warning", "notice", "info", "debug". The default is "info".
--log-sysfacility=NUMBER
Set the facility that ssyysslloogg(3) uses for logging messages. This
switch takes a number as an argument. The default is a value that
corresponds to "LOG_USER" on the system where rwreceiver is
running. This switch produces an error unless
--log-destination=syslog is specified.
--log-basename=LOG_BASENAME
Use LOG_BASENAME in place of the application name in the name of
log files in the log directory. See the description of the
--log-directory switch. This switch does not affect the name of
the process-ID file.
--log-post-rotate=COMMAND
Run COMMAND on the previous day's log file after log rotation.
When this switch is not specified, the previous day's log file is
compressed with ggzziipp(1). When the switch is specified and COMMAND
is the empty string, no action is taken on the log file. Each
occurrence of the string %s in COMMAND will be replaced with the
full path to the log file, and each occurrence of "%%" will be
replaced with "%". If any other character follows "%", rwreceiver
exits with an error. Specifying this switch without also using
--log-directory is an error.
--pidfile=FILE_PATH
Set the complete path to the file in which rwreceiver writes its
process ID (PID) when it is running as a daemon. No PID file is
written when --no-daemon is given. When this switch is not
present, no PID file is written unless the --log-directory switch
is specified, in which case the PID is written to
LOGPATH/rwreceiver.pid.
--no-chdir
Do not change directory to the root directory. When rwreceiver
becomes a daemon process, it changes its current directory to the
root directory so as to avoid potentially running on a mounted file
system. Specifying --no-chdir prevents this behavior, which may be
useful during debugging. The application does not change its
directory when --no-daemon is given.
--no-daemon
Force rwreceiver to run in the foreground---it does not become a
daemon process. This may be useful during debugging.
--help
Print the available options and exit.
--version
Print the version number and information about how SiLK was
configured, then exit the application.
ENVIRONMENT
RWSENDER_TLS_PASSWORD
Specifies the password to use to decrypt the PKCS#12 file specified
in the --tls-pkcs12 switch.
SEE ALSO
rrwwsseennddeerr(8), rrwwppoolllleexxeecc(8), ssiillkk(7), ssyysslloogg(3), cceerrttttooooll(1), ggzziipp(1),
SiLK Installation Handbook
SiLK 3.11.0.1 2016-02-19 rwreceiver(8)