VPN Server [UNSTABLE]¶

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

VPN Server Errors¶

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

error_code	Description
inval	invalid parameters
exist	entry already exists
noent	invalid id
nomem	internal error
unsupp	not supported
inuse	resource in use
busy	resource is busy
ioerror	internal error
size	too many elements

VPN Server List¶

VPN Server Object¶

VPNServer¶

VPNServer has the following attributes:

name string Read-only¶: VPN server name (id)

type enum Read-only¶

VPN server type

type	Description
pptp	PPTP VPN server
openvpn	OpenVPN server

state enum Read-only¶

server state

state
stopped
starting
started
stopping
error

connection_count int Read-only¶: number of active connections

auth_connection_count int Read-only¶: number of active connections that have passed authentication

VPN Server List API¶

GET /api/v4/vpn/¶

Get the list of VPNServer

Example request:

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

Example response:

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

{
    "success": true,
    "result": [
        {
            "state": "stopped",
            "type": "pptp",
            "name": "pptp",
            "connection_count": 0,
            "auth_connection_count": 0
        },
        {
            "state": "stopped",
            "type": "openvpn",
            "name": "openvpn_routed",
            "connection_count": 0,
            "auth_connection_count": 0
        },
        {
            "state": "stopped",
            "type": "openvpn",
            "name": "openvpn_bridge",
            "connection_count": 0,
            "auth_connection_count": 0
        }
    ]
}

VPN Server Config¶

VPNPPTPConfig¶

VPNServerConfig has the following attributes:

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 entries:

pap

chap

mschapv2

values are booleans.

VPNOpenVpnConfig¶

cipher enum¶

cipher

blowfish

aes128

aes256

cipher
blowfish
aes128
aes256

disable_fragment bool¶: disable fragment configuration option

use_tcp bool¶: use TCP instead of UDP

VPNIPSecAuthMode¶

id_source enum¶

source of the connection id

id_source
custom

id_custom string¶: value of the source id when id_source is custom

VPNIPSecConfig¶

ike_version int Read-only¶

IKE protocol version

auth_modes[] array of VPNIPSecAuthMode Read-only¶: map of supported auth modes, currently only psk is supported

VPNServerConfig¶

id string Read-only¶: VPN server id

type enum Read-only¶

VPN server type

type	Description
pptp	PPTP VPN server
openvpn	OpenVPN server
ipsec	IPsec IKEv2 server

enabled bool¶: is the VPN server enabled

enable_ipv4 bool¶

enable IPv4 on this server

NOTE: Not relevant for openvpn_bridge, and pptp

enable_ipv6 bool¶

enable IPv4 on this server

NOTE: Not relevant for openvpn_bridge, and pptp

port int¶

the server port

NOTE: you can only edit the server port when type is openvpn

min_port int Read-only¶: This field indicate the minimum possible value for port (see ConnectionStatus ipv4_port_range)

max_port int Read-only¶: This field indicate the maximum possible value for port (see ConnectionStatus ipv4_port_range)

port_ike int¶

IPSec ike server port

NOTE: only present for ipsec server

port_nat int¶

IPSec nat server port

NOTE: only present for ipsec server

conf_pptp VPNPPTPConfig ¶: only available when type is PPTP

conf_openvpn VPNOpenVpnConfig ¶: only available when type is OpenVPN

conf_ipsec VPNIPSecConfig ¶: only available when type is IPsec

ip_start string Read-only¶: start of the IP range that will be used to give clients an IP

ip_end string Read-only¶: end of the IP range that will be used to give clients an IP

ip6_start string Read-only¶: start of the IPv6 range that will be used to give clients an IPv6

ip6_end string Read-only¶: end of the IPv6 range that will be used to give clients an IPv6

VPN Server Config API¶

Get a VPN config¶

GET /api/v4/vpn/{vpn_id}/config/¶

Get the VPNServerConfig

Example request:

GET /api/v4/vpn/openvpn_routed/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": {
        "enabled": false,
        "port": 1194,
        "conf_openvpn": {
            "cipher": "aes128"
        },
        "id": "openvpn_routed",
        "ip_start": "192.168.27.65",
        "ip_end": "192.168.27.95",
        "type": "openvpn"
    }
}

Update the VPN configuration¶

PUT /api/v4/vpn/openvpn_routed/config/¶

Update the VPNServerConfig

Example request:

PUT /api/v4/vpn/openvpn_routed/config/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "conf_openvpn": {
      "cipher": "blowfish"
    }
}

Example response:

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

{
    "success": true,
    "result": {
        "enabled": false,
        "port": 1194,
        "conf_openvpn": {
            "cipher": "blowfish"
        },
        "id": "openvpn_routed",
        "ip_start": "192.168.27.65",
        "ip_end": "192.168.27.95",
        "type": "openvpn"
    }
}

VPN Server User API¶

VPN users are common to all VPN servers.

