REMRT(1)

📦
version 7.44.0 · 2 versions
, in nixpkgs unstable

✨ REMRT(1) ✨

okay bestie, grab a snack, because this is the remrt page from the BRL-CAD manual and it's genuinely iconic 💅

🌸 NAME 🌸

remrt — the network-distributed (remote) ray-trace dispatcher. yes, that's her job title, and she ate 💖

🦋 SYNOPSIS 🦋

remrt [options] model.g objects...

✨ DESCRIPTION ✨

so remrt is a plug-compatible front end for rt(1) that spreads a ray-traced rendering across, like, many machines on a network. where rt(1) can only use the processors of one single shared-memory host (one machine, one vibe), remrt is the dispatcher — the main character, honestly 👑 — parceling out scanline work to any number of rtsrv(1) worker processes. and those workers can be on hosts of totally different architectures and speeds, no cap. it uses a libpkg(3)-based protocol and collects all the returned pixels into an output file and/or framebuffer. teamwork makes the dream work fr fr 🫶

remrt accepts the exact same command-line arguments as rt(1) — go check the rt(1) manual page for the full list, iykyk. the first positional argument is a BRL-CAD model.g database and the rest are the treetop objects to render. and here's a cute trick: from inside mged(1) you can launch a current-view render with rrt remrt -M -s###, where ### is the desired image resolution ✨

remrt gives you two levels of fault tolerance, which is lowkey generous of her:

  • 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's killed and restarted resumes from where it left off instead of recomputing finished pixels. queen behavior 💅

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 — no prompt, no drama 🙈 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. lazy but make it efficient ✨

without command-line arguments remrt enters an interactive mode where the framebuffer can be attached or released, frames can be queued, and status and control commands can be issued. normally though, 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, and honestly the options are giving schedules:

  • 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
  • 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 ⚠️). pick your fighter 💀

🌈 Work allocation

the allocteby command selects the dispatch strategy. three moods:

  • allocteby frame — 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, bestie, don't skip it. the options most relevant to distributed rendering are:

  • -s # — square image size in pixels (width and height). it's giving "square is fine" 🟪
  • -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 (see libfb(3))
  • -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, sorry bestie)
  • -P # — number of processor cores requested (parsed for rt(1) compatibility; each rtsrv(1) worker selects its own core count independently — she's just here for compatibility, not for micromanaging 💅)

🧚 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). and the same script scales to many hosts by adding host lines to .remrtrc instead of starting workers by hand — glow up at scale 👑

🔒 SECURITY 🔒

bestie, pay attention, this part is serious (but cute) 🛡️

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 — so like, no encryption. you've been warned 😭

🌸 DIAGNOSTICS 🌸

numerous error conditions are possible; descriptive messages are printed on standard error. so many ways to go wrong, and she'll tell you about every one of them 💀

🐛 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 — so don't come for her before you check 😤. 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. classic divide-and-conquer diagnostic moment fr fr

🦋 SEE ALSO 🦋

brlcad(1), rt(1), rtsrv(1), mged(1), fbserv(1), fb-png(1), ssh(1), libfb(3), libpkg(3), librt(3), pix(5)

  1. Muuss, "Workstations, Networking, Distributed Graphics, and Parallel Processing", in "Computer Graphics Techniques: Theory and Practice", ed: Rogers & Earnshaw, Springer Verlag, New York, pages 409-472. 📚

💖 AUTHOR 💖

BRL-CAD Team 🫶

This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.

📬 BUG REPORTS 📬

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org — yes, an actual email address, iconic retro behavior 💌

and that's the whole page, bestie! 🌈 this was REMRT(1) from the BRL-CAD manual — go forth and distribute those rays. periodt 💅✨

📦 where this page comes from