|
|
|
@ -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 ] |
|
|
|
.YS |
|
|
|
.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 |
