mirror/Arsse
1
1
Fork 0
mirror of https://code.mensbeam.com/MensBeam/Arsse.git synced 2024-12-22 21:22:40 +00:00
Code Issues Activity

Documentation for user management and OPML

Browse source
This commit is contained in:
J. King 2019-07-31 14:57:43 -04:00
parent daa3be90c6
commit 1ef669a464
7 changed files with 132 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
docs/en/025_Using_The_Arsse/010_Managing_Users.md
View file

@ -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
View 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
```

0
docs/en/025_Using_The_Arsse/020_Keeping_Newsfeeds_Up_to_Date.md → docs/en/025_Using_The_Arsse/030_Keeping_Newsfeeds_Up_to_Date.md
View file

0
docs/en/025_Using_The_Arsse/030_Upgrading_to_a_New_Version.md → docs/en/025_Using_The_Arsse/040_Upgrading_to_a_New_Version.md
View file

20
docs/en/025_Using_The_Arsse/index.md Normal file
View 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";
```

4
docs/en/030_Supported_Protocols/030_Fever.md
View file

@ -27,9 +27,9 @@ The Fever protocol is incomplete, unusual, _and_ a product of proprietary softwa
# Special considerations # 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 - 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 # Other notes

2
lib/CLI.php
View file

@ -99,7 +99,7 @@ Commands:
user auth <username> <password> user auth <username> <password>
Tests logging in as <username> with password <password>. This only checks 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, The --fever option may be used to test the user's Fever protocol password,
if any. if any.