MMSys2017 - Stall Aware Pacing (SAP) Testbed
ACM MMSys 2017 - Winner of the "Excellence in DASH Award
Stall Aware Pacing (SAP) Testbed
This page highlights the required steps to build our testbed used for evaluating video streaming with stall aware pacing. If you plan to use this code (fully or partially), please cite our paper.
A.H. Zahran, J.J. Quinlan, K. K. Ramakrishnan, C.J. Sreenan. SAP: Stall-Aware Pacing for Improved DASH Video Experience in Cellular Networks. Proc. of ACM Multimedia Systems 2017, Taipei, Taiwan, June 20-23, 2017. (Winner of the "Excellence in DASH Award").
SAP testbed is an extensively extended version of our iVID D-Lite testbed.
In simulator and client nodes, the current version of the scripts assumes the presence of an acocunt called user1. Hence, you should create this account before proceeding to the following steps.
A- Setting up the server
You just need to upload DASH content to the web directory of your selected HTTP server. E.g., /var/www for the apache server. Note that your choice at this stage would affect the automation of experimentation as described in the master controller setup.
B- Setting up end clients
create user1 account before proceeding
B-1 Install MP4Client
In a fresh installation of Ubuntu 14.04 (or Ubuntu 16.04), one needs to install GPAC and its dependencies. To simplify this task, you can download and run this SAP_Client script using administrative privilages.
Testing: Using any valid MPD file link, connect your device to the Internet and run MP4Client URL_TO_MPD command. The client should start and show the video.
$ MP4Client http://www.cs.ucc.ie/~jq5/www_dataset_temp/x264_4sec/bbb_10min/DASH_Files/VOD/bbb_enc_10min_x264_dash.mpd
B-2 Setup the IP configuration of the client node
The clients are allocated IP adresses in the range 12.0.0.x (x=52, 53, 55, ...). Note that corresponding UE in ns3 are allocated also in 12.0.0.y (y=1, 2, ...). Each physical client should be configured by a gateway address corresponding to its UE tap address (e.g., 184.108.40.206 has a gateway of 220.127.116.11, and 18.104.22.168 has a gateway of 22.214.171.124)
Repeat for every client.
C- Setting up the simulator node
create user1 account before proceeding
C-1- Install ns-3
Download and build the current version of 'NS3' as presented in NS3 'Getting Started'. Make sure to build with '--build-profile=optimized', otherwise the LTE module will be very very slow.
C-2- Create the virtual devices required for connecting simulated and real nodes
C-2.a Move 'bridge_network_build.sh' and 'bridge_network_teardown.sh' from SAP_NS3 to a folder of your choice.
C-2.b Execute bridge_network_build.sh with administrative privilages. Note: the ethX interfaces will not be accessible after this script is run. Use 'bridge_network_teardown.sh' to remove the linkages and gain access to the ethX interfaces.
C-3- Update ns3 with iVID code provided.
The ns3 machine has two interfaces eth0 and eth1. The clients are connected to eth0 and the master controller is connected to eth1.
C-3.a Move the provided 'lena-simple-epc-tap-nas.cc' from SAP_NS3 to the scratch folder of NS3 - this is the script that will build the LTE network.
C-3.b Move the provided 'ipv4-list-routing.cc' file from from SAP_NS3 to 'ns-3-dev/src/internet/model' but first make sure to keep a copy of your original 'ipv4-list-routing.cc' file, in case you remove our code. This code is required to change the destination IP address of packets traveling to the clients, based on the IP of the UE within LTE and the IP of the client.
C-3.c Move files from src_lte_model from SAP_NS3 to src/lte/model.
C-3.d rebuild ns3 again.
C-4- Address configurations
- eth0 is configured with a static address 126.96.36.199 and gateway 188.8.131.52
- note that 184.108.40.206 and 220.127.116.11 are allocated to simulated nodes.
Next run './waf --run "lena-simple-epc-tap-nas.cc"'. If you run the script as is it will use default values for the various metrics, i.e. fading model, distances between nodes, etc. You can always choose to pass in parameters using './waf --run "lena-simple-epc-tap-nas.cc --simTime=0.1 --distance=2000"', whereby you set the simulation time to 100ms, the distance between each client to be 2000 and mandate that the mobile fading model be used.
D- Setting up controller node
D-1- enable ip forwarding across different interfaces
sudo sysctl -w net.ipv4.ip_forward=1
D-2- Setup routing information
Finally, as the 11 subnet has no reference to the 12.0.0.x subnet, we need to route all traffic for the 12.0.0.x subnet through a specific node in the LTE network. This is accomplished by adding a static route in the "NAS/master controller". This is achieved with "route add -net 18.104.22.168 netmask 255.255.255.0 gw 22.214.171.124 dev "
To this end, we have reached a stage that would enable performing some manual testing. We can now perform connectivity and video streaming testing. The first step is bringing your network up to connect clients to the server. That can be achieved by activating the LTE network in the simulator node by running the following command
$ ./waf --run "lena-simple-epc-tap-nas.cc --simTime=60 --distance=100
Note that you should choose a sufficient simulation time "simTime" that would enable you to complete what you need to do. Testing more clients may need more time.
At the client, you may use the default browser and pass a valid URL such as the ip address of your server (http://126.96.36.199 in our case)
To test the video streaming, you need to provide a valid URL for an MPD file to MP4Client @ a client node
e.g., $ MP4Client http://188.8.131.52/x264_2sec/Clip_1_16min/Clip_1_enc_16min_x264_dash.mpd
If everything is working fine, you can move to implement the controller code required for orchestrating the experimentaiton and performing traffic management functions.
D-3- setup controller code
Uncompress the controller code from SAP_Master file into your selected folder. The file content is as follows
|file_copying||directory containing scripts used for copying files from/to the master controller node and end-clients|
|tc||directory containing traffic management code|
|config_files||directory containing configuration parameters|
|GPAC||directory containing scripts required for starting and stopping GPAC clients|
|GPAC_test_code||directory containing relevant files for running GPAC with different algorithms and obtaining the output performance metrics|
|master_run.sh||the main shell script for the master controller|
|cavis.lng||AVIS optimization model for lindo solver|
|ssap2.lng||SAP optimization model for lindo solver|
D-4- Enable transparent shell access on other nodes
Enable passwordless remote shell between the master controller node and all other nodes including both the simulator and client node. Read this page to have a better understanding for this step
D-2.a run the following command first to create a pair of public keys
ssh-keygen -t rsa
D-2.b MANUALLY run ssh_create.sh in setup scripts to create passwordless remote shell on all clients by. Remember to change the ip address for every client.
D-5- Update configuration parameters
Browse the files in config_files and update different parameters according to your interests. The scripts are commented to indicate the meaning of different configuration parameters.
D-6- Populate DASH content pointers
Populate DASH content pointers in GPAC_test_code/DASH_MP4Client_script.sh
- urlsDASH should be populated with URLs to mpd files of different movies
- folderDASH should include corresponding abbreviations for different movies
D-7- Copy DASH experimentaiton files to clients
copy GPAC_test_code folder to a subfolder of /home/user1/Code/ of every client
hint: you can do using sft/scp from the controller node as long as you have the network up in the simulator node as it was done in testing
D-8- Install required software
$ sudo apt-get install dsh
dsh is used by the controller to create remote shell on other nodes
Testing Step: At this stage you should be able to test master controller code with no traffic control option ( noTC )
D-9- Optimal traffic management
SAP optimization program is solved using Lindo solver for which a free academic license is avaialable. We provide the optimization model (.lng) file and a binary file in tc folder. However, one should download and install the solver to get it running. The solver must be installed in the root user home directory (i.e., /root/).
This work has emanated from research conducted with the financial support of Science Foundation Ireland (SFI) under Grant Number 13/IA/1892.