Basic examples to get started with NeST

This directory contains the following examples to get started with NeST, and we recommend that the beginners walk through these examples in the same order as they are presented:

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. The main aim of this example is to demonstrate the usage of basic APIs of NeST to create a network topology, configure link attributes, assign IPv4 addresses and test the connectivity between two hosts.

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 *
 8
 9# This program emulates a point to point network between two hosts `h1` and
10# `h2`. Five ping packets are sent from `h1` to `h2`, and the success/failure
11# of these packets is reported.
12
13#################################
14#       Network Topology        #
15#                               #
16#          5mbit, 5ms -->       #
17#   h1 ------------------- h2   #
18#       <-- 10mbit, 100ms       #
19#                               #
20#################################
21
22# Create two hosts, with the names h1 and h2
23# and return it to the python variables `h1` and `h2`
24# The `Node` API takes the name of the node as a string,
25# and the same name is used to return results.
26h1 = Node("h1")
27h2 = Node("h2")
28
29# Connect the above two hosts using a veth (virtual Ethernet)
30# pair and return the interfaces at the end points of the link
31# as a tuple `eth1` and `eth2`. `eth1` interface is at `h1` and
32# `eth2` interface is at `h2`.
33# The `connect` API takes two hosts as the parameters and returns
34# the pair of interfaces.
35(eth1, eth2) = connect(h1, h2)
36
37# Assign IPv4 address to both the interfaces.
38# The `set_address` API takes the address as a string.
39# Note: it is important to mention the subnet.
40eth1.set_address("192.168.1.1/24")
41eth2.set_address("192.168.1.2/24")
42
43# Set the link attributes such as bandwidth and propagation delay.
44# The attributes for the link from `h1` to `h2` are set at
45# interface `eth1` (and vice versa).
46# Note that the bandwidth and propagation delay can be asymmetric.
47# In the real deployments, upload and download bandwidth is not
48# the same, and even propagation delays can vary because the
49# forward and reverse paths can be different.
50eth1.set_attributes("5mbit", "5ms")
51eth2.set_attributes("10mbit", "100ms")
52
53# `Ping` from `h1` to `h2`.
54# The `ping` API, by default, sends five ping packets from `h1` to `h2`
55# and reports whether they succeeded or failed.
56h1.ping(eth2.address)

2. point-to-point-2.py

This program emulates point to point networks that connect two hosts h1 and h2 via a router r1. Five ping packets are sent from h1 to h2, and the success/failure of these packets is reported. This example extends the point-to-point-1.py example. The main aim of this example is to demonstrate how two networks can be interconnected by using a router. The steps to enable IPv4 forwarding in the router and setting default routes in the hosts are covered in this program. We manually set the routes because we are not using dynamic routing protocols like RIP, OSPF and others.

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 *
 8
 9# This program emulates point to point networks that connect two hosts `h1`
10# and `h2` via a router `r1`. Five ping packets are sent from `h1` to `h2`, and
11# the success/failure of these packets is reported.
12
13##########################################################
14#                   Network Topology                     #
15#                                                        #
16#          5mbit, 5ms -->          5mbit, 5ms -->        #
17#   h1 -------------------- r1 -------------------- h2   #
18#       <-- 10mbit, 100ms        <-- 10mbit, 100ms       #
19#                                                        #
20##########################################################
21
22# Create two hosts `h1` and `h2`, and one router `r1`
23h1 = Node("h1")
24h2 = Node("h2")
25r1 = Router("r1")  # Internally, `Router` API enables IP forwarding in `r1`
26
27# Connect `h1` to `r1`, and then `r1` to `h2`
28# `eth1` and `eth2` are the interfaces at `h1` and `h2`, respectively.
29# `etr1a` is the first interface at `r1` which connects it with `h1`
30# `etr1b` is the second interface at `r1` which connects it with `h2`
31(eth1, etr1a) = connect(h1, r1)
32(etr1b, eth2) = connect(r1, h2)
33
34# Assign IPv4 addresses to all the interfaces.
35# Note: this example has two networks, one each on either side of `r1`.
36# Assign IPv4 addresses to interfaces in the left side network. We assume
37# that the IPv4 address of the left side network is `192.168.1.0/24`
38eth1.set_address("192.168.1.1/24")
39etr1a.set_address("192.168.1.2/24")
40
41# Assign IPv4 addresses to interfaces in the right side network. We assume
42# that the IPv4 address of the right side network is `192.168.2.0/24`
43etr1b.set_address("192.168.2.1/24")
44eth2.set_address("192.168.2.2/24")
45
46# Set the link attributes: `h1` --> `r1` --> `h2`
47eth1.set_attributes("5mbit", "5ms")  # from `h1` to `r1`
48etr1b.set_attributes("5mbit", "5ms")  # from `r1` to `h2`
49
50# Set the link attributes: `h2` --> `r1` --> `h1`
51eth2.set_attributes("10mbit", "100ms")  # from `h2` to `r1`
52etr1a.set_attributes("10mbit", "100ms")  # from `r1` to `h1`
53
54# Set default routes in `h1` and `h2` so that the packets that cannot be
55# forwarded based on the entries in their routing table are sent via a
56# default interface.
57h1.add_route("DEFAULT", eth1)
58h2.add_route("DEFAULT", eth2)
59
60# `Ping` from `h1` to `h2`.
61h1.ping(eth2.address)

