Update README.md
This commit is contained in:
jessikitty committed
1 parent
28e2bf167f
commit
3c9bc381c6
1 file changed
+119
-1
@@ -1 +1,119 @@
|
||||
IyBoYS1wYXJlbnRhbC1jb250cm9scwoKQSBIb21lIEFzc2lzdGFudCBkYXNoYm9hcmQgZm9yIHBlci11c2VyLCBwZXItZGV2aWNlIGludGVybmV0IGJsb2NraW5nIHZpYSBPUE5zZW5zZSBmaXJld2FsbCBhbGlhcyBtYW5hZ2VtZW50LiBBc3NpZ24gZGV2aWNlcyB0byB1c2VycyBieSBNQUMgYWRkcmVzcywgYmxvY2svdW5ibG9jayBpbmRpdmlkdWFsbHkgb3IgcGVyLXVzZXIsIGFuZCBvcHRpb25hbGx5IGVuZm9yY2Ugc2NoZWR1bGVkIGFjY2VzcyB3aW5kb3dzLgoKLS0tCgojIyBIb3cgaXQgd29ya3MKCjEuIE9QTnNlbnNlIG1haW50YWlucyBhIGZpcmV3YWxsIGFsaWFzIGNhbGxlZCBgcGFyZW50YWxfYmxvY2tlZGAKMi4gQSBMQU4gcnVsZSBibG9ja3MgYWxsIHRyYWZmaWMgZnJvbSBJUHMgaW4gdGhhdCBhbGlhcwozLiBUaGUgSEEgZGFzaGJvYXJkIGxvb2tzIHVwIGVhY2ggZGV2aWNlJ3MgY3VycmVudCBJUCBmcm9tIGBkZXZpY2VfdHJhY2tlcmAgZW50aXRpZXMgKHByb3ZpZGVkIGJ5IHRoZSBPUE5zZW5zZSBpbnRlZ3JhdGlvbiksIHRoZW4gYWRkcy9yZW1vdmVzIElQcyBmcm9tIHRoZSBhbGlhcyB2aWEgT1BOc2Vuc2UgQVBJCgpCZWNhdXNlIGRldmljZXMgYXJlIGlkZW50aWZpZWQgYnkgKipNQUMgYWRkcmVzcyoqLCBibG9ja3MgcmUtYXBwbHkgYXV0b21hdGljYWxseSB3aGVuIGEgZGV2aWNlIHJlY29ubmVjdHMgd2l0aCBhIG5ldyBJUCAoaGFuZGxlZCBieSBhIHN0YXRlIGNoYW5nZSBsaXN0ZW5lciBpbiB0aGUgZGFzaGJvYXJkKS4KCi0tLQoKIyMgU3RlcCAxIOKAlCBPUE5zZW5zZSBzZXR1cAoKIyMjIDEuMSBDcmVhdGUgdGhlIGZpcmV3YWxsIGFsaWFzCgpGaXJld2FsbCDihpIgQWxpYXNlcyDihpIg77yLCgp8IEZpZWxkIHwgVmFsdWUgfAp8LS0tfC0tLXwKfCBOYW1lIHwgYHBhcmVudGFsX2Jsb2NrZWRgIHwKfCBUeXBlIHwgYEhvc3QocylgIHwKfCBEZXNjcmlwdGlvbiB8IGBQYXJlbnRhbCBDb250cm9scyDigJQgYmxvY2tlZCBkZXZpY2VzYCB8CnwgQ29udGVudCB8ICoobGVhdmUgZW1wdHkg4oCUIG1hbmFnZWQgdmlhIEFQSSkqIHwKClNhdmUsIHRoZW4gKipBcHBseSoqLgoKIyMjIDEuMiBDcmVhdGUgdGhlIGJsb2NraW5nIHJ1bGUKCkZpcmV3YWxsIOKGkiBSdWxlcyDihpIgTEFOIOKGkiDvvIsKCnwgRmllbGQgfCBWYWx1ZSB8CnwtLS18LS0tfAp8IEFjdGlvbiB8ICoqQmxvY2sqKiB8CnwgSW50ZXJmYWNlIHwgTEFOIHwKfCBEaXJlY3Rpb24gfCBpbiB8CnwgUHJvdG9jb2wgfCBhbnkgfAp8IFNvdXJjZSB8IFNpbmdsZSBob3N0IG9yIGFsaWFzIOKGkiBgcGFyZW50YWxfYmxvY2tlZGAgfAp8IERlc3RpbmF0aW9uIHwgYW55IHwKfCBEZXNjcmlwdGlvbiB8IGBQYXJlbnRhbCBDb250cm9scyDigJQgYmxvY2sgaW50ZXJuZXRgIHwKClBvc2l0aW9uIHRoaXMgcnVsZSAqKmFib3ZlKiogeW91ciBkZWZhdWx0IGFsbG93LWFsbCBMQU4gcnVsZS4gU2F2ZSBhbmQgQXBwbHkuCgojIyMgMS4zIENyZWF0ZSBhbiBBUEkga2V5CgpTeXN0ZW0g4oaSIEFjY2VzcyDihpIgVXNlcnMg4oaSICh5b3VyIGFkbWluIHVzZXIgb3IgYSBkZWRpY2F0ZWQgdXNlcikg4oaSIEFQSSBLZXlzIOKGkiDvvIsKClBlcm1pc3Npb25zIG5lZWRlZDogKipGaXJld2FsbDogQWxpYXMqKiAocmVhZCArIHdyaXRlKQoKTm90ZSB0aGUgKipLZXkqKiBhbmQgKipTZWNyZXQqKiDigJQgeW91J2xsIG5lZWQgdGhlbSBmb3Igc2VjcmV0cy55YW1sLgoKLS0tCgojIyBTdGVwIDIg4oCUIEhvbWUgQXNzaXN0YW50IHNldHVwCgojIyMgMi4xIEFkZCBzZWNyZXRzIHRvIGAvY29uZmlnL3NlY3JldHMueWFtbGAKClJlcGxhY2UgdmFsdWVzIHdpdGggeW91ciBhY3R1YWwgT1BOc2Vuc2UgZGV0YWlsczoKCmBgYHlhbWwKb3Buc2Vuc2VfYWxpYXNfYWRkX3VybDogImh0dHBzOi8vWU9VUl9PUE5TRU5TRV9JUC9hcGkvZmlyZXdhbGwvYWxpYXNfdXRpbC9hZGQvcGFyZW50YWxfYmxvY2tlZCIKb3Buc2Vuc2VfYWxpYXNfZGVsX3VybDogImh0dHBzOi8vWU9VUl9PUE5TRU5TRV9JUC9hcGkvZmlyZXdhbGwvYWxpYXNfdXRpbC9kZWxldGUvcGFyZW50YWxfYmxvY2tlZCIKb3Buc2Vuc2VfYXBwbHlfdXJsOiAiaHR0cHM6Ly9ZT1VSX09QTlNFTlNFX0lQL2FwaS9maXJld2FsbC9hbGlhcy9yZWNvbmZpZ3VyZSIKCiMgR2VuZXJhdGUgd2l0aDogZWNobyAtbiAiQVBJS0VZOkFQSVNFQ1JFVCIgfCBiYXNlNjQKb3Buc2Vuc2VfYmFzaWNfYXV0aDogIkJhc2ljIEJBU0U2NF9PRl9LRVlfQ09MT05fU0VDUkVUIgpgYGAKClRvIGdlbmVyYXRlIHRoZSBiYXNlNjQgc3RyaW5nIG9uIGFueSBMaW51eC9tYWNPUyBtYWNoaW5lOgpgYGBiYXNoCmVjaG8gLW4gInlvdXJfYXBpX2tleTp5b3VyX2FwaV9zZWNyZXQiIHwgYmFzZTY0CmBgYAoKIyMjIDIuMiBDb3B5IGZpbGVzIGludG8gcGxhY2UKCmBgYGJhc2gKIyBGcm9tIHlvdXIgY29uZmlnIGRpcmVjdG9yeQpjcCBwYWNrYWdlcy9wYXJlbnRhbF9jb250cm9scy55YW1sIC9jb25maWcvcGFja2FnZXMvCmNwIHd3dy9wYXJlbnRhbF9jb250cm9scy5odG1sIC9jb25maWcvd3d3LwpgYGAKCj4gSWYgeW91IGRvbid0IHVzZSBwYWNrYWdlcyB5ZXQsIGFkZCB0aGlzIHRvIGAvY29uZmlnL2NvbmZpZ3VyYXRpb24ueWFtbGA6Cj4gYGBgeWFtbAo+IGhvbWVhc3Npc3RhbnQ6Cj4gICBwYWNrYWdlczogIWluY2x1ZGVfZGlyX25hbWVkIHBhY2thZ2VzCj4gYGBgCgojIyMgMi4zIEFkZCB0aGUgc2lkZWJhciBwYW5lbAoKQWRkIHRvIGAvY29uZmlnL2NvbmZpZ3VyYXRpb24ueWFtbGA6CgpgYGB5YW1sCnBhbmVsX2lmcmFtZToKICBwYXJlbnRhbF9jb250cm9sczoKICAgIHRpdGxlOiAiUGFyZW50YWwgQ29udHJvbHMiCiAgICBpY29uOiBtZGk6c2hpZWxkLWFjY291bnQKICAgIHVybDogL2xvY2FsL3BhcmVudGFsX2NvbnRyb2xzLmh0bWwKICAgIHJlcXVpcmVfYWRtaW46IHRydWUKYGBgCgojIyMgMi40IFJlc3RhcnQgSG9tZSBBc3Npc3RhbnQKCkNoZWNrIGZvciBlcnJvcnMgaW4gU2V0dGluZ3Mg4oaSIFN5c3RlbSDihpIgTG9ncy4gVGhlIGBpbnB1dF90ZXh0LnBhcmVudGFsX2NvbnRyb2xfY29uZmlnYCBlbnRpdHkgc2hvdWxkIG5vdyBleGlzdC4KCi0tLQoKIyMgU3RlcCAzIOKAlCBEYXNoYm9hcmQgZmlyc3QgcnVuCgoxLiBPcGVuIHRoZSAqKlBhcmVudGFsIENvbnRyb2xzKiogc2lkZWJhciBwYW5lbAoyLiBPbiBmaXJzdCBsb2FkLCB5b3UnbGwgc2VlIGEgc2V0dXAgc2NyZWVuLiBFbnRlcjoKICAgLSAqKkhBIFVSTCoqOiB5b3VyIEhBIFVSTCAoZS5nLiBgaHR0cHM6Ly9oYS5oaWRlYXdheWdhbWluZy5jb20uYXVgKQogICAtICoqTG9uZy1MaXZlZCBUb2tlbioqOiBmcm9tIHlvdXIgSEEgUHJvZmlsZSDihpIgU2VjdXJpdHkg4oaSIExvbmctTGl2ZWQgQWNjZXNzIFRva2VucyDihpIgQ3JlYXRlIFRva2VuCjMuIENsaWNrICoqQ29ubmVjdCoqCgpZb3VyIGNyZWRlbnRpYWxzIGFyZSBzYXZlZCB0byBicm93c2VyIGBsb2NhbFN0b3JhZ2VgIOKAlCB5b3Ugd29uJ3QgbmVlZCB0byBlbnRlciB0aGVtIGFnYWluIG9uIHRoZSBzYW1lIGRldmljZS4KCi0tLQoKIyMgVXNhZ2UKCiMjIyBBZGRpbmcgdXNlcnMKCkNsaWNrICoq77yLIEFkZCBVc2VyKiosIGdpdmUgdGhlbSBhIG5hbWUgYW5kIHBpY2sgYSBjb2xvdXIuCgojIyMgQWRkaW5nIGRldmljZXMKCk9uIGEgdXNlciBjYXJkLCBjbGljayAqKu+8iyBBZGQgRGV2aWNlKiouIEVpdGhlcjoKLSBQaWNrIGZyb20gdGhlICoqZGlzY292ZXJlZCBkZXZpY2VzKiogbGlzdCAoZGV2aWNlcyBLine truncated
|
||||
ha-parental-controls
|
||||
A Home Assistant dashboard for per-user, per-device internet blocking via OPNsense firewall alias management. Assign devices to users by MAC address, block/unblock individually or per-user, and optionally enforce scheduled access windows.
|
||||
|
||||
How it works
|
||||
|
||||
OPNsense maintains a firewall alias called parental_blocked
|
||||
A LAN rule blocks all traffic from IPs in that alias
|
||||
The HA dashboard looks up each device's current IP from device_tracker entities (provided by the OPNsense integration), then adds/removes IPs from the alias via OPNsense API
|
||||
|
||||
Because devices are identified by MAC address, blocks re-apply automatically when a device reconnects with a new IP (handled by a state change listener in the dashboard).
|
||||
|
||||
Step 1 — OPNsense setup
|
||||
1.1 Create the firewall alias
|
||||
Firewall → Aliases → ＋
|
||||
FieldValueNameparental_blockedTypeHost(s)DescriptionParental Controls — blocked devicesContent(leave empty — managed via API)
|
||||
Save, then Apply.
|
||||
1.2 Create the blocking rule
|
||||
Firewall → Rules → LAN → ＋
|
||||
FieldValueActionBlockInterfaceLANDirectioninProtocolanySourceSingle host or alias → parental_blockedDestinationanyDescriptionParental Controls — block internet
|
||||
Position this rule above your default allow-all LAN rule. Save and Apply.
|
||||
1.3 Create an API key
|
||||
System → Access → Users → (your admin user or a dedicated user) → API Keys → ＋
|
||||
Permissions needed: Firewall: Alias (read + write)
|
||||
Note the Key and Secret — you'll need them for secrets.yaml.
|
||||
|
||||
Step 2 — Home Assistant setup
|
||||
2.1 Add secrets to /config/secrets.yaml
|
||||
Replace values with your actual OPNsense details:
|
||||
yamlopnsense_alias_add_url: "https://YOUR_OPNSENSE_IP/api/firewall/alias_util/add/parental_blocked"
|
||||
opnsense_alias_del_url: "https://YOUR_OPNSENSE_IP/api/firewall/alias_util/delete/parental_blocked"
|
||||
opnsense_apply_url: "https://YOUR_OPNSENSE_IP/api/firewall/alias/reconfigure"
|
||||
|
||||
# Generate with: echo -n "APIKEY:APISECRET" | base64
|
||||
opnsense_basic_auth: "Basic BASE64_OF_KEY_COLON_SECRET"
|
||||
To generate the base64 string on any Linux/macOS machine:
|
||||
bashecho -n "your_api_key:your_api_secret" | base64
|
||||
2.2 Copy files into place
|
||||
bash# From your config directory
|
||||
cp packages/parental_controls.yaml /config/packages/
|
||||
cp www/parental_controls.html /config/www/
|
||||
|
||||
If you don't use packages yet, add this to /config/configuration.yaml:
|
||||
yamlhomeassistant:
|
||||
packages: !include_dir_named packages
|
||||
|
||||
2.3 Add the sidebar panel
|
||||
Add to /config/configuration.yaml:
|
||||
yamlpanel_iframe:
|
||||
parental_controls:
|
||||
title: "Parental Controls"
|
||||
icon: mdi:shield-account
|
||||
url: /local/parental_controls.html
|
||||
require_admin: true
|
||||
2.4 Restart Home Assistant
|
||||
Check for errors in Settings → System → Logs. The input_text.parental_control_config entity should now exist.
|
||||
|
||||
Step 3 — Dashboard first run
|
||||
|
||||
Open the Parental Controls sidebar panel
|
||||
On first load, you'll see a setup screen. Enter:
|
||||
|
||||
HA URL: your HA URL (e.g. https://ha.hideawaygaming.com.au)
|
||||
Long-Lived Token: from your HA Profile → Security → Long-Lived Access Tokens → Create Token
|
||||
|
||||
|
||||
Click Connect
|
||||
|
||||
Your credentials are saved to browser localStorage — you won't need to enter them again on the same device.
|
||||
|
||||
Usage
|
||||
Adding users
|
||||
Click ＋ Add User, give them a name and pick a colour.
|
||||
Adding devices
|
||||
On a user card, click ＋ Add Device. Either:
|
||||
|
||||
Pick from the discovered devices list (devices seen by the OPNsense integration)
|
||||
Or enter a MAC address manually
|
||||
|
||||
|
||||
Tip: Set DHCP static leases in OPNsense for kids' devices so their IPs stay consistent, though the dashboard handles IP changes automatically.
|
||||
|
||||
Blocking
|
||||
|
||||
User toggle (top right of card): blocks/unblocks all devices for that user simultaneously
|
||||
Device toggle (on each device row): individual device control
|
||||
|
||||
If a device is offline when you block it, the dashboard marks it blocked and will apply the firewall rule automatically when the device reconnects.
|
||||
Scheduling
|
||||
Expand the 🕐 Schedule section on any user card:
|
||||
|
||||
Enable the schedule toggle
|
||||
Set block and unblock times for weekdays and weekends
|
||||
Times are enforced every minute while the dashboard page is open
|
||||
|
||||
The time range is the blocked window — e.g. 21:00 → 07:00 means blocked from 9pm until 7am (overnight ranges work correctly).
|
||||
HA-native schedule enforcement (optional)
|
||||
For schedules to be enforced even when the dashboard isn't open, uncomment the automation: block at the bottom of packages/parental_controls.yaml and restart HA. Note: the YAML automation requires the from_json Jinja2 filter and HA 2023.4+.
|
||||
|
||||
Troubleshooting
|
||||
Block doesn't seem to apply
|
||||
|
||||
Confirm the parental_blocked alias exists in OPNsense → Firewall → Aliases
|
||||
Check the blocking rule is above the default LAN allow rule
|
||||
Verify your API credentials: test in a browser → https://YOUR_OPNSENSE/api/firewall/alias_util/aliases — should return JSON
|
||||
|
||||
Device not appearing in discovered list
|
||||
|
||||
Make sure the OPNsense integration is installed and the device has been seen recently
|
||||
Try using a manual MAC entry instead
|
||||
|
||||
"Failed to save config"
|
||||
|
||||
Check HA logs for input_text.parental_control_config errors
|
||||
Ensure the package loaded correctly (no YAML errors in startup logs)
|
||||
|
||||
Dashboard won't connect
|
||||
|
||||
Confirm the Long-Lived Token is correct
|
||||
If using a self-signed cert on HA, the page may have cert warnings — trust the cert first by visiting the HA URL directly
|
||||
Reference in new issue
Block a user