Table Of Contents

Previous topic

Storage API [UNSTABLE]

Parental Control

With the parental control API you can define rules to limit or block access to internet for any host on your local network. With a planning you can change the access policy during the day.

The different access policies are:

filter_state Description
allowed access is allowed
denied access is denied
webonly access is granted only for HTTP and HTTPS traffic

Parental Control errors

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

error_code Description
inval invalid request
exist a rule already exists for this host
noent invalid rule id

Parental Filter Config

Parental filter configuration allow you to set the default filter_state to apply to hosts without rules on your network

ParentalFilterConfig
default_filter_mode enum

see available filter_state

Parental Filter Planning

Parental filter planning let you define the parental filter policy based on the week day and the hour.

Parental filter planning have the following attributes:

ParentalFilterPlanning
resolution int Read-only

planning resolution : number of planning slots per day, e.g. 48 means that each slot represent 30 minutes

cdayranges[] array of string

list of custom day range, each custom day range represents a group of days for which you want to use a different planning than other week days.

For instance a custom day range can contain the list of you children holidays

cdayranges Description
:fr_bank_holidays French bank holidays
:fr_school_holidays_a French school holidays - Zone A
:fr_school_holidays_b French school holidays - Zone B
:fr_school_holidays_c French school holidays - Zone C
:fr_school_holidays_corse French school holidays - Corse

each cdayranges can be a coma separated list of cdayranges, for instance ”:fr_bank_holidays,:fr_school_holidays_b”

mapping[] array of enum Read-only

array of states for each corresponding planning slots. the array size is : (number of cdayranges + 7) * resolution

Parental Filter rule object

Parental filter rule objects have the following attributes:

ParentalFilter
id int Read-only

filter id

macs[] array of string

the list of mac addresses the rule should be applied to

hosts[] array of string Read-only

the list of hostnames associated with macs

ip string Read-only

only filled for old rules, you cannot set a rule with an IP

desc string

a description for this rule

forced bool

is set to true, the rule will not use the planning and will always stay in the forced_mode

forced_mode enum

the filter policy to use when forced is set to true (see filter_state for valid states)

tmp_mode_expire int

if != 0 the rule will not use the planning for the next tmp_mode_expire seconds

tmp_mode enum

the filter policy to use when tmp_mode_expire is != 0 (see filter_state for valid states)

scheduling_mode enum Read-only
scheduling_mode Description
forced filter_state is forced to forced_mode
temporary filter_state is temporary set to tmp_mode for the next tmp_mode_expire seconds
planning filter_state is set using the planning
filter_state enum Read-only
filter_state Description
allowed access is allowed
denied access is denied
webonly access is granted only for HTTP and HTTPS traffic
current_mapping_idx int Read-only

current index used in planning to compute filter_state (only relevant when scheduling_mode is planning)

next_change int Read-only

seconds until next filter_state change 0 means filter_state won’t change

Parental Filter API

Get parental filter config

GET /api/v3/parental/config/

Get the ParentalFilterConfig

Example request:

GET /api/v3/parental/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": {
        "default_filter_mode": "allowed"
    }

}

Update parental filter config

PUT /api/v3/parental/config/

Update the ParentalFilterConfig

Example request:

PUT /api/v3/parental/config/ HTTP/1.1
Host: mafreebox.freebox.fr
{
   "default_filter_mode": "denied",
}

Example response:

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

    "success": true,
    "result": {
        "default_filter_mode": "denied"
    }

}

Retrieve all Parental Filter rules

GET /api/v3/parental/filter/

Returns the collection of all ParentalFilter rules.

Example request:

GET /api/v3/parental/filter/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": [
        {
            "forced": false,
            "id": 4,
            "hosts": [
                "iPad-r0ro",
                "iPhone-r0ro"
            ],
            "tmp_mode_expire": 0,
            "ip": "0.0.0.0",
            "forced_mode": "allowed",
            "scheduling_mode": "planning",
            "macs": [
                "D8:A2:CA:FE:BA:DF",
                "D0:23:BE:DE:AD:EF"
            ],
            "current_mapping_idx": 225,
            "next_change": 620,
            "desc": "r0ro",
            "tmp_mode": "allowed",
            "filter_state": "allowed"
        },
        {
            "forced": false,
            "id": 6,
            "hosts": [
                "00:07:CB:00:00:07"
            ],
            "tmp_mode_expire": 0,
            "ip": "0.0.0.0",
            "forced_mode": "allowed",
            "scheduling_mode": "planning",
            "macs": [
                "00:07:CB:00:00:07"
            ],
            "current_mapping_idx": 225,
            "next_change": 0,
            "desc": "",
            "tmp_mode": "allowed",
            "filter_state": "allowed"
        }
    ]
}

