Skip to content
Snippets Groups Projects
quickstart.md 8.38 KiB
Newer Older
  • Learn to ignore specific revisions
  • # Configuration
    
    Configuration through UCI and TR-181 data model is possible.
    
    ## UCI Configuration
    
    The configuration involved parentalcontrol UCI and (optionally) schedules UCI.
    
    ### `parentalcontrol` UCI Configuration
    
    The table below describes the options available in the `parentalcontrol` UCI file:
    
    | Option                       | Type    | Description                                                                  |
    | ---------------------------- | ------- | ---------------------------------------------------------------------------- |
    | `globals`                    | section | Defines global settings for parental controls.                               |
    | `enable` (in `globals`)      | boolean | Enable or disable the parental control globally (`1` for enable).            |
    | `profile`                    | section | Profile contains hosts and is referred to by filters.                        |
    | `name`                       | string  | A descriptive name for the profile (e.g., `kids`).                           |
    | `host`                       | list    | Specifies hosts associated with the profile (MAC addresses or device names). |
    | `profile_urlfilter`          | section | Links URL filtering settings to a profile.                                   |
    | `dm_parent`                  | string  | Refers to the `profile` section by name.                                     |
    | `filter_text`                | list    | List substrings which can be looked into URLs to block them.                 |
    | `profile_urlfilter_schedule` | list    | Refers to schedules defined in the `schedules` UCI file.                     |
    | `profile_urlbundle`          | list    | Refers to `urlbundle` sections.                                              |
    | `enable`                     | boolean | Enable or disable the specific profile URL filter (`1` for enable).          |
    | `urlbundle`                  | section | Bundle contains options for individual urls and bundle files.                |
    | `custom_url`                 | list    | URLs to be resolved and added to daemon's cache at startup and blocked.      |
    | `download_url`               | string  | Remote or local path to a file which contains newline separated URLs         |
    
    ---
    
    **NOTE:** If the bundle is fetched from remote location, then maximum size allowed is 2MB per *download_url* option.
    
    ### `schedules` UCI Configuration
    
    The `schedules` UCI file allows defining time-based schedules for controlling URL filters. Options are described in the table below:
    
    | Option                 | Type    | Description                                                    |
    | ---------------------- | ------- | -------------------------------------------------------------- |
    | `global`               | section | Defines global scheduling settings.                            |
    | `enable` (in `global`) | boolean | Enable or disable scheduling globally (`1` for enable).        |
    | `schedule`             | section | Defines a time-based schedule.                                 |
    | `enable`               | boolean | Enable or disable the specific schedule (`1` for enable).      |
    | `duration`             | integer | Duration of the schedule in seconds (e.g., 28800 for 8 hours). |
    | `day`                  | list    | Days on which the schedule is active (e.g., `Monday`).         |
    | `start_time`           | string  | Start time of the schedule in `HH:MM` format (24-hour clock).  |
    
    ## Explanation of Key Options
    
    ### `filter_text`
    
    - If a URL contains any of these strings, it will be blocked.
    
    ### `custom_url`
    
    - Allows manually defining individual URLs for blocking.
    - The IP addresses for these URLs are added to cache on start up, thus, these will be blocked even if someone alters the DNS configuration of the device.
    
    ### `download_url`
    
    - Specifies a source (local or remote) from where URL bundles can be fetched.
    
    ---
    
    ## Sample UCI configuration
    
    ````bash
    # cat /etc/config/parentalcontrol
    
    config globals 'globals'
    	option enable '1'
    
    config profile 'profile_1'
    	option name 'kids'
    	list host 'aa:00:aa:92:01:01'
    	list host ' D_wan_53_1'
    	list internet_break_schedule 'schedule_1'
    	option internet_break_enable '1'
    	option bedtime_enable '1'
    
    config profile_urlfilter 'profile_1_profile_urlfilter_1'
    	option dm_parent 'profile_1'
    	option access 'Deny'
    	list filter_text 'youtube.com'
    	list profile_urlfilter_schedule 'schedule_1'
    	option enable '1'
    	list profile_urlbundle 'b_kids'
    	list profile_urlbundle 'b_kids1'
    	list profile_urlbundle 'b_kids2'
    	list profile_urlbundle 'b_kids3'
    
    config urlbundle 'urlbundle_1'
    	option name 'b_kids'
    
    	option download_url 'file:///tmp/urlfilter/default/urlbundles/abuse'
    	list custom_url 'facebook.com'
    
    config urlbundle 'urlbundle_2'
    	option name 'b_kids1'
    
    	option download_url 'file:///tmp/urlfilter/default/urlbundles/facebook'
    
    config urlbundle 'urlbundle_3'
    	option name 'b_kids2'
    
    	option download_url 'file:///tmp/urlfilter/default/urlbundles/tiktok'
    
    config urlbundle 'urlbundle_4'
    	option name 'b_kids3'
    
    	option download_url 'file:///tmp/urlfilter/default/urlbundles/porn'
    
    config profile_bedtime_schedule 'profile_1_profile_bedtime_schedule_1'
    	option dm_parent 'profile_1'
    	list day 'Monday'
    	list day 'Tuesday'
    	list day 'Wednesday'
    	option start_time '23:00'
    	option end_time '05:00'
    	option enable '1'
    ````
    
    ````bash
    # cat /etc/config/schedules
    
    config global 'global'
    	option enable '1'
    
    config schedule 'schedule_1'
    	option enable '1'
    	option duration '28800'
    	list day 'Monday'
    	list day 'Tuesday'
    	list day 'Wednesday'
    	list day 'Thursday'
    	list day 'Friday'
    	option start_time '09:00'
    ````
    
    ## Data model configuration
    
    ### URL Filter
    ````bash
    
    bbfdmd -c add Device.X_IOWRT_EU_ParentalControl.Profile.
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.HostList 'aa:00:aa:92:01:01, D_wan_53_1'
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.Name 'kids'
    bbfdmd -c add Device.X_IOWRT_EU_ParentalControl.Profile.1.URLFilter.
    bbfdmd -c add Device.X_IOWRT_EU_ParentalControl.URLBundle.
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.1.Name 'b_kids'
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.1.DownloadURL "file:///tmp/urlfilter/default/urlbundles/abuse"
    
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.1.Enable '1'
    
    bbfdmd -c add Device.X_IOWRT_EU_ParentalControl.URLBundle.
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.2.Name 'b_kids1'
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.2.DownloadURL "file:///tmp/urlfilter/default/urlbundles/facebook"
    
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.2.Enable '1'
    
    bbfdmd -c add Device.X_IOWRT_EU_ParentalControl.URLBundle.
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.3.Name 'b_kids2'
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.3.DownloadURL "file:///tmp/urlfilter/default/urlbundles/tiktok"
    
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.3.Enable '1'
    
    bbfdmd -c add Device.X_IOWRT_EU_ParentalControl.URLBundle.
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.4.Name 'b_kids3'
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.4.DownloadURL "file:///tmp/urlfilter/default/urlbundles/porn"
    
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.URLBundle.4.Enable '1'
    
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.URLFilter.1.URLBundleRef "Device.X_IOWRT_EU_ParentalControl.URLBundle.1,Device.X_IOWRT_EU_ParentalControl.URLBundle.2,Device.X_IOWRT_EU_ParentalControl.URLBundle.3,Device.X_IOWRT_EU_ParentalControl.URLBundle.4"
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Enable 1
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.URLFilter.1.Enable 1
    
    ````
    
    ### Internet break
    
    ````bash
    
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.InternetBreak.ScheduleRef Device.Schedules.Schedule.1
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.InternetBreak.Enable 1
    
    bbfdmd -c add Device.X_IOWRT_EU_ParentalControl.Profile.1.BedTime.Schedule.
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.BedTime.Schedule.1.Days 'Monday,Tuesday,Wednesday'
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.BedTime.Schedule.1.StartTime '23:00'
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.BedTime.Schedule.1.EndTime '05:00'
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.BedTime.Schedule.1.Enable 1
    bbfdmd -c set Device.X_IOWRT_EU_ParentalControl.Profile.1.BedTime.Enable 1