Chute Configuration

The chute configuration is a YAML file (paradrop.yaml) that a chute developer creates to configure how resources from the host operating system should be allocated to the chute. The chute configuration may also appear in JSON format, particularly when manipulating it through the Local HTTP API or through the cloud API. This page describes the structure and interpretation of values in the chute configuration.

Chute Configuration Object

Name Type Description Validations
environment object Environment variables that will be passed to the chute  
host_config object Options that affect the host network through Docker host config  
host_config.port_bindings object Bind host ports to ports inside the chute  
host_config.dns[] array List of DNS servers to be used by the chute  
net object Chute network configuration  
web object Declaration of web services hosted in the chute  
web.port integer Port number of listening web server in chute
  • It must be lower than or equal to 65535
  • It must be greater than or equal to 1

Chute Network Object

Chutes may have one or more network interfaces. All chutes are configured with a default eth0 interface that provides WAN connectivity. Chutes may request additional network interfaces of various types by defining them in the net object. net is a dictionary, so each network object has a name of your choosing. The network name corresponds to the network name in certain Local API endpoints such as /api/v1/chutes/(chute)/networks/(network).

WiFi AP Configuration

A WiFi AP interface is created by setting type=wifi and mode=ap. ap is the default mode for chute WiFi interfaces, so the latter option can be omitted.

Name Type Description Validations
type string (required) Network type, must be wifi for an AP
  • It must match to regexp “wifi”
intfName string (required) Name of the network interface inside the chute
  • It must match to regexp “[a-z][a-z0-9]*”
mode string WiFi interface mode
  • It must match to regexp “ap”
dhcp object DHCP server configuration  
dhcp.leasetime string Duration of client leases, e.g. 2h  
dhcp.limit integer Size of address range beginning at start value.
  • It must be greater than or equal to 1
dhcp.start integer Starting offset for address assignment.
  • It must be greater than or equal to 0
dhcp.relay string Address of a DHCP server if this server will be acting as a relay agent (experimental)  
ipv4_network string Request specific IP network in slash notation  
ssid string ESSID to broadcast
  • Its length must be less than or equal to 32
key string Password required from clients to connect
  • Its length must be greater than or equal to 8
options object Additional options to pass to the AP  
options.nasid string NAS ID for RADIUS  
options.acct_server string RADIUS accounting server  
options.acct_secret string RADIUS accounting secret  
options.acct_interval integer RADIUS accounting update interval (seconds)
  • It must be greater than or equal to 1
options.hidden boolean Disable broadcasting the ESSID in beacons  
options.isolate boolean Disable forwarding traffic between connected clients  
options.maxassoc integer Maximum number of associated clients  
dns[] array List of DNS servers to advertise to connected clients  
l3bridge string Bridge to another network using ARP proxying (experimental)  
requests object Hardware features required by the chute when assigning a physical interface  
requests.hwmode string Required operating mode (11b for old hardware, 11g for 2.4 GHz, 11a for 5 GHz)
  • It must be equal to one of the elements in [“11b”, “11g”, “11a”]

Monitor-mode Interface Configuration (Experimental)

A monitor-mode interface enables a chute to observe all detected WiFi traffic with RadioTap headers.

Name Type Description Validations
type string (required) Network type, must be wifi for monitor mode
  • It must match to regexp “wifi”
intfName string (required) Name of the network interface inside the chute
  • It must match to regexp “[a-z][a-z0-9]*”
mode string (required) Wireless interface mode
  • It must match to regexp “monitor”

VLAN Interface Configuration

A VLAN interface allows tagged traffic on the physical Ethernet ports of the device to be received by the chute. The interface must be configured with a VLAN ID. Incoming traffic with that VLAN tag will be untagged and forwarded to the chute interface. Likewise, traffic leaving the chute interface will be tagged and sent on one the physical ports.

Name Type Description Validations
type string (required) Network type, must be vlan
  • It must match to regexp “wifi”
intfName string (required) Name of the network interface inside the chute
  • It must match to regexp “[a-z][a-z0-9]*”
vlan_id integer (required) VLAN tag for traffic to and from the chute
  • It must be greater than or equal to 1
dhcp object DHCP server configuration  
dhcp.leasetime string Duration of client leases, e.g. 2h  
dhcp.limit integer Size of address range beginning at start value.
  • It must be greater than or equal to 1
dhcp.start integer Starting offset for address assignment.
  • It must be greater than or equal to 0
dhcp.relay string Address of a DHCP server if this server will be acting as a relay agent (experimental)  
ipv4_network string Request specific IP network in slash notation  
dns[] array List of DNS servers to advertise to connected clients  

Example

The following example chute configuration sets up a WiFi access point and a web server running on port 5000. First, we show the example in YAML format.

net:
  wifi:
    type: wifi
    intfName: wlan0
    dhcp:
      start: 3
      limit: 250
      lease: 1h
    ssid: Free WiFi
    options:
      isolate: true
      maxassoc: 100
web:
  port: 5000

Here is the same example in JSON format.

{
  "net": {
    "wifi": {
      "type": "wifi",
      "intfName": "wlan0",
      "dhcp": {
        "start": 3,
        "limit": 250,
        "lease": "1h"
      },
      "ssid": "Free WiFi",
      "options": {
        "isolate": true,
        "maxassoc": 100
      }
    }
  },
  "web": {
    "port": 5000
  }
}

Experimental Features

ParaDrop is under heavy development. Features marked as experimental may be incomplete or buggy. Please contact us if you need help with any of these features.