From 1ef669a464fd608e4335142fafbdeadb2b041364 Mon Sep 17 00:00:00 2001 From: "J. King" Date: Wed, 31 Jul 2019 14:57:43 -0400 Subject: [PATCH] Documentation for user management and OPML --- .../025_Using_The_Arsse/010_Managing_Users.md | 55 +++++++++++++++++++ .../020_Importing_and_Exporting.md | 54 ++++++++++++++++++ ...md => 030_Keeping_Newsfeeds_Up_to_Date.md} | 0 ...n.md => 040_Upgrading_to_a_New_Version.md} | 0 docs/en/025_Using_The_Arsse/index.md | 20 +++++++ docs/en/030_Supported_Protocols/030_Fever.md | 4 +- lib/CLI.php | 2 +- 7 files changed, 132 insertions(+), 3 deletions(-) create mode 100644 docs/en/025_Using_The_Arsse/020_Importing_and_Exporting.md rename docs/en/025_Using_The_Arsse/{020_Keeping_Newsfeeds_Up_to_Date.md => 030_Keeping_Newsfeeds_Up_to_Date.md} (100%) rename docs/en/025_Using_The_Arsse/{030_Upgrading_to_a_New_Version.md => 040_Upgrading_to_a_New_Version.md} (100%) create mode 100644 docs/en/025_Using_The_Arsse/index.md diff --git a/docs/en/025_Using_The_Arsse/010_Managing_Users.md b/docs/en/025_Using_The_Arsse/010_Managing_Users.md index e69de29b..99aeeac9 100644 --- a/docs/en/025_Using_The_Arsse/010_Managing_Users.md +++ b/docs/en/025_Using_The_Arsse/010_Managing_Users.md @@ -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 +``` + + + + + diff --git a/docs/en/025_Using_The_Arsse/020_Importing_and_Exporting.md b/docs/en/025_Using_The_Arsse/020_Importing_and_Exporting.md new file mode 100644 index 00000000..4184e2a9 --- /dev/null +++ b/docs/en/025_Using_The_Arsse/020_Importing_and_Exporting.md @@ -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 + + + + + + + + + + + + + +``` + +# 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 +``` diff --git a/docs/en/025_Using_The_Arsse/020_Keeping_Newsfeeds_Up_to_Date.md b/docs/en/025_Using_The_Arsse/030_Keeping_Newsfeeds_Up_to_Date.md similarity index 100% rename from docs/en/025_Using_The_Arsse/020_Keeping_Newsfeeds_Up_to_Date.md rename to docs/en/025_Using_The_Arsse/030_Keeping_Newsfeeds_Up_to_Date.md diff --git a/docs/en/025_Using_The_Arsse/030_Upgrading_to_a_New_Version.md b/docs/en/025_Using_The_Arsse/040_Upgrading_to_a_New_Version.md similarity index 100% rename from docs/en/025_Using_The_Arsse/030_Upgrading_to_a_New_Version.md rename to docs/en/025_Using_The_Arsse/040_Upgrading_to_a_New_Version.md diff --git a/docs/en/025_Using_The_Arsse/index.md b/docs/en/025_Using_The_Arsse/index.md new file mode 100644 index 00000000..923d6666 --- /dev/null +++ b/docs/en/025_Using_The_Arsse/index.md @@ -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 + Tests logging in as with 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.