3. point-to-point-3.py

This program emulates point to point networks that connect two hosts h1 and h2 via two routers r1 and r2. Five ping packets are sent from h1 to h2, and the success/failure of these packets is reported. This example extends the point-to-point-2.py example. The main aim of this example is to demonstrate how two networks can be interconnected by a network of routers. Besides enabling IPv4 forwarding and setting default routes in hosts, this example requires setting default routes in the routers.

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 *
 8
 9# This program emulates point to point networks that connect two hosts `h1`
10# and `h2` via two routers `r1` and `r2`. Five ping packets are sent from `h1`
11# to `h2`, and the success/failure of these packets is reported.
12
13##############################################################################
14#                              Network Topology                              #
15#                                                                            #
16#        5mbit, 5ms -->          5mbit, 5ms -->          5mbit, 5ms -->      #
17# h1 -------------------- r1 -------------------- r2 -------------------- h2 #
18#     <-- 10mbit, 100ms       <-- 10mbit, 100ms       <-- 10mbit, 100ms      #
19#                                                                            #
20##############################################################################
21
22# Create two hosts `h1` and `h2`, and two routers `r1` and `r2`
23h1 = Node("h1")
24h2 = Node("h2")
25r1 = Router("r1")
26r2 = Router("r2")
27
28# Connect `h1` to `r1`, `r1` to `r2`, and then `r2` to `h2`
29# `eth1` and `eth2` are the interfaces at `h1` and `h2`, respectively.
30# `etr1a` is the first interface at `r1` which connects it with `h1`
31# `etr1b` is the second interface at `r1` which connects it with `r2`
32# `etr2a` is the first interface at `r2` which connects it with `r1`
33# `etr2b` is the second interface at `r2` which connects it with `h2`
34(eth1, etr1a) = connect(h1, r1)
35(etr1b, etr2a) = connect(r1, r2)
36(etr2b, eth2) = connect(r2, h2)
37
38# Assign IPv4 addresses to all the interfaces.
39# Note: this example has three networks: one on the left of `r1`, second
40# between the two routers, and third on the right of `r2`.
41# Assign IPv4 addresses to interfaces in the network which is on the left of
42# `r1`. We assume that the IPv4 address of this network is `192.168.1.0/24`
43eth1.set_address("192.168.1.1/24")
44etr1a.set_address("192.168.1.2/24")
45
46# Assign IPv4 addresses to interfaces in the network which is between the two
47# routers. We assume that the IPv4 address of this network is `192.168.2.0/24`
48etr1b.set_address("192.168.2.1/24")
49etr2a.set_address("192.168.2.2/24")
50
51# Assign IPv4 addresses to interfaces in the network which is on the right of
52# `r2`. We assume that the IPv4 address of this network is `192.168.3.0/24`
53etr2b.set_address("192.168.3.1/24")
54eth2.set_address("192.168.3.2/24")
55
56# Set the link attributes: `h1` --> `r1` --> `r2` --> `h2`
57eth1.set_attributes("5mbit", "5ms")  # from `h1` to `r1`
58etr1b.set_attributes("5mbit", "5ms")  # from `r1` to `r2`
59etr2b.set_attributes("5mbit", "5ms")  # from `r2` to `h2`
60
61# Set the link attributes: `h2` --> `r2` --> `r1` --> `h1`
62eth2.set_attributes("10mbit", "100ms")  # from `h2` to `r2`
63etr2a.set_attributes("10mbit", "100ms")  # from `r2` to `r1`
64etr1a.set_attributes("10mbit", "100ms")  # from `r1` to `h1`
65
66# Set default routes in `h1` and `h2`. Additionally, set default routes in
67# `r1` and `r2` so that the packets that cannot be forwarded based on the
68# entries in their routing table are sent via a default interface.
69h1.add_route("DEFAULT", eth1)
70h2.add_route("DEFAULT", eth2)
71r1.add_route("DEFAULT", etr1b)
72r2.add_route("DEFAULT", etr2a)
73
74# `Ping` from `h1` to `h2`.
75h1.ping(eth2.address)