Retrieve a Parental Filter rule

GET /api/v3/parental/filter/{id}

Returns the ParentalFilter rule with the given id

Example request:

GET /api/v3/parental/filter/4 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "forced": false,
        "id": 4,
        "hosts": [
            "iPad-r0ro",
            "iPhone-r0ro"
        ],
        "tmp_mode_expire": 0,
        "ip": "0.0.0.0",
        "forced_mode": "allowed",
        "scheduling_mode": "planning",
        "macs": [
            "D8:A2:5E:1B:3F:9F",
            "D0:23:DB:20:70:12"
        ],
        "current_mapping_idx": 225,
        "next_change": 529,
        "desc": "",
        "tmp_mode": "allowed",
        "filter_state": "allowed"
    }
}

Delete a Parental Filter rule

DELETE /api/v3/parental/filter/{id}

Deletes the ParentalFilter rule with the given id

Example request:

DELETE /api/v3/parental/filter/4 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 Parental Filter rule

PUT /api/v3/parental/filter/{id}

Updates the ParentalFilter rule with the given id

Example request:

PUT /api/v3/parental/filter/4 HTTP/1.1
Host: mafreebox.freebox.fr
{
   "forced_mode": "denied",
   "forced": true
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "forced": true,
        "id": 4,
        "hosts": [
            "iPad-r0ro",
            "iPhone-r0ro"
        ],
        "tmp_mode_expire": 0,
        "ip": "0.0.0.0",
        "forced_mode": "denied",
        "scheduling_mode": "forced",
        "macs": [
            "D8:A2:5E:1B:3F:9F",
            "D0:23:DB:20:70:12"
        ],
        "current_mapping_idx": 0,
        "next_change": 0,
        "desc": "",
        "tmp_mode": "allowed",
        "filter_state": "denied"
    }
}

Add a Parental Filter rule

POST /api/v3/parental/filter/

Add a parental filter rule

Example request:

POST /api/v3/parental/filter/ HTTP/1.1
Host: mafreebox.freebox.fr
{
   "macs": [
      "00:07:cb:00:00:69",
      "00:07:cb:00:00:42"
    ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "forced": false,
        "id": 7,
        "hosts": [
            "00:07:CB:00:00:69",
            "00:07:CB:00:00:42"
        ],
        "tmp_mode_expire": 0,
        "ip": "0.0.0.0",
        "forced_mode": "allowed",
        "scheduling_mode": "planning",
        "macs": [
            "00:07:CB:00:00:69",
            "00:07:CB:00:00:42"
        ],
        "current_mapping_idx": 4,
        "next_change": 0,
        "desc": "",
        "tmp_mode": "allowed",
        "filter_state": "allowed"
    }
}

Parental Filter Planning API

Get a parental filter Planning

GET /api/v3/parental/filter/{id}/planning

Returns the ParentalFilterPlanning for the filter with the given id

Example request:

GET /api/v3/parental/filter/4/planning HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "cdayranges": [
            ":fr_bank_holidays,:fr_school_holidays_c,"
         ],
        "resolution": 48,
        "mapping": [
            "allowed",
            "allowed",
            "allowed",
            "allowed",
            "allowed",
            "allowed",
            "allowed",

            [ ... ]

            "denied",
            "denied",
            "denied",
            "denied",
            "denied",
            "denied",
            "denied",
            "denied",
            "denied"
        ]
    }
}

Update a parental filter Planning

PUT /api/v3/parental/filter/{id}/planning

Update the ParentalFilterPlanning for the parental filter rule with the given id

Example request:

PUT /api/v3/parental/filter/4/planning HTTP/1.1
Host: mafreebox.freebox.fr
{
   "cdayranges": [],
   "resolution":48,
   "mapping":[
      "webonly","webonly","webonly","webonly","webonly","allowed",
      "allowed","allowed","allowed","allowed","allowed","allowed",

      [ ... ]

      "webonly","webonly","webonly","webonly"
   ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "cdayranges": [],
        "resolution": 48,
        "mapping": [
            "webonly",
            "webonly",
            "webonly",
            "webonly",
            "webonly",
            "allowed",
            "allowed",

            [ ... ]

            "webonly",
            "webonly",
            "webonly",
            "webonly",
            "webonly",
            "webonly"
        ]
    }
}