The clean & modern RSS server that doesn't give you any crap.
https://thearsse.com/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
342 lines
11 KiB
342 lines
11 KiB
.Dd October 27, 2023
|
|
.Dt ARSSE 1
|
|
.Os "The Arsse" 0.10.4
|
|
.
|
|
.
|
|
.Sh NAME
|
|
.Nm arsse
|
|
.Nd manage an instance of The Advanced RSS Environment (The Arsse)
|
|
.
|
|
.
|
|
.Sh SYNOPSIS
|
|
.Nm "arsse user"
|
|
.Op Nm list
|
|
.Nm "arsse user add"
|
|
.Ar username
|
|
.Op Ar password
|
|
.Op Fl Fl admin
|
|
.Nm "arsse user remove"
|
|
.Ar username
|
|
.Nm "arsse user show"
|
|
.Ar username
|
|
.Nm "arsse user set"
|
|
.Ar username
|
|
.Ar property
|
|
.Ar value
|
|
.Nm "arsse user unset"
|
|
.Ar username
|
|
.Ar property
|
|
.Nm "arsse user set\-pass"
|
|
.Ar username
|
|
.Op Ar password
|
|
.Op Fl Fl fever
|
|
.Nm "arsse user unset\-pass"
|
|
.Ar username
|
|
.Op Fl Fl fever
|
|
.Nm "arsse user auth"
|
|
.Ar username
|
|
.Op Ar password
|
|
.Op Fl Fl fever
|
|
.Nm "arsse token list"
|
|
.Ar username
|
|
.Nm "arsse token create"
|
|
.Ar username
|
|
.Op Ar label
|
|
.Nm "arsse token revoke"
|
|
.Ar username
|
|
.Op Ar token
|
|
.Nm "arsse import"
|
|
.Ar username
|
|
.Op Ar file
|
|
.Op Fl f | Fl Fl flat
|
|
.Op Fl r | Fl Fl replace
|
|
.Nm "arsse export"
|
|
.Ar username
|
|
.Op Ar file
|
|
.Op Fl f | Fl Fl flat
|
|
.Nm "arsse daemon"
|
|
.Op Fl Fl fork Ns = Ns Ar pidfile
|
|
.Nm "arsse feed refresh\-all"
|
|
.Nm "arsse feed refresh"
|
|
.Ar n
|
|
.Nm "arsse conf save\-defaults"
|
|
.Nm "arsse"
|
|
.Fl Fl version | Fl h | Fl Fl help
|
|
.
|
|
.
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
allows a sufficiently privileged user to perform various administrative operations related to The Arsse, including:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
Adding and removing users and managing their metadata
|
|
.It
|
|
Managing passwords and authentication tokens
|
|
.It
|
|
Importing and exporting OPML newsfeed-lists
|
|
.El
|
|
.Pp
|
|
These are documented in the next section
|
|
.Sx COMMANDS Ns No .
|
|
Further, seldom-used commands are documented in the subsequent 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
|
|
.Bl -tag
|
|
.It Add an administrator to the database with an explicit password:
|
|
.Bd -literal
|
|
$ arsse user add \-\-admin alice "Curiouser and curiouser!"
|
|
.Ed
|
|
.It Add a regular user to the database with a random password:
|
|
.Bd -literal
|
|
$ arsse user add "Bob the Builder"
|
|
bLS!$_UUZ!iN2i_!^IC6
|
|
.Ed
|
|
.It Make Bob the Builder an administrator:
|
|
.Bd -literal
|
|
$ arsse user set "Bob the Builder" admin true
|
|
.Ed
|
|
.It Disable Alice's account by clearing her password:
|
|
.Bd -literal
|
|
$ arsse user unset\-pass alice
|
|
.Ed
|
|
.It Move all of Foobar's newsfeeds to the root folder:
|
|
.Bd -literal
|
|
$ arsse export foobar \-f | arsse import \-r foobar
|
|
.Ed
|
|
.It Fail to log in as Alice:
|
|
.Bd -literal
|
|
$ arsse user auth alice "Oh, dear!"
|
|
Authentication failed
|
|
$ echo $?
|
|
1
|
|
.Ed
|
|
.El
|
|
.
|
|
.
|
|
.Sh REPORTING BUGS
|
|
Any bugs found in The Arsse may be reported on the Web via the
|
|
.Lk https://code.mensbeam.com/MensBeam/arsse "MensBeam code repository"
|
|
or may be directed to the principal authors by e-mail:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
.Lk https://jkingweb.ca/ "J. King"
|
|
.It
|
|
.Lk https://dustinwilson.com/ "Dustin Wilson"
|
|
.El
|
|
|