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 |
|
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 |
|
intfName | string (required) | Name of the network interface inside the chute |
|
mode | string | WiFi interface mode |
|
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. |
|
dhcp.start | integer | Starting offset for address assignment. |
|
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 |
|
key | string | Password required from clients to connect |
|
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) |
|
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) |
|
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 |
|
intfName | string (required) | Name of the network interface inside the chute |
|
mode | string (required) | Wireless interface mode |
|
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 |
|
intfName | string (required) | Name of the network interface inside the chute |
|
vlan_id | integer (required) | VLAN tag for traffic to and from the chute |
|
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. |
|
dhcp.start | integer | Starting offset for address assignment. |
|
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.