NAME

rfbproxy - record, play back, or export a VNC session

SYNOPSIS

rfbproxy [OPTION]... ACTION files

DESCRIPTION

rfbproxy is a simple proxy for VNC, which allows recording of screen updates, key presses and mouse events, for later replay to a VNC client or export as a series of PPM frames. It can also record screen updates by connecting to a VNC session shared by other client(s). Exporting as a series of PPMs is the first step towards converting a session to video using tools such as mjpegtools(1), ffmpeg(1), and/or ffmpeg2theora.

OPTIONS

ACTION is exactly one of:

-r, --record: record RFB communications and store them in the file (only one file is allowed for files)
-p, --playback: play back the RFB communications that were captured to the files
-x, --export: export as a series of PPM frames written to standard output the RFB communications that were captured to the files

OPTIONS can be:

-c, --stdout: use stdin and stdout for communications with the client. Useful in conjunction with inetd
-l, --loop: (playback only) when file is finished, replay from first FrameBufferUpdate
-d, --date: (record only) append date to end of filename
-s, --shared: (record only) attach to a shared session
-v: increase verbosity
--pause=key: (playback only) when key is pressed, playback will be paused until it is pressed again. key can be either a single lowercase ASCII character or an X Windows keysym in hex (no preceding '0x'). Note that keys between 'a' and 'f' will be interpreted as hexadecimal numbers, and must be specified as '61' through '66'. Backspace is 'ff08'; Return is 'ff0d'; Escape is 'ff1b'; Delete is 'ffff'. (no default)
--cycle=key: (playback only) when multiple files are specified pressing key will cycle between them. Specified in same way as --pause. (no default)
--type=WHAT: (proxy record only) capture either screen updates (`screen') or keyboard/mouse events (`events'). If 'events' are requested, an RFM (remote framebuffer macro) file is recorded that can be played back with rfbplaymacro. (default screen)
--framerate=[ntsc|pal|file|m/n]: (export only) specify framerate by name or numeric ratio (m/n frames per second) (default ntsc)
:n: Occupy VNC display localhost:n (not valid with -c option; default :10).
--server=[server]:display: (record only) use specified VNC server (default localhost:0)

EXAMPLES

rfbproxy -r log.fbs: Wait for a VNC client to connect to localhost:10, then connect to localhost:0 and relay all VNC traffic between them, recording the screen updates in FBS 1.0 format to log.fbs and exiting when the client disconnects. See BUGS AND CAVEATS below for limitations of FBS 1.0.
rfbproxy -rs log.fbs: Connect to localhost:0 as a shared session and record the screen updates in FBS 1.1 format to log.fbs until killed (CNTL-C or kill).
rfbproxy -p log.fbs: Wait for a VNC client to connect to localhost:10, then playback the VNC session recorded in log.fbs.
rfbproxy -pl --cycle=ff0d log.fbs: Looping playback that resets if the Return key hit. Useful for playing back sessions whose colors don't show right because of client-initiated changes in pixel format; hitting Return right away to reset the playback often helps. See BUGS AND CAVEATS below for a better solution.
rfbproxy -x log.fbs | ppmtoy4m -S 420_jpeg | mpeg2enc -o video.mpg: Convert the VNC session in log.fbs to MPEG-2 using mjpegtools(1).
rfbproxy -x log.fbs | ppmtoy4m -S 420_jpeg | ffmpeg -f yuv4mpegpipe -i - -vcodec mpeg4 video.avi: Convert the VNC session in log.fbs to MPEG-4 using ffmpeg(1) (ppmtoy4m(1) is from mjpegtools(1)).

Here's simple shell script that simultaneously records VNC and audio at DVD's 48 kHz sample rate (vrec is from sndtools):

#!/bin/sh

function terminate() {
kill $background_pid
}
trap terminate SIGTERM SIGINT SIGKILL

rfbproxy -rs fbs &
background_pid=$!

vrec -s 48000 -b 16 -r audio

This one converts the recorded fbs/audio pair into a DVD-standard MPEG-2 with MP2 audio using mjpegtools(1) and toolame(1).

#!/bin/sh

rfbproxy -x fbs | ppmtoy4m -S 420_jpeg | \ yuvscaler -n ntsc -O DVD | mpeg2enc -f 8 -o video.mpv
toolame -m mono -s 48 audio audio.mp2
mplex -f 8 -o video.mpg audio.mp2 video.mpv

And this one converts the recorded fbs/audio pair into an DivX6-compatible MPEG-4 with MP3 audio using ffmpeg(1) and lame(1).

#!/bin/sh

lame -m m -x -r -s 48 -h audio audio.mp3
rfbproxy -x fbs | ppmtoy4m -S 420_jpeg | \ ffmpeg -f yuv4mpegpipe -i - -i audio.mp3 \ -vcodec mpeg4 -vtag DivX -b 800 -g 300 -bf 2 -acodec copy video.avi

Both MPEG-2 and MPEG-4 files can be converted to Ogg/Vorbis with ffmpeg2theora:

ffmpeg2theora -o video.ogg video.avi

SECURITY

To avoid recording passwords (even encrypted), rfbproxy discards authentication information when recording a session, and instead changes the recorded authenticated scheme to look like the session used no authentication.

rfbproxy does not authenticate incomming connections in playback mode.

Recording keystrokes with --type=events can record passwords.

BUGS AND CAVEATS

A proxy record will create a version 1.0 FBS file whose pixel formats can't be reliably interpreted, and will probably only work for playback to the same (or a very similar) client that recorded it, and not for export. Shard-session records create version 1.1 FBS files that don't have this problem.

Playback makes no attempt to handle client FramebufferUpdateRequests; it justs transmits a series of FramebufferUpdates exactly as they were recorded. This defect is most noticeable with clients that pan across a session larger than their window size; the exposed areas will probably remain undrawn by rfbproxy. Clients that switch pixel formats (i.e, xvncviewer) can also be affected by this; parts of the screen can remain drawn in a low-resolution format after the client has switched to a high-resolution format. Fix this by stopping the client from changing pixel formats. For xvncviewer try -autoselect=0 -fullcolor (version 4.1.1) or -noauto -depth 24 (version 3.3.7).

If you intend to use the --loop or --cycle options when playing back an FBS 1.0 file, you cannot use the ZRLE encoding when recording. This is because the zlib state cannot be maintained. FBS 1.1 files do not use ZRLE at all.

Suspending rfbproxy (or any script using it) when recording in shared session mode can freeze all sessions attached to the VNC server.

Neither export nor FBS 1.1 playback work on colormap sessions (only true color is supported).

Pixel formats larger than 32 bits are not supported.

AUTHORS

Tim Waugh <twaugh@redhat.com>
Brent Baccala <baccala@freesoft.org>