Examples to demonstrate the usage of config options in NeST

This directory contains the following examples to understand how config options can be used in NeST. These options provide flexibility to the NeST users to customize the parameters used in the experiment. We recommend that you walk through these examples in the same order as they are presented.

1. config-1-point-to-point-1.py

This program emulates a point to point network between two hosts h1 and h2. Five ping packets are sent from h1 to h2, and the success/failure of these packets is reported. It is similar to point-to-point-1.py in examples/basic-examples. This program shows two config options in NeST for ease of experimentation. For this purpose, a new package called config is imported in this program.

By default, NeST deletes all the nodes (or network namespaces) at the end of the experiment. One of the config options in NeST allows the user to customize this behavior, if needed, and retain the namespaces. Another config option in NeST is to avoid giving random names to the namespaces. Since NeST allows multiple programs to run in parallel on the same machine, it internally assigns random names to the namespaces by default. However, when random names are disabled, node names cannot be longer than three characters. We use names h1 and h2 in this example.

IMPORTANT NOTE
Do not forget to delete the namespaces manually before re-running this program. You can delete namespaces one-by-one by using sudo ip netns del h1 command (similarly for h2) or delete all namespaces at once by using sudo ip --all netns del. Be careful if you choose to delete all namespaces because this command will delete all the namespaces in your system (even the ones that were not created by NeST).

Source code

 1# SPDX-License-Identifier: GPL-2.0-only
 2# Copyright (c) 2019-2022 NITK Surathkal
 3
 4########################
 5# SHOULD BE RUN AS ROOT
 6########################
 7from nest.topology import *
 8from nest import config
 9
10# This program emulates a point to point network between two hosts `h1` and
11# `h2`. Five ping packets are sent from `h1` to `h2`, and the success/failure
12# of these packets is reported. It is similar to `point-to-point-1.py` in
13# `examples/basic-examples`. This program shows two `config` options in NeST
14# for ease of experimentation. For this purpose, we have imported a new
15# package called `config` in this program (Line 8 above).
16
17#################################
18#       Network Topology        #
19#                               #
20#          5mbit, 5ms -->       #
21#   h1 ------------------- h2   #
22#       <-- 10mbit, 100ms       #
23#                               #
24#################################
25
26# By default, NeST deletes all the nodes (or network namespaces) at the end of
27# the experiment. One of the `config` options in NeST allows the user to
28# customize this behavior, if needed, and retain the namespaces. Another
29# `config` option in NeST is to avoid giving random names to the namespaces.
30# Since NeST allows multiple programs to run in parallel on the same machine,
31# it internally assigns random names to the namespaces by default. However,
32# when random names are disabled, node names cannot be longer than three
33# characters. We use names `h1` and `h2` in this example.
34
35# The following two lines ensure that NeST does not delete namespaces during
36# the termination of this experiment, and does not assign random names to the
37# namespaces. After running this program, use `ip netns` command to see the
38# namespaces created by NeST. IMPORTANT: Do not forget to delete the namespaces
39# manually before re-running this program. You can delete namespaces one-by-one
40# by using `sudo ip netns del h1` command (similarly for `h2`) or delete all
41# namespaces at once by using `sudo ip --all netns del`. Be careful if you
42# choose to delete all namespaces because this command will delete all the
43# namespaces in your system (even the ones that were not created by NeST).
44config.set_value("delete_namespaces_on_termination", False)
45config.set_value("assign_random_names", False)
46
47# Create two hosts `h1` and `h2`.
48h1 = Node("h1")
49h2 = Node("h2")
50
51# Connect the above two hosts using a veth (virtual Ethernet) pair.
52(eth1, eth2) = connect(h1, h2)
53
54# Assign IPv4 address to both the interfaces.
55# We assume that the IPv4 address of this network is `192.168.1.0/24`.
56eth1.set_address("192.168.1.1/24")
57eth2.set_address("192.168.1.2/24")
58
59# Set the link attributes: `h1` --> `h2` and `h2` --> `h1`
60eth1.set_attributes("5mbit", "5ms")
61eth2.set_attributes("10mbit", "100ms")
62
63# `Ping` from `h1` to `h2`.
64h1.ping(eth2.address)

2. config-2-point-to-point-1.py

This program emulates a point to point network between two hosts h1 and h2. Five ping packets are sent from h1 to h2, and the success/failure of these packets is reported. It is similar to point-to-point-1.py in examples/basic-examples. This program shows a config option in NeST for the purpose of logging. Note: we have imported a new package called config in this program.