4. simple-lan.py

This program emulates a Local Area Network (LAN). Four hosts: h1 to h4 are connected using a switch s1. Five ping packets are sent from h1 to h2 and five ping packets from h3 to h4. The success/failure of these packets is reported. This example demonstrates how to use the Switch class in NeST to set up a LAN.

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 *
 8
 9# This program emulates a Local Area Network (LAN). Four hosts: `h1` to `h4`
10# are connected using a switch `s1`. Five ping packets are sent from `h1` to
11# `h2`, and five ping packets from `h3` to `h4`. The success/failure of these
12# packets is reported.
13
14######################################################################
15#                          Network Topology                          #
16#                                                                    #
17#  h1               h2                          h3               h4  #
18#  |                |                           |                 |  #
19#  ----------------------------- s1 -------------------------------  #
20#                    <------ 100mbit, 1ms ------>                    #
21#                                                                    #
22######################################################################
23
24# Create four hosts `h1` to `h4`, and one switch `s1`
25h1 = Node("h1")
26h2 = Node("h2")
27h3 = Node("h3")
28h4 = Node("h4")
29s1 = Switch("s1")
30
31# Connect all the four hosts to the switch
32# `eth1` to `eth4` are the interfaces at `h1` to `h4`, respectively.
33# `ets1a` is the first interface at `s1` which connects it with `h1`
34# `ets1b` is the second interface at `s1` which connects it with `h2`
35# `ets1c` is the third interface at `s1` which connects it with `h3`
36# `ets1d` is the fourth interface at `s1` which connects it with `h4`
37(eth1, ets1a) = connect(h1, s1)
38(eth2, ets1b) = connect(h2, s1)
39(eth3, ets1c) = connect(h3, s1)
40(eth4, ets1d) = connect(h4, s1)
41
42# Assign IPv4 addresses to all the interfaces.
43# We assume that the IPv4 address of this network is `192.168.1.0/24`.
44# Note: IP addresses should not be assigned to the interfaces on the switch.
45eth1.set_address("192.168.1.1/24")
46eth2.set_address("192.168.1.2/24")
47eth3.set_address("192.168.1.3/24")
48eth4.set_address("192.168.1.4/24")
49
50# Set the link attributes
51eth1.set_attributes("100mbit", "1ms")
52eth2.set_attributes("100mbit", "1ms")
53eth3.set_attributes("100mbit", "1ms")
54eth4.set_attributes("100mbit", "1ms")
55
56# `Ping` from `h1` to `h2`, and `h3` to `h4`.
57h1.ping(eth2.address)
58h3.ping(eth4.address)

5. two-lans-connected-directly.py

This program emulates two Local Area Networks (LANs) connected directly to each other. LAN-1 consists of three hosts h1 to h3 connected to switch s1, and LAN-2 consists three hosts h4 to h6 connected to switch s2. Switches s1 and s2 are connected to each other. Five ping packets are sent from h1 to h4, five from h2 to h5 and lastly, five from h3 to h6. The success/failure of these packets is reported. This program extends simple-lan.py.

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 *
 8
 9# This program emulates two Local Area Networks (LANs) connected directly to
