Apply impairment

puthttp://localhost/v1/impairments/{direction}

Served over the Unix socket /run/chaosd/chaosd.sock

Programs an impairment onto a direction and returns the post-apply AppliedState. Apply takes ownership of the port unconditionally: it replaces whatever stack was there.

Every field of the body is independent. Set as many as needed and they compose into a single qdisc stack. All durations are nanoseconds, percentages are in [0, 100], and correlation and probability are in [0.0, 1.0].

If the kernel rounds or rejects a value, the response carries a divergence list describing the difference.

Path parameters

directionstringRequired

The direction to operate on. Each direction is configured independently. An unknown value returns 400.

Allowedport1port2

Request

application/json

This endpoint expects an Impairment object.

The complete shaping state of one direction. Omitted fields are not applied.

latencyLatencyOptional

Constant or stochastic one-way delay, distinguished by kind.

lossLossOptional

Packet loss, distinguished by model.

rateRateOptional

Token-bucket rate ceiling, backed by tbf.

queueQueueOptional

A bounded pfifo queue at the bottom of the stack.

duplicationDuplicationOptional

reorderingReorderingOptional

corruptionCorruptionOptional

Response

200 · application/json

Post-apply state. Returns an AppliedState object.

directionstringRequired

Allowedport1port2

impairmentImpairmentRequired

The complete shaping state of one direction. Omitted fields are not applied.

divergencelist of DivergenceOptional

Differences between requested and applied state. Omitted when empty.

captured_atinteger <int64>Required

Monotonic timestamp in nanoseconds. The ordering source of truth.

captured_at_wallinteger <int64>Required

Wall-clock time in nanoseconds since the Unix epoch, for human correlation only.

Errors

400

Problem

Unknown direction or malformed body.

403

Problem

Permission denied. The daemon lacks CAP_NET_ADMIN.

422

Problem

The backend cannot apply this configuration, for example Gilbert-Elliott loss or the paretonormal distribution in this release, or the kernel rejected it.

500

Problem

Backend or I/O error.

getGet applied impairment

DELClear impairment

put/v1/impairments/{direction}

curl --unix-socket /run/chaosd/chaosd.sock -X PUT http://localhost/v1/impairments/port1 \
     -H "Content-Type: application/json" \
     -d '{
       "rate": {
         "bps": 25000000,
         "burst_bytes": 50000
       },
       "latency": {
         "kind": "stochastic",
         "mean": 30000000,
         "jitter": 5000000,
         "distribution": {
           "kind": "pareto"
         }
       },
       "loss": {
         "model": "bernoulli",
         "pct": 0.1
       }
     }'

Response

{
  "direction": "port1",
  "impairment": {
    "rate": {
      "bps": 25000000,
      "burst_bytes": 50000
    },
    "latency": {
      "kind": "stochastic",
      "mean": 30000000,
      "jitter": 5000000,
      "distribution": {
        "kind": "pareto"
      }
    },
    "loss": {
      "model": "bernoulli",
      "pct": 0.1
    }
  },
  "captured_at": 123456789,
  "captured_at_wall": 1700000000000000000
}