mirror of
https://code.mensbeam.com/MensBeam/Arsse.git
synced 2024-12-22 13:12:41 +00:00
Complete native groff manual
This commit is contained in:
J. King
parent
7613142221
commit
5579144fee
1 changed files with 357 additions and 5 deletions
|
|
@ -1,10 +1,15 @@
|
|||
.TH ARSSE 1 "2023\-10\-25" "The Arsse 0.10.4"
|
||||
|
||||
.\" This manual was written using stylistic recommendations from the very
|
||||
.\" helpful groff_man_style(7) manual page with some suggestions from the
|
||||
.\" man-pages(7) manual followed as well. When in doubt those manuals should
|
||||
.\" be consulted while making edits to this document.
|
||||
.
|
||||
.TH ARSSE 1 "2023\-10\-26" "The Arsse 0.10.4"
|
||||
.
|
||||
.SH NAME
|
||||
arsse \- manage an instance of The Advanced RSS Environment (The Arsse)
|
||||
|
||||
.
|
||||
.
|
||||
.SH SYNOPSIS
|
||||
|
||||
.SY "arsse user"
|
||||
.RB [ list ]
|
||||
.SY "arsse user add"
|
||||
|
|
@ -54,4 +59,351 @@ arsse \- manage an instance of The Advanced RSS Environment (The Arsse)
|
|||
.RI < username >
|
||||
.RI [< file >]
|
||||
.RB [ \-f | \-\-flat ]
|
||||
.SY "arsse daemon"
|
||||
.RB [ \-\-fork =\c
|
||||
.IR pidfile ]
|
||||
.SY "arsse feed refresh\-all"
|
||||
.SY "arsse feed refresh"
|
||||
.RI < n >
|
||||
.SY "arsse conf save\-defaults"
|
||||
.RI [< file >]
|
||||
.SY "arsse \-\-version"
|
||||
.SY "arsse"
|
||||
.BR \-h | \-\-help
|
||||
.YS
|
||||
.
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
.P
|
||||
.B arsse
|
||||
allows a sufficiently privileged user to perform various administrative operations related to The Arsse, including:
|
||||
.IP \[bu] 2
|
||||
.PD 0
|
||||
Adding and removing users and managing their metadata
|
||||
.IP \[bu] 2
|
||||
Managing passwords and authentication tokens
|
||||
.IP \[bu] 2
|
||||
Importing and exporting OPML newsfeed-lists
|
||||
.PD
|
||||
.P
|
||||
These are documented in the next section
|
||||
.BR COMMANDS .
|
||||
Further, seldom-used commands are documented in the following section
|
||||
.BR "ADDITIONAL COMMANDS" .
|
||||
.
|
||||
.
|
||||
.SH COMMANDS
|
||||
.SS "Managing uses and metadata"
|
||||
.TP
|
||||
.BR "user " [ list ]
|
||||
Displays a simple list of user names with one entry per line
|
||||
.TP
|
||||
.BR "user add " \c
|
||||
.RI < username "> [<" password ">] \c"
|
||||
.RB [ \-\-admin ]
|
||||
Adds a new user to the database with the specified username and password.
|
||||
If
|
||||
.I password
|
||||
is omitted a random password will be generated and printed.
|
||||
.IP
|
||||
The
|
||||
.B \-\-admin
|
||||
flag may be used to mark the user as an administrator.
|
||||
This has no meaning within the context of The Arsse as a whole,
|
||||
but it is used control access to certain features in the Miniflux and Nextcloud News protocols.
|
||||
.TP
|
||||
.BR "user remove " \c
|
||||
.RI < username >
|
||||
Immediately removes a user from the database.
|
||||
All associated data (folders, subscriptions, etc.) are also removed.
|
||||
.TP
|
||||
.BR "user show " \c
|
||||
.RI < username >
|
||||
Displays a table of metadata properties and their assigned values for
|
||||
.IR username .
|
||||
These properties are primarily used by the Miniflux protocol.
|
||||
Consult the section
|
||||
.B USER METADATA
|
||||
for details.
|
||||
.TP
|
||||
.BR "user set " \c
|
||||
.RI < username "> \c"
|
||||
.RI < property "> \c"
|
||||
.RI < value >
|
||||
Sets a metadata property for a user.
|
||||
These properties are primarily used by the Miniflux protocol.
|
||||
Consult the section
|
||||
.B "USER METADATA"
|
||||
for details.
|
||||
.TP
|
||||
.BR "user set " \c
|
||||
.RI < username "> \c"
|
||||
.RI < property >
|
||||
Clears a metadata property for a user.
|
||||
The property is thereafter set to its default value, which is protocol-dependent.
|
||||
.SS "Managing passwords and authentication tokens"
|
||||
.TP
|
||||
.BR "user set\-pass " \c
|
||||
.RI < username "> \c"
|
||||
.RI [< password ">] \c"
|
||||
.RB [ \-\-fever ]
|
||||
Changes a user's password to the specified value.
|
||||
If no password is specified, a random password will be generated and printed.
|
||||
.IP
|
||||
The
|
||||
.B \-\-fever
|
||||
option sets a user's Fever protocol password instead of their general password.
|
||||
As the Fever protocol requires that passwords be stored insecurely,
|
||||
users do not have Fever passwords by default, and logging in to the Fever protocol is disabled until a suitable password is set.
|
||||
It is highly recommended that a user's Fever password be different from their general password.
|
||||
.TP
|
||||
.BR "user set\-pass " \c
|
||||
.RI < username "> \c"
|
||||
.RB [ \-\-fever ]
|
||||
Unsets a user's password, effectively disabling their account.
|
||||
As with password setting, the
|
||||
.B \-\-fever
|
||||
option may be used to operate on a user's Fever password instead of their general password.
|
||||
.TP
|
||||
.BR "user auth " \c
|
||||
.RI < username "> \c"
|
||||
.RI [< password ">] \c"
|
||||
.RB [ \-\-fever ]
|
||||
Tests logging a user in.
|
||||
This only checks that the user's password is correctly recognized;
|
||||
it has no side effects.
|
||||
.IP
|
||||
The
|
||||
.B \-\-fever
|
||||
option may be used to test the user's Fever protocol password, if any.
|
||||
.TP
|
||||
.BR "token list " \c
|
||||
.RI < username >
|
||||
Displays a user's authentication tokens in a simple tabular format.
|
||||
These tokens act as an alternative means of authentication for the Miniflux protocol and may be required by some clients.
|
||||
They do not expire.
|
||||
.TP
|
||||
.BR "token create " \c
|
||||
.RI < username "> \c"
|
||||
.RI [< label >]
|
||||
Creates a new random login token and prints it.
|
||||
These tokens act as an alternative means of authentication for the Miniflux protocol and may be required by some clients.
|
||||
An optional
|
||||
.I label
|
||||
may be specified to give the token a meaningful name.
|
||||
.TP
|
||||
.BR "token revoke " \c
|
||||
.RI < username "> \c"
|
||||
.RI [< token >]
|
||||
Deletes the specified
|
||||
.I token
|
||||
from the database. The token itself must be supplied, not its label.
|
||||
If it is omitted all tokens for
|
||||
.I username
|
||||
are revoked.
|
||||
.SS "Importing and exporting data"
|
||||
.TP
|
||||
.BR "import " \c
|
||||
.RI < username "> \c"
|
||||
.RI [< file ">] \c"
|
||||
.RB [ \-r | \-\-replace "] \c"
|
||||
.RB [ \-f | \-\-flat ]
|
||||
Imports the newsfeeds, folders, and tags found in the OPML formatted
|
||||
.I file
|
||||
into the account of the specified user.
|
||||
If no file is specified, data is instead read from standard input.
|
||||
Import operations are atomic:
|
||||
if any of the newsfeeds listed in the input cannot be retrieved, the entire import operation will fail.
|
||||
.IP
|
||||
The
|
||||
.BR \-\-replace " (or " \-r )
|
||||
option interprets the OPML file as the list of
|
||||
.B all
|
||||
desired newsfeeds, folders and tags, performing any deletion or moving of existing entries which do not appear in the flle.
|
||||
If this option is not specified, the file is assumed to list desired
|
||||
.B additions only.
|
||||
.IP
|
||||
The
|
||||
.BR \-\-flat " (or " \-f )
|
||||
option can be used to ignore any folder structures in the file, importing any newsfeeds directly into the root folder.
|
||||
Combining this with the
|
||||
.B \-\-replace
|
||||
option is possible.
|
||||
.TP
|
||||
.BR "export " \c
|
||||
.RI < username "> \c"
|
||||
.RI [< file ">] \c"
|
||||
.RB [ \-f | \-\-flat ]
|
||||
Exports a user's newsfeeds, folders, and tags to the OPML file specified by
|
||||
.I file\c
|
||||
, or standard output if no file is specified.
|
||||
Note that due to a limitation of the OPML format, any commas present in tag names will not be retained in the export.
|
||||
.IP
|
||||
The
|
||||
.BR \-\-flat " (or " \-f )
|
||||
option can be used to omit folders from the export.
|
||||
Some OPML implementations may not support folders, or arbitrary nesting;
|
||||
this option may be used when planning to import into such software.
|
||||
.
|
||||
.
|
||||
.SH "ADDITIONAL COMMANDS"
|
||||
.TP
|
||||
.BR "daemon" \c
|
||||
.RB [ \-\-fork =\c
|
||||
.IR pidfile ]
|
||||
Starts the newsfeed fetching service.
|
||||
Normally this command is only invoked by systemd.
|
||||
.IP
|
||||
The
|
||||
.B \-\-fork
|
||||
option executes an "old-style" fork-then-terminate daemon rather than a "new-style" non-terminating daemon.
|
||||
This option should only be employed if using a System V-style init daemon on POSIX systems;
|
||||
normally systemd is used. When using this option the daemon will write its process identifier to
|
||||
.I pidfile
|
||||
after forking.
|
||||
.TP
|
||||
.BR "feed refresh\-all"
|
||||
Performs a one-time fetch of all stale feeds.
|
||||
This command can be used as the basis of a
|
||||
.B cron
|
||||
job to keep newsfeeds up-to-date.
|
||||
.TP
|
||||
.BR "feed refresh " \c
|
||||
.RI < n >
|
||||
Performs a one-time fetch of the feed (not subscription) identified by integer
|
||||
.IR n .
|
||||
This is used internally by the fetching service and should not normally be needed.
|
||||
.TP
|
||||
.BR "conf save\-defaults " \c
|
||||
.RI [< file >]
|
||||
Prints default configuration parameters to standard output, or to
|
||||
.I file
|
||||
if specified.
|
||||
Each parameter is annotated with a short description of its purpose and usage.
|
||||
.
|
||||
.
|
||||
.SH "USER METADATA"
|
||||
User metadata are primarily used by the Miniflux protocol,
|
||||
and most properties have identical or similar names to those used by Miniflux.
|
||||
Properties may also affect other protocols, or conversely may have no effect even when using the Miniflux protocol;
|
||||
this is noted below when appropriate.
|
||||
.P
|
||||
Booleans accept any of the values
|
||||
.BR true / false ,
|
||||
.BR 1 / 0 ,
|
||||
.BR yes / no ,
|
||||
or
|
||||
.BR on / off .
|
||||
.P
|
||||
The following metadata properties exist for each user:
|
||||
.TP
|
||||
.BR num " (integer)"
|
||||
The numeric identifier of the user.
|
||||
This is assigned at user creation and is read-only.
|
||||
.TP
|
||||
.BR admin " (boolean)"
|
||||
Boolean. Whether the user is an administrator.
|
||||
Administrators may manage other users via the Miniflux protocol,
|
||||
and also may trigger feed updates manually via the Nextcloud News protocol.
|
||||
.TP
|
||||
.BR lang " (string)"
|
||||
The preferred language of the user as a BCP 47 language tag, for example "en-ca".
|
||||
Note that since The Arsse currently only includes English text it is not used by The Arsse itself,
|
||||
but clients may use this metadatum in protocols which expose it.
|
||||
.TP
|
||||
.BR tz " (string)"
|
||||
The time zone of the user as a Time Zone Database identifier, for example "America/Los_Angeles".
|
||||
.TP
|
||||
.BR root_folder_name " (string)"
|
||||
The name of the root folder, in protocols which allow it to be renamed.
|
||||
.TP
|
||||
.BR sort_asc " (boolean)"
|
||||
Whether the user prefers ascending sort order for articles.
|
||||
Descending order is usually the default,
|
||||
but explicitly setting this property false will also make a preference for descending order explicit.
|
||||
.TP
|
||||
.BR theme " (string)"
|
||||
The user's preferred user-interface theme.
|
||||
This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
|
||||
.TP
|
||||
.BR page_size " (integer)"
|
||||
The user's preferred page size when listing articles.
|
||||
This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
|
||||
.TP
|
||||
.BR shortcuts " (boolean)"
|
||||
Whether to enable keyboard shortcuts.
|
||||
This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
|
||||
.TP
|
||||
.BR gestures " (boolean)"
|
||||
Whether to enable touch gestures.
|
||||
This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
|
||||
.TP
|
||||
.BR reading_time " (boolean)"
|
||||
Whether to calculate and display the estimated reading time for articles.
|
||||
Currently The Arsse does not calculate reading time, so changing this will likely have no effect.
|
||||
.TP
|
||||
.BR stylesheet " (string)"
|
||||
A user stylesheet in CSS format.
|
||||
This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
|
||||
.
|
||||
.
|
||||
.SH EXAMPLES
|
||||
.IP \[bu] 2
|
||||
Add an administrator to the database with an explicit password:
|
||||
.EX
|
||||
$ arsse user add \-\-admin alice "Curiouser and curiouser!"
|
||||
.EE
|
||||
.P
|
||||
.IP \[bu] 2
|
||||
Add a regular user to the database with a random password:
|
||||
.EX
|
||||
$ arsse user add "Bob the Builder"
|
||||
bLS!$_UUZ!iN2i_!\^IC6
|
||||
.EE
|
||||
.P
|
||||
.IP \[bu] 2
|
||||
Make Bob the Builder an administrator:
|
||||
.EX
|
||||
$ arsse user set "Bob the Builder" admin true
|
||||
.EE
|
||||
.P
|
||||
.IP \[bu] 2
|
||||
Disable Alice's account by clearing her password:
|
||||
.EX
|
||||
$ arsse user unset\-pass alice
|
||||
.EE
|
||||
.P
|
||||
.IP \[bu] 2
|
||||
Move all of Foobar's newsfeeds to the root folder:
|
||||
.EX
|
||||
$ arsse export foobar \-f | arsse import \-r foobar
|
||||
.EE
|
||||
.P
|
||||
.IP \[bu] 2
|
||||
Fail to log in as Alice:
|
||||
.EX
|
||||
$ arsse user auth alice "Oh, dear!"
|
||||
Authentication failed
|
||||
$ echo $?
|
||||
1
|
||||
.EE
|
||||
.P
|
||||
.
|
||||
.
|
||||
.SH "REPORTING BUGS"
|
||||
.P
|
||||
Any bugs found in The Arsse may be reported on the Web via the
|
||||
.UR https://\:code.mensbeam.com/\:MensBeam/\:arsse
|
||||
MensBeam code repository
|
||||
.UE \c
|
||||
\&. Reports may also be directed to the principal authors by e-mail:
|
||||
.IP \[bu] 2
|
||||
.UR https://\:jkingweb.ca/
|
||||
J. King
|
||||
.UE
|
||||
.PD 0
|
||||
.IP \[bu] 2
|
||||
.UR https://\:dustinwilson.com/
|
||||
Dustin Wilson
|
||||
.UE
|
||||
.PD
|
||||
Loading…
Reference in a new issue