Skip to content

Commit 937b27e

Browse files
author
Stefan Burnicki
committed
Added a detailed documentation for remote traffic shaping
1 parent eb40e02 commit 937b27e

File tree

2 files changed

+114
-7
lines changed

2 files changed

+114
-7
lines changed

‎docs/install.md

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -55,13 +55,7 @@ wptagent currently supports Windows, Linux and OSX for desktop browsers as well
5555
* ```sudo npm install -g lighthouse```
5656

5757
## Remote traffic-shaping
58-
wptagent supports configuring an external FreeBSD network bridge for traffic-shaping. This is particularly useful for mobile device testing where the devices can be connected to a WiFi access point and the access point is connected through a FreeBSD bridge to get to the network.
59-
60-
i.e. mobile phone <--> WiFi <--> FreeBSD bridge <--> Internet
61-
62-
In this configuration the mobile devices are given static IP addresses and the FreeBSD bridge is pre-configured with 2 dummynet pipes for each IP address (one for inbound and one for outbound traffic). The root account needs to allow for cert-based ssh access from the test machine (with the cert installed in authorized_keys).
63-
64-
Passing the agent a "--shaper external" command-line flag you give it the IP address of the FreeBSD bridge as well as the pipe numbers for inbound and outbound traffic for the device. At test time the agent will ssh to the bridge and adjust the settings for the device as needed.
58+
wptagent supports configuring an external FreeBSD network bridge for traffic-shaping. This is particularly useful for mobile device testing. For further details, see the [remote traffic shaping documentation](./remote_trafficshaping.md).
6559

6660
## OS Notes
6761
### Linux

