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., 12.0.0.52 has a gateway of 12.0.0.1, and 12.0.0.53 has a gateway of 12.0.0.3)

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 11.0.0.14 and gateway 11.0.0.1

- note that 11.0.0.2 and 11.0.0.3 are allocated to simulated nodes. 

Testing

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 12.0.0.0 netmask 255.255.255.0 gw 11.0.0.3 dev "

TESTING Setup

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://9.0.0.1  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://9.0.0.1/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

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.