WEB_FRONTEND_MANUAL.md

Web-Frontend Manual

This page describes the web frontend of LittleBrother which usually can be reached at http://localhost:5555 on your local machine. It offers access to status information (without login) and a configuration interface (with login).

Listing the Status

The menu entry "Status" lists the monitored users. The top level shows the summary of the play times.

A blinking entry denotes an active login. In case the user is currently allowed to play (see green check mark) the column "reasons" shows the estimated remaining play times for the current session (if logged in) and for the day. If the user is currently blocked (see red cross) the same column shows the reasons why the user is not permitted to play and the estimated remaining play time for the day.

The columns contain the following details:

• Context: Shows the active rule set context for the day.

• Today's Activity: Shows the overall active time and the maximum activity duration for the current day. If one of the hosts had a downtime, this column will also show the detected downtime (in yellow) which will be subtracted from the play time.

• Previous Activity Start Time: the time of day when the most recent (except for the current) activity started.

• Previous Activity End Time: the time of day when the most recent (except for the current) activity ended.

• Current Activity Start Time: the time of day when the current activity started. If the user is not currently logged in this column will be empty. If there is a current activity, this value will be blinking.

• Current Activity Duration: the time duration of the current activity. If the user is not currently logged in this column will be empty. If there is a current activity, this value will be blinking.

The second level can be opened by clicking on the name of a user. It will show the daily play time, the number of logins and the hosts of the last seven days of the selected user.

The columns contain the following details:

• Active Time: The overall play time on that day.
• Activity Start: The earliest login of the user on that day.
• Activity Start: The latest logout of the user on that day.
• Host(#procs): A list of hosts that the user logged into on that day including the number of logins on each host.

The third level can be opened by clicking on a day summary of a user. It will show the individual play times and hosts of the selected user on the selected day. The entries are sorted by the start time in descending order with the most recent entry at the top.

About Page

The page shows some status information of the installed version of LittleBrother and a list of supported languages. When reporting issues on GitHub it is usually very helpful for the developers if you include the Git Commit ID into your issue text.

Logging In

The status page and the about page are accessible without login. All other pages require the login credentials of an administration user. Currently, the name of the administration user defaults to admin. The password needs to be set in the configuration file (see the main README).

After successful login the user will be display in the menu bar.

Checking the Topology of the LittleBrother Network

Although LittleBrother can run on a single PC (master), it is possible to monitor several client PCs at the same time. In order to keep the overview over the network of PCs the tab Topology provides a list of the currently known PCs.

It shows the master and all client nodes with the following columns:

• Node Type: Denotes the type of node ("Master" or "Client"). There is exactly one master and 0..N clients. If the node process is running in a Docker container it will have an additional (Docker) remark.

• Node Name: Denotes the unique name of the node. It usually corresponds to the host DNS name, but it can be set in the configuration file.

• App Version: Denotes the version of the LittleBrother process on that node.

• Revision: Denotes the revision of the LittleBrother process on that node.

• Distribution: Denotes the Linux distribution running on that node as reported by package distro.

• Python Version: Denotes the version of the Python interpreter running the LittleBrother process on that node.

• Time Since Last Ping: Denotes the time since the master has received the most recent statistics from that node. Since the default ping time is five seconds this value will usually not exceed four seconds.

Detection of Suspicious Constellations

There is some support for detecting suspicious configuration constellations by highlighting value in the table above in red.

Outdated Clients and Version Checks

If a client is detected whose version is older than 0.3.9 the additional metadata (AppVersion, Revision and Python Version) is not available. In this case the AppVersion will show "< 0.3.9" in red color. If the client version is smaller than the master version, the AppVersion will also show in red. See screenshot above.

As of version 0.4.9 of LittleBrother the master node will check SourceForge for versions automatically. If a new version is found, this version will be reported in a banner underneath the navigation bar. The banner also includes a download link.

The version check refers to a configured update channel with master being the default channel. The version is checked once a day.

Inactive Clients

If the master has not received a message from the client for more than a certain number of seconds (defaults to 60) the value in column Time Since Last Ping will be displayed in red. See screenshot above.

Note: The master cannot differentiate between clients that are only temporarily not available and clients which have completely been removed from the topology. In the latter case the master has to be restarted to "forget" the removed clients.

Administration

The administration page enables the administrator to override the default restrictions for the monitored users. This is possible for the current day and up to 7 days into the future.

The top level shows the names and today's activity of the current monitored users. In case the user is currently allowed to play (see green check mark) the row shows the estimated remaining play times for the current session (if logged in) and for the day. If the user is currently blocked (see red cross) the row shows the reasons why the user is not permitted to play and the estimated remaining play time for the day.

The second level can be opened by clicking on the name of a user. It will show the active restrictions of the current day and the next seven days of the selected user. The column "Context" denotes which rule set is active on the respective day. The entries are sorted by the start time in ascending order with the current day at the top.

The third level can be opened by clicking on a day row. It will show input fields to override the default restrictions of the active rule set of the selected day.

To override settings enter the desired values and click the save button.

Most of the input fields require a certain input format. If the values violate the format, a validation message will be displayed. All errors have to be taken care of before the settings will be saved.

When default values are overridden the day row shows the values in blue color. Removing the overriding values removes the color again.

Managing Time Extensions (handled by the administrator)

Often, it is helpful to be able to extend the time of an active user sessions by some minutes or to grant time to a user who is currently not allowed to user the computer. In principle, this is possible by changing one or several of the settings above, but it is not easy and not quick. In come the time extensions which allow you to do just this.

Normally, that is without an active time extension, the administration below the user summary looks as follows.

The dialog shows a number of green buttons with plus signs and numbers on them denoting minutes. Pressing one of these buttons activates the time extension with the selected number of minutes.

The dialog changes to the following display.

The rule summary on the top right states that the time extension is active and shows the current end time. In the row below there are some red buttons now with minus signs and numbers on them also denoting minutes. Pressing one of these red buttons shortens the time extension by the selected number of minutes. Pressing a green button will further extend the time by the selected number of minutes. Shortening the extension by more than its current length or pressing the red off button will remove the time extension.

The exact point of time when the extension starts depends on the current state of the user:

• The user is active: The time extension is appended to the current session effectively extending it by the number of selected minutes.
• The user is not permitted to use the computer: In this case the time extension is created starting right away and having the length of the selected number of minutes.

Please, note the following aspects:

• Time extensions grant instant computer time overriding other restrictive rules. This will always allow the user to play at least until the end of the time extension. It will, however, not change the daily limit, nor will it influence the way minimum break times are computed.

• In the rule summary, active restrictive rules will still be displayed, but they will be inactive. The only rule that will always show the "right" time is the one regarding the remaining number of minutes in the current session.

• In contrast to the normal rule sets which usually have trouble to cover computer times spanning midnight elegantly, time extensions will handle this case nicely.

Managing Time Extensions (handled by the user)

In addition to the time extensions handled by the administrator, it is also possible to grant a certain time a day which can be used by the user to request time extensions on the fly. This optional time is administered with the corresponding rule set. See the configuration of rule sets further below.

The idea is that time extensions may be required very urgently at the end of session to "kill that final invader" or maybe save a game context. For the user, it would be contact the administrator to ask for a time extension and in some cases it may simply be impossible. With the help of the "optional time" the user can avoid the critical moments. However, using the optional time will NOT increase the overall playtime of the day which is intentional.

The actual request is executed by the user through the tool LittleBrotherTaskbar.

Configuring Users

Before a user can be monitored she has to be added to the users list of LittleBrother. After installation the users list is empty. The application will try to retrieve the users on the master host by querying the /etc/passwd file using standard Python libraries. See Users and UIDs in README for details.

All users found that are not being monitored yet will be offered in the dropdown menu following "Add to monitoring":

To add the user choose the username from the dropdown list and click the add button:

After the user has been added her top level entry will be shown:

Click on the username to change to second level of the user entry:

The details will show the following items:

• Monitored: denotes if the user will actually be monitored. This will be un-ticked for all new users and should only be ticked off after the user has been configured completely using rule sets and optionally devices.

• First Name: sets the first name of the user. When set the first name will be used in notifications instead of the username which may be unpronounceable.

• Last Name: sets the last name of the user. This is only used as label in lists.

• Locale: sets the language in which notifications are spoken to the user. The locale will be passed on to the tool LittleBrotherTaskbar to this purpose. For a new user the locale always defaults to the locale which is detected from the browser.

• Process Name Patterns: use this link to open the next level of configuration for setting regular expressions defining specific processes. See below.

Specifying Login and Prohibited Processes

After opening the link "Process Name Pattern" the next level of configuration opens displaying two text areas for specifying process patterns.

• Login Process Name Pattern: sets a regular expression defining the processes which represents a "login" by the user. The default value comprises all standard shells and systemd which is started by login process using X11. Only change this setting if you absolutely know what you are doing.

  As of version 0.3.12 the pattern will be matched against the complete command line and no longer the process name only. This requires/permits the pattern to be more precise if you have several binaries with the same name in different directories. Thanks to bhulsken for providing a pull request.

  As of version 0.4.4 the pattern can span several lines. The sub patterns on the lines will implicitly be combined into a single pattern using the | operator of regular expressions.

  Note: In order to guarantee backward compatibility prior to version 0.3.12, process name patterns without a single / will be braced by .*( PATTERN ).* so that the original expression will be matched at any location in the command line. If no / is contained in the configured expression it will be used literally.

• Prohibited Process Name Pattern: sets a regular expression describing all the processes that the user is not allowed to start. Per default, the pattern always scans the complete command line of the process. The sub patterns on each line will be braced by .*( PATTERN ).* and combined into a single pattern using the | operator of regular expressions. As soon as a matching process is detected the user be played a notification that the process will be terminated immediately.

Adding Rule Sets

When a new user is created, there is always one default rule created for her which will act as a fallback if no other rule applies. However, the new rule does not contain any restrictions yet:

Use the entry fields to optionally change the default settings:

The fields represent the following restrictions/meaning:

• Label: changes the default label of the rule in lists and messages.

• Context: sets the context (type) of rule. Currently, there are three contexts available. See below.

• Context details: sets the specific details of the chosen context. See below.

• Optional time: When set this optional time can be used by the user to request time extensions in sessions. The time is valid for a whole day. Whenever the user requests a time extension the duration will be subtracted from this value.

• Min Time of Day: optionally sets the earliest time of the day when login is allowed. Timestamps must be given in the format HH:MM in military time. Time durations must be given in the format HHh:MMm. Either part may be omitted and the minutes may exceed 60.

• Max Time of Day: optionally sets the latest time of the day when login is allowed. The format is the same as above.

• Time per Day: optionally sets the duration that the user is allowed to be logged in (for the whole day). The format must be HHh:MMm for HH hours and MM minutes. Either part can be omitted.

• Minimum Break: optionally sets a mandatory break time between sessions. The format is the same as above.

• Max Duration: optionally sets the maximum length of a session. The format is the same as above.

• Free Play: If ticked, the user is allowed to play without any restrictions. Any other restriction in the same rule will be suppressed.

Computing the Break Time

When there is a maximum session time and a minimum break time configured for a rule LittleBrother tries to compute a fair break duration as follows:

• If a user has played her full maximum session time the whole configured break time will apply.

• If a user has played less than her maximum session time the break time will be enforced proportionally that is the effective break time compared to the configured break time will have the same ratio as the actual session time to the maximum session time. Example: the maximum session time is set to 1 hour and the break time to 30 minutes. The user decides to play for 40 minutes in her session which accounts for two thirds of the maximum session time. Hence, the break time will be 2/3*30=20 minutes.

Rule Contexts

Each rule can be seen as a day selector. If all days are to be treated equally one rule should do the job.

If different days are to be treated differently more rules are required besides the default catch all rule. To this purpose the setting Context can be used. If its value is weekplan the setting Context Details will contain either:

• the adverb referring to the day of the week (e.g. sundays),

• the string weekend comprising Saturday and Sunday, or day-coded seven-character string in which 1, X, or Y denotes an active day and any other character denotes an inactive day. For example: the string "X-X-X--" would denote a rule which is active on Mondays, Wednesdays, and Fridays.

If the value of Context is german-vacation-calendar the rule is active for all vacation days of a specific federal state in Germany. In this case the value of context_details denotes the name of the federal state:

• Baden-Württemberg,
• Bayern,
• Berlin,
• Brandenburg,
• Bremen,
• Hamburg,
• Hessen,
• Mecklenburg-Vorpommern,
• Niedersachsen,
• Nordrhein-Westfalen,
• Rheinland-Pfalz,
• Saarland,
• Sachsen,
• Sachsen-Anhalt,
• Schleswig-Holstein, or
• Thüringen.

Note that the vacation schedules are retrieved from the website www.mehr-schulferien.de. The author of LittleBrother cannot be held responsible for incorrect schedules.

Associating Devices with Users

In addition to the hosts which are scanned for logins of the monitored users LittleBrother can be configured to also scan the activity on other devices, e.g. game consoles or smartphones. The assumption is that there is activity on one of these devices when they respond to a ping. Of course, this is a simplification, but it may work in some cases. Please, consider the inherent restrictions:

• The fact that a ping is received just means that the device is "on". However, there may not be any activity on it. In this case the play time will be overestimated. Also, some devices may automatically turn on to check for updates. This will result in phantom play time (sometimes at very odd hours of a day).

• The ping cannot differentiate between users. So this setup only works well, if the devices can clearly be associated with monitored users and are not shared too often.

• Devices which can be played offline will not respond to a ping if disconnected from the local network. In this case the play time will be underestimated.

• The ping returned by smartphones is sometimes hard to interpret. The correlation between successful pings and actual usage is small. The monitoring has to be improved by actually measuring the delay of the ping which requires some fine-tuning.

Note: The following steps are only available if devices have already been set up. See section Configuring Devices below.

To associate a device with a user select the device from the popdown menu

and click the add button

The top level device overview will show a comma separated list of all devices.

Clicking on Devices will open the second level with a list of all device association and some details

In order to change the settings of a device association clicking on the device name. This will open the third level:

The columns contain the following details:

• Monitored: denotes if the device is scanned for the user. Use this switch to temporarily deactivate the scanning. The flag is off by default. It needs to be activated for a new association.

• Blockable: denotes if the network communication of this device is to be blocked when the user has exceeded her time budget. This is done by inserting an appropriate rule into iptables. See

• Advanced Topics for setting up this functionality.

• Percent: denotes the percentage with which the active time of this device will be added as play time to the associated user. The default is 100%. Choosing a value below 100% can be interpreted as e.g. a "social" bonus for a console which allows multiplayer games or e.g. a typical fraction of time that the user spends on the device compared to the overall use of the device (by other users).

To save the settings click on the save button:

Configuring Devices

In addition to the processes of the Linux host the application LittleBrother can be configured to monitor activity on other devices by using the ICMP protocol (ping). The assumption is that when a device returns a quick response to ping it is currently active (or rather has an active user logged in). If, on the other hand, the response is slow or if there is no response at all the device is regarded as inactive.

Note that LittleBrother is not able to terminate any processes on the monitored devices so that the users may easily exceed their permitted access times there. However, any login times on these devices are added to the access times on the Linux hosts so that the remaining access time is still influenced. Also, the minimum break time will apply the point of time when the last other device became inactive.

As of version 0.4.23 LittleBrother may be able to at least restrict network access to the monitored devices. See the section on iptables in Advanced Topics for details.

The top level of the devices page shows a list of all configured devices. If the devices are associated with users their names are shown and also their respective usage percentages.

Clicking on a device name opens the second level showing details on the specific device.

The fields have the following meaning:

• Name: The logical name of the device which will show up in lists. The logical name has to be unique across all devices.

• Host Name: The DNS name or IP address of the device. This address will be used for pinging the device. It has to be a valid address which can be resolved by the name server. Otherwise, the entry will be rejected. Also, the hostname has to be unique across all devices. If you want to monitor devices in your local WI-FI you have to see to it that your WI-FI router always issues the same IP numbers to the same devices. Usually, there is a way to configure the router accordingly. Look out for persistent IP addresses in the manual.

  As of version 0.3.12 of LittleBrother the host name may also have an extended format permitting to ping devices behind a firewall. This feature is supported by ProxyPing. In this case the host name has the following format

    proxy.host.name:port,device.host.name
  

  where proxy.host.name ist the DNS name of proxy host and port is the optional port number. device.host.name denotes the DNS name of the actual device. The port defaults to 6666 which is the default of ProxyPing. If no port is given the colon has to be omitted, too. Of course, instead of either host name an IP address may be used.

  Some examples:

  Host Specification	Description
  my.device.net	Direct ping to device with DNS name my.device.net
  192.168.5.2	Direct ping to device with IP address 192.168.5.2
  my.proxy.somenet,my.hidden.device	Proxy ping to device with DNS name my.hidden.device using ProxyPing located at my.proxy.somenet using default port 6666
  my.proxy.somenet:6665,my.hidden.device	Proxy ping to device with DNS name my.hidden.device using ProxyPing located at my.proxy.somenet using explicit port 6665

  Note that LittleBrother will only check the validity of the proxy host name, whereas the device.host.name will not be checked. For the time being, format errors in the specification above or a wrong device host name will silently be ignored resulting in the device being regarded as down all the time.

• Min Activity Duration [s]: Denotes how many seconds a ping has to be responsive before the device is regarded as active. Durations shorter than this period will be ignored completely.

• Max Active Response Delay [ms]: Denotes the maximum response time (measured in milliseconds) a ping may have to still be regarded as 'active'. For game consoles (often using the local area network) a low value of 10 [ms] is usually OK. For smartphone using WI-FI the value needs to be higher since these devices have a more sluggish response. For iPhones over WI-FI values between 50 [ms] and 80 [ms] have been tested to work pretty well. You will have to monitor the value a bit during the initial phase. If LittleBrother often detects activity where there is none, decrease the value. If, on the other had, activity often goes undetected, increase the value.

• Sample Size: Denotes the number of delay samples used to compute the effective delay as moving average. This value can probably be left as it is.

• Blocked URLs: Use this text are to override the globally URLs which are blocked for the device if the assigned user has exceeded his time budget. Use one DNS name or IP address per line. Each DNS address is checked before the entry can be saved. Note: These entries completely replace the default entries. If you want to have some of the default entries active you will have to repeat them here! To make changes enter the desired values and click the save button.

Adding devices

To add a new device click the add button in the top row:

A new device is added with the generic name "New Device N". Open the entry, edit the settings, and save them.