Reorganize examples into subdirectories

Examples directory has been growing, so add a bit of organization. Signed-off-by: Brenden Blanco <bblanco@plumgrid.com>
egggHang · Nov 4, 2015 · c43e990 · c43e990
1 parent 7a31b18
commit c43e990
Show file tree

Hide file tree

Showing 47 changed files with 135 additions and 52 deletions.
diff --git a/SPECS/bcc.spec b/SPECS/bcc.spec
@@ -70,3 +70,5 @@ Python bindings for BPF Compiler Collection (BCC)
 %exclude /usr/share/bcc/examples/*.pyo
 %exclude /usr/share/bcc/examples/*/*.pyc
 %exclude /usr/share/bcc/examples/*/*.pyo
+%exclude /usr/share/bcc/examples/*/*/*.pyc
+%exclude /usr/share/bcc/examples/*/*/*.pyo
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
@@ -1,5 +1,5 @@
-set(EXAMPLE_FILES hello_world.py task_switch.py task_switch.c simple_tc.py
-                  simulation.py vlan_learning.py vlan_learning.c)
-install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples)
+set(EXAMPLE_PROGRAMS hello_world.py)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples)
 
-add_subdirectory(distributed_bridge)
+add_subdirectory(networking)
+add_subdirectory(tracing)
diff --git a/examples/distributed_bridge/CMakeLists.txt b/examples/distributed_bridge/CMakeLists.txt
diff --git a/examples/networking/CMakeLists.txt b/examples/networking/CMakeLists.txt
@@ -0,0 +1,8 @@
+set(EXAMPLE_FILES simulation.py)
+set(EXAMPLE_PROGRAMS simple_tc.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/networking)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/networking)
+
+add_subdirectory(distributed_bridge)
+add_subdirectory(neighbor_sharing)
+add_subdirectory(vlan_learning)
diff --git a/examples/networking/distributed_bridge/CMakeLists.txt b/examples/networking/distributed_bridge/CMakeLists.txt
@@ -0,0 +1,4 @@
+set(EXAMPLE_FILES simulation.py tunnel.c tunnel_mesh.c)
+set(EXAMPLE_PROGRAMS main.py tunnel_mesh.py tunnel.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/networking/distributed_bridge)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/networking/distributed_bridge)
diff --git a/examples/distributed_bridge/main.py → ...les/networking/distributed_bridge/main.py b/examples/distributed_bridge/main.py → ...les/networking/distributed_bridge/main.py
diff --git a/examples/distributed_bridge/simulation.py → ...tworking/distributed_bridge/simulation.py b/examples/distributed_bridge/simulation.py → ...tworking/distributed_bridge/simulation.py
diff --git a/examples/distributed_bridge/tunnel.c → ...es/networking/distributed_bridge/tunnel.c b/examples/distributed_bridge/tunnel.c → ...es/networking/distributed_bridge/tunnel.c
diff --git a/examples/distributed_bridge/tunnel.py → ...s/networking/distributed_bridge/tunnel.py b/examples/distributed_bridge/tunnel.py → ...s/networking/distributed_bridge/tunnel.py
diff --git a/examples/distributed_bridge/tunnel_mesh.c → ...tworking/distributed_bridge/tunnel_mesh.c b/examples/distributed_bridge/tunnel_mesh.c → ...tworking/distributed_bridge/tunnel_mesh.c
diff --git a/examples/distributed_bridge/tunnel_mesh.py → ...working/distributed_bridge/tunnel_mesh.py b/examples/distributed_bridge/tunnel_mesh.py → ...working/distributed_bridge/tunnel_mesh.py
diff --git a/examples/networking/neighbor_sharing/CMakeLists.txt b/examples/networking/neighbor_sharing/CMakeLists.txt
@@ -0,0 +1,4 @@
+set(EXAMPLE_FILES README.txt simulation.py tc_neighbor_sharing.c)
+set(EXAMPLE_PROGRAMS tc_neighbor_sharing.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/networking/neighbor_sharing)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/networking/neighbor_sharing)
diff --git a/examples/networking/neighbor_sharing/README.txt b/examples/networking/neighbor_sharing/README.txt
@@ -0,0 +1,57 @@
+This example shows how a combination of BPF programs can be used to perform
+per-IP classification and rate limiting. The simulation in this example
+shows an example where N+M devices are combined and use 1 WAN. Traffic sent
+from/to the "neighbor" devices have their combined bandwidth capped at
+128kbit, and the rest of the traffic can use an additional 1Mbit.
+
+This works by sharing a map between various tc ingress filters, each with
+a related set of bpf functions attached. The map stores a list of dynamically
+learned ip addresses that were seen on the neighbor devices and should be
+throttled.
+
+                         /------------\                        |
+neigh1 --|->->->->->->->-|            |                        |
+neigh2 --|->->->->->->->-|    <-128kb-|        /------\        |
+neigh3 --|->->->->->->->-|            |  wan0  | wan  |        |
+         | ^             |   br100    |-<-<-<--| sim  |        |
+         | clsfy_neigh() |            |   ^    \------/        |
+lan1 ----|->->->->->->->-|    <--1Mb--|   |                    |
+lan2 ----|->->->->->->->-|            |   classify_wan()       |
+           ^             \------------/                        |
+           pass()                                              |
+
+To run the example:
+
+$ sudo /path/to/neighbor_sharing/neighbor_sharing.py
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Starting netserver with host 'IN(6)ADDR_ANY' port '12865' and family AF_UNSPEC
+Network ready. Create a shell in the wan0 namespace and test with netperf
+   (Neighbors are 172.16.1.100-102, and LAN clients are 172.16.1.150-151)
+ e.g.: ip netns exec wan0 netperf -H 172.16.1.100 -l 2
+Press enter when finished:
+
+
+In another shell:
+$ sudo ip netns exec wan0 netperf -H 172.16.1.100 -l 2
+MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 172.16.1.100 () port 0 AF_INET : demo
+Recv   Send    Send
+Socket Socket  Message  Elapsed
+Size   Size    Size     Time     Throughput
+bytes  bytes   bytes    secs.    10^6bits/sec
+
+ 87380  16384  16384    4.30        0.18
+
+$ sudo ip netns exec wan0 netperf -H 172.16.1.150 -l 2
+MIGRATED TCP STREAM TEST from 0.0.0.0 (0.0.0.0) port 0 AF_INET to 172.16.1.150 () port 0 AF_INET : demo
+Recv   Send    Send
+Socket Socket  Message  Elapsed
+Size   Size    Size     Time     Throughput
+bytes  bytes   bytes    secs.    10^6bits/sec
+
+ 87380  16384  16384    4.10        1.01
+
+
+The bandwidth is throttled according to the IP.
diff --git a/examples/tunnel_monitor/simulation.py → ...networking/neighbor_sharing/simulation.py b/examples/tunnel_monitor/simulation.py → ...networking/neighbor_sharing/simulation.py
diff --git a/examples/tc_neighbor_sharing.c → ...ng/neighbor_sharing/tc_neighbor_sharing.c b/examples/tc_neighbor_sharing.c → ...ng/neighbor_sharing/tc_neighbor_sharing.c
diff --git a/examples/tc_neighbor_sharing.py → ...g/neighbor_sharing/tc_neighbor_sharing.py b/examples/tc_neighbor_sharing.py → ...g/neighbor_sharing/tc_neighbor_sharing.py
@@ -2,29 +2,6 @@
 # Copyright (c) PLUMgrid, Inc.
 # Licensed under the Apache License, Version 2.0 (the "License")
 
-# This example shows how a combination of BPF programs can be used to perform
-# per-IP classification and rate limiting. The simulation in this example
-# shows an example where N+M devices are combined and use 1 WAN. Traffic sent
-# from/to the "neighbor" devices have their combined bandwidth capped at
-# 128kbit, and the rest of the traffic can use an additional 1Mbit.
-
-# This works by sharing a map between various tc ingress filters, each with
-# a related set of bpf functions attached. The map stores a list of dynamically
-# learned ip addresses that were seen on the neighbor devices and should be
-# throttled.
-
-#                          /------------\                        |
-# neigh1 --|->->->->->->->-|            |                        |
-# neigh2 --|->->->->->->->-|    <-128kb-|        /------\        |
-# neigh3 --|->->->->->->->-|            |  wan0  | wan  |        |
-#          | ^             |   br100    |-<-<-<--| sim  |        |
-#          | clsfy_neigh() |            |   ^    \------/        |
-# lan1 ----|->->->->->->->-|    <--1Mb--|   |                    |
-# lan2 ----|->->->->->->->-|            |   classify_wan()       |
-#            ^             \------------/                        |
-#            pass()                                              |
-
-
 from bcc import BPF
 from pyroute2 import IPRoute, NetNS, IPDB, NSPopen
 from simulation import Simulation

diff --git a/examples/simple_tc.py → examples/networking/simple_tc.py b/examples/simple_tc.py → examples/networking/simple_tc.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/python
 # Copyright (c) PLUMgrid, Inc.
 # Licensed under the Apache License, Version 2.0 (the "License")
 

diff --git a/examples/simulation.py → examples/networking/simulation.py b/examples/simulation.py → examples/networking/simulation.py
diff --git a/examples/tunnel_monitor/README.md → examples/networking/tunnel_monitor/README.md b/examples/tunnel_monitor/README.md → examples/networking/tunnel_monitor/README.md
diff --git a/examples/tunnel_monitor/chord.png → examples/networking/tunnel_monitor/chord.png b/examples/tunnel_monitor/chord.png → examples/networking/tunnel_monitor/chord.png
diff --git a/examples/tunnel_monitor/main.py → examples/networking/tunnel_monitor/main.py b/examples/tunnel_monitor/main.py → examples/networking/tunnel_monitor/main.py
diff --git a/examples/tunnel_monitor/monitor.c → examples/networking/tunnel_monitor/monitor.c b/examples/tunnel_monitor/monitor.c → examples/networking/tunnel_monitor/monitor.c
diff --git a/examples/tunnel_monitor/monitor.py → ...ples/networking/tunnel_monitor/monitor.py b/examples/tunnel_monitor/monitor.py → ...ples/networking/tunnel_monitor/monitor.py
diff --git a/examples/tunnel_monitor/setup.sh → examples/networking/tunnel_monitor/setup.sh b/examples/tunnel_monitor/setup.sh → examples/networking/tunnel_monitor/setup.sh
diff --git a/examples/networking/tunnel_monitor/simulation.py b/examples/networking/tunnel_monitor/simulation.py
@@ -0,0 +1 @@
+../simulation.py
diff --git a/examples/tunnel_monitor/traffic.sh → ...ples/networking/tunnel_monitor/traffic.sh b/examples/tunnel_monitor/traffic.sh → ...ples/networking/tunnel_monitor/traffic.sh
diff --git a/examples/tunnel_monitor/vxlan.jpg → examples/networking/tunnel_monitor/vxlan.jpg b/examples/tunnel_monitor/vxlan.jpg → examples/networking/tunnel_monitor/vxlan.jpg
diff --git a/examples/networking/vlan_learning/CMakeLists.txt b/examples/networking/vlan_learning/CMakeLists.txt
@@ -0,0 +1,4 @@
+set(EXAMPLE_FILES README.txt simulation.py vlan_learning.c)
+set(EXAMPLE_PROGRAMS vlan_learning.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/networking/vlan_learning)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/networking/vlan_learning)
diff --git a/examples/networking/vlan_learning/README.txt b/examples/networking/vlan_learning/README.txt
@@ -0,0 +1,43 @@
+This example shows a unique way to use a BPF program to demux any ethernet
+traffic into a pool of worker veth+namespaces (or any ifindex-based
+destination) depending on a configurable mapping of src-mac to ifindex. As
+part of the ingress processing, the program will dynamically learn the source
+ifindex of the matched source mac.
+
+Simulate a physical network with a vlan aware switch and clients that may
+connect to any vlan. The program will detect the known clients and pass the
+traffic through to a dedicated namespace for processing. Clients may have
+overlapping IP spaces and the traffic will still work.
+
+               |           bpf program                      |
+cli0 --|       |                            /--|-- worker0  |
+cli1 --| trunk | +->--->-handle_p2v(pkt)-> /---|-- worker1  |
+cli2 --|=======|=+                        /----|-- worker2  |
+...  --|       | +-<---<-handle_v2p(pkt)-<-----|--  ...     |
+cliN --|       |                          \----|-- workerM  |
+       |       |                              ^             |
+     phys      |                            veth            |
+    switch     |                                            |
+
+To run the example, simply:
+
+sudo /path/to/vlan_learning/vlan_learning.py
+
+Serving HTTP on 0.0.0.0 port 80 ...
+Serving HTTP on 0.0.0.0 port 80 ...
+Serving HTTP on 0.0.0.0 port 80 ...
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0172.16.1.100 - - [04/Nov/2015 10:54:47] "GET / HTTP/1.1" 200 -
+100   574  100   574    0     0  45580      0 --:--:-- --:--:-- --:--:-- 47833
+
+...
+
+Press enter to exit:
+mac 020000000000 rx pkts = 95, rx bytes = 7022
+                 tx pkts = 0, tx bytes = 0
+mac 020000000001 rx pkts = 95, rx bytes = 7022
+                 tx pkts = 0, tx bytes = 0
+mac 020000000002 rx pkts = 97, rx bytes = 7154
+                 tx pkts = 0, tx bytes = 0
+
diff --git a/examples/networking/vlan_learning/simulation.py b/examples/networking/vlan_learning/simulation.py
@@ -0,0 +1 @@
+../simulation.py
diff --git a/examples/vlan_learning.c → .../networking/vlan_learning/vlan_learning.c b/examples/vlan_learning.c → .../networking/vlan_learning/vlan_learning.c
diff --git a/examples/vlan_learning.py → ...networking/vlan_learning/vlan_learning.py b/examples/vlan_learning.py → ...networking/vlan_learning/vlan_learning.py
@@ -2,27 +2,6 @@
 # Copyright (c) PLUMgrid, Inc.
 # Licensed under the Apache License, Version 2.0 (the "License")
 
-# This example shows a unique way to use a BPF program to demux any ethernet
-# traffic into a pool of worker veth+namespaces (or any ifindex-based
-# destination) depending on a configurable mapping of src-mac to ifindex. As
-# part of the ingress processing, the program will dynamically learn the source
-# ifindex of the matched source mac.
-
-# Simulate a physical network with a vlan aware switch and clients that may
-# connect to any vlan. The program will detect the known clients and pass the
-# traffic through to a dedicated namespace for processing. Clients may have
-# overlapping IP spaces and the traffic will still work.
-
-#                |           bpf program                      |
-# cli0 --|       |                            /--|-- worker0  |
-# cli1 --| trunk | +->--->-handle_p2v(pkt)-> /---|-- worker1  |
-# cli2 --|=======|=+                        /----|-- worker2  |
-# ...  --|       | +-<---<-handle_v2p(pkt)-<-----|--  ...     |
-# cliN --|       |                          \----|-- workerM  |
-#        |       |                              ^             |
-#      phys      |                            veth            |
-#     switch     |                                            |
-
 from bcc import BPF
 from builtins import input
 from pyroute2 import IPRoute, NetNS, IPDB, NSPopen

diff --git a/examples/tracing/CMakeLists.txt b/examples/tracing/CMakeLists.txt
@@ -0,0 +1,6 @@
+set(EXAMPLE_FILES bitehist.c bitehist_example.txt disksnoop.c
+  disksnoop_example.txt task_switch.c tcpv4connect tcpv4connect_example.txt
+  vfsreadlat.c vfsreadlat_example.txt)
+set(EXAMPLE_PROGRAMS bitehist.py disksnoop.py task_switch.py trace_fields.py vfsreadlat.py)
+install(FILES ${EXAMPLE_FILES} DESTINATION share/bcc/examples/tracing)
+install(PROGRAMS ${EXAMPLE_PROGRAMS} DESTINATION share/bcc/examples/tracing)
diff --git a/examples/bitehist.c → examples/tracing/bitehist.c b/examples/bitehist.c → examples/tracing/bitehist.c
diff --git a/examples/bitehist.py → examples/tracing/bitehist.py b/examples/bitehist.py → examples/tracing/bitehist.py
diff --git a/examples/bitehist_example.txt → examples/tracing/bitehist_example.txt b/examples/bitehist_example.txt → examples/tracing/bitehist_example.txt
diff --git a/examples/disksnoop.c → examples/tracing/disksnoop.c b/examples/disksnoop.c → examples/tracing/disksnoop.c
diff --git a/examples/disksnoop.py → examples/tracing/disksnoop.py b/examples/disksnoop.py → examples/tracing/disksnoop.py
diff --git a/examples/disksnoop_example.txt → examples/tracing/disksnoop_example.txt b/examples/disksnoop_example.txt → examples/tracing/disksnoop_example.txt
diff --git a/examples/task_switch.c → examples/tracing/task_switch.c b/examples/task_switch.c → examples/tracing/task_switch.c
diff --git a/examples/task_switch.py → examples/tracing/task_switch.py b/examples/task_switch.py → examples/tracing/task_switch.py
diff --git a/examples/tcpv4connect → examples/tracing/tcpv4connect b/examples/tcpv4connect → examples/tracing/tcpv4connect
diff --git a/examples/tcpv4connect_example.txt → examples/tracing/tcpv4connect_example.txt b/examples/tcpv4connect_example.txt → examples/tracing/tcpv4connect_example.txt
diff --git a/examples/trace_fields.py → examples/tracing/trace_fields.py b/examples/trace_fields.py → examples/tracing/trace_fields.py
diff --git a/examples/vfsreadlat.c → examples/tracing/vfsreadlat.c b/examples/vfsreadlat.c → examples/tracing/vfsreadlat.c
diff --git a/examples/vfsreadlat.py → examples/tracing/vfsreadlat.py b/examples/vfsreadlat.py → examples/tracing/vfsreadlat.py
diff --git a/examples/vfsreadlat_example.txt → examples/tracing/vfsreadlat_example.txt b/examples/vfsreadlat_example.txt → examples/tracing/vfsreadlat_example.txt