tools/telemetry/third_party/webpagereplay/documentation/GettingStarted.md

   1 # Prerequisites
   2 * A Mac running OS X 10.6 ("Snow Leopard") or Linux (tested with Ubuntu
   3 Lucid). Support for Windows is still experimental
   4 * [Python 2.6](http://www.python.org/download/releases/2.6.6/)
   5
   6 # Install
   7 Only do this the first time.
   8
   9 1. Open the Terminal application and download the source.
  10 ```
  11 $ git clone https://github.com/chromium/web-page-replay.git
  12 ```
  13 2. Move to the newly created directory.
  14 ```
  15 $ cd web-page-replay
  16 ```
  17 ## Linux-specific install steps
  18 On Linux, Dummynet must be installed to simulate network conditions.
  19
  20 1. For the Linux code, try downloading the [latest linux sources from Marta
  21 Carbone](http://info.iet.unipi.it/~marta/dummynet/). These are more up-to-date than what is found on the [Dummynet
  22 homepage](http://info.iet.unipi.it/~luigi/dummynet/).
  23 2. 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
  31 include/config/auto.conf are missing.";\
  32         echo "         Run 'make oldconfig && make prepare' on kernel
  33 src 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 ```
  38 3. 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
  44 Dummynet driver must be installed to simulate network conditions
  45 (Drivers for Windows Vista and Windows 7 are currently unavailable).
  46
  47 1. Control Panel -> Network Connections -> Right-click adapter in use ->
  48 select Properties
  49 2. Click Install... -> Service -> Add... -> Have Disk...
  50 3. Browse... ->
  51 web-page-replay-read-only\third_party\ipfw_win32\netipfw.inf
  52 4. Click Open -> Ok -> Ok
  53   - Accept any warnings for installing an unknown driver
  54
  55 # Record
  56 First you must record the web page or pages that you wish to replay.
  57
  58 1. Open the web browser you wish to use and clear its cache so that all
  59 resources will be requested from the network.
  60 2. Switch to the Terminal application and start the program in record mode.
  61 All HTTP requests performed on the machine while it is running will be
  62 saved into the archive.
  63 ```
  64 $ sudo ./replay.py --record ~/archive.wpr
  65 ```
  66 3. Load the web page or pages in the open web browser. Be sure to wait
  67 until each is fully loaded.
  68 4. Stop recording by killing the replay.py process with Ctrl+c. The archive
  69 will be saved to ~/archive.wpr.
  70
  71 # Replay
  72 After you have created an archive, you may later replay it at any time.
  73
  74 1. Start the program in replay mode with a previously recorded archive.
  75 ```
  76 $ sudo ./replay.py ~/archive.wpr
  77 ```
  78 2. Load recorded pages in a web browser. A 404 will be served for any pages
  79 or resources not in the recorded archive.
  80 3. Stop replaying by killing the replay.py process with Ctrl+c.
  81
  82 ## Network simulation examples
  83 During replay, you may simulate desired network conditions. This is
  84 useful for benchmarking.
  85
  86 * 128KByte/s uplink bandwidth, 4Mbps/s downlink bandwidth with 100ms RTT
  87 time
  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
  97 You may choose to disable the forwarding of DNS requests to the local
  98 replay server. If DNS request forwarding is disabled, an external
  99 mechanism 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)
 106 1. Go to Chrome Preferences -> Under the Hood -> Change Proxy Settings
 107 2. Under Manual Proxy configuration -> HTTP proxy, enter 127.0.0.1 for IP
 108 and the port that web page replay is configured to listen to (default
 109 80).
 110
 111 Alternatively, traffic forwarding may also be configured via command
 112 line flags.
 113 ```
 114 $ google-chrome --host-resolver-rules="MAP * 127.0.0.1:80,EXCLUDE localhost"
 115 ```
 116
 117 # HTTPS/SSL support
 118 By default, Web Page Replay, creates a self-signed certificate to serve
 119 SSL traffic. In order for it to work, browsers need to be configured to
 120 ignore certificate errors. Be aware that doing so opens a giant security
 121 hole.
 122
 123 ```
 124 $ google-chrome --ignore-certificate-errors
 125 ```
 126
 127 Firefox has [a configuration file for
 128 exceptions](https://developer.mozilla.org/En/Cert_override.txt). That requires listing
 129 each host that gets used. If you have a better solution, please add it
 130 to the comments below. IE and Safari options are also needed.
 131
 132 To turn off SSL support, run replay.py with "--no-ssl".
 133
 134 # Troubleshooting
 135
 136 ## Permission errors
 137
 138 On Linux, either of the following two errors are permission problems:
 139
 140 ```
 141 python: can't open file './replay.py': [Errno 13] Permission denied
 142 ```
 143 ```
 144 Traceback (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
 149 ImportError: No module named platformsettings
 150 ```
 151 This can happen if you checkout the files to an NFS directory. Either
 152 move the files to a local directory, or make them world
 153 readable/executable.
 154
 155 ## Unable to access auto mounted directories
 156 WPR can cause autofs to hang. On Ubuntu, the following command fixes it:
 157
 158 ```
 159 $ sudo restart autofs
 160 ```
 161
 162 # Help
 163
 164 For full usage instructions and advanced options, see the program's
 165 help.
 166
 167 ```
 168 $ ./replay.py --help
 169 ```