10# each other. LAN-1 consists three hosts `h1` to `h3` connected to switch `s1`,
11# and LAN-2 consists three hosts `h4` to `h6` connected to switch `s2`.
12# Switches `s1` and `s2` are connected to each other. Five ping packets are
13# sent from `h1` to `h4`, five from `h2` to `h5` and lastly, five from `h3`
14# to `h6`. The success/failure of these packets is reported.
15
16#########################################################
17#                    Network Topology                   #
18#           LAN-1                      LAN-2            #
19#   h1 ---------------            ---------------- h4   #
20#                     \         /                       #
21#   h2 --------------- s1 ---- s2 ---------------- h5   #
22#                     /         \                       #
23#   h3 ---------------            ---------------- h6   #
24#             <------ 100mbit, 1ms ------>              #
25#                                                       #
26#########################################################
27
28# Create six hosts `h1` to `h6`, and two switches `s1` and `s2`
29h1 = Node("h1")
30h2 = Node("h2")
31h3 = Node("h3")
32h4 = Node("h4")
33h5 = Node("h5")
34h6 = Node("h6")
35s1 = Switch("s1")
36s2 = Switch("s2")
37
38# Create LAN-1: Connect hosts `h1`, `h2` and `h3` to switch `s1`
39# `eth1` to `eth3` are the interfaces at `h1` to `h3`, respectively.
40# `ets1a` is the first interface at `s1` which connects it with `h1`
41# `ets1b` is the second interface at `s1` which connects it with `h2`
42# `ets1c` is the third interface at `s1` which connects it with `h3`
43(eth1, ets1a) = connect(h1, s1)
44(eth2, ets1b) = connect(h2, s1)
45(eth3, ets1c) = connect(h3, s1)
46
47# Create LAN-2: Connect hosts `h4`, `h5` and `h6` to switch `s2`
48# `eth4` to `eth6` are the interfaces at `h4` to `h6`, respectively.
49# `ets2a` is the first interface at `s2` which connects it with `h4`
50# `ets2b` is the second interface at `s2` which connects it with `h5`
51# `ets2c` is the third interface at `s2` which connects it with `h6`
52(eth4, ets2a) = connect(h4, s2)
53(eth5, ets2b) = connect(h5, s2)
54(eth6, ets2c) = connect(h6, s2)
55
56# Connect switches `s1` and `s2`
57# `ets1d` is the fourth interface at `s1` which connects it with `s2`
58# `ets2d` is the fourth interface at `s2` which connects it with `s1`
59(ets1d, ets2d) = connect(s1, s2)
60
61# Assign IPv4 addresses to all the interfaces.
62# We assume that the IPv4 address of this network is `192.168.1.0/24`.
63# Note: IP addresses should not be assigned to the interfaces on the switches.
64eth1.set_address("192.168.1.1/24")
65eth2.set_address("192.168.1.2/24")
66eth3.set_address("192.168.1.3/24")
67eth4.set_address("192.168.1.4/24")
68eth5.set_address("192.168.1.5/24")
69eth6.set_address("192.168.1.6/24")
70
71# Set the link attributes
72eth1.set_attributes("100mbit", "1ms")
73eth2.set_attributes("100mbit", "1ms")
74eth3.set_attributes("100mbit", "1ms")
75eth4.set_attributes("100mbit", "1ms")
76eth5.set_attributes("100mbit", "1ms")
77eth6.set_attributes("100mbit", "1ms")
78
79# `Ping` from `h1` to `h4`, `h2` to `h5`, and `h3` to `h6`.
80h1.ping(eth4.address)
81h2.ping(eth5.address)
82h3.ping(eth6.address)

6. two-lans-connected-via-router.py

