augmented-traffic-control

Augmented Traffic Control: A tool to simulate network conditions

4,332

600

4,332

View on GitHub

Top Related Projects

aws-sdk-js

7,593

AWS SDK for JavaScript in the browser and Node.js

istio

35,688

Connect, secure, control, and observe services.

linkerd2

10,567

Ultralight, security-first service mesh for Kubernetes. Main repo for Linkerd 2.x.

traefik

50,061

The Cloud Native Application Proxy

Quick Overview

Augmented Traffic Control (ATC) is an open-source tool developed by Facebook that allows developers to simulate network conditions and test their applications in a controlled environment. It provides a web-based interface for configuring and managing network emulation scenarios, making it easier to test and debug network-dependent applications.

Pros

Realistic Network Simulation: ATC can simulate a wide range of network conditions, including bandwidth, latency, packet loss, and jitter, allowing developers to test their applications in a more realistic environment.
Cross-Platform Compatibility: ATC is designed to work across multiple platforms, including Linux, macOS, and Windows, making it accessible to a wide range of developers.
Ease of Use: The web-based interface of ATC provides a user-friendly way to configure and manage network emulation scenarios, reducing the complexity of setting up network testing environments.
Extensibility: ATC is designed to be extensible, allowing developers to create custom network profiles and integrate it with other tools and frameworks.

Cons

Limited Documentation: The project's documentation, while available, could be more comprehensive and easier to navigate, which may make it challenging for new users to get started.
Dependency on Docker: ATC relies on Docker for its network emulation capabilities, which may be a barrier for developers who are not familiar with or comfortable using Docker.
Performance Limitations: Depending on the complexity of the network scenarios being simulated, ATC may have performance limitations, especially on less powerful hardware.
Lack of Active Maintenance: The project is no longer actively maintained by Facebook, which may raise concerns about its long-term viability and support.

Getting Started

To get started with Augmented Traffic Control, follow these steps:

Install Docker on your system. You can download Docker from the official website: https://www.docker.com/get-started
Clone the Augmented Traffic Control repository from GitHub:

git clone https://github.com/facebookarchive/augmented-traffic-control.git

Navigate to the cloned repository and start the ATC server:

cd augmented-traffic-control
docker-compose up -d

Open your web browser and navigate to http://localhost:8000 to access the ATC web interface.
In the web interface, you can create new network profiles, configure network conditions, and start network emulation scenarios.

Here's an example of how to create a new network profile in ATC:

from atc.api.client import ATCClient

# Create an ATC client
client = ATCClient()

# Define the network profile
profile = {
    "name": "My Network Profile",
    "description": "A custom network profile for testing",
    "bandwidth": {
        "down": 1000,
        "up": 500
    },
    "latency": 50,
    "loss": 1,
    "jitter": 10
}

# Create the network profile
client.create_profile(profile)

This code creates a new network profile with the specified bandwidth, latency, packet loss, and jitter settings. You can then use this profile to start network emulation scenarios in the ATC web interface.

Competitor Comparisons

aws-sdk-js

7,593

AWS SDK for JavaScript in the browser and Node.js

Pros of aws/aws-sdk-js

Comprehensive support for a wide range of AWS services, making it a powerful tool for building AWS-based applications.
Actively maintained and regularly updated, ensuring compatibility with the latest AWS offerings.
Extensive documentation and community support, making it easier to get started and troubleshoot issues.

Cons of aws/aws-sdk-js

Larger codebase and dependency footprint compared to facebookarchive/augmented-traffic-control, which may impact project size and complexity.
Primarily focused on AWS services, whereas facebookarchive/augmented-traffic-control is a more general-purpose tool for network traffic control.

Code Comparison

aws/aws-sdk-js

const AWS = require('aws-sdk');
AWS.config.update({
  region: 'us-west-2',
  accessKeyId: 'YOUR_ACCESS_KEY_ID',
  secretAccessKey: 'YOUR_SECRET_ACCESS_KEY'
});

const s3 = new AWS.S3();
s3.listBuckets((err, data) => {
  if (err) console.log(err, err.stack);
  else console.log(data.Buckets);
});

facebookarchive/augmented-traffic-control

const atc = require('augmented-traffic-control');
const server = atc.createServer({
  port: 8000,
  rules: [
    {
      name: 'Slow down all traffic',
      delay: 1000
    }
  ]
});

