{"id":13588103,"url":"https://github.com/lukaszlach/docker-tc","last_synced_at":"2025-04-08T02:34:46.724Z","repository":{"id":38418498,"uuid":"162346961","full_name":"lukaszlach/docker-tc","owner":"lukaszlach","description":":whale: :vertical_traffic_light: Docker Traffic Control - network rate limiting, emulating delays, losses, duplicates, corrupts and reorders of network packets using only container labels or a command-line interface.","archived":false,"fork":false,"pushed_at":"2023-12-02T17:18:24.000Z","size":17,"stargazers_count":677,"open_issues_count":14,"forks_count":40,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-06T07:40:17.317Z","etag":null,"topics":["chaos-engineering","docker","docker-network","network-emulation","traffic-control"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukaszlach.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-18T21:24:42.000Z","updated_at":"2024-11-04T16:39:58.000Z","dependencies_parsed_at":"2022-07-14T03:30:31.201Z","dependency_job_id":"6e784d44-e5f7-4ec8-9ca2-eb2edfee4149","html_url":"https://github.com/lukaszlach/docker-tc","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaszlach%2Fdocker-tc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaszlach%2Fdocker-tc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaszlach%2Fdocker-tc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaszlach%2Fdocker-tc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukaszlach","download_url":"https://codeload.github.com/lukaszlach/docker-tc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247765120,"owners_count":20992242,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chaos-engineering","docker","docker-network","network-emulation","traffic-control"],"created_at":"2024-08-01T15:06:30.693Z","updated_at":"2025-04-08T02:34:46.485Z","avatar_url":"https://github.com/lukaszlach.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# Docker Traffic Control\n\n![Version](https://img.shields.io/badge/version-18.12-lightgrey.svg?style=flat)\n[![Docker pulls](https://img.shields.io/docker/pulls/lukaszlach/docker-tc.svg?label=docker+pulls)](https://hub.docker.com/r/lukaszlach/docker-tc)\n[![Docker stars](https://img.shields.io/docker/stars/lukaszlach/docker-tc.svg?label=docker+stars)](https://hub.docker.com/r/lukaszlach/docker-tc)\n\n**Docker Traffic Control** allows to set a rate limit on the container network and can emulate network conditions like delay, packet loss, duplication, and corrupt for the Docker containers, all that basing only on labels. [HTTP API](#http-api) allows to [fetch](#get) and [pause](#delete) existing rules and to [manually overwrite](#post) them, [command-line interface](#command-line) is also available. **Project is written entirely in Bash** and is distributed as a [Docker image](https://hub.docker.com/r/lukaszlach/docker-tc/).\n\n## Running\n\nFirst run Docker Traffic Control daemon in Docker. The container needs `NET_ADMIN` capability and the `host` network mode to manage network interfaces on the host system, `/var/run/docker.sock` volume allows to observe Docker events and query container details.\n\n```bash\ndocker run -d \\\n    --name docker-tc \\\n    --network host \\\n    --cap-add NET_ADMIN \\\n    --restart always \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    -v /var/docker-tc:/var/docker-tc \\\n    lukaszlach/docker-tc\n```\n\n\u003e You can also pass `HTTP_BIND` and `HTTP_PORT` environment variables, which default to `127.0.0.1:4080`.\n\nThis repository contains `docker-compose.yml` file in root directory, you can use it instead of manually running `docker run` command. Newest version of image will be pulled automatically and the container will run in daemon mode.\n\n```bash\ngit clone https://github.com/lukaszlach/docker-tc.git\ncd docker-tc\ndocker-compose up -d\n```\n\n\u003e When using `docker-compose.yml` configuration is stored in the `.env` file, also provided in this repository.\n\n## Usage\n\nAfter the daemon is up it scans all running containers and starts listening for `container:start` events triggered by Docker Engine. When a new container is up (also a new Swarm service) and contains `com.docker-tc.enabled` label set to `1`, Docker Traffic Control starts applying network traffic rules according to the rest of the labels from `com.docker-tc` namespace it finds.\n\nDocker Traffic Control recognizes the following labels:\n\n* `com.docker-tc.enabled` - when set to `1` the container network rules will be set automatically, any other value or if the label is not specified - the container will be ignored\n*  `com.docker-tc.limit` - bandwidth or rate limit for the container, accepts a floating point number, followed by a unit, or a percentage value of the device's speed (e.g. 70.5%). Following units are recognized:\n    * `bit`, `kbit`, `mbit`, `gbit`, `tbit`\n    * `bps`, `kbps`, `mbps`, `gbps`, `tbps`\n    * to specify in IEC units, replace the SI prefix (k-, m-, g-, t-) with IEC prefix (ki-, mi-, gi- and ti-) respectively\n* `com.docker-tc.delay` - length of time packets will be delayed, accepts a floating point number followed by an optional unit:\n    * `s`, `sec`, `secs`\n    * `ms`, `msec`, `msecs`\n    * `us`, `usec`, `usecs` or a bare number\n* `com.docker-tc.loss` - percentage loss probability to the packets outgoing from the chosen network interface\n* `com.docker-tc.duplicate` - percentage value of network packets to be duplicated before queueing\n* `com.docker-tc.corrupt` - emulation of random noise introducing an error in a random position for a chosen percent of packets\n\n\u003e Read the [tc command manual](http://man7.org/linux/man-pages/man8/tc.8.html) to get detailed information about parameter types and possible values.\n\nRun the `busybox` container on custom network to create virtual network interface, specify all possible labels and try to `ping google.com` domain.\n\n```bash\ndocker network create test-net\ndocker run -it \\\n\t--net test-net \\\n\t--label \"com.docker-tc.enabled=1\" \\\n\t--label \"com.docker-tc.limit=1mbps\" \\\n\t--label \"com.docker-tc.delay=100ms\" \\\n\t--label \"com.docker-tc.loss=50%\" \\\n\t--label \"com.docker-tc.duplicate=50%\" \\\n\t--label \"com.docker-tc.corrupt=10%\" \\\n\tbusybox \\\n\tping google.com\n```\n\nYou should see output similar to shown below, `ping` correctly reports duplicates, packets are delayed and some of them lost.\n\n```\nPING google.com (216.58.215.78): 56 data bytes\n64 bytes from 216.58.215.78: seq=0 ttl=54 time=1.010 ms\n64 bytes from 216.58.215.78: seq=1 ttl=54 time=101.031 ms\n64 bytes from 216.58.215.78: seq=2 ttl=54 time=101.045 ms\n64 bytes from 216.58.215.78: seq=3 ttl=54 time=101.011 ms\n64 bytes from 216.58.215.78: seq=4 ttl=54 time=101.028 ms\n64 bytes from 216.58.215.78: seq=5 ttl=54 time=101.060 ms\n64 bytes from 216.58.215.78: seq=5 ttl=54 time=154.685 ms (DUP!)\n64 bytes from 216.58.215.78: seq=6 ttl=54 time=101.084 ms\n64 bytes from 216.58.215.78: seq=8 ttl=54 time=101.085 ms\n64 bytes from 216.58.215.78: seq=8 ttl=54 time=1001.130 ms (DUP!)\n64 bytes from 216.58.215.78: seq=11 ttl=54 time=102.218 ms\n64 bytes from 216.58.215.78: seq=15 ttl=54 time=114.437 ms\n64 bytes from 216.58.215.78: seq=16 ttl=54 time=101.471 ms\n64 bytes from 216.58.215.78: seq=17 ttl=54 time=101.068 ms\n64 bytes from 216.58.215.78: seq=17 ttl=54 time=1001.162 ms (DUP!)\n64 bytes from 216.58.215.78: seq=19 ttl=54 time=101.104 ms\n^C\n--- google.com ping statistics ---\n20 packets transmitted, 13 packets received, 3 duplicates, 35% packet loss\nround-trip min/avg/max = 1.010/152.299/1001.162 ms\n```\n\n## HTTP API\n\nAPI available via HTTP allows you to manage network control rules manually on chosen container.\n\nIf you have running containers already or do not want to add Docker Traffic Control labels, you can use the [`POST` endpoint](#post) to set the rules manually or in an automated process.\n\n\u003e HTTP was chosen for local management instead of `docker exec` so that you can still easily control Docker Traffic Control on Swarm Nodes, utilize any service discovery and manage remotely using any HTTP client.\n\n### GET\n\n```\nGET /\u003ccontainer-id|container-name\u003e HTTP/1.1\n```\n\nGet traffic control rules for a single container.\n\n```bash\ncurl localhost:4080/221517ae59d1\ncurl localhost:4080/my-container-name\n```\n\n### LIST\n\n```\nLIST /\u003ccontainer-id|container-name\u003e HTTP/1.1\n```\n\nList all traffic control rules for all running containers.\n\n```bash\ncurl -X LIST localhost:4080\n```\n\n### DELETE\n\n```\nDELETE /\u003ccontainer-id|container-name\u003e HTTP/1.1\n```\n\nDelete all container's traffic control rules. Container is also added to the ignore list to prevent further changes whether it has proper labels set or not.\n\n```bash\ncurl -X DELETE localhost:4080/my-container-name\n```\n\n### PUT\n\n```\nPUT /\u003ccontainer-id|container-name\u003e HTTP/1.1\n```\n\nPut back the container to the scanning poll and remove it from the ignore list.\n\n```bash\ncurl -X PUT localhost:4080/221517ae59d1\n```\n\n### POST\n\n```\nPOST /\u003ccontainer-id|container-name\u003e HTTP/1.1\n\u003crate|delay|loss|corrupt|duplicate\u003e=\u003cvalue\u003e\u0026...\n```\n\nUpdate container's traffic control rules. Container does not have to have any labels set, it can be any running container. All previous rules for this container are removed.\n\n```bash\ncurl -d'delay=300ms' localhost:4080/my-container-name\ncurl -d'rate=512kbps' localhost:4080/221517ae59d1\ncurl -d'rate=1mbps\u0026loss=10%' localhost:4080/my-container-name\n```\n\n## Command-line\n\nSet up a command that may be available for all users...\n\n```bash\necho 'curl -sSf -X \"$1\" \"localhost:4080/$2?$3\"' \u003e /usr/bin/docker-tc\nchmod +x /usr/bin/docker-tc\n```\n\n... or set up a local command alias:\n\n```bash\nalias docker-tc='curl -sSf -X \"$1\" \"localhost:4080/$2?$3\"'\n```\n\n### Usage\n\n```bash\ndocker-tc get 221517ae59d1\ndocker-tc list\ndocker-tc delete my-container-name\ndocker-tc put 221517ae59d1\ndocker-tc set my-container-name 'delay=300ms\u0026rate=1000kbps'\n```\n\n## Build\n\n```bash\ngit clone https://github.com/lukaszlach/docker-tc.git\ncd docker-tc\nmake\ndocker images | grep docker-tc\n```\n\n## Supported platforms\n\nDocker Traffic Control only works on Linux distributions like Debian, Ubuntu, CentOS or Fedora.\n\n* MacOS - not supported due to lack of host network mode support\n* Windows - not supported due to separate network stack between Linux and Windows containers\n\n## Deploy on Swarm\n\n**Warning:** Although this project is prepared for Docker Swarm you will not be able to deploy it as a service because of the [moby/moby#25885](https://github.com/moby/moby/issues/25885) issue. This section is theoretical.\n\nCreate a global service named `docker-tc` that will scan all containers and other services that are currently running or will start in the future.\n\n```bash\ndocker service create \\\n    --name docker-tc \\\n    --mode global \\\n    --restart-condition any \\\n    --network host \\\n    --cap-add NET_ADMIN \\\n    --mount \"type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock\" \\\n    --mount \"type=bind,src=/var/docker-tc,dst=/var/docker-tc\" \\\n    lukaszlach/docker-tc\n```\n\n\u003e `/var/docker-tc` directory has to exist on Docker Swarm nodes before deploying the service\n\n## Contributors\n\n[![](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/images/0)](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/links/0)[![](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/images/1)](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/links/1)[![](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/images/2)](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/links/2)[![](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/images/3)](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/links/3)[![](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/images/4)](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/links/4)[![](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/images/5)](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/links/5)[![](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/images/6)](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/links/6)[![](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/images/7)](https://sourcerer.io/fame/lukaszlach/lukaszlach/docker-tc/links/7)\n\n## Licence\n\nMIT License\n\nCopyright (c) 2018-2019 Łukasz Lach \u003cllach@llach.pl\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukaszlach%2Fdocker-tc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukaszlach%2Fdocker-tc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukaszlach%2Fdocker-tc/lists"}