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/v4/parental/config/¶

Get the ParentalFilterConfig

Example request:

GET /api/v4/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/v4/parental/config/¶

Update the ParentalFilterConfig

Example request:

PUT /api/v4/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/v4/parental/filter/¶

Returns the collection of all ParentalFilter rules.

Example request:

GET /api/v4/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/v4/parental/filter/{id}¶

Returns the ParentalFilter rule with the given id

Example request:

GET /api/v4/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/v4/parental/filter/{id}¶

Deletes the ParentalFilter rule with the given id

Example request:

DELETE /api/v4/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/v4/parental/filter/{id}¶

Updates the ParentalFilter rule with the given id

Example request:

PUT /api/v4/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/v4/parental/filter/¶

Add a parental filter rule

Example request:

POST /api/v4/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/v4/parental/filter/{id}/planning¶

Returns the ParentalFilterPlanning for the filter with the given id

Example request:

GET /api/v4/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/v4/parental/filter/{id}/planning¶

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

Example request:

PUT /api/v4/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"
        ]
    }
}