tcconfig

Home-page: https://github.com/thombashi/tcconfig
Author: Tsuyoshi Hombashi
Author-email: tsuyoshi.hombashi@gmail.com
License: MIT License
Description-Content-Type: UNKNOWN
Description:
tcconfig
==========
.. image:: https://travis-ci.org/thombashi/tcconfig.svg?branch=master
:target: https://travis-ci.org/thombashi/tcconfig
:alt: Linux CI test status

.. image:: https://img.shields.io/github/stars/thombashi/tcconfig.svg?style=social&label=Star
:target: https://github.com/thombashi/tcconfig
:alt: GitHub repository

Summary
---------
A Simple tc command wrapper tool. Easy to set up traffic control of network bandwidth/latency/packet loss/packet-corruption to a network interface.

Traffic control features
------------------------

Traffic shaping target
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Apply traffic shaping rules to specific targets:

- Outgoing/Incoming packets
- Source/Destination IP-address/network (IPv4/IPv6)
- Source/Destination ports

Moreover, exclude from shaping rules from specific targets:

- Source/Destination IP-address/network (IPv4/IPv6)
- Source/Destination ports

Available parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following parameters can set to network interfaces:

- Network bandwidth rate ``[G/M/K bps]``
- Network latency ``[microseconds/milliseconds/seconds/minutes]``
- Packet loss rate ``[%]``
- Packet corruption rate ``[%]``
- Packet duplicate rate ``[%]``
- Packet reordering rate ``[%]``

.. image:: docs/gif/tcset_example.gif

Usage
=======

Set traffic control (``tcset`` command)
-----------------------------------------
``tcset`` is a command to add traffic control rule to a network interface (device).

e.g. Set a limit on bandwidth up to 100Kbps
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console

# tcset --device eth0 --rate 100k

e.g. Set network latency
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can use time units (such as us/sec/min/etc.) to designate delay time.

Set 100 milliseconds network latency
'''''''''''''''''''''''''''''''''''''''''''''''''''
.. code-block:: console

# tcset --device eth0 --delay 100ms

Set 10 seconds network latency
'''''''''''''''''''''''''''''''''''''''''''''''''''
.. code-block:: console

# tcset --device eth0 --delay 10sec

