Toxiproxy

Search for Toxiproxy in the Marketplace, select the SecureAnyCloud publisher, and select Create.

Configure the network security group to allow TCP 8080 (the demo proxy) from the clients that will use it, and TCP 22 for administration. Leave port 8474 closed. You drive the control API locally, not over the network.

Create the resource group and VM, then open the demo proxy and SSH ports:

RG="resilience-test"; LOCATION="eastus"; VM_NAME="toxiproxy1" IMAGE_URN="sac1647283583153:toxiproxy-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:toxiproxy-ubuntu-24-04:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
# Open the demo proxy + admin ports on the VM's NSG (NOT 8474):
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 8080 --priority 1001
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1002

On first boot the image resolves the VM public IP, starts the bundled upstream and Toxiproxy, restores the demo proxy with its sample latency toxic, and writes a per-VM instance info file. This completes within a minute. SSH in as azureuser and read the instance details:

sudo cat /root/toxiproxy-credentials.txt

The file records this VM's connection facts: the host, the control API endpoint, and the demo proxy name, listen port and upstream. Toxiproxy has no authentication store, so there is no password to rotate. The control API is protected by being bound to loopback only.

Both toxiproxy.service and the bundled toxiproxy-demo-upstream.service should be active. The control API listens on 127.0.0.1:8474 (loopback), the demo upstream on 127.0.0.1:8899 (loopback), and the demo proxy on 8080 (reachable on the VM). Run:

systemctl is-active toxiproxy.service
systemctl is-active toxiproxy-demo-upstream.service /usr/local/bin/toxiproxy-server --version ss -tln | grep -E ':8474|:8080|:8899'

Expected output:

active active toxiproxy-server version 2.12.0 LISTEN 0 5 127.0.0.1:8899 0.0.0.0:* LISTEN 0 4096 127.0.0.1:8474 0.0.0.0:* LISTEN 0 4096 *:8080 *:*

List the proxies, then inspect the demo. The demo forwards the public port 8080 to the bundled loopback upstream and carries a sample downstream latency toxic.

toxiproxy-cli list toxiproxy-cli inspect demo

Expected output:

demo [::]:8080 127.0.0.1:8899 enabled 1 sac_latency type=latency stream=downstream toxicity=1.00 attributes=[ jitter=0 latency=500 ]

Send an HTTP request through the demo proxy on port 8080. It reaches the bundled upstream and returns HTTP 200. The sample 500 millisecond latency toxic delays the response, and the delay shows in the round-trip time.

curl -s -o /dev/null -w 'HTTP %{http_code}, round-trip %{time_total}s\n' http://localhost:8080/

Expected output (about half a second, from the sample toxic):

HTTP 200, round-trip 0.501998s

This is what Toxiproxy is for: changing network conditions deterministically, on demand. Add a stronger latency toxic, observe the slower round trip, then remove it and confirm the proxy is fast again. Put the flags before the proxy name, so the proxy name is always the last argument.

toxiproxy-cli toxic add -t latency -a latency=2000 -n slow_demo -d demo curl -s -o /dev/null -w 'with 2000ms toxic: HTTP %{http_code}, round-trip %{time_total}s\n' http://localhost:8080/ toxiproxy-cli toxic remove -n slow_demo demo

Expected output:

Added downstream latency toxic 'slow_demo' on proxy 'demo' with 2000ms toxic: HTTP 200, round-trip 2.503320s Removed toxic 'slow_demo' on proxy 'demo'

The Toxiproxy control API is unauthenticated, so it must never be reachable from the network. This image binds it to 127.0.0.1:8474. You can verify this: the API answers on the loopback address but is refused on the VM's own network address.

curl -s -o /dev/null -w 'API on 127.0.0.1:8474 -> HTTP %{http_code}\n' http://127.0.0.1:8474/version
PIP=$(hostname -I | awk '{print $1}')
curl -sS -m 3 "http://$PIP:8474/version" >/dev/null 2>&1 \
  && echo "reachable on $PIP:8474 (unexpected)" \
  || echo "control API refused on $PIP:8474 (loopback only, as designed)"

Expected output:

API on 127.0.0.1:8474 -> HTTP 200 control API refused on 10.0.0.19:8474 (loopback only, as designed)

To test your own application, create a proxy in front of the dependency you want to disrupt, such as a database, cache or API. Your application then connects to the proxy's listen address instead of the real dependency, and you add or remove toxics to shape the connection. For example, put a proxy in front of a Postgres database:

# Create a proxy: your app connects to port 15432, traffic forwards to the real database. toxiproxy-cli create -l 0.0.0.0:15432 -u db-internal.example:5432 pg
# Add 3 seconds of latency, then a bandwidth cap, then a timeout — one at a time or together: toxiproxy-cli toxic add -t latency -a latency=3000 -n lat -d pg toxiproxy-cli toxic add -t bandwidth -a rate=100 -n slow -d pg toxiproxy-cli toxic add -t timeout -a timeout=1500 -n to -d pg
# Remove a toxic, or disable the whole proxy to simulate the dependency going down: toxiproxy-cli toxic remove -n lat pg toxiproxy-cli toggle pg

Open the proxy's listen port on your VM's network security group only if the client is remote. Within the VM, no port needs opening.

A toxic applies to the downstream direction (data returning to the client, -d, the default) or the upstream direction (data flowing to the dependency, -u). The common types and their key attributes are:

latency -a latency=<ms> -a jitter=<ms> add delay (optionally jittered) bandwidth -a rate=<KB/s> cap throughput slow_close -a delay=<ms> delay the TCP close timeout -a timeout=<ms> hold then drop with no data (0 = hold forever) reset_peer -a timeout=<ms> send a TCP RST after the delay slicer -a average_size=<b> -a delay=<us> slice data into small packets limit_data -a bytes=<n> close the connection after N bytes

Use --toxicity <0..1> (or --tox) to apply a toxic to only a fraction of connections. This is ideal for simulating intermittent failures.

• Never open port 8474. The control API is unauthenticated by design. Keep it loopback only and drive it over SSH or from within the VM. If you must reach it from elsewhere, tunnel it over SSH (ssh -L 8474:127.0.0.1:8474 azureuser@<vm>). Never open it on the NSG.
• Scope the demo and your own proxy ports. Allow the proxy data ports (for example 8080) only from the client networks that need them.
• Treat proxies as test infrastructure. Toxiproxy is intended for test and staging environments. Do not place it on a production data path.
• Keep the OS and Toxiproxy patched. Unattended security upgrades remain enabled on the running VM.

Shopify develops Toxiproxy and distributes it under the MIT license. This SecureAnyCloud image bundles the unmodified official Toxiproxy binaries. SecureAnyCloud provides the packaging, the secure-by-default posture (control API bound to loopback only), the self-contained demo, the systemd integration, and 24/7 support with a guaranteed 24-hour response SLA.

SecureAnyCloud is not affiliated with or endorsed by Shopify or the Toxiproxy project. Toxiproxy is a mark of its respective owner and is used here only to identify the software.

Deploy on Azure

Find Toxiproxy on Ubuntu 24.04 LTS on the Azure Marketplace, published by SecureAnyCloud. Deploy from the Portal or the Azure CLI as shown above.

Need Help?

Email sales@secureanycloud.com for deployment help, configuration questions or licensing inquiries.

Deploy on Azure

Launch Toxiproxy resilience testing proxy on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com