Skip to content
Snippets Groups Projects
quickstart.md 9.77 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_IOPSYS_EU_ParentalControl.Profile.
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.HostList 'aa:00:aa:92:01:01, D_wan_53_1'
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.Name 'kids'
    bbfdmd -c add Device.X_IOPSYS_EU_ParentalControl.Profile.1.URLFilter.
    bbfdmd -c add Device.X_IOPSYS_EU_ParentalControl.URLBundle.
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.URLBundle.1.Name 'b_kids'
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.URLBundle.1.DownloadURL "file:///tmp/urlfilter/default/urlbundles/abuse"
    bbfdmd -c add Device.X_IOPSYS_EU_ParentalControl.URLBundle.
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.URLBundle.2.Name 'b_kids1'
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.URLBundle.2.DownloadURL "file:///tmp/urlfilter/default/urlbundles/facebook"
    bbfdmd -c add Device.X_IOPSYS_EU_ParentalControl.URLBundle.
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.URLBundle.3.Name 'b_kids2'
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.URLBundle.3.DownloadURL "file:///tmp/urlfilter/default/urlbundles/tiktok"
    bbfdmd -c add Device.X_IOPSYS_EU_ParentalControl.URLBundle.
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.URLBundle.4.Name 'b_kids3'
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.URLBundle.4.DownloadURL "file:///tmp/urlfilter/default/urlbundles/porn"
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.URLFilter.1.URLBundleRef "Device.X_IOPSYS_EU_ParentalControl.URLBundle.1,Device.X_IOPSYS_EU_ParentalControl.URLBundle.2,Device.X_IOPSYS_EU_ParentalControl.URLBundle.3,Device.X_IOPSYS_EU_ParentalControl.URLBundle.4"
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Enable 1
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.URLFilter.1.Enable 1
    ````
    
    ### Internet break
    
    ````bash
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.InternetBreak.ScheduleRef Device.Schedules.Schedule.1
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.InternetBreak.Enable 1
    ````
    
    ### Bedtime
    
    ````bash
    bbfdmd -c add Device.X_IOPSYS_EU_ParentalControl.Profile.1.BedTime.Schedule.
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.BedTime.Schedule.1.Days 'Monday,Tuesday,Wednesday'
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.BedTime.Schedule.1.StartTime '23:00'
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.BedTime.Schedule.1.EndTime '05:00'
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.BedTime.Schedule.1.Enable 1
    bbfdmd -c set Device.X_IOPSYS_EU_ParentalControl.Profile.1.BedTime.Enable 1
    ````
    
    ## Ubus Calls
    
    The following Ubus calls are supported by the application:
    
    ### `show_config`
    
    - Displays the current `parentalcontrol` and `schedules` configurations.
    
    ````bash
    # ubus call urlfilter show_config
    {
    	"profiles": [
    		{
    			"profile": "profile_1",
    			"host": [
    				"aa:00:aa:92:01:01"
    			],
    			"urlfilter": {
    				"parent": "profile_1",
    				"access_policy": "deny",
    				"filter_text": [
    					"youtube.com"
    				],
    				"urlbundle": {
    					"name": "b_kids",
    					"custom_url": [
    						"facebook.com"
    					]
    				},
    				"urlbundle": {
    					"name": "b_kids1",
    					"custom_url": [
    
    					]
    				},
    				"urlbundle": {
    					"name": "b_kids2",
    					"custom_url": [
    
    					]
    				},
    				"urlbundle": {
    					"name": "b_kids3",
    					"custom_url": [
    
    					]
    				},
    				"schedule": {
    					"enable": "enabled",
    					"duration": 28800,
    					"start_time": "09:00",
    					"weekdays": [
    						"inactive",
    						"active",
    						"active",
    						"active",
    						"active",
    						"active",
    						"inactive"
    					]
    				}
    			}
    		}
    	]
    }
    ````
    
    ### `dump`
    
    - Dumps the active URL filter rules along with scheduling information.
    
    ````bash
    # ubus call urlfilter dump
    {
    	"dns_cache": [
    		{
    			"url": "facebook.com",
    			"hits": 0,
    			"ipv4_addr": [
    				{
    					"addr": "54.153.56.183"
    				}
    			]
    		}
    	],
    	"url_list": [
    		{
    			"url": "youtube.com",
    			"hits": 0
    		},
    		{
    			"url": "facebook.com",
    			"hits": 0
    		}
    	],
    	"dns_server": [
    		{
    			"server": "172.30.30.108"
    		},
    		{
    			"server": "2001:db8:1::53"
    		}
    	]
    }
    ````
    
    ### `default_bundles`
    
    - Lists the default URL bundles available for filtering.
    
    ````bash
    # ubus call urlfilter default_bundles
    {
    	"default_bundles": "abuse,tracking,ads,porn,redirect,facebook,fraud,scam,torrent,drugs,piracy,tiktok,gambling,crypto"
    }
    ````
    
    ---