VPN Server User Object¶

VPNUser¶

VPNUser has the following attributes:

login string¶: VPN user login

password string Write-only¶: VPN user password (length must be between 8 and 32)

password_set bool Read-only¶: True if a password was provided for this user

ip_reservation ipv4¶

You can specify the IP you want to assign to this user. If you don’t want to use a specific IP pass an empty string or omit this property.

The IP must be in the VPN range (see ip_start, ip_end).

VPN Server User List¶

GET /api/v4/vpn/user/¶

Get the list of VPNUser

Example request:

GET /api/v4/vpn/user/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{
    "success": true,
    "result": [
        {
            "ip_reservation": "",
            "login": "test-1392677633-np",
            "password_set": false
        },
        {
            "ip_reservation": "",
            "login": "test-1392677633",
            "password_set": true
        }
    ]
}

Get a VPN user¶

GET /api/v4/vpn/user/{login}¶

Gets the VPNUser with the given login

Example request:

GET /api/v4/vpn/user/test-1392677633-np HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{
    "success": true,
    "result": {
        "ip_reservation": "",
        "login": "test-1392677633-np",
        "password_set": false
    }
}

Add a VPN User¶

POST /api/v4/vpn/user/¶

Creates a new VPNUser.

Example request:

POST /api/v4/vpn/user/ HTTP/1.1
Host: mafreebox.freebox.fr

{
  "login": "vpnuser01",
  "password": "thisisasecret",
  "ip_reservation": "192.168.27.69"
}

Example response:

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

{
    "success": true,
    "result": {
        "ip_reservation": "192.168.27.69",
        "login": "vpnuser01",
        "password_set": true
    }
}

Delete a VPN User¶

DELETE /api/v4/vpn/user/{login}¶

Deletes the VPNUser

Example request:

DELETE /api/v4/vpn/user/vpnuser01 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{
    "success": true
}

Update a VPN User¶

PUT /api/v4/vpn/user/{login}¶

Updates the VPNUser task with the given login

Example request:

PUT /api/v4/vpn/user/test-1392677633-np HTTP/1.1
Host: mafreebox.freebox.fr

{
    "password": "donttellanyone"
}

Example response:

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

{
    "success": true,
    "result": {
        "ip_reservation": "",
        "login": "test-1392677633-np",
        "password_set": true
    }
}

VPN IP Pool¶

Get the VPN server IP pool reservations¶

GET /api/v4/vpn/ip_pool/¶

Gets the VPNUser with the given login

Example request:

GET /api/v4/vpn/ip_pool/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{
    "success": true,
    "result": {
        "ip_start": "192.168.27.65",
        "ip_end": "192.168.27.95",
        "reservations": [
            {
                "login": "test",
                "ip": "192.168.27.69"
            }
        ]
    }
}

VPN Server Connection API¶

This API allows listing the active connections to the VPN server

VPN Connection Object¶

VPNConnection¶

VPNConnection has the following attributes:

id string Read-only¶: connection id

vpn strong Read-only¶: related VPN server id

user string Read-only¶: user login

authenticated bool Read-only¶: is the connection authenticated

auth_time int Read-only¶: timestamp of the authentication

src_ip ipv4 Read-only¶: connection source IP address

src_port int Read-only¶: connection source port

local_ip int Read-only¶: attributed IP address from VPN adress pool

rx_bytes int Read-only¶: rx bytes

tx_bytes int Read-only¶: tx bytes

Get the list of connections¶

GET /api/v4/vpn/connection/¶

Get the list of VPNUser

Example request:

GET /api/v4/vpn/user/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{
    "success": true,
    "result": [
        {
            "rx_bytes": 94,
            "authenticated": true,
            "tx_bytes": 94,
            "user": "test",
            "id": "pptp-2",
            "vpn": "pptp",
            "src_ip": "93.184.216.119",
            "auth_time": 1392895603,
            "local_ip": "192.168.27.65"
        }
    ]
}

Close a given connection¶

DELETE /api/v4/vpn/connection/{id}¶

Deletes the VPNUser

Example request:

DELETE /api/v4/vpn/connection/pptp-2 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{
    "success": true
}

VPN User configuration file API¶

For OpenVPN server, you can download a configuration file that will be used to configure the VPN client

Donwload a user configuration file¶

GET /api/v4/vpn/download_config/{server_name}/{login}¶

Download an OpenVPN configuration file for the given server and login

WARNING: each time you download a new configuration file for a particular user, you invalidate previous configuration file emitted for this user

Example request:

GET /api/v4/vpn/connection/pptp-2 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Date: Thu, 20 Feb 2014 13:14:01 GMT
Server: nginx
Content-Type: application/x-openvpn-profile
Content-Disposition: attachment; filename="config_openvpn_routed_test.ovpn"
Keep-Alive: timeout=5, max=99
Connection: Keep-Alive
Transfer-Encoding: chunked

[ ... ]