SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from CentOS Other silk-rwreceiver-3.19.1-3.el8.x86_64.rpm

rwreceiver

Section: SiLK Tool Suite (8)
Updated: 2021-01-04
Index 

NAME

rwreceiver - Accepts files transferred from rwsender(s) 

SYNOPSIS

To listen for incoming connections:

  rwreceiver --mode=server --server-port=[HOST:]PORT        --client-ident=IDENT [--client-ident=IDENT ...]        ...

To make outgoing connections:

  rwreceiver --mode=client --server-address=IDENT:HOST:PORT        [--server-address=IDENT:HOST:PORT ...]        ...  rwreceiver  SERVER_MODE_OR_CLIENT_MODE_SWITCHES        --identifier=IDENT --destination-directory=DIR_PATH        [ --tls-ca=TRUST_FILE          { { --tls-cert=CERTIFICATE_FILE --tls-key=KEY_FILE }            | --tls-pkcs12=PKCS12_FILE }          [--tls-priority=TLS_PRIORITY] [--tls-security=TLS_SECURITY]          [--tls-crl=CRL_FILE] [--tls-debug-level=DB_LEVEL] ]        [--post-command=COMMAND]        [--duplicate-destination=DIR_PATH          [--duplicate-destination=DIR_PATH...] ]        [--unique-duplicates]        [--freespace-minimum=SIZE] [--space-maximum-percent=NUM]        { --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 ormore rwsender(8) processes. The received files are stored in adestination directory.

rwreceiver creates multiple copies of the files it receives whenone or more --duplicate-destination switches are specified. Ifpossible, the duplicate file is created as a reference (a hard link)to the original file. The --unique-duplicates switch tellsrwreceiver not to use hard links and forces rwreceiver to createan individual copy of the file in each duplicate destinationdirectory. Failure to create a file in any of the duplicatedestination directories is noted in rwreceiver's log but it is nottreated as a failure to transfer the file. Only when a file cannot becreated in the destination-directory does rwreceiver consider thetransfer as failed.

The --post-command switch tells rwreceiver to execute a commandon each file that it successfully receives after the file has beenwritten to the destination directory and copied to each duplicatedestination directory. The command may include a placeholder whichrwreceiver fills with the path to the file in the destinationdirectory. The exit status of the command is ignored byrwreceiver. Any output on "stdout" or "stderr" from COMMANDnormally appears in the log when the log messages are being written toa local log file. See also the rwpollexec(8) daemon. 

Interaction with rwsender

Either rwsender or rwreceiver may act as the server with theother acting as the client. That is, an rwsender server maylisten for connections from rwreceiver clients, or an rwsenderclient may attempt to connect to one or more rwreceiver servers.

In addition, each rwsender and rwreceiver is configured with anidentifier of its own and the identifier(s) of the rwreceiver(s) orrwsender(s) that may connect to it. The connection is closed ifthe identifier provided by other process is not recognized.

Every rwsender that communicates with the same rwreceiver musthave a unique identifier; likewise, every rwreceiver thatcommunicates with the same rwsender must have a unique identifier.Ideally, the identifier should provide some information about wherethe rwsender or rwreceiver program is running and what sort ofdata it is transferring. 

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 tomonitor its disk usage. These switches were added in SiLK 3.6.

If receiving a file from an rwsender process would violate thelimits specified in those switches, rwreceiver closes theconnection to that rwsender. This causes the connection to bereestablished, and rwsender tries to transfer the file again. Ifthe filesystem is still full, rwreceiver closes the connectionagain. After a delay, the connection is reestablished. This loop isrepeated until the file is successfully transferred. The delaybetween each retry starts at five seconds and grows in five secondincrements to a maximum of one minute.

When monitoring its disk usage, rwreceiver accounts for one copy ofthe number of bytes in the file. rwreceiver does not account forthe filesystem overhead associated with creating a file, and it doesnot 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 afile it receives from rwsender. Administrators may find thisinformation useful when configuring other software to work withrwreceiver.
1.
rwsender sends the name of the file, the size of the file, and thefile's permission bits to rwreceiver.
2.
If a file with that name already exists in rwreceiver's destinationdirectory, rwreceiver checks the file's on-disk size. If the sizeis 0 and no other rwreceiver thread is currently handling thatfile, rwreceiver assumes it is an aborted attempt to send the file,and rwreceiver removes the existing file. Otherwise, rwreceivertells rwsender that the name represents a duplicate file, at whichpoint rwsender moves the file to its error directory.
3.
When neither --freespace-minimum nor --space-maximum-percent isspecified, processing moves to the next step. Otherwise,rwreceiver verifies that there is space on the filesystem to holdone copy of the file. As described in the ``Disk Usage'' sectionabove, rwreceiver delays processing the file until space isavailable.
4.
rwreceiver creates a 0-length placeholder file having the name ofthe file being transferred, and rwreceiver closes this file. Thepermission bits on this file are all 0.
5.
The rwreceiver process creates a second file whose name consists ofa dot (.) followed by the name of the file being transferred. Thepermission bits on this file are those sent by rwsender.
6.
rwreceiver writes the data it receives from rwsender into thedot 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 (usinga hard link if possible). A failure to copy the file into a duplicatedestination is noted in the log file, but otherwise the error isignored.
9.
rwreceiver renames the dot file to replace the placeholder file.
10.
The rwreceiver process tells the rwsender process that thetransfer was successfully completed.
11.
rwreceiver prepares the command specified by the --post-commandswitch, perhaps filling in the complete path to the file in thedestination directory, and executes the command.
 

OPTIONS

Option names may be abbreviated if the abbreviation is unique or is anexact match for an option. A parameter to an option may be specifiedas --arg=param or --arg param, though the first form isrequired for options that take optional parameters. 

Application-specific switches

The following set of switches are required:
--identifier=IDENT
Use the name IDENT when establishing a connection with anrwsender 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, rwreceiverlistens for connections from rwsender clients; when MODE isclient, rwreceiver attempts to connect to rwsender servers.
--destination-directory=DIR_PATH
Place the transferred files into DIR_PATH. Note that rwreceiveruses this as its processing directory; see the ``File Creation''section above for details.
 

Server-mode switches

When running in server mode, the following switches are required:
--server-port=[HOST:]PORT
Listen for incoming rwsender client connections on PORT asHOST. If HOST is omitted, rwreceiver listens on anyaddress. HOST may be a name or an IP address; when HOST is anIPv6 address, it must be enclosed in square brackets.
--client-ident=IDENT
Allow connections from an rwsender client whose identifier isIDENT. This switch may be repeated to allow multiple rwsenderclients to connect. rwreceiver closes the connection if anrwsender client connects and does not provide a valid identifier.
 

Client-mode switch

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 numberPORT on the machine HOST. rwreceiver closes the connectionunless the rwsender identifies itself as IDENT. This switch maybe repeated to connect to multiple rwsender servers. HOST maybe a name or an IP address; when HOST is an IPv6 address, it mustbe enclosed in square brackets.
 

Transport Layer Security switches

It is possible to build SiLK with support for the GnuTLS TransportLayer Security library (<https://www.gnutls.org/>) which allowsrwsender and rwreceiver to use an encrypted/authenticatedchannel for their communication. When SiLK includes GnuTLS support,the following switches are available. To enable use of GnuTLS, specifythe --tls-ca switch and either the --tls-pkcs12 switch or boththe --tls-cert and --tls-key switches.
--tls-ca=TRUST_FILE
Set the trusted certificate authorities to those in TRUST_FILE,where TRUST_FILE is the complete path to a file containing aPEM-encoded list of certificates. This list of authorities is used toverify the certificate sent by rwsender. This switch must beused in conjunction with either the --tls-pkcs12 switch or both the--tls-cert and the --tls-key switches.
--tls-cert=CERTIFICATE_FILE
Set the certificate list (path) for rwreceiver's private key to thelist of certificates in CERTIFICATE_FILE, where CERTIFICATE_FILEis the complete path to a file containing the PEM-encodedcertificates. This switch may only be used in conjunction with the--tls-ca and --tls-key switches.
--tls-key=KEY_FILE
Read rwreceiver's private encryption key for TLS from KEY_FILE,where KEY_FILE is the complete path to a PEM-encoded file. Thisswitch may only be used in conjunction with the --tls-ca and--tls-cert switches.
--tls-pkcs12=PKCS12_FILE
Set rwreceiver's encryption certificate and private key for TLS tothe contents of PKCS12_FILE, where PKCS12_FILE is the completepath to a file containing the PKCS#12 contents in DER-format. Thisswitch may only be used in conjunction with the --tls-ca switch.rwreceiver uses the value in the RWRECEIVER_TLS_PASSWORD environmentvariable to decrypt the PKCS#12 file. If this variable is not set,rwreceiver assumes the password is the empty string.
--tls-priority=TLS_PRIORITY
Set the preference order (priority) for ciphers, key exchange methods,message authentication codes, and compression methods to those inTLS_PRIORITY. This switch is optional; the default value is"NORMAL". The argument is parsed by the GnuTLS library, and theavailable arguments depend on the version of GnuTLS linked with SiLK.Detailed information on the format of the argument is available in theGnuTLS documentation under Priority Strings (e.g.,<https://gnutls.org/manual/html_node/Priority-Strings.html>) providesthe set for the most recent version of GnuTLS; the values used at yoursite may be different). See also the output of runninggnutls-cli(1) with the --priority-list switch. Since SiLK3.18.0.
--tls-security=TLS_SECURITY
Set the security level to use when generating Diffie-Hellmanparameters to TLS_SECURITY, where TLS_SECURITY is one of "low","medium", "high", or "ultra". This switch is optional, and whennot specified a value of "medium" is used. For the meaning of thesevalues see Selecting cryptographic key sizes in the GnuTLSdocumentation at your site (e.g.,<https://gnutls.org/manual/html_node/Selecting-cryptographic-key-sizes.html>).Since SiLK 3.18.0.
--tls-crl=CRL_FILE
Update the list of trusted certificates with the certificaterevocation lists contained in CRL_FILE, where CRL_FILE is thecomplete path to a file containing PEM-encoded list of CRLs. Thisswitch is optional. Since SiLK 3.18.0.
--tls-debug-level=DB_LEVEL
Set the debugging level used internally by the GnuTLS library toDB_LEVEL, an integer between 0 and 99 inclusive. The messages arewritten to the log destation at the "info" level. The default valueof 0 disables debugging. Larger values may reveal sensitiveinformation and should be used carefully. A value above 10 enablesall debugging options. Since SiLK 3.18.0.
 

Required logging switches

One of the following logging switches is required:
--log-destination=DESTINATION
Specify the destination where logging messages are written. WhenDESTINATION begins with a slash "/", it is treated as a filesystem path and all log messages are written to that file; there is nolog rotation. When DESTINATION does not begin with "/", it mustbe 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 syslog(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 theform

 DIR_PATH/LOG_BASENAME-YYYYMMDD.log

where YYYYMMDD is the current date and LOG_BASENAME is theapplication name or the value passed to the --log-basename switchwhen provided. The log files are rotated: At midnight local time, anew log is opened, the previous file is closed, and the commandspecified by --log-post-rotate is invoked on the previous day's logfile. (Old log files are not removed by rwreceiver; theadministrator should use another tool to remove them.) When thisswitch is provided, a process-ID file (PID) is also written in thisdirectory unless the --pidfile switch is provided.

--log-pathname=FILE_PATH
Use FILE_PATH as the complete path to the log file. The log fileis not rotated.
 

Optional application-specific switches

The following switches are optional:
--post-command=COMMAND
Run COMMAND on a file once it has been successfully received. Thefollowing "%"-conversions are supported in COMMAND: %s isreplaced with the full path of the transferred file in the destinationdirectory, %I is replaced with the identifier of the rwsenderthat sent the file, and "%%" is replaced with "%". If any othercharacter follows "%", rwreceiver exits with an error. Note thatCOMMAND is only invoked on files in the destination directory;however, at the time COMMAND is invoked, rwreceiver hasalready copied the file into each of the duplicate destinationdirectories, if any. See also the rwpollexec(8) daemon.
--duplicate-destination=DIR_PATH
Create a duplicate of each transferred file in the directory DIR_PATH.This option may be specified multiple times to create multipleduplicates. This duplicate is made by a hard link to the file in thedestination-directory if possible, otherwise a complete copy is made(see also --unique-duplicates). If there are errors copying thefile to this directory, the error is logged but the process continuesas if the transfer was successful. (rwreceiver considers atransfer as failed only when the file cannot be created in thedestination-directory.)
--unique-duplicates
Force the duplicate file created in each duplicate-destinationdirectory to be a complete copy of the file in thedestination-directory instead of a hard link to the file. Using hardlinks 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 isnot provided.
--freespace-minimum=SIZE
Set the minimum amount free space (in bytes) to maintain on the filesystem where the --destination-directory is located. rwreceiverdelays processing of any file that would cause it to violate thislimit (see ``Disk Usage'' above). The default value of this switch is0, 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 numberfollowed by a suffix "K", "M", "G", or "T", which represents thenumerical value multiplied by 1,024 (kilo), 1,048,576 (mega),1,073,741,824 (giga), and 1,099,511,627,776 (tera), respectively. Forexample, 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 filesystem (100%). rwreceiver delays processing of files that wouldcause it to violate this limit. The NUM parameter does not need tobe an integer. See also --freespace-minimum and ``Disk Usage''.
 

Optional logging and daemon switches

The following are optional switches related to logging and running asa daemon:
--log-level=LEVEL
Set the severity of messages that are logged. The levels from mostsevere to least are: "emerg", "alert", "crit", "err", "warning","notice", "info", "debug". The default is "info".
--log-sysfacility=NUMBER
Set the facility that syslog(3) uses for logging messages. Thisswitch takes a number as an argument. The default is a value thatcorresponds to "LOG_USER" on the system where rwreceiver isrunning. 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 oflog files in the log directory. See the description of the--log-directory switch. This switch does not affect the name ofthe 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 iscompressed with gzip(1). When the switch is specified andCOMMAND is the empty string, no action is taken on the log file.Each occurrence of the string %s in COMMAND is replaced with thefull path to the log file, and each occurrence of "%%" is replacedwith "%". If any other character follows "%", rwreceiver exitswith 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 itsprocess ID (PID) when it is running as a daemon. No PID file iswritten when --no-daemon is given. When this switch is notpresent, no PID file is written unless the --log-directory switchis specified, in which case the PID is written toLOGPATH/rwreceiver.pid.
--no-chdir
Do not change directory to the root directory. When rwreceiverbecomes a daemon process, it changes its current directory to the rootdirectory so as to avoid potentially running on a mounted file system.Specifying --no-chdir prevents this behavior, which may be usefulduring 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 adaemon process. This may be useful during debugging.
 

Help switches

The following switches provide help:
--help
Print the available options and exit.
--version
Print the version number and information about how SiLK wasconfigured, then exit the application.
 

ENVIRONMENT

RWRECEIVER_TLS_PASSWORD
Specifies the password to use to decrypt the PKCS#12 file specified inthe --tls-pkcs12 switch. When this is not provided, a NULLpassword is used. Set this environment variable to the empty stringfor an empty password.
 

SEE ALSO

rwsender(8), rwpollexec(8), silk(7), gnutls-cli(1),certtool(1), syslog(3), gzip(1),SiLK Installation Handbook


 

Index

NAME
SYNOPSIS
DESCRIPTION
Interaction with rwsender
Disk Usage
File Creation
OPTIONS
Application-specific switches
Server-mode switches
Client-mode switch
Transport Layer Security switches
Required logging switches
Optional application-specific switches
Optional logging and daemon switches
Help switches
ENVIRONMENT
SEE ALSO

This document was created byman2html,using the manual pages.