|
|
@ -11,7 +11,7 @@ |
|
|
|
.Sh SYNOPSIS |
|
|
|
.Nm "arsse user" |
|
|
|
.Op Nm list |
|
|
|
.Nm "arsee user add" |
|
|
|
.Nm "arsse user add" |
|
|
|
.Ar username |
|
|
|
.Op Ar password |
|
|
|
.Op Fl Fl admin |
|
|
@ -77,12 +77,223 @@ Managing passwords and authentication tokens |
|
|
|
Importing and exporting OPML newsfeed-lists |
|
|
|
.El |
|
|
|
.Pp |
|
|
|
.Sm off |
|
|
|
These are documented in the next section |
|
|
|
.Sx COMMANDS |
|
|
|
\&. Further, seldom-used commands are documented in the following section |
|
|
|
.Sx "ADDITIONAL COMMANDS" |
|
|
|
\&. |
|
|
|
.Sm on |
|
|
|
.Sx COMMANDS Ns No . |
|
|
|
Further, seldom-used commands are documented in the following section |
|
|
|
.Sx ADDITIONAL COMMANDS Ns No . |
|
|
|
. |
|
|
|
. |
|
|
|
.Sh COMMANDS |
|
|
|
. |
|
|
|
.Ss Managing users and metadata |
|
|
|
.Bl -tag |
|
|
|
.It Nm "user" Op Nm list |
|
|
|
Displays a simple list of user names with one entry per line |
|
|
|
.It Nm "user add" Ar username Oo Ar password Oc Oo Fl Fl admin Oc |
|
|
|
Adds a new user to the database with the specified username and password. |
|
|
|
If |
|
|
|
.Ar password |
|
|
|
is omitted a random password will be generated and printed. |
|
|
|
.Pp |
|
|
|
The |
|
|
|
.Fl Fl 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. |
|
|
|
.It Nm "user remove" Ar username |
|
|
|
Immediately removes a user from the database. |
|
|
|
All associated data (folders, subscriptions, etc.) are also removed. |
|
|
|
.It Nm "user show" Ar username |
|
|
|
Displays a table of metadata properties and their assigned values for |
|
|
|
.Ar username Ns No . |
|
|
|
These properties are primarily used by the Miniflux protocol. |
|
|
|
Consult the section |
|
|
|
.Sx USER METADATA |
|
|
|
for details. |
|
|
|
.It Nm "user set" Ar username Ar property Ar value |
|
|
|
Sets a metadata property for a user. |
|
|
|
These properties are primarily used by the Miniflux protocol. |
|
|
|
Consult the section |
|
|
|
.Sx USER METADATA |
|
|
|
for details. |
|
|
|
.It Nm "user unset" Ar username Ar property |
|
|
|
Clears a metadata property for a user. |
|
|
|
The property is thereafter set to its default value, which is protocol-dependent. |
|
|
|
.El |
|
|
|
. |
|
|
|
.Ss Managing passwords and authentication tokens |
|
|
|
.Bl -tag |
|
|
|
.It Nm "user set\-pass" Ar username Oo Ar password Oc Oo Fl Fl fever Oc |
|
|
|
Changes a user's password to the specified value. |
|
|
|
If no password is specified, a random password will be generated and printed. |
|
|
|
.Pp |
|
|
|
The |
|
|
|
.Fl Fl 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. |
|
|
|
.It Nm "user unset\-pass" Ar username Oo Fl Fl fever Oc |
|
|
|
Unsets a user's password, effectively disabling their account. |
|
|
|
As with password setting, the |
|
|
|
.Fl Fl fever |
|
|
|
option may be used to operate on a user's Fever password instead of their general password. |
|
|
|
.It Nm "user auth" Ar username Ar password Oo Fl Fl fever Oc |
|
|
|
Tests logging a user in. |
|
|
|
This only checks that the user's password is correctly recognized; |
|
|
|
it has no side effects. |
|
|
|
.Pp |
|
|
|
The |
|
|
|
.Fl Fl fever |
|
|
|
option may be used to test the user's Fever protocol password, if any. |
|
|
|
.It Nm "token list" Ar 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. |
|
|
|
.It Nm "token create" Ar username Oo Ar label Oc |
|
|
|
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 |
|
|
|
.Ar label |
|
|
|
may be specified to give the token a meaningful name. |
|
|
|
.It Nm "token revoke" Ar username Oo Ar token Oc |
|
|
|
Deletes the specified |
|
|
|
.Ar token |
|
|
|
from the database. |
|
|
|
The token itself must be supplied, not its label. |
|
|
|
If it is omitted all tokens for |
|
|
|
.Ar username |
|
|
|
are revoked. |
|
|
|
.El |
|
|
|
. |
|
|
|
.Ss Importing and exporting data |
|
|
|
.Bl -tag |
|
|
|
.It Nm "import" Ar username Oo Ar file Oc Oo Fl r | Fl Fl replace Oc Oo Fl f | Fl Fl flat Oc |
|
|
|
Imports the newsfeeds, folders, and tags found in the OPML formatted |
|
|
|
.Ar 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. |
|
|
|
.Pp |
|
|
|
The |
|
|
|
.Fl Fl replace |
|
|
|
(or |
|
|
|
.Fl r Ns |
|
|
|
) option interprets the OPML file as the list of |
|
|
|
.Em 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 |
|
|
|
.Em additions only Ns No . |
|
|
|
.Pp |
|
|
|
The |
|
|
|
.Fl Fl flat |
|
|
|
(or |
|
|
|
.Fl f Ns |
|
|
|
) option can be used to ignore any folder structures in the file, importing any newsfeeds directly into the root folder. |
|
|
|
Combining this with the |
|
|
|
.Fl Fl replace |
|
|
|
option is possible. |
|
|
|
.It Nm "export" Ar username Oo Ar file Oc Oo Fl f | Fl Fl flat Oc |
|
|
|
Exports a user's newsfeeds, folders, and tags to the OPML file specified by |
|
|
|
.Ar file Ns |
|
|
|
, 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. |
|
|
|
.Pp |
|
|
|
The |
|
|
|
.Fl Fl flat |
|
|
|
(or |
|
|
|
.Fl f Ns |
|
|
|
) 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. |
|
|
|
.El |
|
|
|
. |
|
|
|
. |
|
|
|
.Sh ADDITIONAL COMMANDS |
|
|
|
.Bl -tag |
|
|
|
.It Nm "daemon" Oo Fl Fl fork Ns = Ns Ar pidfile Oc |
|
|
|
Starts the newsfeed fetching service. |
|
|
|
Normally this command is only invoked by systemd. |
|
|
|
.Pp |
|
|
|
The |
|
|
|
.Fl Fl 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 |
|
|
|
.Ar pidfile |
|
|
|
after forking. |
|
|
|
.It Nm "feed refresh\-all" |
|
|
|
Performs a one-time fetch of all stale feeds. |
|
|
|
This command can be used as the basis of a |
|
|
|
.Nm cron |
|
|
|
job to keep newsfeeds up-to-date. |
|
|
|
.It Nm "feed refresh" Ar n |
|
|
|
Performs a one-time fetch of the feed (not subscription) identified by integer |
|
|
|
.Ar n Ns No . |
|
|
|
This is used internally by the fetching service and should not normally be needed. |
|
|
|
.It Nm "conf save\-defaults" Oo Ar file Oc |
|
|
|
Prints default configuration parameters to standard output, or to |
|
|
|
.Ar file |
|
|
|
if specified. |
|
|
|
Each parameter is annotated with a short description of its purpose and usage. |
|
|
|
.El |
|
|
|
. |
|
|
|
. |
|
|
|
.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. |
|
|
|
.Pp |
|
|
|
Booleans accept any of the values |
|
|
|
.Ar true Ns No / Ns Ar false Ns No , |
|
|
|
.Ar 1 Ns No / Ns Ar 0 Ns No , |
|
|
|
.Ar yes Ns No / Ns Ar no Ns No , |
|
|
|
or |
|
|
|
.Ar on Ns No / Ns Ar off Ns No . |
|
|
|
.Pp |
|
|
|
The following metadata properties exist for each user: |
|
|
|
.Pp |
|
|
|
.Bl -tag |
|
|
|
.It Cm num No (integer) |
|
|
|
The numeric identifier of the user. |
|
|
|
This is assigned at user creation and is read-only. |
|
|
|
.It Cm admin No (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. |
|
|
|
.It Cm lang No (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. |
|
|
|
.It Cm tz No (string) |
|
|
|
The time zone of the user as a Time Zone Database identifier, for example "America/Los_Angeles". |
|
|
|
.It Cm root_folder_name No (string) |
|
|
|
The name of the root folder, in protocols which allow it to be renamed. |
|
|
|
.It Cm sort_asc No (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. |
|
|
|
.It Cm theme No (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. |
|
|
|
.It Cm page_size No (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. |
|
|
|
.It Cm shortcuts No (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. |
|
|
|
.It Cm gestures No (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. |
|
|
|
.It Cm reading_time No (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. |
|
|
|
.It Cm stylesheet No (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. |
|
|
|
.El |
|
|
|
. |
|
|
|
. |
|
|
|
.Sh EXAMPLES |
|
|
|