VPN Client [UNSTABLE]¶

The VPN Client API allows you to control the Freebox VPN Client

VPN Client Errors¶

When attempting to access this API, you may encounter the following errors:

error_code	Description
inval	invalid parameters
nomem	internal error
ioerror	internal error
nodev	invalid device
noent	invalid id
netdown	network is not available
exist	entry already exists
busy	resource is busy

VPN Client Configuration¶

VPN Client Configuration Object¶

VPNClientConfig¶

VPNClientConfig has the following attributes:

id string Read-only¶: VPN config id

description string¶: VPN description

type enum¶

VPN server type

type	Description
pptp	PPTP VPN server
openvpn	OpenVPN server

active bool¶: is this configuration active. Only one configuration is active at a time.

conf_pptp VPNClientConfigPPTP¶: only available when type is PPTP

VPNClientConfig

VPNClientConfigPPTP has the following attributes:

remote_host string¶: remote host IP or name

username string¶: VPN username

password string Write-only¶: VPN password

mppe enum¶

mppe	Description
disable	disable mppe
require	require mppe
require_128	require 128 bits mppe

allowed_auth dict¶

allowed authentication methods dictionnary with following keys:

eap

pap

chap

mschap

mschapv2

values are booleans.

Get VPN Client configuration list¶

GET /api/v4/vpn_client/config/¶

Get the list of VPNClientConfig

Example request:

GET /api/v4/vpn_client/config/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": [
        {
            "type": "pptp",
            "description": "test vpn2",
            "active": true,
            "id": "vpn0",
            "conf_pptp": {
                "mppe": "require",
                "username": "freeuser",
                "remote_host": "vpnhost.example.org",
                "allowed_auth": {
                    "eap": false,
                    "mschap": false,
                    "mschapv2": true,
                    "chap": false,
                    "pap": false
                }
            }
        },
        {
            "type": "pptp",
            "description": "test vpn1",
            "active": false,
            "id": "vpn1",
            "conf_pptp": {
                "mppe": "require",
                "username": "testuser",
                "remote_host": "example.org",
                "allowed_auth": {
                    "eap": false,
                    "mschap": false,
                    "mschapv2": true,
                    "chap": false,
                    "pap": false
                }
            }
        }
    ]
}

Get a VPN client config¶

GET /api/v4/vpn_client/config/{id}¶

Get the VPNClientConfig

Example request:

GET /api/v4/vpn_client/config/vpn0 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
         "type": "pptp",
         "description": "test vpn2",
         "active": true,
         "id": "vpn0",
         "conf_pptp": {
             "mppe": "require",
             "username": "freeuser",
             "remote_host": "vpnhost.example.org",
             "allowed_auth": {
                 "eap": false,
                 "mschap": false,
                 "mschapv2": true,
                 "chap": false,
                 "pap": false
             }
         }
    }
}

Add a VPN client configuration¶

POST /api/v4/vpn_client/config/¶

Creates a new VPNClientConfig.

Example request:

POST /api/v4/vpn_client/config/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "type": "pptp",
   "description": "test pptp",
   "active": false,
   "conf_pptp": {
      "mppe": "require",
      "username": "fbxtest",
      "password": "",
      "remote_host": "test.example.org",
      "allowed_auth": {
         "mschapv2": true
      }
   }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "type": "pptp",
        "description": "test pptp",
        "active": false,
        "id": "vpn2",
        "conf_pptp": {
            "password": "",
            "mppe": "require",
            "username": "fbxtest",
            "remote_host": "test.example.org",
            "allowed_auth": {
                "eap": false,
                "mschap": false,
                "mschapv2": true,
                "chap": false,
                "pap": false
            }
        }
    }
}

Delete a VPN client Configuration¶

DELETE /api/v4/vpn_client/config/{id}¶

Deletes the VPNClientConfig

Example request:

DELETE /api/v4/vpn_client/config/vpn2 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true
}

Update the VPN client configuration¶

PUT /api/v4/vpn_client/config/{id}¶

Update the VPNServerConfig