server.start();
console.log('ATC server started on port 8000');

istio

35,688

Connect, secure, control, and observe services.

Pros of Istio

Istio provides a comprehensive service mesh solution, offering advanced traffic management, security, and observability features.
The project has a large and active community, with extensive documentation and a wide range of supported platforms.
Istio integrates well with popular cloud platforms and Kubernetes, making it a suitable choice for modern cloud-native applications.

Cons of Istio

Istio can be complex to set up and configure, especially for smaller or less experienced teams.
The resource requirements of Istio can be higher compared to simpler traffic control solutions, which may be a concern for resource-constrained environments.
Istio's feature set may be overkill for some use cases, where a more lightweight solution like Augmented Traffic Control might be more appropriate.

Code Comparison

Augmented Traffic Control (ATC):

def get_network_profile(self):
    """
    Get the current network profile.
    """
    return self.network_profile

Istio:

func (c *Client) GetNetworkProfile(ctx context.Context, name string, opts ...Option) (*NetworkProfile, error) {
    url := fmt.Sprintf("%s/network-profiles/%s", c.baseURL, name)
    resp, err := c.doRequest(ctx, http.MethodGet, url, nil, opts...)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var profile NetworkProfile
    if err := json.NewDecoder(resp.Body).Decode(&profile); err != nil {
        return nil, err
    }

    return &profile, nil
}

The code comparison shows that Augmented Traffic Control has a simpler and more concise implementation for getting the current network profile, while Istio's implementation is more verbose and includes additional error handling and response parsing logic.

linkerd2

10,567

Ultralight, security-first service mesh for Kubernetes. Main repo for Linkerd 2.x.

Pros of Linkerd2

Linkerd2 is a lightweight, open-source service mesh that provides advanced traffic management and observability features.
It offers a simple and intuitive command-line interface (CLI) for easy deployment and configuration.
Linkerd2 has a strong focus on security, with automatic mTLS (mutual TLS) encryption and identity-based authorization.

Cons of Linkerd2

Linkerd2 may have a steeper learning curve compared to Augmented Traffic Control, especially for users new to service meshes.
The project's documentation, while comprehensive, may not be as user-friendly as Augmented Traffic Control's.
Linkerd2 may have a higher resource footprint than Augmented Traffic Control, as it requires a control plane and sidecar proxies.

Code Comparison

Augmented Traffic Control (ATC) sample configuration:

# ATC configuration
networks:
  - name: default
    type: ethernet
    bandwidth: 1Mbps
    latency: 100ms
    loss: 1%
    corruption: 0.1%
    duplicate: 0.1%

Linkerd2 sample configuration:

# Linkerd2 configuration
apiVersion: linkerd.io/v1beta1
kind: ServiceProfile
metadata:
  name: web-svc
spec:
  routes:
  - condition:
      method: GET
      pathRegex: /healthz
    isRetryable: true
    isFailureAcceptable: true

traefik

50,061

The Cloud Native Application Proxy

Pros of Traefik

Ease of Use: Traefik is known for its user-friendly configuration and setup process, making it a popular choice for developers and system administrators.
Dynamic Routing: Traefik can automatically configure itself based on changes in your infrastructure, such as new services or containers, without the need for manual intervention.
Extensive Ecosystem: Traefik integrates with a wide range of cloud providers, container orchestration platforms, and service discovery tools, providing a flexible and adaptable solution.

Cons of Traefik

Complexity: While Traefik is powerful, its feature-rich nature can make it more complex to configure and manage, especially for smaller projects or teams.
Performance Overhead: Traefik's dynamic routing and service discovery features can introduce some performance overhead, which may be a concern for high-traffic or latency-sensitive applications.

Code Comparison

Here's a brief code comparison between Traefik and Augmented Traffic Control:

Traefik configuration (YAML):

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false

certificatesResolvers:
  letsencrypt:
    acme:
      email: "your-email@example.com"
      storage: /etc/traefik/acme/acme.json
      httpChallenge:
        entryPoint: web

Augmented Traffic Control configuration (JSON):

