config.example.toml

# This is an example configuration file for Rattan CLI.
#
# Fileds with "Default" are optional.
# User can specify the configuration file by the `-c` option of `rattan`.
#
# **ATTENTION**: Check firewall settings before running Rattan CLI.
# Please make sure you allow the following addresses:
# - 10.1.1.0/24
# - 10.2.1.0/24
# For example, you can run the following commands if using `ufw`:
# - `ufw allow from 10.1.1.0/24`
# - `ufw allow from 10.2.1.0/24`
# 
# Run `rattan` will generate some network namespaces and veth pairs to
# emulate the network environment. The network topology is like:
#
#    ns-left                                                           ns-right
# +-----------+ [Internet]                               [Internet] +-----------+
# |    vL0    |    |                 ns-rattan                 |    |    vR0    |
# |  external | <--+          +---------------------+          +--> |  external |
# |   vL1-L   |               |  vL1-R  [P]   vR1-L |               |   vR1-R   |
# | .1.1.x/32 | <-----------> |.1.1.2/32   .2.1.2/32| <-----------> | .2.1.x/32 |
# |   vL2-L   |               |  vL2-R        vR2-L |               |   vR2-R   |
# | .1.2.y/32 | <-----------> |.1.2.2/32   .2.2.2/32| <-----------> | .2.2.y/32 |
# ~    ...    ~   Veth pairs  ~  ...           ...  ~   Veth pairs  ~    ...    ~
# +-----------+               +---------------------+               +-----------+
#
# Then Rattan will build and link the cells according to the configuration file.
# Each cell emulates some network characteristics, such as bandwidth, delay, loss, etc.
#
# Then the `COMMAND` specified to `rattan` will run in the `ns-left` network namespace.
# If not specified, the `$SHELL` will run.
#
# Sections:
# - [general] Section: How to run the rattan itself in general
# - [env] Section: How to build the environment
# - [http] Section: HTTP Control Server configuration
# - [cells] Section: Emulation cells configuration
# - [links] Section: How to link the cells
# - [resource] Section: How to use system resource
# - [commands] Section: Commands to run in rattan
#


# ----- General Section -----
# This section determines how to run the rattan itself in general.
[general]

# Configure the path to store compressed packet log.
# This logging feature will only be enabled when the `packet_log` field is specified.
# The meta data of flows will be stored in the file of name `packet_log`.flows
# packet_log = "./example.log"

# ----- General Section End -----


# ----- Environment Section -----
# This section determines how to build the environment.
[env]

# Netns mode
# Possible values:
# - "Compatible" : The `ns-left` side is a new network namespace
#                  (named "ns-left-xxxxxx") and the `ns-right` side is
#                  the host network namespace. (Mahimahi is this mode)
# - "Isolated"   : The `ns-left` side is a new network namespace
#                  (named "ns-left-xxxxxx") and the `ns-right` side is
#                  another new network namespace (named "ns-right-xxxxxx").
#                  Now only partially supported in the CLI.
# - "Container"  : Temporarily not supported
#
# Default: "Compatible"
mode = "Compatible"

# The number of veth pairs between `ns-left` and `ns-rattan`
# Possible values: 1..=254
# Default value: 1
left_veth_count = 2

# Similar to `left_veth_count`
# right_veth_count = 1

# ----- Environment Section End -----


# ----- HTTP Section -----
# This section configures Rattan's HTTP control server.
[http]

# Enable HTTP server
#
# Default: false
enable = false

# HTTP server port
#
# Default: 8086
port = 8086

# ----- HTTP Section End -----


# ----- Cells Section -----
# This section describes the emulation cells.
# Each cell has a unique string ID, defined like "[cells.<ID>]".
# Each cell **MUST** have a "type" field, which determines the cell type and cell configuration fields.
# Possible cell types:
# - "Bw"       : Fixed bandwidth
# - "BwReplay" : Bandwidth trace replayer
# - "Delay"    : Fixed delay
# - "Loss"     : Loss pattern
# - "Custom"   : Custom cell, only specify the cell ID used in link section,
#                and the cell must be built by the user
[cells]


