CLI reference

!-- Generated from the source code by make docs-gen. -->

rk: 5G protocol testing tool.

Runik drives protocol procedures, described as YAML flows, against 5G and 4G cores. Run one-shot from the command line (run-flow / run-suite), or as a worker for Runik Control (daemon), which schedules jobs and keeps the reports.

Usage

Code

run-flow / run-suite shared options

Flag	Description
`-templates <dir>[,<dir>...]`	Required. Templates dir(s), recursively walked (kind:flow\|suite per YAML); several dirs are one catalog, a name in two is an error.
`-c, -config <file>`	Config YAML file
`-s, -subscribers <file>`	Subscribers YAML file (consumed in-memory; one per UE)
`-gen-subscriber`	Synthesize a subscriber per UE in memory instead of -s
`-subscriber-seed <n	0xhex>`
`-subscriber-start-msin <n> / -subscriber-count <n>`	With -subscriber-seed: the first MSIN (default 1) and how many (default 0 = unbounded)
`-wire-dump`	Print a TX/RX hex dump of every frame and the JSON trace (was part of -trace)
`-output <fmt>`	Result format: text (default), json, or junit (for CI/agents)
`-output-file <path>`	Write the json/junit report to this file instead of stdout (the human summary still prints to stdout)
`-metrics-port <port>`	Serve Prometheus runik_* metrics at /metrics on this port (0 = off).
`-metrics-addr <addr>`	Address /metrics (and RK_PPROF=1's /debug/pprof) binds (default 127.0.0.1, this machine only; 0.0.0.0 for a remote scraper)
`-fuzz-seed <n	0xhex>`
`-fuzz-out <dir>`	Root dir for fuzz run artifacts (default ./fuzz-runs, or $D3X_FUZZ_OUT)
`-fuzz-metrics-url <url>`	SUT /metrics URL for the panic-counter oracle; a positive d3x_recovered_panics_total delta FAILS
`-fuzz-known-good <flow>`	Known-good flow replayed as the state-corruption oracle; a replay that stops passing FAILS
`-allow-cmd-actions`	Allow 'type: cmd' actions, which execute local programs named by the flow YAML. OFF by default: this is a security boundary

run-flow Options

Flag	Description
`-flow <name>`	Flow to execute (resolved by name from the templates dir)
`-repetitions <n>`	Number of flow starts. Default: 1, or -rate x -duration starts when -rate is given (a server flow stays at 1 context); an explicit 0 is unbounded
`-rate <n>`	Flow starts per second, the first at t=0 (default: 0 = burst all at once)
`-duration <duration>`	Spawn window (e.g., 5m): with -rate N and no -repetitions, N x duration starts. A client burst (-rate 0) ignores it, with a warning; a server flow listens for it
`-timeout <duration>`	Deadline for the WHOLE run, not per UE (default: 30s). UEs still in flight when it fires are counted timed out, which fails the verdict, so so it must exceed the spawn window (repetitions/rate) plus the flow's own on_timeout
`-fuzz-known-good-every <s>`	Replay the known-good flow every N seconds during the campaign (0 = once, after it)
`-ramp / -ramp-from / -max-inflight / -catchup`	Shape a client run's starts: ramp the rate from -ramp-from over -ramp, cap UEs in progress, drop or burst late starts
`-hold <d>`	Population hold: UEs that reach the flow's hold_state stay there d> after the last start, then run its HoldRelease transition
`-idle <d>`	Server flow: end once it has served something and been quiet for d> (a core side that runs until its load side is done)

Load runs (run-flow: a flow with a load: block, or -steps; run-suite: a step with a load: block)

Flag	Description
`-steps <r[:d],...>`	The steps' start rates, each optionally with its spawn window (100,200,400:30s). Makes any client flow a load run
`-ues <n>`	UEs each step starts
`-stop-when <k=v,...>`	The knee rule: success_below=99.9,p99_above=3x_first (or 250ms),spawn_missed_above=0.1,spawn_lag_p99_above=50ms,spawn_shift_above=1s,uplane_loss_above=1,uplane_tx_short_above=5 (dn_tx_short_above and uplane_dn_unknown_ues_above: in a load: block only)
`-drain <d>`	How long past its spawn window and hold a step may take (default 30s); -timeout, when given, bounds the whole sweep
`-peer-metrics <url>`	A peer rk's /metrics, scraped around every step into the report as peer-reported data
`-profile-dir <dir> / -profile-window <d>`	CPU + heap pprof per step; the CPU profile covers the last d> of the step's spawn window (default the whole step)
`-cpus <list>`	Pin rk itself to these CPUs (taskset -c syntax) and size GOMAXPROCS to them; Linux only (run-flow and run-suite)

Notes

Code

run-suite Options

Flag	Description
`-suite <name>`	Suite to execute (resolved by name from the templates dir)
`-repetitions <n>`	Number of full suite cycles. Default: 1, or unbounded (until -duration) when -duration is given
`-duration <duration>`	Run cycles back-to-back until this elapses
`-timeout <duration>`	The deadline for the WHOLE run, as on run-flow (default: none); when it fires, always_run (teardown) steps do not run. The per-step default is -step-timeout
`-step-timeout <duration>`	Timeout of every step that declares no 'timeout:' of its own (default: 30s)
`-fail-fast`	Stop at the first failed step: skip the rest of the cycle (always_run steps still run) and run no further cycle

Notes

Code

fuzz Options (manifest-driven wire-fuzz campaigns; JSON report to stdout)

Flag	Description
`-target <sel>`	Target name, comma-list, or selector (nf=amf \| protocol=pfcp \| all). Required.
`-budget <dur>`	TOTAL campaign wall-clock, DIVIDED across selected targets (never per-target); default 2m
`-fuzz-seed <s>`	'auto' or 'random' (fresh random, printed for replay), a 0x-hex/decimal value to pin, or empty / 'template' (template default)
`-manifest <path>`	Fuzz manifest (default: fuzz/targets.yaml, searched up from cwd)
`-templates <dir>[,<dir>...]`	Override the manifest's templates dir(s)
`-c, -config <file>`	Override the manifest's env config (single target only)
`-s, -subscribers <file>`	Override the manifest's subscribers file
`-fuzz-metrics-url <url>`	Override the panic-counter oracle's SUT /metrics URL
`-fuzz-known-good <flow>`	Override the state-corruption oracle's known-good replay flow
`-fuzz-out <dir>`	Artifact root (default $D3X_FUZZ_OUT, else ./fuzz-runs)
`-output-file <path>`	Write the JSON campaign report to this file instead of stdout

Notes

Code

Daemon Options (control-plane worker)

Flag	Description
`-control <addr>`	runik-control ControlPlane address host:port (required)
`-token <t>`	Join token presented in Register (visible in the process list; prefer -token-file or env RK_TOKEN)
`-token-file <file>`	Read the join token from this file (env: RK_TOKEN_FILE)
`-tls`	Dial the console with TLS, verified against the system roots
`-ca <file>`	Verify the console against this CA bundle (PEM); implies -tls
`-cert <file>`	Client certificate (PEM) for a console that requires mutual TLS; its Common Name or a DNS SAN must equal -id; needs -key
`-key <file>`	Client certificate key (PEM)
`-server-name <name>`	Name to verify the console certificate against (default: the host in -control)
`-insecure`	Dial in cleartext. Without -tls/-ca this is required unless the console is on loopback: the token and subscriber keys would cross the network in clear
`-id <id>`	Worker id (default: hostname)
`-labels <k=v,...>`	Comma-separated scheduler labels (e.g. region=eu,env=lab); a malformed, empty or repeated label exits 2
`-max-held-bytes <n>`	Memory budget for reports and suite cycles the console has not acknowledged (default 256 MiB, at least 64 MiB)
`-drain-timeout <dur>`	On the first SIGINT/SIGTERM: how long to wait for held reports to be acknowledged before exiting (default 20s); a second signal exits at once
`-metrics-port <port> / -metrics-addr <addr>`	Serve Prometheus /metrics (addr default 127.0.0.1); needs the licence feature obs.prometheus
`-debug / -trace / -json / -logfile <path> / -log-caller`	Logging, as in Logging Options; -log-caller adds the source location to each line
`load model`	A console job carries run-flow's load model and subscriber seed (-ramp, -ramp-from, -max-inflight, -hold, -catchup, -subscriber-seed, -subscriber-start-msin, -subscriber-count) in its workload; the daemon applies them as run-flow does and refuses what run-flow refuses. One load spread over N daemons gives each 1/N of the rate and caps, and a disjoint slice of the MSIN range
`SIGHUP`	Re-read the licence file: the next job is gated against it, and the worker registers again if what it may advertise changed
`-allow-cmd-actions`	DANGEROUS. Let console-dispatched flows run `type: cmd`, executing local programs on this host. OFF by default; only set it for a console you fully trust. The programs run as the daemon's user and can read its token file and command line

Subscriber Options

Flag	Description
`subscriber generate`	Generate subscriber credentials (offline): Runik's subscribers YAML, or a core's provisioning file
`-format runik	core
`-seed <n	0xhex>`
`-c <env.yaml>`	Take the PLMN and the gNB `ue:` DNN and S-NSSAI from an env (a core's profile) instead of -mcc/-mnc
`-output-file <path>`	The file written (default subscribers.yaml/.csv/.json/.sh by -format, 0600)

Report Options (presentation of Runik's own JSON reports; nothing is judged)

Flag	Description
`report summarize <report.json>...`	Per step: offered/achieved/peak start rate, success, flow and message latency, spawn lag/missed, CPU, RSS, GC, peer, verdict, knee
`report compare <before.json> <after.json>`	The same figures side by side per rate, with the change in percent
`report hosts -samples <name>=<f.jsonl>... <report.json>`	Per load step: each host's steal (average and worst interval), each sampled process's CPU, counter and device-drop deltas over the step's window (`rk host sample` files), beside the report's own knee/stop marks; -knee for those rows only; -output json too
`-max-cell-steal <pct>`	report hosts: exit 6 when a host's steal over the whole cell is above pct, so a driver repeats the cell on the exit code
`-output md	csv / -output-file path>`

Host Options (measure the hosts a run runs on; nothing is judged)

Flag	Description
`host sample -output-file <f.jsonl>`	One JSON line an interval until SIGINT/SIGTERM (or -duration): /proc/stat's cpu line (steal included), loadavg, and what the flags below name; pure /proc
`-interval <d>`	Time between samples (default 1s)
`-pids-dir <dir> / -pid <name>=<pid>`	Processes to sample: every name>.pid in dir (re-read each sample), and named pids
`-threads <name,...>`	Also sample those processes' threads
`-nstat <Name,...> / -netdev <dev,...>`	/proc/net/snmp\|netstat counters by nstat name (UdpRcvbufErrors) and /proc/net/dev counters per device

Server Options

Flag	Description
`server uspace`	Run uplane receiver via kernel sockets
`server dpdk`	Run uplane receiver via DPDK (embedded runik-dpdk-c; full build only); run 'server -h' for backend-specific flags
`server dn`	Runik's data network: UL sink and DL source for UDP throughput, per-flow reports; -gtpu terminates N3 itself with no core
`-metrics-port / -metrics-addr`	uspace and dpdk: serve /metrics on addr:port (addr default 127.0.0.1); needs the licence feature obs.prometheus

Check Options

Flag	Description
`check -c <file>`	Probe transport connectivity: NGAP to every AMF, Diameter CER/CEA to every peer
`-output <fmt>`	text (default), json, or junit
`-output-file <path>`	Write the json/junit report to this file

Validate Options (static license precheck; no execution)

Flag	Description
`validate -flow <file>`	Check a flow YAML against the license: required proto.* + limits; exit 0 permitted / 1 denied (2 usage, 4 flow/config not loadable, 5 licence unreadable)
`validate -flow <name> -templates <dir>`	Resolve the flow by name from a templates dir instead of a file
`-c <config>`	Also check the env config (transports, responder mode, datapath)
`-s <file> / -rate / -repetitions / -duration`	Also check the planned workload against max_subscribers / max_rate / max_repetitions (resolved as run-flow resolves it)

Discovery Options (offline; for agents)

Flag	Description
`describe -flow <file>`	Print a flow's (or suite's) states/events/actions + mermaid diagram (-output json for JSON)
`lint -flow <file>`	Parse + preparse one flow offline; exit 0 valid / 1 on error
`lint -suite <file>`	Parse one suite offline (structure only; add -templates dir> to resolve what it names)
`lint -templates <dir>`	Parse + preparse every flow/suite in a dir and resolve every suite's references; exit 1 on any
`vocab`	Dump JSON: enricher names + accepted params, check ops, internal events, metric keys
`schema`	Emit a JSON Schema for the flow/suite YAML

Exit codes (run-flow / run-suite / check: gate CI on these)

Code

Logging Options (run-flow, run-suite, fuzz, check, daemon; server backends take -debug and -quiet, uspace and dpdk also -trace)

Flag	Description
`-debug`	Enable debug logging
`-trace`	Enable trace-level logging (verbose); the TX/RX hex dump is -wire-dump
`-quiet`	Log warnings and errors only
`-json`	Output logs as JSON (default: console). Always the log format: describe's output format is -output json
`-logfile <path>`	Write logs to file (run-flow, run-suite, fuzz)

Environment

Flag	Description
`RK_PPROF=1`	Also serve /debug/pprof (and arm block/mutex profiling) on the -metrics-port listener, bound to -metrics-addr
`D3X_LICENSE_FILE`	Licence file to use instead of the default search (an unreadable one exits 5)
`D3X_FUZZ_OUT`	Fuzz artifact root when -fuzz-out is not given (default ./fuzz-runs)
`D3X_TEMPLATES, TMPL_ROOT`	Templates dir `rk fuzz` uses when neither the manifest nor -templates names one (checked in that order, then a d3x-templates dir found up from the cwd)
`D3X_DEV_PUB`	devlicense builds only: one development public key file to trust
`D3X_DEV_KEY_DIR`	devlicense builds only: directory of development public keys to trust
`RK_TOKEN, RK_TOKEN_FILE`	daemon: the join token, or the file holding it

Common Options

Flag	Description
`-h, --help`	Show this message and exit
`-v, --version`	Print version and exit

Examples

Code