{
  "profiles": [
    {
      "name": "default",
      "description": "Default profile",
      "rules": [
        {
          "name": "Limit bandwidth",
          "type": "bandwidth",
          "options": {
            "download": 1024,
            "upload": 512
          }
        }
      ]
    }
  ]
}

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Augmented Traffic Control

Full documentation for the project is available at http://facebook.github.io/augmented-traffic-control/.

Overview

Augmented Traffic Control (ATC) is a tool to simulate network conditions. It allows controlling the connection that a device has to the internet. Developers can use ATC to test their application across varying network conditions, easily emulating high speed, mobile, and even severely impaired networks. Aspects of the connection that can be controlled include:

bandwidth
latency
packet loss
corrupted packets
packets ordering

In order to be able to shape the network traffic, ATC must be running on a device that routes the traffic and sees the real IP address of the device, like your network gateway for instance. This also allows any devices that route through ATC to be able to shape their traffic. Traffic can be shaped/unshaped using a web interface allowing any devices with a web browser to use ATC without the need for a client application.

ATC is made of multiple components that interact together:

atcd: The ATC daemon which is responsible for setting/unsetting traffic shaping. atcd exposes a Thrift interface to interact with it.
django-atc-api: A Django app based on Django Rest Framework that provides a RESTful interface to atcd.
django-atc-demo-ui: A Django app that provides a simple Web UI to use atc from a mobile phone.
django-atc-profile-storage: A Django app that can be used to save shaping profiles, making it easier to re-use them later without manually re-entering those settings.

By splitting ATC in sub-components, it make it easier to hack on it or build on top of it. While django-atc-demo-ui is shipped as part of ATC's main repository to allow people to be able to use ATC out of the box, by providing a REST API to atcd, it makes it relatively easy to interact with atcd via the command line and opens the path for the community to be able to build creative command line tools, web UI or mobile apps that interact with ATC.

Requirements

Most requirements are handled automatically by pip, the packaging system used by ATC, and each ATC package may have different requirements and the README.md files of the respective packages should be checked for more details. Anyhow, some requirements apply to the overall codebase:

Python 2.7: Currently, ATC is only supported on python version 2.7.
Django 1.10: Currently, ATC is only supported using django version 1.10.

Installing ATC

The fact that ATC is splitted in multiple packages allows for multiple deployment scenarii. However, deploying all the packages on the same host is the simplest and most likely fitting most use cases.

To get more details on how to install/configure each packages, please refer to the packages' respective READMEs.

Packages

The easiest way to install ATC is by using pip.

pip install atc_thrift atcd django-atc-api django-atc-demo-ui django-atc-profile-storage

Django

Now that we have all the packages installed, we need to create a new Django project in which we will use our Django app.

django-admin startproject atcui
cd atcui

Now that we have our django project, we need to configure it to use our apps and we need to tell it how to route to our apps.

Open atcui/settings.py and enable the ATC apps by adding to INSTALLED_APPS:

INSTALLED_APPS = (
    ...
    # Django ATC API
    'rest_framework',
    'atc_api',
    # Django ATC Demo UI
    'bootstrap_themes',
    'django_static_jquery',
    'atc_demo_ui',
    # Django ATC Profile Storage
    'atc_profile_storage',
)

Now, open atcui/urls.py and enable routing to the ATC apps by adding the routes to urlpatterns:

...
...
from django.views.generic.base import RedirectView
from django.conf.urls import include

urlpatterns = [
    ...
    # Django ATC API
    url(r'^api/v1/', include('atc_api.urls')),
    # Django ATC Demo UI
    url(r'^atc_demo_ui/', include('atc_demo_ui.urls')),
    # Django ATC profile storage
    url(r'^api/v1/profiles/', include('atc_profile_storage.urls')),
    url(r'^$', RedirectView.as_view(url='/atc_demo_ui/', permanent=False)),
]

Finally, let's update the Django DB:

python manage.py migrate

Running ATC

All require packages should now be installed and configured. We now need to run the daemon and the UI interface. While we will run ATC straight from the command line in this example, you can refer to example sysvinit and upstart scripts.

atcd

atcd modifies network related settings and as such needs to run in privileged mode:

sudo atcd

Supposing eth0 is your interface to connect to the internet and eth1, your interface to connect to your lan, this should just work. If your setting is slightly different, use the command line arguments --atcd-wan and --atcd-lan to adapt to your configuration.

ATC UI