# Bw Cell Example
[cells.up_1]
type = "Bw"

# Type of bandwidth calculation
# Possible values:
# - "LinkLayer"    : Count the link layer size (NetworkLayer + 38)
#                    38 = 8 (Preamble + SFD) + 14 (Ethernet header) + 4 (CRC)
#                         + 12 (Interframe gap)
# - "NetworkLayer" : Count the network layer size
#
# Default: "NetworkLayer"
bw_type = "NetworkLayer"

# Bandwidth
# Now we need to break down the bandwidth into two parts: <gbps> and <bps>,
# which means (1e9 * <gbps> + <bps>) bps. Here <bps> must be less than 1e9.
# For example, the following line means 1.2 Gbps.
#
# Default: Unlimited
bandwidth = "1Gbps 200Mbps"

# Queue type
# Possible values:
# - "Infinite" : Infinite queue
# - "DropTail" : DropTail queue
# - "DropHead" : DropHead queue
# - "CoDel"    : CoDel queue
#
# Default: "Infinite"
queue = "DropTail"

# Queue configuration
# Different queue types have different configurations.
# - For Infinite queue, no configuration is needed.
#
# - For DropTail queue and DropHead queue, we have 3 fields:
#   - "packet_limit" : Queue size in packets numbers.  Default: Unlimited
#   - "byte_limit"   : Queue size in bytes.            Default: Unlimited
#   - "bw_type"      : Type of byte calculation.       Default: "NetworkLayer"
#   Queue size is limited by both "packet_limit" and "byte_limit".
#
# - For CoDel queue, we have 6 fields:
#   - "packet_limit" : Queue size in packets numbers.  Default: Unlimited
#   - "byte_limit"   : Queue size in bytes.            Default: Unlimited
#   - "bw_type"      : Type of byte calculation.       Default: "NetworkLayer"
#   - "interval"     : CoDel Interval.                 Default: 100ms
#   - "target"       : CoDel Target Delay.             Default: 5ms
#   - "mtu"          : MTU for CoDel decision.         Default: 1500
#
queue_config = { packet_limit = 60 }


# Delay Cell Example
[cells.up_2]
type = "Delay"

# Delay
# Delay is a string like 10ms, 1s, 100us, etc.
#
# Default: "0ms"
delay = "10ms"

# Delay Replay Cell Example
[cells.up_3]
type = "DelayReplay"

# Delay trace
#
# Should specify the delay trace file in JSON or TOML format.
# The parser will automatically detect the format by the file extension.
#
# The Delay trace is formated as DelayTraceConfig in `netem-trace` crate.
# Refer to: <https://docs.rs/netem-trace/latest/netem_trace/>
# For example, the following trace will switch between 10ms and 50ms delays at 1-second intervals and the trace will repeat forever.
trace = "./assets/dynamic-delay.json"

# Loss Replay Cell Example
[cells.up_4]
type = "LossReplay"

# Loss trace
#
# Should specify the loss trace file in JSON or TOML format.
# The parser will automatically detect the format by the file extension.
#
# The Loss trace is formated as LossTraceConfig in `netem-trace` crate.
# Refer to: <https://docs.rs/netem-trace/latest/netem_trace/>
# For example, the following trace will switch between 0.0 and 0.5 loss rates at 1-second intervals and the trace will repeat forever.
trace = "./assets/dynamic-loss.toml"

# BwReplay Cell Example
[cells.down_1]
type = "BwReplay"

# Bandwitdh trace
#
# Should specify the bandwidth trace file either in Mahimahi format, or in JSON or TOML format (netem-trace) .
# The parser will automatically detect the format by the file extension.
#
# Bandwitdh trace in JSON or TOML format (netem-trace format)
# Formated as BwTraceConfig in `netem-trace` crate.
# Refer to: <https://docs.rs/netem-trace/latest/netem_trace/>
#
# Bandwidth trace file (Mahimahi format)
# Trace file is in the format of Mahimahi bandwidth trace file.
# Refer to: <https://github.com/ravinet/mahimahi/tree/master/traces>
# For example, the following trace means 24Mbps forever.
trace = "./assets/24Mbps.trace"

