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

rwsender

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

NAME

rwsender - Watch directory for files and transfer them to rwreceiver(s)

SYNOPSIS

To listen for incoming connections:

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

To make outgoing connections:

  rwsender --mode=client --server-address=IDENT:HOST:PORT        [--server-address=IDENT:HOST:PORT ...]        ...  rwsender  SERVER_MODE_OR_CLIENT_MODE_SWITCHES        --identifier=IDENT --incoming-directory=DIR_PATH        --processing-directory=DIR_PATH --error-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] ]        [--local-directory=[[IDENT]:]DIR_PATH          [--local-directory=[[IDENT]:]DIR_PATH ...]]        [--unique-local-copies]        [--filter=IDENT:REGEXP] [--priority=NUM:REGEXP]        [--polling-interval=NUM]        [--send-attempts=NUM] [--block-size=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]  rwsender --help  rwsender --version

DESCRIPTION

rwsender is a daemon which watches an incoming directory for files.As files are added to the incoming directory, they are moved into aprocessing directory and then transferred over the network to one ormore rwreceiver(8) processes. Files in the incoming directory mayalso be ``transferred'' to one or more local directories.

As rwsender scans the incoming directory, it ignores a file if itssize is 0 bytes or if its name begins with a dot ("."). On eachscan, if rwsender detects a file name that was not present in theprevious scan, it records the name and size of the file. If the filehas a different size on the next scan, the new size is recorded. Oncethe file has the same size on two consecutive scans, rwsender movesthe file to the processing directory and queues it for transfer.

Interaction with rwreceiver

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.

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 anrwreceiver 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, rwsenderlistens for connections from rwreceiver clients; when MODE isclient, rwsender attempts to connect to rwreceiverservers.
--incoming-directory=DIR_PATH: Periodically scan the directory DIR_PATH for files to transfer. Asrwsender scans DIR_PATH, it ignores a file if its name beginswith a dot (".") or if its size is 0 bytes. When a file is firstdetected, its size is recorded, and the file must have the same sizefor two consecutive scans before rwsender will add it to sendingqueue. The interval between scans is set by --polling-interval.DIR_PATH must be a complete directory path.
--processing-directory=DIR_PATH: Use DIR_PATH as a location to cache files until they are successfullytransferred. For each rwreceiver IDENT specified on the commandline, a subdirectory is created under DIR_PATH to hold a copy of eachfile that is to be sent to that rwreceiver. (rwsender uses areference (a hard link) to the file instead of a copy of the file whenpossible.) DIR_PATH must be a complete directory path.
--error-directory=DIR_PATH: Move a file that is rejected by an rwreceiver (for example, becauseit has a duplicate filename) to the subdirectory IDENT of DIR_PATH,where IDENT is the identifier of the rwreceiver that rejectedthe file. DIR_PATH must be a complete directory path.

Server-mode switches

When running in server mode, the following switches are required:

--server-port=[HOST:]PORT: Listen for incoming rwreceiver client connections on PORT asHOST. If HOST is omitted, rwsender 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 rwreceiver client whose identifier isIDENT. This switch may be repeated to allow multiple rwreceiverclients to connect. rwsender closes the connection if anrwreceiver 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 rwreceiver server listening to portnumber PORT on the machine HOST. rwsender closes theconnection unless the rwreceiver identifies itself as IDENT.This switch may be repeated to connect to multiple rwreceiverservers. HOST may be a name or an IP address; when HOST is anIPv6 address, it must be 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 rwreceiver. 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 rwsender'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 rwsender'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 rwsender'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.rwsender uses the value in the RWSENDER_TLS_PASSWORD environmentvariable to decrypt the PKCS#12 file. If this variable is not set,rwsender 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 rwsender; 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

These are application-specific switches that are not required:

--local-directory=[[IDENT]:]DIR_PATH

Create a duplicate of each incoming file in the directory DIR_PATH.This switch may be specified multiple times to create multipleduplicates. The duplicate is made by a reference (a hard link) to thefile in the processing-directory if possible, otherwise a completecopy is made. (Note that any modification-in-place to a filereference affects all references to that file; use--unique-local-copies to avoid this). If IDENT is specified,filters may be used to determine which files get copied toDIR_PATH. See --filter forfilter details. When DIR_PATH contains the colon character and noIDENT is wanted, a single colon may precede DIR_PATH todesignate an empty IDENT.

--unique-local-copies

Force the duplicate file created in each local-directory to be acomplete copy of the file in the processing-directory instead of areference (a hard link) to the file. Using references saves diskspace and is faster than making a complete copy; however, anymodification-in-place to one file affects all files. rwsenderalways makes a complete copy when it is unable to make a reference.This switch is ignored when the --local-directory switch is notprovided.

--filter=IDENT:REGEXP

Configure rwsender to transfer files matching the regularexpression REGEXP to the rwreceiver whose identifier isIDENT, or to copy files to the local directory labeled as IDENT.This switch may be repeated. When this switch is not provided, allrwreceivers and local directories get all files. When this switchis provided, any files not matching a REGEXP are left in theincoming directory and are not transferred.

The regular expression must be a POSIX 1003.2 modern or extendedregular expressions, roughly akin to those used by egrep(1).Documentation might be found in the regex(7) or re_format(7)manual pages on your system.

The filter is only applied to files in the incoming-directory. Once afile has been moved into an rwreceiver-specific subdirectory of theprocessing-directory, restarting rwsender with a different set of--filter switches does not affect the files previously queued foreach rwreceiver. To apply the filters to unsent files, you muststop the rwsender process, move all files from the subdirectoriesof the processing-directory to the incoming-directory, and restart therwsender process.

--priority=NUM:REGEXP

Set the priority of files that match REGEXP to NUM. NUM mustbe an integer between 0 and 100 inclusive. In the current version ofrwsender, priorities 0 through 50 get grouped into a single lowpriority bin, and priorities 51 through 100 get grouped into a singlehigh priority bin. Files in the high priority bin are generallybe sent before files in the low priority bin. The default priority ofa file is 50. This switch may be repeated for multiple priorities.

--polling-interval=NUM

Configure rwsender to check the incoming directory for new filesevery NUM seconds. The default polling interval is 15 seconds.

--send-attempts=NUM

For each file going to an rwreceiver, make NUM attempts to openthe file, map its contents, and send the contents to thatrwreceiver. After NUM attempts, the file is ignored byrwsender but the file remains in the rwreceiver-specificsubdirectory of the processing directory. Unless the file is manuallyremoved from the processing directory, rwsender again attempts tosend the file when rwsender is restarted. The limit may be set toa value from 1 to 65535. When NUM is 0, there is no limit. Thedefault number of attempts is 5.

--block-size=NUM

Specify the chunk size in bytes that rwsender uses when sendingfiles to rwreceivers. The default number of bytes is 8192; thevalid range is 256 to 65535.

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 rwsender is running.This switch produces an error unless --log-destination=syslog isspecified.
--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 "%", rwsender 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 rwsender 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/rwsender.pid.
--no-chdir: Do not change directory to the root directory. When rwsenderbecomes 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 rwsender 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

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

BUGS

An attempt should be made to use a unique name for each file put intothe incoming directory. When a file is added to the incomingdirectory that has the same name as a file in the processingdirectory, the file added to the incoming directory replaces theexisting file in the processing directory.

Index

NAME

SYNOPSIS

DESCRIPTION

Interaction with rwreceiver

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

BUGS

This document was created byman2html,using the manual pages.