The environment

The environment file (-c env.yaml) describes your lab:

• the network functions rk simulates, and the ones it talks to;
• the transports that connect them.

Flows don't contain addresses: they name NFs by role, and the environment says where those NFs are. Each key is listed in the generated configuration reference.

Shape

A minimal environment

One simulated gNB that connects to the AMF under test and sends ICMP user-plane traffic:

NFs

• name is unique within the environment.
• role is one of: gnb, amf, smf, ausf, udm, pcf, nrf, upf, mme, pgw, af, pcrf, hss, bsf, nssf, udr, nef, external. Use external for non-3GPP REST peers, such as a vendor admin API.
• transport names an entry under transports:.
• The role block goes with the role: gnb: for a gNB, amf: for an AMF. Only the block that matches the role is read.

Each protocol accepts these roles:

All the gNBs in one environment must be of one kind: all NGAP or all N3-only. Each UE is assigned one of them at random.

The gNB's UE defaults

gnb.ue sets what each simulated UE asks for:

• dnn, by default internet;
• snssai, by default SST 1 with no SD;
• suci.protection_scheme: 0 (null, the default), 1 (profile A) or 2 (profile B). Schemes 1 and 2 need hn_pubkey (hex) and hn_pubkey_id (up to 254).

The AMF block

amf: sets served_guami, relative_capacity, and allowed_gnbs (matched on the RAN node name in NG Setup). An empty allowed_gnbs accepts any gNB.

Transports

Each transport has a protocol and exactly the matching block.

ngap

• local_sctp: the local SCTP address. Give a port to bind one; leave it out to let the kernel pick.
• local_gtpu: the N3 address.
• peers: each with address and port (default 38412), and an optional primary.
• sctp: tuning: RTO, heartbeat, retransmissions, buffers, streams.

Which side rk plays is decided by the NFs, not by mode:

• An environment with an amf NF listens and accepts gNBs (the AMF side; licence feature server.mode).
• Otherwise, its gNBs connect to the peers and run NG Setup by themselves.

Only the first NGAP transport in an environment is used.

SCTP multi-homing. local_sctp and a peer's address can list several IP addresses, either comma-separated or as a YAML list. rk then dials all of a peer's addresses at once.

• Every listed address must be an IP literal, not a wildcard.
• A port goes in the port field, never in a peer's address.

diameter

local:

• origin_host and origin_realm (required), application_ids (at least one);
• vendor_id, by default 3GPP;
• product_name, by default rk;
• watchdog_interval;
• listen to accept peers, over SCTP, TCP, TLS or DTLS;
• responder.timeout, by default 30s.

peers:

• name, transport (sctp or tcp), addr and port (no default; 3868 is usual);
• destination_host and destination_realm;
• connection_mode: initiator (the default), responder or both;
• tls: true to dial the peer over TLS (transport tcp only; 5868 is the usual port). ca_file verifies the peer's certificate (by default the system roots), server_name is the name it must carry (by default addr), and cert_file with key_file is the client certificate rk presents. TLS 1.2 or newer. Over SCTP, tls: true is refused when the file loads: Diameter over SCTP is secured with DTLS, which rk accepts on listen but doesn't dial.

routes: by realm and application. Each route's local_action is relay (the default), local, proxy or redirect.

Only the first Diameter transport in an environment is used.

sbi and rest

Client or server: give exactly one of

• base_url (http or https): rk calls the NF there;
• listen: rk serves the NF itself.

TLS (tls:):

• cert_file and key_file go together.
• A server needs both.
• client_auth applies to servers only. It's require when ca_file is set, otherwise none.
• A server without a tls: block serves cleartext HTTP/2 (h2c).
• http1: true uses HTTP/1.1.

Authentication:

• SBI takes oauth2 (token URL, client or NF instance ID, scope). The client secret comes from an environment variable.
• REST takes auth of type basic, bearer, api_key or none. Secrets come only from environment variables (*_env), never from the file.

pfcp

• mode: client (needs peer.addr and peer.port) or server (needs local as host:port).
• node_id is required: ipv4, ipv6 or fqdn, with a value.

gtpu

• local (IPv4, required) and an optional peer. The port is always 2152.
• A gNB on a gtpu transport is an N3 endpoint with no N2: it sends user-plane traffic, but no NGAP. See Test a UPF.
• A upf on a gtpu transport with reflector: answers GTP-U itself: it echoes uplink traffic back as downlink.

Validate

rk check -c env.yaml loads and validates the file, then probes it (see Use rk in CI). A key the config doesn't have is refused when the file loads, with the file, line and key, for example env.yaml: parse config: line 11: unknown key "prot" in transports.n2.ngap.peers[0] (did you mean "port"?). Validation errors name the key too, for example:

• transport "n3" not declared in transports:
• exactly one of base_url (client mode) or listen (server mode) is required

A file that doesn't load or validate stops every command with exit code 4.

Every key

The environment configuration reference lists every key, generated from the source code. The CLI reference lists every command and flag.