# Queue type
# Same as Bw cell
queue = "CoDel"


# Loss Cell Example
[cells.down_2]
type = "Loss"

# Loss pattern
# The loss pattern describes how the packets are dropped when going through.
# It is a list of float numbers, each number is the loss rate of one packet.
# The loss rate is in the range of [0, 1].
# Loss pattern will repeat the last value until stop dropping packets.
# For example, the pattern [0.1, 0.2, 0.3] means [0.1, 0.2, 0.3, 0.3, 0.3, ...].
# Set the last value of the pattern to 0 to limit the maximum number of consecutive packet losses.
# If you want to drop packets i.i.d., just set the pattern to a single number, such as [0.1].
#
# Default: []
pattern = [0.1, 0.2]


# Shadow Cell Example
[cells.shadow]
type = "Shadow"


# Router Cell Example
[cells.router]
type = "Router"

# Egress connections
# 
# It is an ordered list of strings, where each one is a cell ID.
# Each item represents the cell connected to the i-th interface of the Router Cell.
# For example, the following one means `left1` connected to interface 0, and `left2` connected to interface 1.
# At the same time, the length of the list determines the range of interfaces id in the routing_table.
#
# Warning: Due to the order of cell construction, Router Cells should not be directly connected to another Router Cell.
# The recommended solution is to add a Shadow Cell to represent the Router Cell being connected, and link them in Links Section. 
egress_connections = ["left1", "left2"]

# Initial routing table
[[cells.router.routing_table]]
prefix = "10.1.1.1/24"
interface_id = 0

[[cells.router.routing_table]]
prefix = "10.1.2.1/24"
interface_id = 1

[[cells.router.routing_table]]
prefix = "10.2.0.0/16"
# no interface_id, meaning drop

# ----- Cells Section End -----


# ----- Links Section -----
# This section describes how to link the cells.
#
# "left" and "right" are preserved cell IDs, which respectively represent
# the `ns-left` side veth (named `vL1-R`) and the `ns-right` side veth (named `vR1-L`).
# But if a network namespace has more than one veth NICs, `ns-left` side for example, "left1", "left2" etc. will be defined.
#
# The other cell IDs are defined by user in the cells section.
#
# Each line describes a one-way link from a cell egress to a cell ingress.
# For example, the following line means:
# +-------+  -------->  shadow --->  up_1  --->  up_2  ---> +-------+
# | left1 | <==+           ^                                | right |
# +-------+    }= router <-|------- down_2 <--- down_1 <--- +-------+
# | left2 | <==+           |
# +-------+  --------------+
# 
# Note: The double line "<===" from router is connected in Cells Section

[links]
left1 = "shadow"
left2 = "shadow"
shadow = "up_1"
up_1 = "up_2"
up_2 = "right"
right = "down_1"
down_1 = "down_2"
down_2 = "router"
# We do not need to link the Router Cell to other cells anymore, as we have done it in Cells Section.

# ----- Links Section End -----

# --- Resource Section -----
# This section describes how rattan use system resource
# `cores` are cores rattan are allowed to use
[resource]
cores = [1]

# ----- Resource Section End -----

# ----- Commands Section -----
# This section describes the commands to run in rattan.
#
# When in `Compatible` mode, only the left and shell options are used,
# and the commands will run in the `ns-left` network namespace.
#
# When in `Isolated` mode, only the left and right options are used,
# and the commands will run in the `ns-left` and `ns-right` network namespace, respectively.
[commands]
left = ["echo", "hello world"]
# right = ["echo", "hello world"]
# Possible values: "Default", "Sh", "Bash", "Fish" and "Zsh"
shell = "Default"