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 Specification

type object
properties
  • name
Name of the chute.
type string
  • description
Description of the chute to be shown to users.
type string
  • version
Version of the chute.
anyOf
type string
type number
  • services
Services to be installed with the chute.
type object
patternProperties
  • w+
Service Specification
  • web
type object
properties
  • service
Name of chute service which provides the web service.
type string
  • port
Listening port inside the chute.
type integer
maximum 65536
minimum 1
additionalProperties False
additionalProperties False
definitions
  • interface
Interface Specification
type object
properties
  • type
Network interface type.
type string
enum monitor, vlan, wifi-ap
  • dhcp
type object
properties
  • leasetime
Duration of client leases, e.g. 2h.
type string
pattern d+[dhms]
  • limit
Size of address range beginning at start value.
type integer
minimum 1
  • start
Starting offset for address assignment.
type integer
minimum 3
additionalProperties False
  • dns
List of DNS servers to advertise to connected clients.
type array
items
type string
  • wireless
type object
properties
  • ssid
ESSID to broadcast.
type string
maxLength 32
  • key
Wireless network password.
type string
minLength 8
  • nasid
NAS identifier for RADIUS.
type string
  • acct_server
RADIUS accounting server.
type string
  • acct_secret
RADIUS accounting secret.
type string
  • acct_interval
RADIUS accounting update interval (seconds).
type integer
minimum 1
  • hidden
Disable broadcasting the ESSID in beacons.
type boolean
  • isolate
Disable forwarding traffic between connected clients.
type boolean
  • maxassoc
Maximum number of associated clients.
type integer
minimum 0
additionalProperties False
  • requirements
type object
properties
  • hwmode
Required operating mode (11b for old hardware, 11g for 2.4 GHz, 11a for 5 Ghz).
type string
enum 11b, 11g, 11a
  • ipv4_network
Required IP network in slash notation.
type string
pattern ^d+.d+.d+.d+/d+
additionalProperties False
  • l3bridge
Bridge to another network using ARP proxying (experimental).
type string
  • vlan-id
VLAN tag for traffic to and from the interface.
type integer
maximum 4094
minimum 1
additionalProperties False
  • service
Service Specification
type object
properties
  • type
Type of chute service.
type string
enum light, normal, image
  • source
Source directory for this service.
type string
  • image
Image specification for services that pull a Docker image.
type string
  • command
anyOf
type string
type array
items
type string
  • dns
List of DNS servers to be used within the container.
type array
items
type string
  • environment
Environment variables.
type object
  • interfaces
Network interfaces to be connected.
type object
patternProperties
  • w{1,16}
Interface Specification
  • requests
type object
properties
  • as-root
Run service as privileged user.
type boolean
  • port-bindings
Port bindings from host to service container.
type array
items
type object
properties
  • external
External (host) port number.
type integer
maximum 65536
minimum 1
  • internal
Internal (container) port number.
type integer
maximum 65536
minimum 1
additionalProperties False
additionalProperties False
additionalProperties False

Chute Service Object

Chutes consist of one or more services, which are long-running processes that implement the functionality of the chute. Services may be built from code in the chute project, from a Dockerfile, or pulled as images from the public Docker Hub.

Service Specification

type object
properties
  • type
Type of chute service.
type string
enum light, normal, image
  • source
Source directory for this service.
type string
  • image
Image specification for services that pull a Docker image.
type string
  • command
anyOf
type string
type array
items
type string
  • dns
List of DNS servers to be used within the container.
type array
items
type string
  • environment
Environment variables.
type object
  • interfaces
Network interfaces to be connected.
type object
patternProperties
  • w{1,16}
Interface Specification
  • requests
type object
properties
  • as-root
Run service as privileged user.
type boolean
  • port-bindings
Port bindings from host to service container.
type array
items
type object
properties
  • external
External (host) port number.
type integer
maximum 65536
minimum 1
  • internal
Internal (container) port number.
type integer
maximum 65536
minimum 1
additionalProperties False
additionalProperties False
additionalProperties False

Chute Interface 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 interfaces object. interfaces is a dictionary, where the key should be the desired interface name inside your chute, e.g. wlan0. The same key is used to reference the interface in certain API endpoints such as /api/v1/chutes/(chute)/networks/(network).

Interface Specification

type object
properties
  • type
Network interface type.
type string
enum monitor, vlan, wifi-ap
  • dhcp
type object
properties
  • leasetime
Duration of client leases, e.g. 2h.
type string
pattern d+[dhms]
  • limit
Size of address range beginning at start value.
type integer
minimum 1
  • start
Starting offset for address assignment.
type integer
minimum 3
additionalProperties False
  • dns
List of DNS servers to advertise to connected clients.
type array
items
type string
  • wireless
type object
properties
  • ssid
ESSID to broadcast.
type string
maxLength 32
  • key
Wireless network password.
type string
minLength 8
  • nasid
NAS identifier for RADIUS.
type string
  • acct_server
RADIUS accounting server.
type string
  • acct_secret
RADIUS accounting secret.
type string
  • acct_interval
RADIUS accounting update interval (seconds).
type integer
minimum 1
  • hidden
Disable broadcasting the ESSID in beacons.
type boolean
  • isolate
Disable forwarding traffic between connected clients.
type boolean
  • maxassoc
Maximum number of associated clients.
type integer
minimum 0
additionalProperties False
  • requirements
type object
properties
  • hwmode
Required operating mode (11b for old hardware, 11g for 2.4 GHz, 11a for 5 Ghz).
type string
enum 11b, 11g, 11a
  • ipv4_network
Required IP network in slash notation.
type string
pattern ^d+.d+.d+.d+/d+
additionalProperties False
  • l3bridge
Bridge to another network using ARP proxying (experimental).
type string
  • vlan-id
VLAN tag for traffic to and from the interface.
type integer
maximum 4094
minimum 1
additionalProperties False

WiFi AP Configuration

A WiFi AP interface is created by setting type=wifi-ap. There are many options for configuring the WiFi AP available through the wireless section of the interface object.

Monitor-mode Interface Configuration (Experimental)

A monitor-mode interface enables a chute to observe all detected WiFi traffic with RadioTap headers. A monitor-mode interface is created by setting type=wifi-monitor.

Monitor-mode interfaces are disallowed by default but can be enabled if you have administrative access to a node. This is because monitor-mode interfaces are potentially dangerous. They enable malicious chutes to record network traffic, and furthermore, the feature itself is experimental. There may be issues with kernel drivers or our implementation that cause system instability.

If you understand the risks and wish to enable monitor-mode interfaces, connect to your node using SSH and run the following command.:

snap set paradrop-daemon base.allow-monitor-mode=true

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.

Example

The following example chute configuration sets up a WiFi access point and a web server running on port 5000. It also shows how to install and connect a database from a public image.

name: seccam
description: A Paradrop chute that performs motion detection using a simple WiFi camera.
version: 1

services:
  main:
    type: light
    source: .
    image: python2
    command: python -u seccam.py

    environment:
      IMAGE_INTERVAL: 2.0
      MOTION_THRESHOLD: 40.0
      SECCAM_MODE: detect

    interfaces:
      wlan0:
        type: wifi-ap

        dhcp:
          leasetime: 12h
          limit: 250
          start: 4

        wireless:
          ssid: seccam42
          key: paradropseccam
          hidden: false
          isolate: true

        requirements:
          hwmode: 11g

    requests:
      as-root: true
      port-bindings:
        - external: 81
          internal: 81

  db:
    type: image
    image: mongo:3.0

web:
  service: main
  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.