Merge branch '4-manpage' into 'master'

Resolve "Add manpage docs for malcontent-client monitor, set and oars-section commands"

Closes #4

See merge request pwithnall/malcontent!98
This commit is contained in:
Philip Withnall 2020-10-27 18:28:31 +00:00
commit e1cd202ad5
1 changed files with 152 additions and 4 deletions

View File

@ -1,7 +1,7 @@
.\" Manpage for malcontent\-client. .\" Manpage for malcontent\-client.
.\" Documentation is under the same licence as the malcontent .\" Documentation is under the same licence as the malcontent
.\" package. .\" package.
.TH man 8 "13 Jun 2019" "1.1" "malcontent\-client man page" .TH man 8 "27 Oct 2020" "1.2" "malcontent\-client man page"
.\" .\"
.SH NAME .SH NAME
.IX Header "NAME" .IX Header "NAME"
@ -13,6 +13,14 @@ malcontent\-client \- Parental Controls Access Utility
\fBmalcontent\-client get\-app\-filter [\-q] [\-n] [\fPUSER\fB] \fBmalcontent\-client get\-app\-filter [\-q] [\-n] [\fPUSER\fB]
.PP .PP
\fBmalcontent\-client check\-app\-filter [\-q] [\-n] [\fPUSER\fB] \fPARG\fB \fBmalcontent\-client check\-app\-filter [\-q] [\-n] [\fPUSER\fB] \fPARG\fB
.PP
\fBmalcontent\-client set\-app\-filter [\-q] [\-n] [\fPUSER\fB] \fPARG\fB
.PP
\fBmalcontent\-client oars\-section [\-q] [\-n] [\fPUSER\fB] \fPSECTION\fB
.PP
\fBmalcontent\-client get\-session\-limits [\-q] [\-n] [\fPUSER\fB]
.PP
\fBmalcontent\-client monitor [\-q] [\fPUSER\fB]
.\" .\"
.SH DESCRIPTION .SH DESCRIPTION
.IX Header "DESCRIPTION" .IX Header "DESCRIPTION"
@ -24,8 +32,8 @@ controls.
.PP .PP
It communicates with accounts-service, which stores parental controls data. It communicates with accounts-service, which stores parental controls data.
.PP .PP
Its first argument is a command to run. Currently, the only supported commands Its first argument is a command to run. The supported commands are documented
are \fBget\-app\-filter\fP and \fBcheck\-app\-filter\fP. below.
.PP .PP
The command line API and output format are unstable and likely to change in The command line API and output format are unstable and likely to change in
future versions of \fBmalcontent\-client\fP. future versions of \fBmalcontent\-client\fP.
@ -33,6 +41,13 @@ future versions of \fBmalcontent\-client\fP.
.SH \fBget\-app\-filter\fP OPTIONS .SH \fBget\-app\-filter\fP OPTIONS
.IX Header "get\-app\-filter OPTIONS" .IX Header "get\-app\-filter OPTIONS"
.\" .\"
Get the app filter for a user. For example:
.RS
.ad l
# malcontent\-client get\-app\-filter timmy
.ad b
.RE
.\"
.IP "\fBUSER\fP" .IP "\fBUSER\fP"
Username or ID of the user to get the app filter for. If not specified, the Username or ID of the user to get the app filter for. If not specified, the
current user will be used by default. current user will be used by default.
@ -49,6 +64,18 @@ authorization.)
.SH \fBcheck\-app\-filter\fP OPTIONS .SH \fBcheck\-app\-filter\fP OPTIONS
.IX Header "check\-app\-filter OPTIONS" .IX Header "check\-app\-filter OPTIONS"
.\" .\"
Check if a given program, content type or flatpak ref is permitted to be used by
a user, according to their current app filter. For example:
.RS
.ad l
# malcontent\-client check\-app\-filter timmy $(which gnome\-calculator)
.PP
# malcontent\-client check\-app\-filter timmy x\-scheme\-handler/http
.PP
# malcontent\-client check\-app\-filter timmy app/com.realm667.WolfenDoom_Blade_of_Agony/x86_64/stable
.ad b
.RE
.\"
.IP "\fBUSER\fP" .IP "\fBUSER\fP"
Username or ID of the user to get the app filter for. If not specified, the Username or ID of the user to get the app filter for. If not specified, the
current user will be used by default. current user will be used by default.
@ -66,6 +93,127 @@ Do not allow interactive authorization with polkit. If this is needed to
complete the operation, the operation will fail. (Default: Allow interactive complete the operation, the operation will fail. (Default: Allow interactive
authorization.) authorization.)
.\" .\"
.SH \fBset\-app\-filter\fP OPTIONS
.IX Header "set\-app\-filter OPTIONS"
.\"
Set the app filter for a user, replacing all previous values in it. For example:
.RS
.ad l
# malcontent\-client set\-app\-filter timmy \\
\-\-disallow\-user\-installation \\
$(which gnome\-calculator) \\
x\-scheme\-handler/http \\
app/com.realm667.WolfenDoom_Blade_of_Agony/x86_64/stable
.ad b
.RE
.\"
.IP "\fBUSER\fP"
Username or ID of the user to set the app filter for. If not specified, the
current user will be used by default.
.\"
.IP "\fBARG\fP"
Item to filter in the users app filter. This could either be an absolute path
or flatpak ref of a program to block; a content type to block all programs
handling that type; or an OARS \fBsection=value\fP pair to block installation of
apps with a more extreme rating for that OARS section. Multiple items may be
specified, and they will replace the users current app filter in entirety. If
zero items are specified, the app filter is cleared.
.\"
.IP "\fB\-\-allow\-user\-installation\fP"
Allow the user to install flatpaks to their user repository.
.\"
.IP "\fB\-\-disallow\-user\-installation\fP"
Disallow the user from installing flatpaks to their user repository.
.\"
.IP "\fB\-\-allow\-system\-installation\fP"
Allow the user to install flatpaks to the system repository.
.\"
.IP "\fB\-\-disallow\-system\-installation\fP"
Disallow the user from installing flatpaks to the system repository.
.\"
.IP "\fB\-q\fP, \fB\-\-quiet\fP"
Only output error messages, and no informational messages, as the operation
progresses. (Default: Output informational messages.)
.\"
.IP "\fB\-n\fP, \fB\-\-no\-interactive\fP"
Do not allow interactive authorization with polkit. If this is needed to
complete the operation, the operation will fail. (Default: Allow interactive
authorization.)
.\"
.SH \fBoars\-section\fP OPTIONS
.IX Header "oars\-section OPTIONS"
.\"
Get the value set for a specific OARS section from the app filter of the given
user. For example:
.RS
.ad l
# malcontent\-client oars\-section timmy language\-profanity
.ad b
.RE
.\"
.IP "\fBUSER\fP"
Username or ID of the user to get the OARS filter for. If not specified, the
current user will be used by default.
.\"
.IP "\fBSECTION\fP"
OARS section to get the restriction level of the given user for.
For example, \fBlanguage\-profanity\fP.
.\"
.IP "\fB\-q\fP, \fB\-\-quiet\fP"
Only output error messages, and no informational messages, as the operation
progresses. (Default: Output informational messages.)
.\"
.IP "\fB\-n\fP, \fB\-\-no\-interactive\fP"
Do not allow interactive authorization with polkit. If this is needed to
complete the operation, the operation will fail. (Default: Allow interactive
authorization.)
.\"
.SH \fBget\-session\-limits\fP OPTIONS
.IX Header "get\-session\-limits OPTIONS"
.\"
Get the session limits set for a user. For example:
.RS
.ad l
# malcontent\-client get\-session\-limits timmy
.ad b
.RE
.\"
.IP "\fBUSER\fP"
Username or ID of the user to get the session limits for. If not specified, the
current user will be used by default.
.\"
.IP "\fB\-q\fP, \fB\-\-quiet\fP"
Only output error messages, and no informational messages, as the operation
progresses. (Default: Output informational messages.)
.\"
.IP "\fB\-n\fP, \fB\-\-no\-interactive\fP"
Do not allow interactive authorization with polkit. If this is needed to
complete the operation, the operation will fail. (Default: Allow interactive
authorization.)
.\"
.IP "\fB\-\-now yyyy\-mm\-ddThh:mm:ssZ\fP"
Check session limits (in particular, session expiry time) against the given
date/time, provided in ISO 8601 format. (Default: Current date/time.)
.\"
.SH \fBmonitor\fP OPTIONS
.IX Header "monitor OPTIONS"
.\"
Monitor changes to the parental controls settings for a specific user. For
example:
.RS
.ad l
# malcontent\-client monitor timmy
.ad b
.RE
.\"
.IP "\fBUSER\fP"
Username or ID of the user to monitor the parental controls for. If not
specified, the current user will be used by default.
.\"
.IP "\fB\-q\fP, \fB\-\-quiet\fP"
Only output error messages, and no informational messages, as the operation
progresses. (Default: Output informational messages.)
.\"
.SH "ENVIRONMENT" .SH "ENVIRONMENT"
.IX Header "ENVIRONMENT" .IX Header "ENVIRONMENT"
.\" .\"
@ -119,7 +267,7 @@ An operation failed and no more specific error information is available.
.\" .\"
Any bugs which are found should be reported on the project website: Any bugs which are found should be reported on the project website:
.br .br
\fIhttps://support.endlessm.com/\fP \fIhttps://gitlab.freedesktop.org/pwithnall/malcontent/-/issues\fP
.\" .\"
.SH AUTHOR .SH AUTHOR
.IX Header "AUTHOR" .IX Header "AUTHOR"