IP Getting started guide

This guide is meant to be your first resource for learning about the virtual network architecture and our stencil tools. We’ll be adding more implementation resources in the next day or so. For now, your work should be mostly focused on design.

Essential resources

As you start the project, you should be aware of the following resources:

  • Gearup I (recording, notes) is a video overview of how the project architecture works, how to use the tools, and how to debug. We highly recommend watching this! We’ll also have another gearup (Gearup II) in the second week of the project; if you’re looking for more info, you can view last year’s Gearup II recording beforehand.
  • Lecture 7: is about the exactly the concepts you need for the first half of the project (networking stacks, IP forwarding). You should watch this before you start–it will help, we promise!
  • Lecture 8 and 9: Will fill in more important details about how IP forwarding and RIP work. Stay tuned for these, they will really help!

Cloning the stencil

You should have received an email with your project team assignment and a personalized stencil link. If are enrolled in the course and you did not get an email, please contact Nick ASAP.

To make development easier, we recommend cloning your stencil code for this project so you can access files in it from your development container. To do this, we recommend cloning the stencil in your DEV-ENVIRONMENT/home directory, where DEV-ENVIRONMENT is the name of the folder you used when you cloned the development container.

Here’s an example of what your filesystem might look like:

 - ...
 |--DEV-ENVIRONMENT
 | |--docker/ 
 | |--home/
 | | |--snowcast-yourname/
 | | |--ip-team-name/    # <----------------- Clone your stencil here!
 | |--run-container
 | |-- ...
 ...

As with snowcast, your stencil repo is almost completely blank. We have provided a few tools that you can use to build and test your implementation, which are described below:

  • reference/: Contains our reference version of virtual host and router programs, vhost and vrouter–you can use these for testing! (Apple Silicon users: your reference version is in the reference/arm64 directory instead.)
  • nets: Network definition files, matching Sample Networks
  • util/vnet_generate: Script to create configuration files for each network
  • util/vnet_run: Script to run the virtual network

The following sections briefly describe how to run the virtual network and play around using the reference implementation. Later, you can follow the same procedure with your own vhost and vrouter binaries.

How to run the virtual network

At a high level, there are a few steps to running a virtual network:

  1. Select the topology you want to run (ie, how many hosts/routers, and how they’re connected). For a list of pre-made topologies, see Sample Networks. You can also build your own!

  2. Generate configuration files (lnx files) for each node using util/vnet_generate: these are the files that tell each node how to connect to the network at startup (ie, its interfaces, IP addresses, local network configuration etc.)

  3. Run the network using util/vnet_run: given a set of config files and your vhost and vrouter binaries, this will start up all the processes for you so you don’t have to!

Generating the lnx files

Let’s say we want to run the doc-example topology, which is located in your stencil at nets/doc-example.json. To generate the configuration files, do the following:

  1. Open a terminal in your container and cd to your stencil directory

  2. Run the following: util/vnet_generate nets/doc-example.json doc-example

You should see output that looks like this:

cs1680-user@3d58a59f4be7:~/iptcp-ndemarinis$ util/vnet_generate nets/doc-example.json doc-example
Output directory doc-example does not exist, creating
Writing doc-example/r1.lnx
Writing doc-example/r2.lnx
Writing doc-example/h1.lnx
Writing doc-example/h2.lnx
Writing doc-example/h3.lnx

This creates a directory called doc-example in your stencil repo, with a .lnx file for how each node should be set up. For an overview of what goes inside each .lnx file and how it works, see the gearup video.

Running the network

Note: To see a video of the entire process, we recommend watching the Gearup II video, which demonstrates everything here.

vnet_run automatically launches node processes for all nodes in a virtual network in a tmux session. tmux is a terminal multiplexer, a program that allows you to run multiple processes in the same terminal and navigate between them. It’s okay if you haven’t used tmux before–we’ll show you how it works!

You can run vnet_run like this:

cs1680-user@3d58a59f4be7:$ util/vnet_run --bin-dir <directory with vhost and vrouter> <directory with lnx files>

For example, to run doc-example network with the reference vhost and vrouter, you can run one of the following commands (pick based on your architecture):

On x86-64 systems:

cs1680-user@3d58a59f4be7:$ util/vnet_run --bin-dir reference doc-example

On Apple Silicon (M1/M2/M3/etc mac) systems:

cs1680-user@3d58a59f4be7:$ util/vnet_run --bin-dir reference/arm64 doc-example

