> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-api-modify-body.md).

# Linux API modify body

Linux API modify body is a chaos fault that starts a local proxy on the target Linux machine, redirects traffic to/from `TARGET_SERVICE_PORT` through the proxy on `PROXY_PORT`, and overwrites the request or response body with `RESPONSE_BODY` for matching API calls for `DURATION`. `DATA_DIRECTION` chooses whether to modify the `request`, `response`, or `both`. Filters and HTTPS interception controls mirror [Linux API block](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-api-block.md). The fault runs through the Linux Chaos Infrastructure (LCI) systemd service installed on the target VM.

Use this fault to test how callers handle unexpected payloads: whether body validation catches malformed data, whether response parsers crash or recover, whether PII redaction works correctly, and whether monitoring detects the unexpected data within the alerting SLA.

{% hint style="info" %}
**RUN YOUR FIRST EXPERIMENT**

If you have not installed the Linux Chaos Infrastructure yet, go to [Linux Chaos Infrastructure](/resilience-testing/chaos-engineering/use-chaos-engineering/infrastructure/types/legacy-infra/linux.md) to install the agent and connect the VM to the control plane.
{% endhint %}

***

### Use cases <a href="#use-cases" id="use-cases"></a>

Run this fault when you want to answer concrete questions like:

* **Body validation:** When `RESPONSE_BODY` substitutes an unexpected payload, do callers validate it cleanly or crash?
* **PII redaction:** Substitute redacted strings to verify the application does not leak sensitive data through logs or downstream calls.
* **Stub responses:** Inject a fixed payload to exercise downstream paths without changing the upstream service.
* **Monitoring fidelity:** Do alerts on schema-validation failures and business-metric anomalies fire within the alerting SLA?

***

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* **Linux Chaos Infrastructure installed:** The `linux-chaos-infrastructure` systemd service is `active` on the target VM and the infrastructure is in `CONNECTED` state. Go to [Linux Chaos Infrastructure](/resilience-testing/chaos-engineering/use-chaos-engineering/infrastructure/types/legacy-infra/linux.md) to install it.
* **Target service port reachable:** `TARGET_SERVICE_PORT` is the port the application listens on (ingress) or the upstream service port (egress).
* **Proxy port free:** `PROXY_PORT` (default `20000`) is not bound by another process.
* **HTTPS material if `HTTPS_ENABLED=true`:** Provide a CA bundle in `HTTPS_ROOT_CERT_FILE` and additional certificates in `CUSTOM_CERTIFICATES`.
* **`/tmp` is exec-mountable.**

***

### Supported environments <a href="#supported-environments" id="supported-environments"></a>

The fault has been tested on the following Linux distributions. Go to [Linux fault requirements](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/permissions.md) to see the full compatibility matrix.

| Platform                                        | Support status |
| ----------------------------------------------- | -------------- |
| Ubuntu 16+, Debian 10+                          | Supported      |
| CentOS 7+, RHEL 7+, Fedora 30+                  | Supported      |
| openSUSE LEAP 15.4+ / SUSE Linux Enterprise 15+ | Supported      |

***

### Permissions required <a href="#permissions-required" id="permissions-required"></a>

This fault is classified as an **Advanced** Linux fault. It requires the Linux Chaos Infrastructure systemd service to run with the root user and root user group on the target VM so it can install iptables redirects and bind the proxy port. No cloud credentials are needed.

***

### Fault tunables <a href="#fault-tunables" id="fault-tunables"></a>

Configure the following fault parameters when you add Linux API modify body to an experiment in Chaos Studio. Defaults are shown for reference.

**Required parameters**

| Tunable         | Description                                                          | Default    |
| --------------- | -------------------------------------------------------------------- | ---------- |
| `RESPONSE_BODY` | Body string used to overwrite matching request or response payloads. | (required) |

**Chaos parameters**

