initial commit

README.md

@@ -0,0 +1,83 @@
+# Exercises
+
+In this page, you find the Advanced Topics in Communication Networks exercises.
+Every week we will release a set of exercises.
+
+### Clone this repository to your VM
+
+We use this repository to provide you with all the files that you need to solve the exercises. Use the following commands to get a local clone of the repository _in your VM_ (make sure you are logged in with the user `p4`):
+
+```bash
+cd /home/p4/
+git clone https://gitlab.ethz.ch/nsg/adv-comm-net-exercises.git
+```
+
+### Update local repository to get new tasks and solutions
+
+Remember to pull this repository before every exercise session:
+
+```bash
+cd /home/p4/adv-comm-net-exercises
+git pull https://gitlab.ethz.ch/nsg/adv-comm-net-exercises.git
+```
+
+### Update P4 Utils
+
+P4 utils is under constant development, thus bug fixes or new features can appear from one week to another, keep it updated.
+
+```bash
+cd ~/p4-tools/p4-utils
+git pull
+```
+
+### Documentation
+
+In this repository, you also find useful [documentation](./documentation) that will help you to better understand P4.
+We will periodically add new content to the documentation, so make sure you check it regularly (i.e. do `git pull`).
+
+### Required Software
+
+In order to be able to compile p4 code, run it in a software switch and
+create topologies with hosts, several dependencies and open source tools need
+to be installed.
+
+Since the installation process can be a bit
+confusing and cumbersome we provide you with a [Vagrant](https://www.vagrantup.com/intro/index.html)
+script that automatically builds a virtual machine with all required software already installed. You can find the VM setup
+instructions in the [P4 Virtual Machine Installation](vm/README.md) document.
+
+## Exercises
+
+### Week 1: First contact with P4 (20/09/2018)
+
+ * [Packet Reflector](./exercises/01-Reflector)
+ * [Repeater](./exercises/02-Repeater)
+
+### Week 2: Basic L2 Switch (27/10/2018)
+
+ * [Simple L2 Forwarding](./exercises/03-L2_Basic_forwarding)
+ * [Broadcasting Packets](./exercises/03-L2_Flooding)
+ * [Learning Switch](./exercises/04-L2_Learning)
+
+### Week 3: L3 Switch and Stateful Programming (04/10/2018)
+
+ * [Heavy Hitter Detector](./exercises/06-Heavy_Hitter_Detector)
+ * [ECMP](./exercises/05-ECMP)
+ * [Flowlet Switching](./exercises/05-Flowlet_Switching)
+
+### Week 4:  Probabilistic Data Structures (11/10/2018)
+
+ * [Count-Min Sketch](../exercises/07-Count-Min-Sketch)
+
+### Week 5: Advanced L3 Features (18/10/2018)
+
+ * [Simple Routing](./exercises/08-Simple_Routing)
+ * [Traceroutable Network](./exercises/09-Traceroutable)
+
+### Week 6: (25/10/2018)
+
+ * [Congestion Aware Load Balancing (part 1)](./exercises/10-Congestion_Aware_Load_Balancing)
+
+### Week 7: (1/11/2018)
+
+ * [Congestion Aware Load Balancing (part 2)](./exercises/10-Congestion_Aware_Load_Balancing)

documentation/FAQ.md

@@ -0,0 +1,2 @@
+# FAQ
+

documentation/README.md

@@ -0,0 +1,34 @@
+# Documentation
+
+This documentation contains helpful information that will help you getting started
+with P4.
+
+We will keep adding content. The questions that get asked often will be added to the
+FAQ section. Useful resources and documentation will also be added if something new
+comes or if people ask about it.
+
+Before asking something to us check if the solution to your problem can be found in any of the
+following documents and links.
+
+#### Getting Started With P4:
+
+1. [Build VM](../vm/README.md#build-vm-using-vagrant) Build The VM from scratch using Vagrant
+2. [Download VM](../vm/README.md#download-the-ova-package) Get the OVA Image to directly import it to VirtualBox
+3. [P4 Repositories](p4lang-repository-structure.md) Guide to the public p4lang repositories
+4. [P4 Utils](https://github.com/nsg-ethz/p4-utils) Mininet Extension to build P4 networks
+
+#### P4 References
+
+1. [P4 Spec](https://p4.org/p4-spec/) P4 Language and Related Specifications
+2. [P4-guide](https://github.com/jafingerhut/p4-guide) Repository which contains a lot of useful information, examples,
+   tests of what works or what does not, etc.
+
+#### Resources
+
+1. [Manual Topology Setup](./mininetless) Example that shows how to run a small topology without using mininet
+2. [Useful Scripts](useful-scripts.md) Set of useful scripts
+3. [Simple Switch](simple-switch.md) Bmv2 Simple Switch implementation documentation
+4. [Control Plane](control-plane.md) Simple Switch Control plane documentation
+5. [Debugging and Troubleshooting](debugging-and-troubleshooting.md) Debugging and Troubleshooting guidelines
+6. [Scapy](scapy.md) Scapy Packet Manipulation library written in python
+7. [FAQ](FAQ.md) List of most asked questions from students

documentation/control-plane.md

@@ -0,0 +1,93 @@
+# Control Plane
+
+## Simple Switch CLI
+
+We can use the Simple Switch CLI to configure the switch and populate match-action tables.
+
+#### Running the CLI
+
+To get the switch CLI simply run:
+
+```bash
+simple_switch_CLI --thrift-port <port>
+```
+
+The CLI connect to the Thrift RPC server running in each switch process.
+9090 is the default value but of course if you are running several devices
+on your machine, you will need to provide a different port for each.
+One CLI instance can only connect to one switch device.
+
+#### Filling tables
+
+The most used commands to modify table contents are:
+
+  * table_set_default <table_name> <action_name> <action_parameters>
+  * table_add <table_name> <action_name> <match_fields> => <action_parameters>
+
+For example if we have the following table:
+
+```
+action drop(){
+     // drops packet
+     mark_to_drop();
+}
+
+table table_name {
+
+   action action_name(bit<8> action_parameter){
+       ...
+   }
+
+   key = {
+       standard_metadata.ingress_port: exact;
+   }
+
+   actions = {
+       drop;
+       action_name;
+   }
+```
+
+
+```bash
+table_set_default table_name drop
+table_add table_name action_name 1 => 5
+```
+
+The first command would set the default action, and action parameters (none in this case) for table `table_name`. Thus, when
+using the `table_name` table if there is no match, the drop action will be called.
+
+In the second example command adds an entry that matches if the `standard_metadata.ingress_port` is equal to 1 and executes the
+action `action_name` with `action_parameter` set to 5.
+
+#### Writing the CLI input in a file
+
+You can also populate the table writing the commands directly in a text file and then feeding the CLI:
+
+```bash
+simple_switch_CLI --thrift-port <port> < command_file.txt
+```
+
+#### Using P4 utils configuration file
+
+Alternatively, you can use the p4-utils configuration file (i.e `p4app.json`) to set a `cli` configuration
+file for each switch. When creating the topology, or rebooting switches, p4-utils will automatically use
+the file to populate and configure switches.
+
+To set default `cli` configuration files you need to define your switches like:
+
+```javascript
+    "switches": {
+      "s1": {
+        "cli_input": "<path_to_cli_commands_file>"
+      }
+    }
+```
+
+You can find all the documentation about `p4app.json` in the `p4-utils` [documentation](https://github.com/nsg-ethz/p4-utils#topology-description).
+
+
+### P4 Utils Control Plane API
+
+You can find a wrapper of the Control Plane CLI as one of the features of p4-utils. It basically allows you to do the same but instead of using text sent to
+the CLI you can use the power of a scripting language such as python. You can read more about this API [here](https://github.com/nsg-ethz/p4-utils#control-plane-api).

documentation/debugging-and-troubleshooting.md

@@ -0,0 +1,138 @@
+# Debugging and Troubleshooting
+
+### Monitoring Traffic
+
+Sniffing traffic can be a very powerful tool when debugging your P4 program. Basic things like verifying
+if traffic crosses certain path, or if header fields look like expected can be easily achieved by just
+observing traffic. For that, there is a wide range of tools that can be used:
+
+#### Pcap Files:
+
+The `simple_switch` provides an option to save all the traffic that crosses its interfaces in a pcap file. To
+enable pcap logging when starting your switch, use the `--pcap=<output_dir>` command line option. For Example:
+
+```bash
+sudo simple_switch -i 0@<iface0> -i 1@<iface1> --pcap=<output_dir> <path to JSON file>
+```
+
+Pcap logging will create several files using the following naming: `<sw_name>-<intf_num>_<in|out>.pcap`.
+
+**P4 Utils Integration**:
+
+If you enable pcap in the `p4app.json` configuration file, switches will be started with the `--pcap` option and use as output dir `./pcap`.
+
+#### Wireshark/Tshark:
+
+Another option is to observe the traffic as it flows. For that you can use tools like `tshark` and its GUI version `wireshark`. Wireshark
+is already installed in the VM, you can find its executable in the desktop.
+
+To capture traffic with tshark run:
+
+```bash
+sudo tshark -i <interface_name>
+```
+
+#### Tcpdump:
+
+Similarly, and if you prefer, you can use `tcpdump` (also already installed in the VM).
+
+To capture traffic with tcpdump run (shows link-layer information and does not resolve addresses):
+
+```bash
+sudo tcpdump -en -i <interface_name>
+```
+
+### Logging
+
+To enable logging, make sure that you enabled `--with-nanomsg` flag to `configure` before compiling `bmv2`.
+
+#### Console logging
+
+To enable console logging when starting your switch, use the `--log-console` command line option. For example:
+
+```bash
+sudo simple_switch -i 0@<iface0> -i 1@<iface1> --log-console <path to JSON file>
+```
+
+This will print all the messages in the terminal. Since this is not the most convenient, you can always redirect
+it to a log file:
+
+```bash
+sudo simple_switch -i 0@<iface0> -i 1@<iface1> --log-console <path to JSON file> >/path_to_file/sw.log
+```
+
+#### P4 Utils Integration
+
+If you enable logging in the `p4app.json` configuration file, switches will automatically write all the console logging
+into a file in the `./log` directory and with `<sw_name>.log`.
+
+#### CLI logging
+
+If logging is enabled, and you use the `simple_switch_CLI` when starting the topology (with `p4utils`) the output
+of the `cli` will be also logged in the log folder under the name `<sw_name>_cli_output.log`
+
+#### Event logging
+
+To enable event logging when starting your switch, use the *--nanolog* command
+line option. For example, to use the ipc address *ipc:///tmp/bm-log.ipc*:
+
+    sudo ./simple_switch -i 0@<iface0> -i 1@<iface1> --nanolog ipc:///tmp/bm-log.ipc <path to JSON file>
+
+Use [tools/nanomsg_client.py](https://github.com/p4lang/behavioral-model/blob/master/tools/nanomsg_client.py) as follows when the
+switch is running:
+
+    sudo ./nanomsg_client.py [--thrift-port <port>]
+
+The script will display events of significance (table hits / misses, parser
+transitions, ...) for each packet.
+
+When using `P4 utils` to create the topology, each switch will automatically get assigned with a
+`thrift-port`. There are several ways to find the mapping between switch and port, but the easiest is
+to check the `print` messages displayed by `p4run`. Try to find a line that looks like:
+
+```bash
+s1 -> Thrift port: 9090
+```
+
+### Debugger
+
+To enable the debugger, make sure that you passed the `--enable-debugger` flag
+to `configure`. You will also need to use the `--debugger` command line flag
+when starting the switch.
+
+Use [tools/p4dbg.py](https://github.com/p4lang/behavioral-model/blob/master/tools/p4dbg.py) as follows when the switch is running to
+attach the debugger to the switch:
+
+    sudo ./p4dbg.py [--thrift-port <port>]
+
+You can find a P4 debugger user guide in the bmv2
+ [docs](https://github.com/p4lang/behavioral-model/blob/master/docs/p4dbg_user_guide.md).
+
+### Attaching Information to a Packet
+
+Some times you do not want to use the logging system or debugger, or basically they are disabled. Yet, you could still
+get some insights on what the code does by just modifying a header field depending on which part of the code
+gets executed and check that value when the packet leaves the switch. Of course you can do something more sophisticated, and
+and use several fields, read the value of a register and save it in the header, and so on.
+
+### If the above did not solve your problem:
+
+P4, and all the tools around are quite new. Several times things just do not work
+because there is a bug in the compiler or in the software switch implementation.
+
+1. First of all, check what the [P4-16 specification](https://p4.org/p4-spec/docs/P4-16-v1.0.0-spec.html) says about that. The specification
+is quite generic and not always will be able to give you a direct answer about what should be
+the expected behaviour of some 'Action', since the answer can be completely related to what a
+specific switch implementation does (in our case the bmv2 simple switch).
+
+2. Check the `p4-org` mailing list. Probably you are not the first one having this problem, and someone
+already asked what you need in the mailing list. A good trick to get only results from the mailing list when
+googling them is to write your query as follows : `site:http://lists.p4.org/ <query>`. If you type in google
+`site:http://lists.p4.org/ "simple_switch"` you will get all the threads where the word `simple_switch` appears.
+
+3. Check the `github` issues section of [`bmv2`](https://github.com/p4lang/behavioral-model/issues)
+and [`p4c`](https://github.com/p4lang/p4c/issues) repositories. By default the searching bar adds a `is:issue is:open`
+filter, you can just remove it and write a `keyword` to find information about the issue and how to solve it.
+
+4. If you do not find the solution anywhere, you can write in the mailing list yourself, or open an issue
+in github.