‎docs/remote_trafficshaping.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Remote traffic-shaping
2+
wptagent supports configuring an external FreeBSD network bridge for traffic-shaping. This is particularly useful for mobile device testing where the devices can be connected to a WiFi access point and the access point is connected through a FreeBSD bridge to get to the network.
3+
4+
i.e. mobile devices <--> WiFi Access Point <--> FreeBSD bridge <--> Internet
5+
6+
In this configuration the mobile devices are given static IP addresses and the FreeBSD bridge is pre-configured with 2 dummynet pipes for each IP address (one for inbound and one for outbound traffic). The root account needs to allow for cert-based ssh access from the test machine (with the cert installed in authorized_keys).
7+
8+
Passing the agent a "--shaper remote" command-line flag you give it the IP address of the FreeBSD bridge as well as the pipe numbers for inbound and outbound traffic for the device (see below). At test time the agent will ssh to the bridge and adjust the settings for the device as needed.
9+
10+
## Basic setup
11+
12+
You can probably use any device with two network interfaces.
13+
14+
* Install FreeBSD
15+
* Optional: Set you keyboard layout by running `kbdmap` and adding the result output (i.e. `keymap="de.noacc.kbd"`) to `/etc/rc.conf`.
16+
* Enable sshd by adding `sshd_enable="YES"` to `/etc/rc.conf`
17+
* Enable SSH root login by adding `PermitRootLogin yes` to `/etc/ssh/sshd_config`
18+
* Install your SSH key(s) by adding the public keys to `/root/.ssh/authorized_keys`
19+
* Make sure dummynet is loaded on startup by adding the following lines to `/boot/loader.conf`:
20+
```
21+
if_bridge_load="YES"
22+
dummynet_load="YES"
23+
```
24+
25+
## Bridge setup
26+
27+
Check the names of your network interfaces by running `ifconfig` in this documentation they are called `re0` and `re1`, so you need change this to you actual interface names in all code below.
28+
29+
The WiFi access point is connected to `re0`.
30+
The main network is connected to `re1`. We want re1 to get an IP via DHCP.
31+
32+
Add the following lines to `/etc/rc.conf`:
33+
```
34+
#BRIDGE CONFIG. re0 and re1 are both ethernet devices
35+
# re1 is connected to main network
36+
cloned_interfaces="bridge0"
37+
ifconfig_bridge0="addm re0 addm re1 up"
38+
# use dhcp for the ethernet device linked to the actual router (re1)
39+
ifconfig_re1="DHCP up"
40+
ifconfig_re0="up"
41+
42+
#IPFW Config (includes pipe definitions used for traffic shaping)
43+
firewall_enable="YES"
44+
firewall_type="open"
45+
firewall_script="/etc/ipfw.rules"
46+
```
47+
48+
If you **don't** want to use DHCP but a static IP for the bridge, you need to exchange the line `ifconfig_re1="DHCP up"` by a configuration like this:
49+
```
50+
ifconfig_re1="inet 192.168.1.3 netmask 255.255.255.0"
51+
defaultrouter="192.168.1.1"
52+
nameserver 192.168.1.1
53+
```
54+
55+
## Dummynet pipe setup
56+
The last line in `/etc/rc.conf` attempts to load ipfw rules from `/etc/ipfw.rules` which should include the pipe definitions that can be used for actual traffic shaping:
57+
58+
```
59+
subnet=192.168.201
60+
interface=re0
61+
62+
ipfw -q flush
63+
ipfw -q pipe flush
64+
65+
# SSH traffic to bypass shaping
66+
ipfw add skipto 60000 proto tcp src-port 22
67+
ipfw add skipto 60000 proto tcp dst-port 22
68+
# disable bootstrap traffic from outside to bridged devices
69+
ipfw add deny ip from any to any bootps via re0
70+
71+
# Static pipes assigned by IP address to the $subnet.x subnet
72+
for i in `seq 2 9`
73+
do
74+
ipfw pipe $i config delay 0ms noerror
75+
ipfw pipe 30$i config delay 0ms noerror
76+
ipfw queue $i config pipe $i queue 100 noerror mask dst-port 0xffff
77+
ipfw queue 30$i config pipe 30$i queue 100 noerror mask src-port 0xffff
78+
ipfw add queue $i ip from any to $subnet.$i out xmit $interface
79+
ipfw add queue 30$i ip from $subnet.$i to any out recv $interface
80+
done
81+
for i in `seq 10 90`
82+
do
83+
ipfw pipe $i config delay 0ms noerror
84+
ipfw pipe 3$i config delay 0ms noerror
85+
ipfw queue $i config pipe $i queue 100 noerror mask dst-port 0xffff
86+
ipfw queue 3$i config pipe 3$i queue 100 noerror mask src-port 0xffff
87+
ipfw add queue $i ip from any to $subnet.$i out xmit $interface
88+
ipfw add queue 3$i ip from $subnet.$i to any out recv $interface
89+
done
90+
91+
ipfw add 60000 pass all from any to any
92+
```
93+
94+
First, make sure that you that you correctly define the variables:
95+
* `$interface` (in this case `re0`) is the interface name connected to the WiFi access point
96+
* `$subnet` (in this case `192.168.201`) is the subnet of all mobile devices with static IPs
97+
98+
The logic in this file first allow unshaped traffic for SSH access and prevents any bootstrap traffic (e.g. for DHCP) from outside to the mobile devices.
99+
100+
The main logic is in the loop where it sets up pipes 2-90 and 302-390 as matched pairs and assigns each one of them to traffic going to each of the static IP addresses 192.168.201.2 through 192.168.201.90.
101+
102+
Pipes 2-90 are the inbound pipes for each of the phones and 302-390 are the outbound pipes. This allows to keep the configuration to be unchanged for up to 89 devices.
103+
104+
## WPT agent setup
105+
106+
Make sure each agent that uses external traffic shaping has it's ssh key installed on the FreeBSD bridge, so it can access the bridge with root privileges via SSH.
107+
108+
Assign a static IP in the subnet defined in the pipe setup to the **testing device** whose traffic should be shaped (not the agent itself when using mobile devices!).
109+
110+
Start the WPT agent with the argument `--shaper remote,<bridge address>,<down pipe>,<up pipe>`.
111+
112+
*Example:* If the hostname your free BSD bridge is `wpt-trafficshaper` and the static IP of the mobile device is `192.168.201.5`, the IPFW configuration automatically assigned the pipes `5` and `305` to `192.168.201.5` for inbound and outbound traffic.
113+
Therefore you need to start the wpt agent with `--shaper remote,wpt-trafficshaper,5,305`

0 commit comments

Comments
 (0)