Example request:

PUT /api/v4/vpn_client/config/vpn0 HTTP/1.1
Host: mafreebox.freebox.fr

{
   "active": false
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
         "type": "pptp",
         "description": "test vpn2",
         "active": false,
         "id": "vpn0",
         "conf_pptp": {
             "mppe": "require",
             "username": "freeuser",
             "remote_host": "vpnhost.example.org",
             "allowed_auth": {
                 "eap": false,
                 "mschap": false,
                 "mschapv2": true,
                 "chap": false,
                 "pap": false
             }
         }
    }
}

VPN Client Status¶

VPN Client Status Object¶

VPNClientStatus¶

VPNClientStatus has the following attributes:

enabled bool Read-only¶: is VPN client enabled

active_vpn string Read-only¶: active VPN id

active_vpn_description string Read-only¶: active VPN description

type enum Read-only¶

active VPN type

type	Description
pptp	PPTP VPN server
openvpn	OpenVPN server

state enum Read-only¶

state	Description
waiting_wan	waiting for wan connection
going_up	connecting
up	connected
going_down	disconnecting
down	disconnected

last_up int Read-only¶: timestamp of last successfull connection

last_try int Read-only¶: timestamp of last connection attempt

next_try int Read-only¶: seconds left until next connection attempt

last_error enum Read-only¶

last_error	Description
none	no error
internal	internal error
authentication_failed	wrong credentials
auth_failed	wrong credentials
resolv_failed	invalid host name
connect_timeout	connection timeout
connect_failed	connection failed
setup_control_failed	PPTP session negociation failure
setup_call_failed	PPTP session failure
protocol	protocol error
remote_terminated	connection closed by remote peer
remote_disconnect	connection closed by remote peer

stats VpnClientStats Read-only¶: connection statistics

IPv4 VpnClientIpInfo Read-only¶: connection IPv4 information

VpnClientStats¶

rate_up int Read-only¶: current upload rate (in byte/s)

rate_down int Read-only¶: current download rate (in byte/s)

bytes_up int Read-only¶: total bytes uploaded

bytes_down int Read-only¶: total bytes downloaded

VpnClientIpInfo¶

config_valid bool Read-only¶: is the configuration valid

ip_mask dict Read-only¶: assigned IP and netmask

domain string Read-only¶: provided domain

gateway IPv4 Read-only¶: provided gateway

dns[] array of ipv4 Read-only¶: list of dns servers

provider enum Read-only¶

ip_mask source

provider	Description
none	none
static	static IP configuration
ppp	ppp
dhcp	DHCP server

routes list Read-only¶: list of provided routes

dhcp dict Read-only¶: DHCP status information

Get the VPN client status¶

GET /api/v4/vpn_client/status¶

Get the VPNClientStatus

Example request:

GET /api/v4/vpn_client/status HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "enabled": true,
        "type": "pptp",
        "last_error": "none",
        "active_vpn_description": "test vpn",
        "last_try": 1392904509,
        "state": "up",
        "stats": {
            "rate_up": 0,
            "bytes_down": 94,
            "bytes_up": 94,
            "rate_down": 0
        },
        "active_vpn": "vpn1",
        "next_try": 0,
        "last_up": 1392904510,
        "ipv4": {
            "routes": { },
            "config_valid": true,
            "ip_mask": {
                "ip": "192.168.27.65",
                "mask": "255.255.255.255"
            },
            "provider": "ppp",
            "dhcp": {
                "state": "down",
                "renew_remaining": 0,
                "dhcp_options": { },
                "lease_remaining": 0,
                "lease_time": 0,
                "rebind_remaining": 0,
                "server_id": 0
            },
            "dns": [
                "212.27.38.253"
            ],
            "domain": "",
            "gateway": "212.27.38.253"
        }
    }
}

Get the VPN client logs¶

GET /api/v4/vpn_client/log¶

Example request:

GET /api/v4/vpn_client/log HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": "2014-02-20 14:55:10 dbg: ppp: pppd: sent [ ... ] "
}