RPIPE

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
ENVIRONMENT VARIABLES
SECURITY CONSIDERATIONS
AUTHORS
BUG REPORTS
COPYRIGHT

---

NAME

rpipe - remote pipe multiplexer

SYNOPSIS

rpipe [-sTv] [-a IPADDR] [-g GROUP[,GROUP...]] [-n NUMBER] [-p FILE] [-S FACILITY] [-u USER] ARG...

rpipe -h | -V

DESCRIPTION

The rpipe tool is a simple TCP multiplexer that makes it possible to send data over the network to the standard input of a remote program much as one would do the same with a local program using shell pipe construct.

The program operates in three modes: server, client and test.

In server mode (requested by the -s command line option), it listens for TCP requests on the indicated IP address and port (default: port 1 on all available network interfaces). The first command line argument is treated as full pathname of the command on the server and the rest of arguments as initial arguments for that command.

Upon receiving an incoming connection, its first line is split into words and appended to the command line stub constructed as described above. The resulting command line is then run and the rest of incoming data is supplied to it as its standard input.

The server replies with an RFC 1078 compliant response line and waits for the program to terminate. Any data received over the network are piped to the program’s standard input. The program’s standard output is captured and sent back to the client. During transmission, each linefeed character (LF, ASCII 10) is replaced by two characters: newline (CR, ASCII 13) and linefeed. A dot appearing at the beginning of a line is duplicated. End of program output is marked with a <CRLF>.<CRLF> marker. When the program terminates, its exit status (as returned by wait(2)) is formatted in decimal and sent over the network, followed by <CRLF>.

In client mode, rpipe sends its arguments as the first line of the request immediately followed by its standard input. Any data received from the remote end is first decoded by reverting the process described above and then reproduced on the standard output. The command will exit with the same exit status as returned by the remote program. If an error occurred, it will exit with code 69 (EX_UNAVAILABLE), or 71 (EX_OSERR), depending on the error.

The test mode is designed to assist in testing the package. It is enabled by the -T switch. It this mode, rpipe starts the server listening on an arbitrary port on localhost and connects to it as client. The -a option is ignored. Command line arguments must consist of two parts, delimited by a -- separator. The part before -- supplies arguments for the server, and the part after it supplies arguments for the client.

In other words, the invocation rpipe -T COMMAND ARG1 -- ARG2 ARG3 is roughly equivalent to:

rpipe -s -a:PORT COMMAND ARG1 &
rpipe -s -a:PORT ARG2 ARG3

where PORT stands for the first free port on localhost. When the program exits, both instances are terminated.

OPTIONS

-a IPADDR[:PORT]

In server mode: define IP address and port to listen on. Either IPADDR or PORT, but not both, can be omitted. If PORT is omitted, it defaults to 1 (the tcpmux service). In this case the colon is optional. If IPADDR is omitted the colon is mandatory. Missing IPADDR defaults to 0.0.0.0.

If this option is not used, the IP address is obtained from the environment variable RPIPE_ADDRESS. If it is not set, the default 0.0.0.0:1 is used.

In client mode, this option defines the IP address (and optional port) to send data to. At least the IPADDR portion must be present. If not set, the IP address will be obtained from the environment variable RPIPE_ADDRESS. If it is not set, an error is signaled.

-g GROUP[,GROUP...]

Valid in server mode only. Run the command with GROUP as the primary owner group. Any additional GROUPs are set as the supplementary groups. Each GROUP can be either a symbolic group name, or a numeric GID preceded by a plus sign.

See also the -u option.

-h

Print a short help summary and exit.

-n NUMBER

Valid in server mode only. Set maximum number of simultaneous connections. Default is 128.

-p FILE

Valid in server mode only. Read run-time execution privileges for the command from FILE. Each non-empty line in FILE consists of two or more words separated by whitespace. The first word is a subcommand name, the second one is the name of the user to run the subcommand as, and remaining words are groups to run as. Comments are introduced with the hash sign and extend up to the end of the line. Before running the command, the first argument from the command line obtained from the client is looked up in that file. If found, the rest of fields gives the privileges to run the constructed command with. If not found, user and group supplied by -u and -g options (if given) will be used.

-S FACILITY

Log messages to the given syslog facility. FACILITY is one of auth, authpriv, cron, daemon, ftp, kern, lpr, mail, news, user, uucp, local0 through local7, or a decimal facility number.

By default all messages are written to stderr.

	-s		Enable server mode.
	-T		Enable the test mode.

-u USER

In server mode. Run the command with the privileges of USER, which is either a symbolic user name or a numeric UID (in decimal), preceded by a plus sign.

	-V		Print program version and copyright information and exit.
	-v		Increase verbosity level.

ENVIRONMENT VARIABLES

RPIPE_ADDRESS

IP address and optional port to listen to (in server mode), or to connect to (in client mode).

SECURITY CONSIDERATIONS

The program is intended for deployment in a secure environment. No authorization is performed. No data encryption is implemented.

AUTHORS

Sergey Poznyakoff

BUG REPORTS

Report bugs to <gray@gnu.org.ua>.

COPYRIGHT

Copyright © 2019--2021 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

---