This program emulates two Local Area Networks (LANs) connected via a router. LAN-1 consists three hosts h1 to h3 connected to switch s1, and LAN-2 consists three hosts h4 to h6 connected to switch s2. Switches s1 and s2 are connected to each other via a router r1. Five ping packets are sent from h1 to h4, five from h2 to h5 and lastly, five from h3 to h6. The success/failure of these packets is reported. This program extends two-lans-connected-directly.py.

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 *
  8
  9# This program emulates two Local Area Networks (LANs) connected via a router.
 10# LAN-1 consists three hosts `h1` to `h3` connected to switch `s1`, and
 11# LAN-2 consists three hosts `h4` to `h6` connected to switch `s2`. Switches
 12# `s1` and `s2` are connected to each other via a router `r1`. Five ping
 13# packets are sent from `h1` to `h4`, five from `h2` to `h5` and lastly, five
 14# from `h3` to `h6`. The success/failure of these packets is reported.
 15
 16##################################################################
 17#                       Network Topology                         #
 18#           LAN-1                           LAN-2                #
 19#   h1 ---------------                      --------------- h4   #
 20#                     \                    /                     #
 21#   h2 --------------- s1 ----- r1 ----- s2 --------------- h5   #
 22#                     /                    \                     #
 23#   h3 ---------------                      --------------- h6   #
 24#   <- 100mbit, 1ms ->  <- 10mbit, 10ms ->  <- 100mbit, 1ms ->   #
 25#                                                                #
 26##################################################################
 27
 28# Create six hosts 'h1' to 'h6'
 29h1 = Node("h1")
 30h2 = Node("h2")
 31h3 = Node("h3")
 32h4 = Node("h4")
 33h5 = Node("h5")
 34h6 = Node("h6")
 35
 36# Create two switches 's1' and 's2'
 37s1 = Switch("s1")
 38s2 = Switch("s2")
 39
 40# Create a router 'r1'
 41r1 = Router("r1")
 42
 43# Create LAN-1: Connect hosts `h1`, `h2` and `h3` to switch `s1`
 44# `eth1` to `eth3` are the interfaces at `h1` to `h3`, respectively.
 45# `ets1a` is the first interface at `s1` which connects it with `h1`
 46# `ets1b` is the second interface at `s1` which connects it with `h2`
 47# `ets1c` is the third interface at `s1` which connects it with `h3`
 48(eth1, ets1a) = connect(h1, s1)
 49(eth2, ets1b) = connect(h2, s1)
 50(eth3, ets1c) = connect(h3, s1)
 51
 52# Create LAN-2: Connect hosts `h4`, `h5` and `h6` to switch `s2`
 53# `eth4` to `eth6` are the interfaces at `h4` to `h6`, respectively.
 54# `ets2a` is the first interface at `s2` which connects it with `h4`
 55# `ets2b` is the second interface at `s2` which connects it with `h5`
 56# `ets2c` is the third interface at `s2` which connects it with `h6`
 57(eth4, ets2a) = connect(h4, s2)
 58(eth5, ets2b) = connect(h5, s2)
 59(eth6, ets2c) = connect(h6, s2)
 60
 61# Connect switches `s1` and `s2` to router `r1`
 62# `ets1d` is the fourth interface at `s1` which connects it with `r1`
 63# `ets2d` is the fourth interface at `s2` which connects it with `r1`
 64# `etr1a` is the first interface at `r1` which connects it with `s1`
 65# `etr1b` is the second interface at `r1` which connects it with `s2`
 66(ets1d, etr1a) = connect(s1, r1)
 67(ets2d, etr1b) = connect(s2, r1)
 68
 69# Assign IPv4 addresses to all the interfaces of network on the left of `r1`
 70# We assume that the IPv4 address of this network is `192.168.1.0/24`.
 71# Assign IPv4 addresses to the hosts
 72eth1.set_address("192.168.1.1/24")
 73eth2.set_address("192.168.1.2/24")
 74eth3.set_address("192.168.1.3/24")
 75
 76# Assign IPv4 address to the switch `s1` on the left of `r1`
 77s1.set_address("192.168.1.4/24")
 78
 79# Assign IPv4 address to the left interface of `r1`
 80etr1a.set_address("192.168.1.5/24")
 81
 82# Assign IPv4 addresses to all the interfaces of network on the right of `r1`
 83# We assume that the IPv4 address of this network is `192.168.2.0/24`.
 84# Assign IPv4 addresses to the hosts
 85eth4.set_address("192.168.2.1/24")
 86eth5.set_address("192.168.2.2/24")
 87eth6.set_address("192.168.2.3/24")
 88
 89# Assign IPv4 address to the switch `s2` on the right of `r1`
 90s2.set_address("192.168.2.4/24")
 91
 92# Assign IPv4 address to the right interface of `r1`
 93etr1b.set_address("192.168.2.5/24")
 94
 95# Set the attributes of the links between hosts and switches
 96eth1.set_attributes("100mbit", "1ms")
 97eth2.set_attributes("100mbit", "1ms")
 98eth3.set_attributes("100mbit", "1ms")
 99eth4.set_attributes("100mbit", "1ms")
100eth5.set_attributes("100mbit", "1ms")
101eth6.set_attributes("100mbit", "1ms")
102
103# Set the attributes of the links between `r1` and switches
104etr1a.set_attributes("10mbit", "10ms")
105etr1b.set_attributes("10mbit", "10ms")
106
107# Set the default routes for hosts `h1`, `h2` and `h3` via `etr1a`
108h1.add_route("DEFAULT", eth1, etr1a.address)
109h2.add_route("DEFAULT", eth2, etr1a.address)
110h3.add_route("DEFAULT", eth3, etr1a.address)
111
112# Set the default routes for hosts `h4`, `h5` and `h6` via `etr1b`
113h4.add_route("DEFAULT", eth4, etr1b.address)
114h5.add_route("DEFAULT", eth5, etr1b.address)
115h6.add_route("DEFAULT", eth6, etr1b.address)
116
117# `Ping` from `h1` to `h4`, `h2` to `h5`, and `h3` to `h6`.
118h1.ping(eth4.address)
119h2.ping(eth5.address)
120h3.ping(eth6.address)