1# Prerequisites
2* A Mac running OS X 10.6 ("Snow Leopard") or Linux (tested with Ubuntu
3Lucid). Support for Windows is still experimental
4* [Python 2.6](http://www.python.org/download/releases/2.6.6/)
5
6# Install
7Only do this the first time.
8
91. Open the Terminal application and download the source.
10```
11$ git clone https://github.com/chromium/web-page-replay.git
12```
132. Move to the newly created directory.
14```
15$ cd web-page-replay
16```
17## Linux-specific install steps
18On Linux, Dummynet must be installed to simulate network conditions.
19
201. For the Linux code, try downloading the [latest linux sources from Marta
21Carbone](http://info.iet.unipi.it/~marta/dummynet/). These are more up-to-date than what is found on the [Dummynet
22homepage](http://info.iet.unipi.it/~luigi/dummynet/).
232. Build and install:
24```
25$ tar -C /tmp -xvzf ipfw3-20120119.tgz
26$ cd /tmp/ipfw3-20120119
27$ make
28[Ignore output like the following:]
29        echo "  ERROR: Kernel configuration is invalid.";\
30        echo "         include/generated/autoconf.h or
31include/config/auto.conf are missing.";\
32        echo "         Run 'make oldconfig && make prepare' on kernel
33src to fix it.";\
34[The lines will print without "echo" if there is an actual error.]
35$ sudo insmod dummynet2/ipfw_mod.ko
36$ sudo cp ipfw/ipfw /usr/local/sbin
37```
383. To remove it later
39```
40$ sudo rmmod ipfw_mod.ko
41```
42## Windows-specific install steps
43*Windows support is experimental and not well tested.* On Windows XP, the
44Dummynet driver must be installed to simulate network conditions
45(Drivers for Windows Vista and Windows 7 are currently unavailable).
46
471. Control Panel -> Network Connections -> Right-click adapter in use ->
48select Properties
492. Click Install... -> Service -> Add... -> Have Disk...
503. Browse... ->
51web-page-replay-read-only\third_party\ipfw_win32\netipfw.inf
524. Click Open -> Ok -> Ok
53  - Accept any warnings for installing an unknown driver
54
55# Record
56First you must record the web page or pages that you wish to replay.
57
581. Open the web browser you wish to use and clear its cache so that all
59resources will be requested from the network.
602. Switch to the Terminal application and start the program in record mode.
61All HTTP requests performed on the machine while it is running will be
62saved into the archive.
63```
64$ sudo ./replay.py --record ~/archive.wpr
65```
663. Load the web page or pages in the open web browser. Be sure to wait
67until each is fully loaded.
684. Stop recording by killing the replay.py process with Ctrl+c. The archive
69will be saved to ~/archive.wpr.
70
71# Replay
72After you have created an archive, you may later replay it at any time.
73
741. Start the program in replay mode with a previously recorded archive.
75```
76$ sudo ./replay.py ~/archive.wpr
77```
782. Load recorded pages in a web browser. A 404 will be served for any pages
79or resources not in the recorded archive.
803. Stop replaying by killing the replay.py process with Ctrl+c.
81
82## Network simulation examples
83During replay, you may simulate desired network conditions. This is
84useful for benchmarking.
85
86* 128KByte/s uplink bandwidth, 4Mbps/s downlink bandwidth with 100ms RTT
87time
88```
89$ sudo ./replay.py --up 128KByte/s --down 4Mbit/s --delay_ms=100 archive.wpr
90```
91* 1% packet loss rate
92```
93$ sudo ./replay.py --packet_loss_rate=0.01 ~/archive.wpr
94```
95
96## Using browser proxy settings
97You may choose to disable the forwarding of DNS requests to the local
98replay server. If DNS request forwarding is disabled, an external
99mechanism must be used to forward traffic to the replay server.
100
101* Disable DNS forwarding
102```
103$ ./replay.py --no-dns_forwarding --record ~/archive.wpr
104```
105* Forwarding traffic to replay server (via Google Chrome on linux)
1061. Go to Chrome Preferences -> Under the Hood -> Change Proxy Settings
1072. Under Manual Proxy configuration -> HTTP proxy, enter 127.0.0.1 for IP
108and the port that web page replay is configured to listen to (default
10980).
110
111Alternatively, traffic forwarding may also be configured via command
112line flags.
113```
114$ google-chrome --host-resolver-rules="MAP * 127.0.0.1:80,EXCLUDE localhost"
115```
116
117# HTTPS/SSL support
118By default, Web Page Replay, creates a self-signed certificate to serve
119SSL traffic. In order for it to work, browsers need to be configured to
120ignore certificate errors. Be aware that doing so opens a giant security
121hole.
122
123```
124$ google-chrome --ignore-certificate-errors
125```
126
127Firefox has [a configuration file for
128exceptions](https://developer.mozilla.org/En/Cert_override.txt). That requires listing
129each host that gets used. If you have a better solution, please add it
130to the comments below. IE and Safari options are also needed.
131
132To turn off SSL support, run replay.py with "--no-ssl".
133
134# Troubleshooting
135
136## Permission errors
137
138On Linux, either of the following two errors are permission problems:
139
140```
141python: can't open file './replay.py': [Errno 13] Permission denied
142```
143```
144Traceback (most recent call last):
145  File "./replay.py", line 50, in <module>
146    import dnsproxy
147  File "/home/slamm/p/wpr/dnsproxy.py", line 19, in <module>
148    import platformsettings
149ImportError: No module named platformsettings
150```
151This can happen if you checkout the files to an NFS directory. Either
152move the files to a local directory, or make them world
153readable/executable.
154
155## Unable to access auto mounted directories
156WPR can cause autofs to hang. On Ubuntu, the following command fixes it:
157
158```
159$ sudo restart autofs
160```
161
162# Help
163
164For full usage instructions and advanced options, see the program's
165help.
166
167```
168$ ./replay.py --help
169```
170