Home

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 - optional - The array with the full list of MAC addresses that can be blocked.
• 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.

{
    "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] }
    ]
}

Hex MsgPack:

00000000: 83a6 7765 656b 6c79 9382 a474 696d 650a  ..weekly...time.
00000010: a769 6e64 6578 6573 9300 0103 82a4 7469  .indexes......ti
00000020: 6d65 14a7 696e 6465 7865 7391 0082 a474  me..indexes....t
00000030: 696d 651e a769 6e64 6578 6573 c0a4 6d61  ime..indexes..ma
00000040: 6373 94b1 3131 3a32 323a 3333 3a34 343a  cs..11:22:33:44:
00000050: 3535 3a61 61b1 3232 3a33 333a 3434 3a35  55:aa.22:33:44:5
00000060: 353a 3636 3a62 62b1 3333 3a34 343a 3535  5:66:bb.33:44:55
00000070: 3a36 363a 3737 3a63 63b1 3434 3a35 353a  :66:77:cc.44:55:
00000080: 3636 3a37 373a 3838 3a64 64a8 6162 736f  66:77:88:dd.abso
00000090: 6c75 7465 9182 a975 6e69 785f 7469 6d65  lute...unix_time
000000a0: ce59 e583 17a7 696e 6465 7865 7392 0002  .Y....indexes...

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.

{
    "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}
    ]

Helpful Things

If the weekly is not present, the default semantics are to not block any MAC addresses.

If the absolute is not present, there is no affect on the lists of blocked MAC addresses.

Don't want to hand encode from JSON to Msgpack? Neither do we! This tool makes the process simple & painless:

http://kawanet.github.io/msgpack-lite/