| Tunable               | Description                                                                                                                                                                                                      | Default |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `DURATION`            | Total duration of the fault. Accepts `[hours]h[minutes]m[seconds]s` format.                                                                                                                                      | `30s`   |
| `TARGET_SERVICE_PORT` | Port of the application (ingress) or upstream service (egress) to intercept.                                                                                                                                     | `80`    |
| `PROXY_PORT`          | Port on which the local proxy listens.                                                                                                                                                                           | `20000` |
| `NETWORK_INTERFACE`   | Network interface used for ingress redirection.                                                                                                                                                                  | `eth0`  |
| `DATA_DIRECTION`      | Direction of data to modify. Accepts `request`, `response`, or `both`.                                                                                                                                           | `both`  |
| `RAMP_TIME`           | Wait period in seconds before and after the fault. Go to [ramp time](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/common-tunables-for-all-faults.md#ramp-time) to read how it is applied. | `0`     |

**Request filters (combine as needed)**

| Tunable           | Description                            | Default |
| ----------------- | -------------------------------------- | ------- |
| `PATH_FILTER`     | API path glob to match.                | `""`    |
| `HEADERS_FILTERS` | HTTP headers filter.                   | `""`    |
| `METHODS`         | Comma-separated HTTP methods to match. | `""`    |

**Direction and source/destination filters**

| Tunable             | Description                                           | Default   |
| ------------------- | ----------------------------------------------------- | --------- |
| `SERVICE_DIRECTION` | `ingress` or `egress`.                                | `ingress` |
| `SOURCE_HOSTS`      | Comma-separated source host names (ingress only).     | `""`      |
| `SOURCE_IPS`        | Comma-separated source IPs (ingress only).            | `""`      |
| `DESTINATION_HOSTS` | Comma-separated destination host names (egress only). | `""`      |
| `DESTINATION_IPS`   | Comma-separated destination IPs (egress only).        | `""`      |
| `DESTINATION_PORTS` | Comma-separated destination ports (egress only).      | `""`      |

**HTTPS interception (egress)**

| Tunable                | Description                         | Default |
| ---------------------- | ----------------------------------- | ------- |
| `HTTPS_ENABLED`        | Enable HTTPS interception.          | `false` |
| `HTTPS_ROOT_CERT_FILE` | Path to the root CA bundle.         | `""`    |
| `CUSTOM_CERTIFICATES`  | Base64-encoded custom certificates. | `""`    |

Tunables that apply to every fault are documented in [common tunables for all faults](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/common-tunables-for-all-faults.md).

***

### Fault execution in brief <a href="#fault-execution-in-brief" id="fault-execution-in-brief"></a>

Adds an iptables redirect that routes `TARGET_SERVICE_PORT` traffic through the local proxy on `PROXY_PORT` for `DURATION`. Matching API calls have their body (per `DATA_DIRECTION`) overwritten with `RESPONSE_BODY` before being forwarded. On exit, the iptables redirect and proxy are removed.

***

### Expected behavior during fault execution <a href="#expected-behavior-during-fault-execution" id="expected-behavior-during-fault-execution"></a>

* Matching API calls deliver `RESPONSE_BODY` in place of the real body (or in addition to the real body, depending on `DATA_DIRECTION`).
* Body schema validators in dependent code fire if the new body does not match the expected schema.
* Status code and headers are unchanged unless paired with [Linux API status code](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-api-status-code.md) or [Linux API modify header](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-api-modify-header.md).
* After the duration ends, the iptables redirect is removed and the proxy stops; bodies pass through unchanged.

{% hint style="info" %}
**WHEN THE FAULT ENDS**

The chaos pod removes the iptables redirect and stops the local proxy. The next request flows directly with the original body.
{% endhint %}

#### Signals to watch <a href="#signals-to-watch" id="signals-to-watch"></a>

Attach [resilience probes](/resilience-testing/chaos-engineering/use-chaos-engineering/probes.md) to assert each layer:

* **Validation errors:** Use a [Prometheus probe](/resilience-testing/chaos-engineering/use-chaos-engineering/probes/apm-probes.md) on body-validation or schema-mismatch counters.
* **End-to-end behavior:** Use an [HTTP probe](/resilience-testing/chaos-engineering/use-chaos-engineering/probes/http-probe.md) on a user-visible endpoint.
* **Business metrics:** Use a Prometheus probe on a business-level success metric (orders accepted, payments completed).

***

### Verify the fault execution effect <a href="#verify-the-fault-execution-effect" id="verify-the-fault-execution-effect"></a>

1. **Send a matching request from the VM.**

   ```bash
   curl -i http://localhost:<TARGET_SERVICE_PORT><PATH_FILTER-example>
   ```

   The response body should equal `RESPONSE_BODY` during the chaos window.
2. **Inspect iptables redirects.**

   ```bash
   sudo iptables -t nat -L -n -v | grep <PROXY_PORT>
   ```
3. **Inspect Linux Chaos Infrastructure logs.**

   ```bash
   sudo journalctl -u linux-chaos-infrastructure -n 100 --no-pager
   ```

***

### Recovery and cleanup <a href="#recovery-and-cleanup" id="recovery-and-cleanup"></a>

* **End of duration:** The chaos pod removes the iptables redirect and stops the proxy when `DURATION` elapses.
* **Abort the experiment:** Stopping the experiment from Chaos Studio also removes the redirect and stops the proxy.
* **Manual recovery:** If the redirect survives an abort, inspect with `sudo iptables -t nat -L -n -v` and delete the rule; kill the proxy with `sudo lsof -i :<PROXY_PORT>` followed by `sudo kill <pid>`.

***

### Limitations <a href="#limitations" id="limitations"></a>

* **Body replacement, not patch:** `RESPONSE_BODY` overwrites the body entirely; partial JSON patches are not supported.
* **Content-Length:** The proxy updates `Content-Length` to match `RESPONSE_BODY`. Chunked encodings are handled but very large bodies may incur overhead.
* **HTTPS requires certificates** for matching by path/header/method.
* **Single VM scope:** Each fault run targets one VM.
* **`/tmp` exec required.**

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>Linux API modify body fault did not modify any body in Harness Chaos Engineering</summary>

Verify PATH\_FILTER and METHODS match your test traffic. For HTTPS endpoints, set HTTPS\_ENABLED=true and provide HTTPS\_ROOT\_CERT\_FILE. Confirm the iptables redirect is in place with sudo iptables -t nat -L -n -v.

</details>

<details>

<summary>Content-Length mismatch errors in callers</summary>

The proxy updates Content-Length to match RESPONSE\_BODY. If callers still see length errors, they may be parsing chunked responses; ensure RESPONSE\_BODY is valid for the target Content-Type.

</details>

<details>

<summary>Body modification persisted after the experiment ended</summary>

If the iptables redirect was not removed, inspect with sudo iptables -t nat -L -n -v and delete the rule. Kill any orphan proxy on PROXY\_PORT.

</details>

***

### Related faults <a href="#related-faults" id="related-faults"></a>

* [Linux API modify header](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-api-modify-header.md): Override headers instead of the body.
* [Linux API status code](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-api-status-code.md): Change the status code (and optionally the body).
* [Linux JVM modify return](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-jvm-modify-return.md): Override method return values inside the JVM instead of at the HTTP layer.