Network Config API

Network Config API allows devices to be configured to have their network connectivity shaped and re-routed outside of a network capture session.

NOTE: Browsers are not yet supported for use with this API.

NOTE: This API is intended for use outside of a capture session. To use network config during a capture session, use the <code class="dcode">networkConfig</code> configuration key in the Session API or the <code class="dcode">headspin:networkConfig</code> Appium Capability]

The network shaping functionality present in this API allows for the following attributes of devices' network connectivity to be configured.

• Download bandwidth
• Upload bandwidth
• Added packet loss
• Added round-trip network latency

The network routing functionality in this API is split into two categories:

• Traffic: Routing of raw network traffic with routing rules related to traffic destination IP or hostname and port.
• DNS: Routing of DNS queries with routing rules based on the domain in question.

API Reference

• List valid network endpoints
• Set device network configuration
• Get device network configuration
• Clear device network configuration

List Valid Network Endpoints

Example

curl -X GET https://<your_api_token>@api-dev.headspin.io/v1/network/{android-device-id}@{hostname}/endpoints

Optional Parameters

• <code class="dcode">?type={dns|traffic}</code>: If set, only return available DNS or traffic endpoints.

Response

{
  "success": true,
  "traffic_endpoints": [
    {
      "key": "default"
    },
    {
      "key": "pbox"
    },
    {
      "key": "somewhere-remote",
      "rule": "net 192.168.0.0/24"
    }
  ],
  "dns_endpoints": [
    {
      "key": "default"
    },
    {
      "key": "pbox"
    },
    {
      "key": "some-other-endpoint"
    }
  ]
}

Format

Set Device Network Configuration

Example

The following sets a basic network config that limits the device's download bandwidth to 15.6 Mbps, upload bandwidth to 12.8 Mbps, adds 50ms of latency, and routes the device's network traffic out of its default route.

curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/network/{android-device-id}@{hostname}/config \
  -d '{"shaping": {"down": 15.6, "up": 12.8, "rtt", 0.05}, "traffic_endpoints": [{"key": "default"}]}'

The following sets a network config without shaping but with complex routing. Traffic destined for <code class="dcode">192.168.120.0/24</code> is routed to <code class="dcode">mars</code>. All other traffic is handled by the device's default route.

curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/network/{android-device-id}@{hostname}/config \
  -d '{"traffic_endpoints": [{"key": "mars", "rule": "net 192.168.120.0/24"}]}'

Body

Response

{
  "success": true
}

Format

• <code class="dcode">success</code> -- Indicates if the operation was successful.

Get Device Network Configuration

Example

The following gets the current network config for <code class="dcode">{android_device_id}@{android_hostname}</code> if you have the device locked.

curl -X GET https://<your_api_token>@api-dev.headspin.io/v1/network/{android-device-id}@{hostname}/config

Response

{
  "success": true,
  "network_config": {
    "shaping": {
      "down": 200,
      "up": null,
      "rtt": null,
      "loss": null
    },
    "traffic_endpoints": [
      {
        "key": "local",
        "rule": "(true)"
      }
    ],
    "dns_endpoints": []
  }
}

Format

• <code class="dcode">success</code> -- Indicates if the operation was successful.
• <code class="dcode">network_config</code> -- A network configuration object in the same format as taken by Set Device Network Configuration

Clear Device Network Configuration

Example

curl -X DELETE https://<your_api_token>@api-dev.headspin.io/v1/network/{android-device-id}@{hostname}/config

Response

{
  "success": true
}

Format

• <code class="dcode">success</code> -- Indicates if the operation was successful.

Routing Language Specification

General

The following language elements apply both to routing rules for raw network traffic and for DNS queries.

• <code class="dcode">(&lt;rule>)</code> -- Parenthesis are used for grouping rules for precedence disambiguation.
• <code class="dcode">true</code> -- Always route traffic.
• <code class="dcode">false</code> -- Never route traffic.
• <code class="dcode">not &lt;rule></code> -- Negate a rule.
• <code class="dcode">&lt;rule> and &lt;rule></code> -- Routes traffic if both rules evaluate to true.
• <code class="dcode">&lt;rule> or &lt;rule></code> -- Route traffic if any rules evaluate to true.

Traffic

The following language elements apply to rules for routing raw network traffic.

• Any rule in General
• <code class="dcode">tcp</code> -- Route TCP traffic
• <code class="dcode">tcp port &lt;port></code> -- Route TCP traffic destined for port <code class="dcode">&lt;port></code>.
• <code class="dcode">tcp portrange &lt;port>-&lt;port></code> -- Route TCP traffic destined for a port in port range <code class="dcode">&lt;port>-&lt;port></code>.
• <code class="dcode">udp</code> -- Route UDP traffic
• <code class="dcode">udp port &lt;port></code> -- Route UDP traffic destined for port <code class="dcode">&lt;port></code>.
• <code class="dcode">udp portrange &lt;port>-&lt;port></code> -- Route UDP traffic destined for a port in port range <code class="dcode">&lt;port>-&lt;port></code>.
• <code class="dcode">net &lt;ip address></code> -- Route traffic destined for the configured IP address.
• <code class="dcode">net &lt;ip address> mask &lt;netmask></code> -- Route traffic destined for the subnet defined by the configured IP address and netmask.
• <code class="dcode">net &lt;cidr></code> -- Route traffic destined for the subnet defined by the configured CIDR notation.
• <code class="dcode">host &lt;glob pattern></code> -- Route traffic destined for a host matching <code class="dcode">&lt;pattern></code>. NOTE: This is evaluated using reverse DNS lookups and may not function in all cases. If a particular case is not functioning, use specific IP addresses or subnets using a <code class="dcode">net</code> rule.

DNS

The following language elements apply to rules for routing DNS queries.

• Any rule in General
• <code class="dcode">host &lt;glob pattern></code> -- Route DNS questions for a domain that matches the <code class="dcode">pattern</code>.