NeST supports different levels of logging by using Python’s logging levels. By default, the logging is enabled at INFO level. Other levels supported are: NOTSET, TRACE, DEBUG, WARNING, ERROR and CRITICAL.

Source code

 1# SPDX-License-Identifier: GPL-2.0-only
 2# Copyright (c) 2019-2022 NITK Surathkal
 3
 4########################
 5# SHOULD BE RUN AS ROOT
 6########################
 7from nest.topology import *
 8from nest import config
 9
10# This program emulates a point to point network between two hosts `h1` and
11# `h2`. Five ping packets are sent from `h1` to `h2`, and the success/failure
12# of these packets is reported. It is similar to `point-to-point-1.py` in
13# `examples/basic-examples`. This program shows a `config` option in NeST
14# for the purpose of logging. Note: we have imported a new package called
15# `config` in this program (Line 8 above).
16
17#################################
18#       Network Topology        #
19#                               #
20#          5mbit, 5ms -->       #
21#   h1 ------------------- h2   #
22#       <-- 10mbit, 100ms       #
23#                               #
24#################################
25
26# NeST supports different levels of logging by using Python's logging levels.
27# By default, the logging is enabled at INFO level. Other levels supported are:
28# NOTSET, TRACE, DEBUG, WARNING, ERROR and CRITICAL.
29
30# The following line configures the NeST to log at ERROR level. When this
31# program is run, it does not print INFO statements on the console as done in
32# some of the other examples in NeST. Only errors are printed to the console.
33config.set_value("log_level", "ERROR")
34
35# Create two hosts `h1` and `h2`.
36h1 = Node("h1")
37h2 = Node("h2")
38
39# Connect the above two hosts using a veth (virtual Ethernet) pair.
40(eth1, eth2) = connect(h1, h2)
41
42# Assign IPv4 address to both the interfaces.
43# We assume that the IPv4 address of this network is `192.168.1.0/24`.
44eth1.set_address("192.168.1.1/24")
45eth2.set_address("192.168.1.2/24")
46
47# Set the link attributes: `h1` --> `h2` and `h2` --> `h1`
48eth1.set_attributes("5mbit", "5ms")
49eth2.set_attributes("10mbit", "100ms")
50
51# `Ping` from `h1` to `h2`.
52h1.ping(eth2.address)

3. config-3-point-to-point-1.py

This program emulates a point to point network between two hosts h1 and h2. Five ping packets are sent from h1 to h2, and the success/failure of these packets is reported. It is similar to point-to-point-1.py in examples/basic-examples. This program shows a config option in NeST to import custom configuration from a JSON file. This option overwrites the default values in NeST for the parameters that are specified in the JSON file. The default values of other parameters are not overwritten. Note: we have imported a new package called config in this program.

This program uses the config option to read the configuration from the file named custom-config.json which is placed in the current directory. If the JSON file is named as nest-config.json and placed in the same directory as this program, or in /etc or ~/, then this program does not need to use the config option. It directly reads the configuration from nest-config.json.

Source code

 1# SPDX-License-Identifier: GPL-2.0-only
 2# Copyright (c) 2019-2022 NITK Surathkal
 3
 4########################
 5# SHOULD BE RUN AS ROOT
 6########################
 7from nest.topology import *
 8from nest import config
 9import os
10from pathlib import Path
11
12# This program emulates a point to point network between two hosts `h1` and
13# `h2`. Five ping packets are sent from `h1` to `h2`, and the success/failure
14# of these packets is reported. It is similar to `point-to-point-1.py` in
15# `examples/basic-examples`. This program shows a `config` option in NeST to
16# import custom configuration from a JSON file. This option overwrites the
17# default values in NeST for the parameters that are specified in the JSON
18# file. The default values of other parameters are not overwritten. Note: we
19# have imported a new package called `config` in this program (Line 8 above).
20
21#################################
22#       Network Topology        #
23#                               #
24#          5mbit, 5ms -->       #
25#   h1 ------------------- h2   #
26#       <-- 10mbit, 100ms       #
27#                               #
28#################################
29
30# The following lines enable NeST to read the configuration from the file
31# named `custom-config.json` which is placed in the same directory as this
32# program. ALTERNATIVE: If you prefer to import custom configuration without
33# using the two lines shown below, name the JSON file as `nest-config.json`
34# and keep it in the same directory as this program, or in /etc, or ~/.
35# In this example, `custom-config.json` changes the default values of
36# `assign_random_names` and `delete_namespaces_on_termination`, and changes the
37# `log_level` to `ERROR`.
38# IMPORTANT: Do not forget to delete the namespaces after running this program.
39CONFIG_DIR = Path(os.path.abspath(__file__)).parent
40config.import_custom_config(CONFIG_DIR / "custom-config.json")
41
42# Create two hosts `h1` and `h2`.
43h1 = Node("h1")
44h2 = Node("h2")
45
46# Connect the above two hosts using a veth (virtual Ethernet) pair.
47(eth1, eth2) = connect(h1, h2)
48
49# Assign IPv4 address to both the interfaces.
50# We assume that the IPv4 address of this network is `192.168.1.0/24`.
51eth1.set_address("192.168.1.1/24")
52eth2.set_address("192.168.1.2/24")
53
54# Set the link attributes: `h1` --> `h2` and `h2` --> `h1`
55eth1.set_attributes("5mbit", "5ms")
56eth2.set_attributes("10mbit", "100ms")
57
58# `Ping` from `h1` to `h2`.
59h1.ping(eth2.address)

