RTSRV(1)

📦 version 7.44.0, in nixpkgs unstable

💅 RTSRV(1) 💅

okay so this is the rtsrv page from the BRL-CAD manual set — the remote ray-tracing worker situation. buckle up bestie, we're distributing a render 🎀

✨ NAME ✨

rtsrv — the remote ray-tracing worker for the remrt distributed renderer. yes that's her job title 💅

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

okay so rtsrv is literally the worker process of the remrt(1) distributed ray-tracing system. she connects to a running remrt dispatcher, receives the name of a BRL-CAD .g geometry database plus the view parameters over the network via libpkg(3), ray-traces the pixel ranges she's been assigned using librt(3), and sends the resulting pixels back to the dispatcher. many rtsrv instances can run at once — no cap — and remrt hands each one a non-overlapping range of scan-lines and reassembles the results into the final image. it's giving teamwork, it's giving main character energy 👑

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

in the network form, rtsrv opens a TCP connection to control-host on tcp-port and then services protocol messages from remrt: she 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. periodt 💀

unless -d is given, rtsrv daemonizes after connecting on POSIX systems: she 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. (windows girlies, you're exempt from the fork behavior 😭)

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 honestly such a convenient way to drive a running remrt session remotely. lowkey iconic 🔥

⭐ 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. more -d, more yapping 🙈
  • -S token — session authentication token: the 64-character (256-bit) hex token printed to standard error by remrt at startup. it gets 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. it's the friendship bracelet that proves you belong 💖
  • -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)). note the capital X, bestie, they're different flags, do NOT mix them up 💀
  • -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. where she's headed 🗺️
  • 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. so like, check stderr, she told you 👀
  • cmd — optional single command string to send to the remrt dispatcher, after which rtsrv exits without ray tracing. drive-by command delivery, slay 🚗

🌈 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. more workers = more speed = more slay 🧚

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. chef's kiss, no notes 👑

💜 SEE ALSO 💜

remrt(1), rt(1), ssh(1), brlcad(1), mged(1), librt(3), libpkg(3), pix(5)

like, go read all of them. iykyk 📚

🌸 AUTHOR 🌸

BRL-CAD Team — the collective, the iconique 🫶

this software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory. yes the government owns this and yes that's a long-running copyright era, we respect the legacy 👑

🙈 BUG REPORTS 🙈

reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org. don't suffer in silence bestie, tell the devs 💌

ngl if something's acting cursed, that's a bug, and bugs go to the email above. fr fr.

okay that's the whole page!! source/version is BRL-CAD, and this is the rtsrv(1) page out of that set — copyright range 1989-2026. go forth and distribute that render, bestie 💅✨🦋

📦 where this page comes from