pawmsf / measurement-kit

Portable C++14 network measurement library

MeasurementKit

Portable C++14 network measurement library

---

branch	travis-ci	coveralls	gitlab-ci	circle-ci
master
stable

MeasurementKit is a library that implements open network measurement methodologies (performance, censorship, etc.) and targets mobile platforms (Android and iOS).

It is meant to be embedded by third party applications with specific network measurement needs and/or to be used by researchers as a basis to implement novel tools.

Currently it implements the following high-level tests:

• OONI's Web Connectivity test

• the network diagnostic tool network performance test

• OONI's DNS Injection test

• OONI's HTTP Invalid Request Line test

• OONI's TCP Connect test

• OONI's Meek Fronted Requests test

• OONI's HTTP Header Field Manipulation test

• Neubot's MPEG DASH test

It contains building-block functionalities useful to implement your own tests. More in detail it currently implements:

• TCP connection (with which you can create a TCP connection towards and endpoint, receive and send data)

• DNS client (with which you can resolve and reverse-resolve A and AAAA records using arbitrary name servers)

• HTTP client (with which you can send HTTP/1.1 requests and receive and parse the corresponding responses)

• traceroute for Android (with which you can send individual traceroute probes with a specified payload and TTL)

• mlab-ns client (with which you can interact with Measurement Lab backend to know the server with which to run tests)

• the functionality to communicate with the OONI collector

• the functionality to communicate with the OONI bouncer

In the short term we plan to add to MeasurementKit:

• more OONI tests

Other functionalities that we would like to add are building-blocks functionalities such as uTP, and traceroute for iOS.

The following index illustrates the content of the remainder of this file:

• How to clone the repository
• How to test a specific branch
• How to build MeasurementKit
  • How to build MeasurementKit on a Unix-like system
  • How to test MeasurementKit on a Unix-like system
  • How to build MeasurementKit on Android
  • How to build MeasurementKit on iOS
  • How to add MeasurementKit to an Xcode project
• How to use MeasurementKit

How to clone the repository

To clone MeasurementKit repository, do:

git clone https://github.com/measurement-kit/measurement-kit

How to test a specific branch

If you need to checkout a specific branch (say feature/foo) for testing it, clone the repository and then type:

git fetch origin
git checkout feature/foo

Then proceed with the instruction to build and test MeasurementKit.

For more detailed instructions see contributing instructions.

How to build MeasurementKit

How to build MeasurementKit on a Unix-like system

Very briefly, to build from the git repository do:

./autogen.sh
./configure
make

See the Unix tutorial for more details.

How to test MeasurementKit on a Unix-like system

Once you have built MeasurementKit, run tests like:

make check

How to build MeasurementKit on Android

We have a specific repository for compiling MeasurementKit for Android. You may also want to read the documentation explaining how to cross compile MK dependencies for Android.

How to build MeasurementKit on iOS

Having Xcode command line tools installed, run:

./build/ios/library

See the iOS tutorial for more info.

How to add MeasurementKit to an Xcode project.

Make sure your Podfile looks like this:

target 'YourTargetNameHere' do
    pod 'measurement_kit',
      :git => 'https://github.com/measurement-kit/measurement-kit.git',
      :branch => 'stable'
end

Run pod install (or pod update) and remember to open the .xcworkspace rather than the .xcodeproj. See the iOS tutorial for more info.

How to use MeasurementKit

You probably want to start using the nettests API that is the high level API for running tests. To this end, see also the nettests API examples and the Unix tutorial.