Reference
Validation

Validation

Use this runbook when validating RayLimit on a real Linux host.

Source-Level Checks

When validating from a checkout, run the make targets that match your change before exercising the binary on a host:

make test         # go vet + full test suite
make test-race    # test suite under the race detector
make vet          # go vet across all packages
make vuln         # govulncheck across all packages
make shellcheck   # shellcheck the release shell scripts
make build        # build bin/raylimit

Use the narrowest set that matches your change; make test-race, make vuln, and make shellcheck are most relevant when touching concurrency, dependencies, or the installer scripts respectively.

Host Readiness Checks

command -v raylimit
command -v tc
sudo -n true
ip link show dev eth0

Expected outcome:

  • the binary is available
  • tc is installed
  • privilege escalation works if you plan to execute
  • the device you intend to shape exists

Safe Validation Order

1. Confirm Basic CLI Health

raylimit version
raylimit --help

2. Discover Candidate Runtimes

sudo raylimit discover
sudo raylimit discover --format json

3. Inspect The Runtime You Plan To Touch

sudo raylimit inspect --pid 1234
sudo raylimit inspect --pid 1234 --format json

4. Dry-Run The Shared Baseline, per_ip, And Specific Variants

sudo raylimit limit --pid 1234 --ip all --device eth0 --direction upload --rate 4096
sudo raylimit limit --pid 1234 --ip all --ip-aggregation per_ip --device eth0 --direction upload --rate 4096
sudo raylimit limit --pid 1234 --ip 203.0.113.10 --device eth0 --direction upload --rate 2048
sudo raylimit limit --pid 1234 --ip 203.0.113.20 --device eth0 --direction upload --unlimited

At this point you are checking:

  • subject selection
  • address handling
  • shared baseline versus specific behavior
  • per_ip evidence state and concrete expansion behavior
  • observation quality
  • decision clarity

5. Dry-Run Inbound And Outbound

sudo raylimit limit --pid 1234 --inbound api-in --device eth0 --direction upload --rate 2048
sudo raylimit limit --pid 1234 --outbound proxy-out --device eth0 --direction upload --rate 2048

For these families, the main validation goal is to confirm whether selector derivation is concrete or blocked.

6. Execute Only Concrete Paths

sudo raylimit limit --pid 1234 --ip 203.0.113.10 --device eth0 --direction upload --rate 2048 --execute

Use one concrete path first. Do not try to validate every family live at once.

7. Repeat A Matching Request To Check No-Op

sudo raylimit limit --pid 1234 --ip 203.0.113.10 --device eth0 --direction upload --rate 2048

If the observed managed state already matches, the decision can become no_op.

Remove Validation

Validate remove separately from apply:

sudo raylimit limit --pid 1234 --ip 203.0.113.10 --device eth0 --direction upload --remove
sudo raylimit limit --pid 1234 --ip 203.0.113.10 --device eth0 --direction upload --remove --execute
sudo raylimit limit --pid 1234 --ip all --ip-aggregation per_ip --device eth0 --direction upload --remove
sudo raylimit limit --pid 1234 --ip all --device eth0 --direction upload --remove

Test specific-IP remove, per_ip remove, and shared-baseline remove independently. They do not represent the same cleanup scope.

Good Validation Signals

You have a strong result when:

  • runtime discovery is clear
  • inspection is readable in text and JSON
  • dry-run output explains the requested state and decision cleanly
  • live execution is concrete only in its safe scope
  • repeated matching requests can become no-op
  • remove only cleans managed state for the selected subject
OverviewTroubleshooting