Table Of Contents

Previous topic

System

Next topic

VPN Client [UNSTABLE]

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/v3/vpn/

Get the list of VPNServer

Example request:

GET /api/v3/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  
disable_fragment bool

disable fragment configuration option

VPNServerConfig
id string Read-only

VPN server id

type enum Read-only

VPN server type

type Description
pptp PPTP VPN server
openvpn OpenVPN server
enabled bool

is the VPN server enabled

port int

the server port

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

conf_pptp VPNPPTPConfig

only available when type is PPTP

conf_openvpn VPNOpenVpnConfig

only available when type is OpenVPN

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

VPN Server Config API

Get a VPN config

GET /api/v3/vpn/{vpn_id}/config/

Get the VPNServerConfig

Example request:

GET /api/v3/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/v3/vpn/openvpn_routed/config/

Update the VPNServerConfig

Example request:

PUT /api/v3/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/v3/vpn/user/

Get the list of VPNUser

Example request:

GET /api/v3/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/v3/vpn/user/{login}

Gets the VPNUser with the given login

Example request:

GET /api/v3/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/v3/vpn/user/

Creates a new VPNUser.

Example request:

POST /api/v3/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/v3/vpn/user/{login}

Deletes the VPNUser

Example request:

DELETE /api/v3/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/v3/vpn/user/{login}

Updates the VPNUser task with the given login

Example request:

PUT /api/v3/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/v3/vpn/ip_pool/

Gets the VPNUser with the given login

Example request:

GET /api/v3/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/v3/vpn/connection/

Get the list of VPNUser

Example request:

GET /api/v3/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/v3/vpn/connection/{id}

Deletes the VPNUser

Example request:

DELETE /api/v3/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/v3/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/v3/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

[ ... ]