This tells vnet_run to look in the reference (or reference/arm64) dir for the vhost and vrouter binaries, and to look in doc-example for the lnx files. See vnet_run --help for more options.

vnet_net will create a tmux session with one terminal for each node in one big window, which should look like this:

Let’s break down what we’re seeing here:

  • You should see one pane per node in the network (the image above labels a few). Each pane is numbered–the top-left corner of each pane shows the name of the node and its pane number.
  • You should see your terminal’s cursor in one of the panes. This is the active pane. When you type, your input goes to the active pane. You can switch which pane is active with some tmux commands (listed below).

At the start, you should see just a > prompt in each pane–this is the prompt for the REPL for the reference node. You can start typing in any pane to run commands.

Controlling tmux (and sending a packet!)

Commands in tmux are typically in the form of Ctrl+b KEY. This means you should first press Ctrl+b, release, and then press the next key. Ctrl+b is known as an “escape sequence” that tells tmux that your input is a tmux command and not input for the terminal.

To give you some practice with tmux and working with the virtual network, we can demonstrate how to run commanands in different panes by sending a packet from h1 to h3 in the virtual network:

  1. Let’s first find h3’s IP address. Press Ctrl+b o until your cursor moves to the pane for h3. In this pane, run the li command, which should look like this:

  1. Use Ctrl+b o to move over to the pane for h1

  2. In h1’s terminal, run the command send <h3's IP address> aaaaa, filling in the IP address from step 1 in place of <h3's IP address>. This sends a test packet from h1 to h3

  3. You should see a message appear in h3’s terminal like this:

If your terminal looks like this, you just sent your first test packet, yay! 😎🎉

Bonus: notice the TTL on the received packet. The reference uses a starting TTL value of 32. Does this make sense given the doc-example network’s topology (see here for a picture)? When you build your vhost and vrouter, you should be asking yourself these same questions!

For the milestone: To show you can run the tools, take a screenshot of your tmux window after you sent a packet and push it to your repository. If you have issues, please come to office hours or you can ask us during your milestone meeting.

Our favorite tmux commands

(Skim now, remember for later) Here are our favorite commands for working with tmux for these project

  • Ctrl+b o: Cycle between panes (super useful)
  • Ctrl+b z: “Zoom in” on one pane, making it fullscreen (Ctrl+b z to go back) (super useful)
  • Ctrl+b :, then type kill session <Enter>: Kill the session (and all nodes) (super useful)
  • Ctrl+b space: Cycle various pane layouts
  • Ctrl+b q <number key>: Switch directly to pane number N
  • Ctrl+b d: Detach the session (but leave it running); reattach with tmux attach

Try these out as you spend more time testing your virtual network!

Don't like tmux's keyboard commands?

We don’t either! Fortunately, you can customize them as much as you like! For an intro on how to customize tmux, see here.

“Why don’t you customize them for us, then?” We want you to be able to use the skills you learn in this class when you’re out in the real world—and in the real world, you won’t have our container setup or our configuration files. In general, customizations like this are a great way to learn more about systems tools and Linux—we want you to build these skills!

Want to learn more about tmux?

If you want to learn more about tmux, we recommend the following:

Closing your vnet_run session

When you want to exit your virtual network session, use the following tmux command:

  1. Press Ctrl+b :
  2. Type kill-session
  3. Press Enter

This stops all your running vhost and vrouter instances and shuts down tmux. You can start it up again by running vnet_run again.

If something goes wrong: If for some reason the close process fails, or tmux exits improperly such that it fails to start again, run vnet_run with the --clean option, ie. vnet_run --clean ....
This should clear out any old tmux sessions before starting the network.

More ways to use vnet_run

This is only the beginning–there are many more ways you can use vnet_run to help with testing and debugging. For more info, see the following:

Next steps

Now that you have seen the network run, we recommend getting started by taking a look at the following resources:

  • This section of the handout describes more about the virtual network architecture
  • The Implementation start guide has a step-by-step tutorial how to think about setting up your UDP sockets and viewing your virtual IP traffic in Wireshark, which is the primary way you’ll test this project. Do this tutorial when you’re ready to start writing actual code (ie, after your milestone), or earlier if you want a more hands-on introduction.
  • The Tools and Resources has more info about our essential code examples, more ways to use vnet_run, and more debugging strategies

We’ll be posting more resources soon as well!