Set 0.5 minutes (30 seconds) network latency
'''''''''''''''''''''''''''''''''''''''''''''''''''
.. code-block:: console

# tcset --device eth0 --delay 0.5min

e.g. Set 0.1% packet loss
^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console

# tcset --device eth0 --loss 0.1

e.g. All of the above at once
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console

# tcset --device eth0 --rate 100k --delay 100 --loss 0.1

e.g. Specify the IP address of traffic control
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console

# tcset --device eth0 --delay 100 --network 192.168.0.10

e.g. Specify the IP network and port of traffic control
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console

# tcset --device eth0 --delay 100 --network 192.168.0.0/24 --port 80

Delete traffic control (``tcdel`` command)
------------------------------------------

``tcdel`` is a command to delete traffic shaping rules from a network interface (device).

e.g. Delete traffic control of ``eth0``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can delete all of the shaping rules for the ``eth0`` with ``-a``/``--all`` option:

.. code-block:: console

# tcdel --device eth0 --all

Display traffic control configurations (``tcshow`` command)
-----------------------------------------------------------
``tcshow`` is a command to display the current traffic control settings for network interface(s).

Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

# tcset --device eth0 --delay 10 --delay-distro 2 --loss 0.01 --rate 0.25M --network 192.168.0.10 --port 8080
# tcset --device eth0 --delay 1 --loss 0.02 --rate 500K --direction incoming
# tcshow --device eth0
{
"eth0": {
"outgoing": {
"dst-network=192.168.0.10/32, dst-port=8080": {
"delay": "10.0",
"loss": "0.01",
"rate": "250K",
"delay-distro": "2.0"
},
"dst-network=0.0.0.0/0": {}
},
"incoming": {
"dst-network=0.0.0.0/0": {
"delay": "1.0",
"loss": "0.02",
"rate": "500K"
}
}
}
}

For more information
----------------------
More examples are available at
http://tcconfig.rtfd.io/en/latest/pages/usage/index.html

Installation
============
Installing from PyPI
------------------------------
``tcconfig`` can be installed from `PyPI <https://pypi.python.org/pypi>`__ via
`pip <https://pip.pypa.io/en/stable/installing/>`__ (Python package manager) command.

.. code:: console

sudo pip install tcconfig

Installing from files
------------------------------
The following package includes ``tcconfig`` and dependency packages.
This package is for environments which cannot access to
`PyPI <https://pypi.python.org/pypi>`__ directly.

How to install:

1. Navigate to ``https://github.com/thombashi/tcconfig/releases/``
2. Download the latest version of ``tcconfig_wheel.tar.gz``
3. Copy ``tcconfig_wheel.tar.gz`` to installation target
4. ``tar xvf tcconfig_wheel.tar.gz``
5. ``cd tcconfig_wheel/``
6. ``./install.sh``

Dependencies
============
Python 2.7+ or 3.4+

Linux packages
--------------
- ``iproute``/``iproute2``/``iproute-tc`` (mandatory: required for ``tc`` command)
- ``iptables`` (optional: required to when you use ``--iptables`` option)

Linux kernel module
----------------------------
- ``sch_netem``

Python packages
---------------
Dependency python packages are automatically installed during
``tcconfig`` installation via pip.

- `DataPropery <https://github.com/thombashi/DataProperty>`__
- `ipaddress <https://pypi.python.org/pypi/ipaddress>`__
- `logbook <http://logbook.readthedocs.io/en/stable/>`__
- `pyparsing <https://pyparsing.wikispaces.com/>`__
- `six <https://pypi.python.org/pypi/six/>`__
- `subprocrunner <https://github.com/thombashi/subprocrunner>`__
- `typepy <https://github.com/thombashi/typepy>`__
- `voluptuous <https://github.com/alecthomas/voluptuous>`__

Optional
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- `netifaces <https://bitbucket.org/al45tair/netifaces>`__
- Suppress excessive error messages if this package installed

Test dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- `allpairspy <https://github.com/thombashi/allpairspy>`__
- `pingparsing <https://github.com/thombashi/pingparsing>`__
- `pytest <http://pytest.org/latest/>`__
- `pytest-runner <https://pypi.python.org/pypi/pytest-runner>`__
- `tox <https://testrun.org/tox/latest/>`__

Documentation
===============
http://tcconfig.rtfd.io/

Troubleshooting
=================
http://tcconfig.readthedocs.io/en/latest/pages/troubleshooting.html

Keywords: traffic control,tc,traffic shaping,bandwidth,latency,packet loss
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*

Metadata

Release files for tcconfig 0.17.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tcconfig 0.17.0
File	Size	Uploaded	Provenance
tcconfig-0.17.0.tar.gz	44.1 kB	Nov 4, 2017	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for tcconfig 0.17.0
File	Interpreter	ABI	Platform	Reset
tcconfig-0.17.0-py2.py3-none-any.whl 45.1 kB Nov 4, 2017 Without provenance	Python 3, Python 2	none	any	Details

Total release size: 89.3 kB

Release files / tcconfig-0.17.0.tar.gz

Download URL	tcconfig-0.17.0.tar.gz
Size	44.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`6c587983aa4ef51235dc8ea061791bc852f23f715c7091be4091c7c1cd655147`
BLAKE2b-256 checksum How to use checksums	`2828ed0713a6d6d8427de3c4a8bb3f2995c12e6b84401c04b4cc6feefd76a93a`
Upload date	Nov 4, 2017
Uploaded using Trusted Publishing? What is trusted publishing?	No

Release files / tcconfig-0.17.0-py2.py3-none-any.whl

Download URL	tcconfig-0.17.0-py2.py3-none-any.whl
Size	45.1 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`d11ff1141a96dc1f4b794a875edaf5acfb10ca3ba0244558d7baffd27d716368`
BLAKE2b-256 checksum How to use checksums	`10f04ef26fc82381ff5babf27eb2a5aace4bb3eb1e23c18d44f4218ce45a171e`
Upload date	Nov 4, 2017
Uploaded using Trusted Publishing? What is trusted publishing?	No

Security for tcconfig 0.17.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.