4. config-4-point-to-point-1.py

This program emulates a point to point network between two hosts h1 and h2. Five ping packets are sent from h1 to h2, and the success/failure of these packets is reported. It is similar to config-2-point-to-point-1.py example. This program shows a config option for the purpose of tracing internal Linux commands (for example, those of iproute2) executed by NeST. Note: we have imported a new package called config in this program.

NeST supports different levels of logging by using Python’s logging levels. By default, the logging is enabled at INFO level. Other levels supported are: NOTSET, TRACE, DEBUG, WARNING, ERROR and CRITICAL. This program enables the TRACE level log, which creates a file called commands.sh with all the iproute2 commands NeST internally executes. But by default, NeST assigns random names to the network namespaces. Hence, when TRACE level log is enabled, the names of network namespaces visible in commands.sh would be random, and not user-friendly. To make the names look user-friendly, random name assignment is disbaled in this program.

Source code

 1# SPDX-License-Identifier: GPL-2.0-only
 2# Copyright (c) 2019-2022 NITK Surathkal
 3
 4########################
 5# SHOULD BE RUN AS ROOT
 6########################
 7from nest.topology import *
 8from nest import config
 9
10# This program emulates a point to point network between two hosts `h1` and
11# `h2`. Five ping packets are sent from `h1` to `h2`, and the success/failure
12# of these packets is reported. It is similar to `config-2-point-to-point-1.py`
13# example. This program shows a `config` option for the purpose of tracing
14# internal Linux commands (for example, those of iproute2) executed by NeST.
15# Note: we have imported a new package called `config` in this program (Line 8
16# above).
17
18#################################
19#       Network Topology        #
20#                               #
21#          5mbit, 5ms -->       #
22#   h1 ------------------- h2   #
23#       <-- 10mbit, 100ms       #
24#                               #
25#################################
26
27# NeST supports different levels of logging by using Python's logging levels.
28# By default, the logging is enabled at INFO level. Other levels supported are:
29# NOTSET, TRACE, DEBUG, WARNING, ERROR and CRITICAL.
30
31# The following line configures the NeST to log at TRACE level. When this
32# program is run, it create a file called `commands.sh` with all the iproute2
33# commands NeST internally executes.
34config.set_value("log_level", "TRACE")
35
36# By default, NeST assigns random names to the network namespaces. Hence, when
37# TRACE level log is enabled, the names of network namespaces visible in
38# `commands.sh` would be random, and not user-friendly. To make the names look
39# user-friendly, disable random name assignment in NeST.
40config.set_value("assign_random_names", False)
41
42# Create two hosts `h1` and `h2`.
43h1 = Node("h1")
44h2 = Node("h2")
45
46# Connect the above two hosts using a veth (virtual Ethernet) pair.
47(eth1, eth2) = connect(h1, h2)
48
49# Assign IPv4 address to both the interfaces.
50# We assume that the IPv4 address of this network is `192.168.1.0/24`.
51eth1.set_address("192.168.1.1/24")
52eth2.set_address("192.168.1.2/24")
53
54# Set the link attributes: `h1` --> `h2` and `h2` --> `h1`
55eth1.set_attributes("5mbit", "5ms")
56eth2.set_attributes("10mbit", "100ms")
57
58# `Ping` from `h1` to `h2`.
59h1.ping(eth2.address)

The details of all config options supported in NeST are available here.