REMRT(1)

NAME

remrt - network-distributed (remote) ray-trace dispatcher

On this page

SYNOPSIS
DESCRIPTION
- Control file
- Work allocation
OPTIONS
EXAMPLES
SECURITY
DIAGNOSTICS
BUGS
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

remrt [options] model.g objects...

remrt is a plug-compatible front end for rt(1) that spreads a ray-traced rendering across many machines on a network. Where rt(1) can use only the processors of a single shared-memory host, remrt acts as a dispatcher: it parcels out scanline work to any number of rtsrv(1) worker processes — possibly on hosts of differing architectures and speeds — using a libpkg(3)-based protocol, and collects the returned pixels into an output file and/or framebuffer.

remrt accepts the same command-line arguments as rt(1); see the rt(1) manual page for the full list of options. The first positional argument is a BRL-CAD model.g database and the rest are the treetop objects to render. From within mged(1) a current-view render can be launched with rrt remrt -M -s, where is the desired image resolution.

remrt provides two levels of fault tolerance. Any rtsrv(1) worker (or network link) that fails has its outstanding work reassigned to other workers automatically, and failed hosts marked "active" are periodically retried. remrt also writes received pixels to disk immediately, so a dispatcher that is killed and restarted resumes from where it left off rather than recomputing finished pixels.

To launch workers automatically, remrt runs ssh(1) on each configured host (the client binary name defaults to ssh and may be overridden at compile time via the SSH macro). Password-less authentication must be configured so workers start without a prompt. Local workers are launched over a libpkg(3) IPC channel (an anonymous pipe or socketpair on POSIX, inherited handles on Windows) and need no TCP listener; the TCP listener is brought up lazily only when a remote or passive worker must connect back.

Without command-line arguments remrt enters an interactive mode in which the framebuffer can be attached or released, frames can be queued, and status and control commands can be issued. Normally remrt runs in batch mode, taking its work from the command line, the script read on standard input, and the .remrtrc control file.

Control file

remrt reads a .remrtrc file (from the current directory, else the user’s home directory) containing ordinary remrt commands run before processing begins. Its main use is one host command per worker host:

host wolf   passive cd /tmp/cad/.remrt.4d
host voyage always  cd /tmp/cad/.remrt.4d
host whiz   hacknight convert /tmp

The first argument is the host name. The second says when to use the host: always (retry roughly every 10 minutes whenever idle), night (1800-0800 plus weekends), hacknight (0400-1300), passive (never auto-start; accept the host only if rtsrv(1) is started there manually), rs [rays/sec] (like always with an optional performance hint), or passrs [rays/sec] (like passive with a performance hint). The third argument says where the database lives: cd changes to the named directory and reads the files already present there (most efficient, but the files must be staged manually), while convert ships a machine-independent copy of the .g file to the host before starting rtsrv(1) (convenient, but auxiliary data such as height fields, textures, and bump maps are not transferred).

Work allocation

The allocteby command selects the dispatch strategy. allocteby frame is a free-for-all over one frame at a time, giving the shortest time to the first finished frame (best for interactive demos). allocteby load withholds a worker from a frame unless at least 10% of its measured capacity is still needed. allocteby movie hands each worker a whole frame, minimizing prep overhead and maximizing throughput for long animations.

OPTIONS

remrt parses the complete rt(1) option set; consult rt(1) for the full description. The options most relevant to distributed rendering are:

-s #: Square image size in pixels (width and height).
-w / -n: Image width and height (scanlines) in pixels.
-o file: Base name for the output .pix file(s); frames are stored as file.N. With no -o and no -F, frames go to temporary files.
-F framebuffer: Send pixels to the named framebuffer.
-M: Read a model2view matrix and animation script from standard input, rather than rendering a single azimuth/elevation view.
-a deg / -e deg: Auto-size view azimuth and elevation in degrees (ignored with -M).
-P #: Number of processor cores requested (parsed for rt(1) compatibility; each rtsrv(1) worker selects its own core count independently).

EXAMPLES

Example 1. Driving a local remrt/rtsrv render by hand

# 1. start a framebuffer server (X11 here; use /dev/wgl on Windows)
fbserv -s2048 -p0 -F/dev/X

# 2. in MGED, frame the scene and save a view script
#       saveview remrt.rt
#    then edit remrt.rt: replace "rt" with "remrt",
#    replace "-o file" with "-F0", and add "-s2048"

# 3. run the edited script to start the dispatcher
./remrt.rt

# 4. from a directory holding the same model.g, start a worker
rtsrv -d localhost 4446

# 5. when all frames report done, save the framebuffer to disk
fb-png -F0 -s2048 image.png

This drives the whole pipeline on one machine without ssh(1): the dispatcher listens on its default TCP port (4446), a manually started rtsrv(1) worker connects back to it, and the finished image is read out of the framebuffer with fb-png(1). The same script scales to many hosts by adding host lines to .remrtrc instead of starting workers by hand.

SECURITY

At startup remrt generates a 256-bit random session token, prints it to standard error, and appends -S token to each rtsrv(1) worker it auto-launches. Workers echo the token in their version handshake and remrt rejects any mismatch. Manually started (passive) workers that present no token are still accepted by default for backward compatibility; to authenticate them, pass the printed token:

rtsrv -S <token> server_host 4446

When built with OpenSSL, all dispatcher-to-worker traffic is encrypted with TLS 1.2 or later. remrt acts as the TLS server, generating an in-memory RSA-2048 self-signed certificate by default; the session token provides application-level authentication in place of certificate verification. Sites with pre-provisioned certificates may set REMRT_TLS_CERT (PEM certificate chain) and REMRT_TLS_KEY (matching PEM private key) before starting remrt. Without OpenSSL, connections fall back to plain TCP.

DIAGNOSTICS

Numerous error conditions are possible; descriptive messages are printed on standard error.

BUGS

Most problems seen while using remrt actually originate in the rt(1) program or the librt(3) library, with which it shares a great deal of code. If a frame fails to render correctly, try it on a single machine with rt(1) to determine whether the fault is in the ray tracing or in the distributed-computation machinery.