FBSERV(1)

NAME

fbserv - serve a BRL-CAD framebuffer to remote or local clients

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
SECURITY
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

fbserv [-v] [-T] [-A] [-{sS} _squaresize_] [-{wW} _width_] [-{nN} _height_] [-p _port_] [-F _framebuffer_] [_port_] [_framebuffer_]
fbserv [-v] [-A] [-F _framebuffer_] -I _ipc_addr_

fbserv opens a framebuffer and makes it available to BRL-CAD programs (such as rt(1), pix-fb(1), and fb-pix(1)) that access a framebuffer over the libpkg protocol. It can run in three ways: as a stand-alone daemon that forks a fresh server for each connection, as a single-framebuffer server that opens one device and holds it open across many interleaved connections, or as an inetd(8) remote framebuffer server.

By default fbserv listens for TCP connections. The -p option sets the TCP port and the -F option names the framebuffer device. Either may instead be given positionally: the first non-option argument is taken as the port and the second as the framebuffer device. A port below 1024 has 5559 added to it, so port 0 maps to the default 5559. When -F is given, fbserv opens that device immediately and keeps it open (a reattachable, state-preserving framebuffer); otherwise the framebuffer named in each client’s open request is opened and closed per connection.

The -s (or -S) option requests a square framebuffer of the given size in pixels; -w (or -W) sets width and -n (or -N) sets height independently. If invoked from inetd(8) with an open socket on file descriptor 0, fbserv processes a single connection and exits.

With -I ipc_addr, fbserv uses a libpkg IPC transport instead of binding a TCP listener, and -p is ignored. Listener-capable IPC addresses accept repeated local client connections; inherited endpoint addresses serve a single client, for parent/child process handoff. Clients reach an IPC server using a framebuffer name of the form *ipc:*ipc_addr.

OPTIONS

-v: Enable verbose status output.
-T: Enable TLS encryption for protocol traffic. Requires an OpenSSL-enabled build; the FBSERV_TLS environment variable has the same effect.
-A: Strict authentication: reject any client that does not present a valid token via the protocol authentication message.
-s squaresize, -S squaresize: Request a square framebuffer of squaresize by squaresize pixels.
-w width, -W width: Set the framebuffer width in pixels.
-n height, -N height: Set the framebuffer height in pixels.
-p port: Set the TCP port number. Ports below 1024 have 5559 added.
-F framebuffer: Open framebuffer at startup and hold it open across all client connections.
-I ipc_addr: Use the libpkg IPC transport at ipc_addr instead of binding a TCP listener. The address is generated by the invoking application and should be treated as opaque. In this mode -p is ignored.
-h, -?: Print a usage message and exit.

SECURITY

Token authentication works with or without TLS. If FBSERV_TOKEN is set in the environment (to 64 hex characters) before fbserv starts, that value is used as the required shared token; clients must set the same FBSERV_TOKEN value. If FBSERV_TOKEN is not set, fbserv generates a fresh token at startup and prints it to standard error. With -A, clients that do not authenticate are rejected; without it, unauthenticated clients are still accepted.

EXAMPLES

Example 1. Reattachable framebuffer for rendering

fbserv -s 1024 0 /dev/wgl &
rt -F 0 -s 1024 model.g component

Open a persistent 1024x1024 framebuffer on the local display and bind it to port 0 (which maps to default port 5559), then ray trace into it with rt(1). Because the device stays open, successive renders accumulate in the same framebuffer and the image survives between client connections.

Example 2. Authenticated TLS server

export FBSERV_TOKEN=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
fbserv -T -A -p 0 -F /dev/wgl &
rt -F 0 model.g object

Run fbserv in encrypted, strictly authenticated mode. Both the server and every client must share the same FBSERV_TOKEN; the -T flag enables TLS (in an OpenSSL-enabled build) and -A rejects any client that fails to authenticate.