mirror of
https://code.mensbeam.com/MensBeam/Arsse.git
synced 2024-12-22 13:12:41 +00:00
Documentation for user management and OPML
This commit is contained in:
parent
daa3be90c6
commit
1ef669a464
7 changed files with 132 additions and 3 deletions
|
@ -0,0 +1,55 @@
|
|||
[TOC]
|
||||
|
||||
# Preface
|
||||
|
||||
This section describes in brief some CLI commands. Please read [the general notes on the command line interface](index) before continuing.
|
||||
|
||||
# Adding Users
|
||||
|
||||
When first installed, The Arsse has no users configured. You may add users by executing the following command:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php user add "user@example.com" "example password"
|
||||
```
|
||||
|
||||
The password argument is optional: if no password is provided, a random one is generated and printed out:
|
||||
|
||||
```console
|
||||
$ sudo -u www-data php arsse.php user add "jane.doe"
|
||||
Ji0ivMYqi6gKxQK1MHuE
|
||||
```
|
||||
|
||||
# Setting and Changing Passwords
|
||||
|
||||
Setting's a user's password is practically identical to adding a password:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php user set-pass "user@example.com" "new password"
|
||||
```
|
||||
|
||||
As when adding a user, the password argument is optional: if no password is provided, a random one is generated and printed out:
|
||||
|
||||
```console
|
||||
$ sudo -u www-data php arsse.php user set-pass "jane.doe"
|
||||
Ummn173XjbJT4J3Gnx0a
|
||||
```
|
||||
|
||||
## Setting and Changing Passwords for Fever
|
||||
|
||||
Before a user can make use of [the Fever protocol](/en/Supported_Protocols/Fever), a Fever-specific password for that user must be set. It is _highly recommended_ that this not be the samer as the user's main password. The password can be set by adding the `--fever` option to the normal password-changing command:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php user set-pass --fever "user@example.com" "fever password"
|
||||
```
|
||||
|
||||
As when setting a main password, the password argument is optional: if no password is provided, a random one is generated and printed out:
|
||||
|
||||
```console
|
||||
$ sudo -u www-data php arsse.php user set-pass --fever "jane.doe"
|
||||
YfZJHq4fNTRUKDYhzQdR
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
54
docs/en/025_Using_The_Arsse/020_Importing_and_Exporting.md
Normal file
54
docs/en/025_Using_The_Arsse/020_Importing_and_Exporting.md
Normal file
|
@ -0,0 +1,54 @@
|
|||
[TOC]
|
||||
|
||||
# Preface
|
||||
|
||||
This section describes in brief some CLI commands. Please read [the general notes on the command line interface](index) before continuing.
|
||||
|
||||
# Importing Newsfeeds from OPML
|
||||
|
||||
It's possible to import not only newsfeeds but also folders and Fever groups using OPML files. The process is simple:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php import "user@example.com" "subscriptions.opml"
|
||||
```
|
||||
|
||||
The importer is forgiving, but some OPML files may fail, with the reason printed out. Files are either imported in total, or not at all.
|
||||
|
||||
# Exporting Newsfeeds to OPML
|
||||
|
||||
It's possible to export not only newsfeeds but also folders and Fever groups to OPML files. The process is simple:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php export "user@example.com" "subscriptions.opml"
|
||||
```
|
||||
|
||||
The output might look like this:
|
||||
|
||||
```xml
|
||||
<opml version="2.0">
|
||||
<head/>
|
||||
<body>
|
||||
<outline text="Folder">
|
||||
<outline text="Subfolder">
|
||||
<outline type="rss" text="Feed 1" xmlUrl="http://example.com/feed1"/>
|
||||
</outline>
|
||||
<outline type="rss" text="Feed 2" xmlUrl="http://example.com/feed2" category="group 1,group 2"/>
|
||||
<outline type="rss" text="Feed 3" xmlUrl="http://example.com/feed3" category="group 1"/>
|
||||
</outline>
|
||||
<outline type="rss" text="Feed 4" xmlUrl="http://example.com/feed4" category="group 2,group 3"/>
|
||||
</body>
|
||||
</opml>
|
||||
```
|
||||
|
||||
# Managing Newsfeeds via OPML
|
||||
|
||||
Not all protocols supported by The Arsse allow modifying newsfeeds or folders, et cetera; additionally, not all clients support these capabilities even if the protocol has the necessary features. An OPML export/import sequence with the `--replace` import option specified, however, makes any kind of modification possible. For example:
|
||||
|
||||
```sh
|
||||
# export your newsfeeds
|
||||
sudo -u www-data php arsse.php export "user@example.com" "subscriptions.opml"
|
||||
# make any changes you want in your editor of choice
|
||||
nano "subscriptions.opml"
|
||||
# re-import the modified information
|
||||
sudo -u www-data php arsse.php import "user@example.com" "subscriptions.opml" --replace
|
||||
```
|
20
docs/en/025_Using_The_Arsse/index.md
Normal file
20
docs/en/025_Using_The_Arsse/index.md
Normal file
|
@ -0,0 +1,20 @@
|
|||
# Preface
|
||||
|
||||
This section details a few administrative tasks which may need to be performed after installing The Arsse. As no Web-based administrative interface is included, these tasks are generally performed via command line interface.
|
||||
|
||||
Though this section describes some commands briefly, complete documentation of The Arsse's command line interface is not included in this manual. Documentation for CLI commands can instead be viewed with the CLI itself by executing `php arsse.php --help`.
|
||||
|
||||
# A Note on Command Invocation
|
||||
|
||||
Particularly if using an SQLite database, it's important that administrative commands be executed as the same user who owns The Arsse's files. To that end the examples in this section all use the verbose formulation `sudo -u www-data php arsse.php` (with `www-data` being the user under which Web servers run in Debian), but it is possible to simplify invocation to `sudo arsse` if an executable file named `arsse` is created somewhere in the sudo path with the following content:
|
||||
|
||||
```php
|
||||
#! /usr/bin/env php
|
||||
<?php
|
||||
if (posix_geteuid() == 0) {
|
||||
$info = posix_getpwnam("www-data");
|
||||
posix_setegid($info['gid']);
|
||||
posix_seteuid($info['uid']);
|
||||
}
|
||||
include "/usr/share/arsse/arsse.php";
|
||||
```
|
|
@ -27,9 +27,9 @@ The Fever protocol is incomplete, unusual, _and_ a product of proprietary softwa
|
|||
|
||||
# Special considerations
|
||||
|
||||
- Because of Fever's unusual and insecure authentication scheme, a Fever-specific password [must be created](/en/Getting_Started/Managing_Users) before a user can communicate via the Fever protocol
|
||||
- Because of Fever's unusual and insecure authentication scheme, a Fever-specific password [must be created](/en/Using_The_Arsse/Managing_Users) before a user can communicate via the Fever protocol
|
||||
- The Fever protocol does not allow for adding or modifying feeds. Another protocol or OPML importing must be used to manage feeds
|
||||
- Unlike other protocols supported by The Arsse, Fever uses "groups" (more commonly known as tags or labels) instead of folders to organize feeds. Currently OPML importing is the only means of managing groups
|
||||
- Unlike other protocols supported by The Arsse, Fever uses "groups" (more commonly known as tags or labels) instead of folders to organize feeds. Currently [OPML importing](/en/Using_The_Arsse/Importing_and_Exporting) is the only means of managing groups
|
||||
|
||||
# Other notes
|
||||
|
||||
|
|
|
@ -99,7 +99,7 @@ Commands:
|
|||
user auth <username> <password>
|
||||
|
||||
Tests logging in as <username> with password <password>. This only checks
|
||||
that the user's password is currectly recognized; it has no side effects.
|
||||
that the user's password is correctly recognized; it has no side effects.
|
||||
|
||||
The --fever option may be used to test the user's Fever protocol password,
|
||||
if any.
|
||||
|
|
Loading…
Reference in a new issue