docs: Expand README to be more informative

Include various architectural-level details of the project.

Signed-off-by: Philip Withnall <withnall@endlessm.com>
This commit is contained in:
Philip Withnall 2019-04-02 17:48:32 +01:00
parent a1d1d307f1
commit a4f5cdd1d0
1 changed files with 53 additions and 7 deletions

View File

@ -6,20 +6,66 @@ non-administrator accounts on a Linux system. Typically, when this is
used, a non-administrator account will be for a child using the system; and the used, a non-administrator account will be for a child using the system; and the
administrator accounts will be for the parents. administrator accounts will be for the parents.
It provides an accounts service vendor extension for storing an app filter to It provides an
[accounts-service](https://gitlab.freedesktop.org/accountsservice/accountsservice)
vendor extension for storing an app filter to
restrict the childs access to certain applications; and a simple library for restrict the childs access to certain applications; and a simple library for
accessing and applying the app filter. accessing and applying the app filter. This results in the policy being stored
in `/var/lib/AccountsService/users/${user}`, which is a key file readable and
writable only by the accounts-service daemon. Access to the data is mediated
through accounts-services D-Bus interface, which libmalcontent is a client
library for
All the library APIs are currently unstable and are likely to change wildly. All the library APIs are currently unstable and are likely to change wildly.
Two kinds of policy are currently supported:
* A filter specifying whether installed applications are allowed to be run;
this is typically set up to restrict access to a limited set of
already-installed applications — but it can be set up to only allow access
to a fixed list of applications and deny access to all others.
Applications which are not currently installed are not subject to this
filter.
* A set of mappings from [OARS categories](https://hughsie.github.io/oars/) to
the maximum ratings for those categories which are permissible for a user to
install apps with. For example, a mapping of `violence-realistic=mild` would
prevent any applications containing more than mild violence from being
installed. Applications which are already installed are not subject to this
filter.
Additional policies may be added in future.
Example usage
---
malcontent ships a `malcontent-client` application which can be used to get and
set parental controls policies for users.
```
$ # This sets the parental controls policy for user philip to allow no \\
installation of apps with anything more than none for realistic violence, \\
and to blacklist running the org.freedesktop.Bustle flatpak:
$ malcontent-client set philip \\
violence-realistic=none \\
app/org.freedesktop.Bustle/x86_64/stable
App filter for user 1000 set
```
With that policy in place, other applications which are aware of malcontent will
apply the policy:
```
$ flatpak run org.freedesktop.Bustle
error: Running app/org.freedesktop.Bustle/x86_64/stable is not allowed by the policy set by your administrator
```
Dependencies Dependencies
------------ ------------
• accounts-service * accounts-service
• dbus-daemon * dbus-daemon
• gio-2.0 ≥ 2.54 * gio-2.0 ≥ 2.54
• glib-2.0 ≥ 2.54 * glib-2.0 ≥ 2.54
• gobject-2.0 ≥ 2.54 * gobject-2.0 ≥ 2.54
Licensing Licensing
--------- ---------