RTSRV(1)

NAME

rtsrv - remote ray-tracing worker for the remrt distributed renderer

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

rtsrv [-d] [-S token] [-x hex_flags] [-X hex_flags] control-host tcp-port [cmd]
rtsrv [-d] [-S token] -I ipc-addr

rtsrv is the worker process of the remrt(1) distributed ray-tracing system. It connects to a running remrt dispatcher, receives the name of a BRL-CAD .g geometry database and the view parameters over the network via libpkg(3), ray-traces the assigned pixel ranges with librt(3), and sends the resulting pixels back to the dispatcher. Many rtsrv instances may run at once; remrt hands each a non-overlapping range of scan-lines and reassembles the results into the final image.

rtsrv is normally launched automatically by remrt, either on remote hosts via ssh(1) or as a local child over an inherited IPC channel (the -I form). It may also be started by hand so that machines unreachable by SSH can join a render.

In the network form, rtsrv opens a TCP connection to control-host on tcp-port and then services protocol messages from remrt: it opens the named .g database locally, prepares the requested object tree(s), applies each view matrix, and ray-traces the assigned scan-lines, returning each completed block of pixels to the dispatcher. When remrt signals end-of-work the connection is closed and rtsrv exits.

Unless -d is given, rtsrv daemonizes after connecting on POSIX systems: it forks, detaches from the controlling terminal, redirects standard I/O to the null device, and drops to the lowest scheduling priority. Steps requiring POSIX-only APIs are skipped on Windows.

If the optional cmd argument is supplied, rtsrv sends that single string to the remrt dispatcher as a command and exits immediately without ray tracing, which is a convenient way to drive a running remrt session remotely.

OPTIONS

-d: Debug (foreground) mode. Disables daemonization so rtsrv stays in the foreground. Repeat the flag (-d -d) to raise the verbosity of the protocol tracing written to standard error.
-S token: Session authentication token: the 64-character (256-bit) hex token printed to standard error by remrt at startup. It is appended to the version handshake so remrt can confirm the worker belongs to this session. When remrt auto-launches workers it adds this flag for you; supply it by hand only for manually started workers that must present the token generated by a running remrt session.
-x hex_flags: Set the librt debug flags (same meaning as the -x flag of rt(1)).
-X hex_flags: Set the optical-shader debug flags (same meaning as the -X flag of rt(1)).
-I ipc-addr: Connect over the local IPC channel at ipc-addr instead of opening a TCP socket. Used internally when remrt spawns a worker on the same machine; no control-host or tcp-port is given in this form. If omitted, the address may instead be inherited through the PKG_ADDR environment variable.
control-host: Hostname or IP address of the machine running remrt.
tcp-port: TCP port on which remrt is listening. remrt tries 4446 first and counts upward if that port is busy; it prints the chosen port to standard error.
cmd: Optional single command string to send to the remrt dispatcher, after which rtsrv exits without ray tracing.

EXAMPLES

Example 1. Add manual workers to a remrt session

# On the dispatcher host, start remrt and note the port + session token:
remrt -o output.pix scene.g all < scene.rt

# On any reachable machine, attach a foreground worker to that session:
rtsrv -d -S 3f8a1c0b...e4 dispatcher.example.com 4446

Starts remrt (which prints its listening port and session token), then attaches an rtsrv worker to it. Launch several rtsrv processes against the same dispatcher to spread the render across additional CPUs and hosts.

Example 2. Drive a running remrt remotely

rtsrv dispatcher.example.com 4446 status

Sends the status command to the remrt instance on port 4446 of dispatcher.example.com and exits, without performing any ray tracing. This is equivalent to typing status at the interactive remrt prompt.