The UI on the other hand is a standard Django Web app and can be run as a normal user. Make sure you are in the directory that was created when you ran django-admin startproject atcui and run:

python manage.py runserver 0.0.0.0:8000

You should now be able to access the web UI at http://localhost:8000

ATC Code Structure

ATC source code is available under the atc directory, it is currently composed of:

atc_thrift the thrift interface's library
atcd the ATC daemon that runs on the router doing the traffic shaping
django-atc-api A django app that provides a RESTful interface to atcd
django-atc-demo-ui A django app that provides a simple demo UI leveraging the RESTful API
django-atc-profile-storage A django app that allows saving shaping profiles to DB allowing users to select their favorite profile from a list instead of re-entering all the profile details every time.

The chef directory contains 2 chef cookbooks:

atc A cookbook to deploy ATC. It also allows to deploy ATC in a Virtual Box VM in order to develop on ATC.
atclient Set up a Linux Desktop VM that can be used to test shaping end to end.

atcd

atcd is the daemon that runs on the router that does the shaping. Interaction with the daemon is done using thrift. The interface definition can be found in atc_thrift.thrift.

atc_thrift

atc_thrift defines the thrift interface to communicate with the atcd daemon.

django-atc-api

django-atc-api is a django app that provide a REST API to the atcd daemon. Web applications, command line tools can use the API in order to shape/unshape traffic.

django-atc-demo-ui

django-atc-demo-ui is a simple Web UI to enable/disable traffic shaping. The UI is mostly written in React

django-atc-profile-storage

django-atc-profile-storage allows saving profiles to DB. A typical use case will be to save a list of predefined/often used shaping settings that you want to be able to accessing in just a few clicks/taps.

Developing on ATC

To make ATC development easier, we use Virtual Box and Vagrant to provision and run a VM that will run the ATC daemon and the ATC UI from your git checkout.

Interacting with ATC will only shape the traffic within the VM and not on the host.

Setting up the environment

Note: vagrant is an easy way to set up a test environment, but virtualization will produce different results than a setup on bare-metal. We recommend using vagrant only for testing/development and using bare-metal for setups which require realistic shaping settings.

You will need to install VirtualBox, Vagrant and a couple of plugins:

VirtualBox
Vagrant
Chef DK
Install some vagrant plugins:
vagrant plugin install vagrant-berkshelf --plugin-version '>= 2.0.1'
vagrant plugin install vagrant-omnibus
Clone this repo: git clone git@github.com:facebook/augmented-traffic-control.git atc

Running ATC

Once in the repo, go to the chef/atc directory and run:

vagrant up trusty

This will take some time before it completes, once the VM is provision, SSH into it:

vagrant ssh trusty

You should now be able to access ATC at: http://localhost:8080/

Using the Sample Profiles

Once you've got ATC up and running, you can run the script utils/restore-profiles.sh to setup the set of default profiles.

The script needs to be passed a hostname:port with the location of your ATC instance:

utils/restore-profiles.sh localhost:8080

After doing this, you should see the 10 sample profiles listed below in your ATC instance:

2G - Developing Rural
2G - Developing Urban
3G - Average
3G - Good
Cable
DSL
Edge - Average
Edge - Good
Edge - Lossy
No Connectivity

Naturally, you cannot improve your natural network speed by selecting a faster profile than your service. For example, selecting the Cable profile will not make your network faster if your natural connection speed resembles DSL more closely.

Hacking on the code

Hacking on ATC is done from the host and tested in the VM. In order to reflect the changes, you will need to start the services manually.

Both atcd and atcui have their python libraries installed in a python virtualenv so you will need to activate the environment in order to be able to run the services.

The virtualenv is installed in /usr/local/atc/venv/bin/activate .

source /usr/local/atc/venv/bin/activate

Running the daemon

The atcd daemon is running under the root user privileges, all operations below needs to be done as root.

To run the daemon manually, first make sure it is not running in the background:

service atcd stop

And run the daemon:

atcd

Once you are happy with your changes and you want to test them, you will need to kill the daemon and restart it in order to apply the changes.

Running the API/UI

This is a django project and, when running the django built-in HTTP server, will detect code changes and reload automatically.

To run the HTTP REST API and UI:

cd /var/django && python manage.py runserver 0.0.0.0:8000

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot