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 [ ... ] "
}