Skip to content

Home

Jump to bottom
Weston Schmidt edited this page Sep 30, 2021 · 15 revisions

Goal

Aker is an experimental module for selectively blocking MAC addresses based on a succinct schedule in MsgPack.

The primary goal for Aker is to accept a weekly schedule with the optional exceptions added to the schedule so that there is very little interaction between Aker and it's controlling agent. Aker will ultimately call another program (passed by command line arguments) with a list of MAC addresses to block at the time they should be blocked - replacing any previously existing schedule.

Ultimately Aker will choose either the weekly or the absolute to apply for any defined times. If both define a window that overlap, the absolute is chosen. Aker is designed to do what it's told & not to try to merge schedules.

Schedule Schema

Below is an example schema represented in JSON for clarity, then MsgPack for accuracy.

  • weekly - optional - This is the section of the document that describes the recurring weekly schedule.
  • time - required - The number of seconds since the most recent Sunday midnight defining the starting time to block this list of MAC addresses. 12:00:01 AM is time = 1.
  • indexes - required - The list of indexes into the macs array to apply during this window of time.
  • macs - required - The array with the full list of MAC addresses that can be blocked. If present and empty, the schedule is considered invalid.
  • absolute - optional - This is the section of the document that describes the window of time that replaces the normal weekly schedule. All times in the absolute schedule are considered contiguous and are required to fully express the schedule. At the point in time where the latest unix_time entry is encountered, this entry is applied and is in effect until the next scheduled event in the absolute will be triggered.
  • unix_time - required - The unix time (number of seconds since January 1, 1970) defining the starting time to block this list of MAC addresses. Additionally, the special value of 0 is allowed to indicate a time that has passed in order to accommodate slight clock differences between client and server.
  • time_zone - required - The time zone name the weekly portion of the schedule is referenced to.
  • report_rate - optional (default: 0) - The number of seconds between metrics reports sent through Xmidt. A random value between 0 and report_rate is added to the reports to prevent spikes. The value 0 indicates no report should be sent. The shortest reporting rate permitted is 3600 seconds (1 hour) in 1.1.0.

If both weekly and absolute are missing or empty, the schedule is considered invalid.

{
    "time_zone": "America/New_York",

    "weekly": [
        { "time": 10, "indexes": [0, 1, 3] },
        { "time": 20, "indexes": [0] },
        { "time": 30, "indexes": null }
    ],

    "macs": [
        "11:22:33:44:55:aa",
        "22:33:44:55:66:bb",
        "33:44:55:66:77:cc",
        "44:55:66:77:88:dd"
    ],

    "absolute": [
        { "unix_time": 1508213527, "indexes": [0, 2] }
    ],

    "report_rate": 3600
}

Hex MsgPack:

00000000: 85a9 7469 6d65 5f7a 6f6e 65b0 416d 6572  ..time_zone.Amer
00000010: 6963 612f 4e65 775f 596f 726b a677 6565  ica/New_York.wee
00000020: 6b6c 7993 82a4 7469 6d65 0aa7 696e 6465  kly...time..inde
00000030: 7865 7393 0001 0382 a474 696d 6514 a769  xes......time..i
00000040: 6e64 6578 6573 9100 82a4 7469 6d65 1ea7  ndexes....time..
00000050: 696e 6465 7865 73c0 a46d 6163 7394 b131  indexes..macs..1
00000060: 313a 3232 3a33 333a 3434 3a35 353a 6161  1:22:33:44:55:aa
00000070: b132 323a 3333 3a34 343a 3535 3a36 363a  .22:33:44:55:66:
00000080: 6262 b133 333a 3434 3a35 353a 3636 3a37  bb.33:44:55:66:7
00000090: 373a 6363 b134 343a 3535 3a36 363a 3737  7:cc.44:55:66:77
000000a0: 3a38 383a 6464 a861 6273 6f6c 7574 6591  :88:dd.absolute.
000000b0: 82a9 756e 6978 5f74 696d 65ce 59e5 8317  ..unix_time.Y...
000000c0: a769 6e64 6578 6573 9200 02ab 7265 706f  .indexes....repo
000000d0: 7274 5f72 6174 65cd 0e10                 rt_rate...

Example Use Cases

A simple schedule on an account with two devices, the first of which is blocked on school nights from 9:00 PM to 9:00 AM.

{
    "time_zone": "America/New_York",
    "macs": [
        "11:22:33:44:55:aa",
        "66:77:88:99:ee:ff"
    ],
    "weekly": [
        { "time": 75600, "indexes": [0] },
        { "time": 118800, "indexes": null },
        { "time": 162000, "indexes": [0] },
        { "time": 205200, "indexes": null },
        { "time": 248400, "indexes": [0] },
        { "time": 291600, "indexes": null },
        { "time": 334800, "indexes": [0] },
        { "time": 378000, "indexes": null },
        { "time": 421200, "indexes": [0] },
        { "time": 464400, "indexes": null }
    ]
}

A modification on the above account, with the intention of blocking access from now (January 1st, 2020, 6:00PM) for the duration of one hour. This occurs outside of the normal blocked window.

    // ...
    "absolute": [
        { "unix_time": 1577901600, "indexes": [0]},
        { "unix_time": 1577905200, "indexes": null}
    ]

A modification of the first example, with the intention of canceling the blockage of any devices for the duration of the rest of the evening (January 1st, 2020, 6:00PM). This occurs outside of the normal blocked window. Note this simply replaces the next regularly scheduled event.

    // ...
    "absolute": [
        { "unix_time": 1577912400, "indexes": null}
    ]

A modification of the first example, with the intention of canceling the blockage of any devices for the duration of the rest of the evening starting now (January 1st, 2020, 10:00PM). This occurs during an active block window. Note the ending event is required and coincides with a regularly scheduled event. This is necessary to determine the natural expiration of the absolute schedule when a value of 0 is used to indicate the immediate start of this schedule.

    // ...
    "absolute": [
        { "unix_time": 0, "indexes": null},
        { "unix_time": 1577955600, "indexes": null}
    ]

Timezone Data

Aker depends on the POSIX timezone data. If the platform running Aker has an incomplete or reduced list of timezones, there is nothing Aker will do to correct that. It is up to the producer of schedules to coordinate with the list of available timezones on the target device. This coordination is outside the scope of Aker.

Helpful Things

Clone this wiki locally