Configuration¶

Ryll can be configured via command-line arguments and .vv configuration files.

Command Line Options¶

ryll [OPTIONS]

Connection Source (one required)¶

Option	Description
`--url <URL>`	Fetch .vv configuration file from HTTP URL
`--file <PATH>`	Load .vv configuration from local file
`--direct <CONN>`	Direct connection: `HOST:PORT` or `HOST:PORT:TLS_PORT`

Operating Modes¶

Option	Default	Description
`--headless`	false	Run without GUI (for automated testing)
`--cadence`	false	Send automatic keystroke every 2 seconds

USB Device Redirection¶

Option	Default	Description
`--usb-disk <PATH>`	none	Present a RAW disk image as a USB mass storage device (repeatable)
`--usb-disk-ro <PATH>`	none	Same as `--usb-disk` but read-only (repeatable)

Capture and Debugging¶

Option	Default	Description
`--capture <DIR>`	none	Write pcap + video capture to directory
`-v, --verbose`	false	Enable debug-level logging
`--latency-file <PATH>`	none	Write latency measurements to CSV file

Examples¶

# Connect using a .vv file from a URL
ryll --url https://cloud.example.com/console/vm-123.vv

# Connect using a local .vv file
ryll --file ~/downloads/myvm.vv

# Direct connection to a SPICE server (insecure)
ryll --direct 192.168.1.100:5900

# Direct connection with TLS
ryll --direct 192.168.1.100:5900:5901

# Headless mode for automated testing
ryll --file test.vv --headless

# Performance testing with latency tracking
ryll --file test.vv --cadence --latency-file latency.csv

# Capture protocol traffic and display video
ryll --file test.vv --capture /tmp/capture

# Verbose output for debugging
ryll --file test.vv -v

# Attach a RAW disk image as a USB flash drive
ryll --file test.vv --usb-disk /path/to/image.raw

# Attach a read-only USB disk
ryll --file test.vv --usb-disk-ro /path/to/image.raw

# Headless mode with USB disk
ryll --file test.vv --headless --usb-disk /tmp/test.raw

.vv File Format¶

The .vv (virt-viewer) file is an INI-format configuration file. Ryll supports the standard virt-viewer format used by remote-viewer and other SPICE clients.

Basic Format¶

[virt-viewer]
type=spice
host=192.168.1.100
port=5900

Supported Fields¶

Field	Required	Description
`host`	Yes	SPICE server hostname or IP address
`port`	No*	SPICE insecure port (usually 5900+)
`tls-port`	No*	SPICE TLS port for secure connections
`password`	No	SPICE password for authentication
`ca`	No	Inline PEM CA certificate for TLS verification
`host-subject`	No	Expected server certificate subject

Example .vv Files¶

Minimal (insecure connection):

[virt-viewer]
type=spice
host=192.168.1.100
port=5900

With password:

[virt-viewer]
type=spice
host=192.168.1.100
port=5900
password=mysecretpassword

TLS connection with inline CA (as generated by Shaken Fist):

[virt-viewer]
type=spice
host=spice.example.com
tls-port=5901
ca=-----BEGIN CERTIFICATE-----\nMIIE...(base64)...\n-----END CERTIFICATE-----\n

Note: the ca= field contains the PEM certificate inline with \n escape sequences for newlines, not a file path. Either port or tls-port (or both) must be specified.

Full configuration:

[virt-viewer]
type=spice
host=spice.example.com
port=5900
tls-port=5901
password=mysecretpassword
ca=-----BEGIN CERTIFICATE-----\nMIIE...\n-----END CERTIFICATE-----\n
host-subject=CN=spice.example.com

Keyboard Shortcuts¶

These shortcuts are available during a GUI session. They are consumed by ryll and not forwarded to the guest VM.

Shortcut	Action
F11	Toggle the live traffic viewer side panel
F12	Open / close the bug report dialog
Escape	Close the bug report dialog, or skip region selection

Environment Variables¶

Currently, ryll does not use environment variables for configuration. All settings are provided via command-line arguments or .vv files.

Logging¶

Ryll uses the tracing crate for logging. By default, INFO-level messages are shown. Use -v or --verbose for DEBUG-level output.

Log output goes to stderr, so you can redirect stdout for data output:

ryll --file test.vv --headless 2>debug.log

Latency File Format¶

When --latency-file is specified, ryll writes latency measurements in CSV format:

timestamp,latency_ms
1706540400.123,45.2
1706540402.125,43.8
1706540404.127,44.1

timestamp: Unix timestamp of the measurement
latency_ms: Time from keystroke to display update in milliseconds

This is primarily useful in cadence mode, where keystrokes are generated at known intervals.

USB Device Redirection¶

Ryll can present a RAW disk image as a USB mass storage device to the remote VM. The guest OS sees a standard USB flash drive and can partition, format, mount, read, and write it.

Creating a Test Image¶

# Create a 64MB empty image
dd if=/dev/zero of=test.raw bs=1M count=64

# Optionally format it with a filesystem
mkfs.ext4 test.raw

QEMU Requirements¶

The SPICE server (QEMU) must have USB redirection enabled:

-device qemu-xhci,id=xhci
-chardev spicevmc,id=usbredir1,name=usbredir
-device usb-redir,chardev=usbredir1,id=redir1

Use make test-qemu-usb to start a pre-configured QEMU instance.

Usage¶

# GUI mode
ryll --direct localhost:5900 --usb-disk test.raw

# Headless mode
ryll --direct localhost:5900 --headless --usb-disk test.raw

# Read-only (guest cannot write to the image)
ryll --direct localhost:5900 --usb-disk-ro test.raw

Notes¶

Only the first --usb-disk / --usb-disk-ro is connected (SPICE supports one device per usbredir channel).
The image file must be at least 512 bytes.
If the file size is not a multiple of 512, trailing bytes are inaccessible (a warning is logged).
The device auto-connects when the usbredir channel's hello exchange completes.
Use --capture <DIR> to capture usbredir protocol traffic to usbredir.pcap for debugging.

USB Panel (GUI Mode)¶

In GUI mode, click the USB button in the status bar to open the USB device management panel. The panel shows:

Channel status — whether a usbredir channel is available from the SPICE server.
Connected device — the currently redirected device with elapsed connection time.
Device list — all available USB devices (physical and virtual). Physical devices are enumerated from the host via nusb. Virtual devices come from --usb-disk flags and runtime additions. Each device has a Connect or Disconnect button.
Add Disk... — opens a native file picker to add a RAW disk image as a virtual USB device for the current session. A "Read-only" checkbox controls write access. The file is validated (must be a regular file,

= 512 bytes).
Refresh — re-enumerates available devices. Useful if USB devices were plugged in or removed after the panel was opened.
Error display — connection failures appear in red with a Dismiss button and a "Report this as a bug" button that opens the bug report dialog pre-populated with the USB error and usbredir channel context.

The panel can be open simultaneously with the Traffic viewer panel. Devices added via the panel persist for the session but are not saved across restarts — use --usb-disk for persistent configuration.

Physical USB device passthrough requires the host to have accessible USB devices (appropriate permissions, not claimed by a kernel driver). The panel enumerates whatever nusb can see — if the list is empty, check host USB permissions.

📝 Report an issue with this page