Rd — Remote Desktop (RDP) client for Plan 9

Rd is a remote desktop client for the Plan 9 operating system family. It implements Microsoft Remote Desktop Protocol (RDP) and lets you interact with a remote graphical desktop by:

• decoding server “update” PDUs (screen drawing operations) and rendering them locally
• capturing local input (keyboard/mouse) and forwarding it to the server

Rd is written in C and is packaged as a single executable (rd) built from a set of small protocol/UI modules.

---

Supported Plan 9 systems

Rd targets both:

• Plan 9 from Bell Labs, 4th Edition (the “9legacy” line), and
• 9front

The build system resolves platform distinctions automatically in the mkfile based on the build host environment.

---

Protocol and security notes

• Rd targets RDP5-era and newer servers and does not support pre‑RDP5 versions.

• The server must support an upgrade equivalent to STARTTLS (Windows XP SP2 / Windows Server 2003 and newer).

• Server X.509 certificates are verified by okThumbprint against the thumbprint list in:

  • /sys/lib/tls/rdp

---

Building and installing

Rd follows the conventional Plan 9 build workflow:

• Build (for the current host architecture):

  mk
  

• Install (for the current host architecture):

  mk install
  

• Build and install for all supported architectures:

  mk installall
  

---

Usage

rd [-0A] [-T title] [-a depth] [-c wdir] [-d dom] [-k keyspec] [-s shell] [net!]server[!port]

Rd takes exactly one non-optional argument: a server connection string.

Connection string format

The simplest form is just a server name:

• server

The connection string can also include a specific Plan 9 network stack (instead of the default /net/tcp) and an explicit port:

• [net!]server[!port]

Examples:

• windows.example.com
• tcp!windows.example.com!3389

Options

• -k keyspec
  Adds extra attributes to the factotum key query used to obtain credentials (the attributes are appended to the query passed to auth_getuserpasswd).

• -d dom
  Specifies a Windows domain name to authenticate against (for domain logons).

• -A
  Disables factotum-based “auto logon”. With -A, Rd requests the server to present an interactive logon screen instead, and credentials are entered and validated inside the remote GUI session. At that stage, credential submission occurs over an encrypted channel.

• -T title
  Customizes the local window label. By default it is:

  • rd <hostname>

• -a depth
  Select an alternative image depth (bits per pixel). The default is 24 (“full color”).

• -s shell
  Requests a specific logon shell (remote session startup program).

• -c wdir
  Requests a specific remote working directory.

• -0
  Requests attaching to the server’s console session (if supported by the server/negotiation).

---

High-level architecture (for readers of the code)

A quick overview of the runtime flow and the major modules.

1) Entry point and session state

• The program starts in rd.c (main()).
• A single Rdp struct (declared in dat.h) represents the session: network fd, negotiated protocol state, screen parameters, authentication fields, and extension/virtual-channel state.

2) Connection and handshake pipeline

Connection setup follows a staged pipeline:

1. Parse command-line options (title, depth, domain, shell override, working directory, console attach).
2. Optionally obtain credentials from factotum.
3. dial() the server (default TCP port 3389).
4. Perform X.224 transport/session handshake.
5. Initialize the local screen/window.
6. Perform the main RDP handshake (negotiation/capabilities/licensing/activation).

3) Concurrency model: network loop + local input helpers

After handshaking, Rd runs:

• A main network loop that repeatedly:
  • reads and parses protocol messages (readmsg)
  • dispatches them through a session state machine (apply)
• Helper processes created with rfork(RFPROC|RFMEM) to read local devices:
  • mouse input (/dev/mouse)
  • keyboard input (/dev/cons, raw mode via /dev/consctl)
  • clipboard/snarf integration (“snarf” polling)

The helpers forward local events to the server while the main process handles incoming updates and rendering.

4) Message parsing, updates, and rendering

Incoming data is modeled as Msg structures (dat.h) covering:

• X.224 and MCS control PDUs for setup/activation
• licensing messages
• input events
• server “update” PDUs (screen updates)
• virtual channel traffic

Server updates are decoded into higher-level update structures (image updates, palette/colormap updates, pointer warp, etc.) and then rendered via the Plan 9 drawing subsystem.

5) Virtual channels (extensions)

Rd includes a virtual-channel abstraction (Vchan) that:

• maps named channels to handler callbacks
• buffers/defragments channel fragments
• supports features such as clipboard/snarf synchronization
• provides hooks for extensions such as audio and device-redirection-style messages

---

Repository layout (selected files)

Start here:

• rd.c — program entry point, handshake pipeline, network loop, local input helpers
• dat.h — session (Rdp) and protocol/message model (Msg, update structures, virtual channels)
• mkfile — build rules and object list

Protocol and transport:

• x224.c — X.224 connection setup/teardown and TPDU framing (transport/session layer)
• mcs.c — MCS (T.12x) connection/channel management helpers
• mpas.c — core RDP “share control/data” PDU helpers (control flow, security header sizing, transmit prep)
• msg.c — message encode/decode (readmsg/writemsg) and typed Msg marshalling
• cap.c — capability parsing/serialization used during negotiation

Security:

• tls.c / tls9f.c — TLS support and certificate/thumbprint verification glue (build selects the appropriate file)

Rendering and graphics updates:

• draw.c — apply server drawing orders/bitmap updates to the local Plan 9 window
• load.c — bitmap/cache loading helpers used by update decoding
• rle.c — RLE decompression used for bitmap/update payloads
• mppc.c — MPPC decompression used for compressed update payloads
• eclip.c — clipping/region helpers for drawing operations

Input and window integration:

• mouse.c — mouse event encoding and client-to-server forwarding (and pointer warp support)
• kbd.c — keyboard event encoding and client-to-server forwarding
• wsys.c — window-system integration helpers (resizes, window events, etc.)

Virtual channels and extensions:

• vchan.c — virtual channel table setup, fragmentation/defragmentation, and send/dispatch support
• rpc.c — higher-level request/response helpers used by some channel-style interactions
• audio.c — audio virtual channel handling and client-side playback hooks
• efs.c — extension/virtual channel support for device-redirection-style messages (see Efsmsg in dat.h)

Utilities and tests:

• alloc.c — allocation helpers (emalloc/erealloc)
• utf16.c — UTF‑16 conversion helpers used by several protocol fields
• aud_test.c — audio-related tests
• efs_test.c — tests for EFS/extension encoding/decoding
• msg_test.c — message parsing/encoding tests

Headers:

• fns.h — shared internal function declarations across modules