From 30e3f2fc3d121a5d0bdf6ed201da7965ecbca7df Mon Sep 17 00:00:00 2001 From: default Date: Sun, 4 Dec 2022 07:18:24 +0100 Subject: [PATCH] Updated documentation. --- doc/snac.1 | 6 ++---- doc/snac.5 | 59 ++++++++++++++++++++++++------------------------------ doc/snac.8 | 16 +++++++-------- 3 files changed, 35 insertions(+), 46 deletions(-) diff --git a/doc/snac.1 b/doc/snac.1 index 3e34725..0b6d75a 100644 --- a/doc/snac.1 +++ b/doc/snac.1 @@ -141,12 +141,12 @@ the post and its children anymore. The command-line tool provide the following commands: .Bl -tag -offset indent .It Cm init Op basedir -Initializes the database. This is an interactive command; necessary +Initializes the data storage. This is an interactive command; necessary information will be prompted for. The .Ar basedir directory must not exist. .It Cm upgrade Ar basedir -Upgrades the database disk layout after installing a new version. +Upgrades the data storage after installing a new version. Only necessary if .Nm complains and demands it. @@ -166,8 +166,6 @@ Starts the daemon. Processes the output queue of the specied user, sending all enqueued messages and re-enqueing the failing ones. This command must not be executed if the server is running. -.It Cm passwd Ar basedir Ar uid -Changes the password for a user (interactive). .It Cm follow Ar basedir Ar uid Ar actor Sends a Follow message for the specified actor URL. .It Cm request Ar basedir Ar uid Ar url diff --git a/doc/snac.5 b/doc/snac.5 index 02bd85b..0b58a2d 100644 --- a/doc/snac.5 +++ b/doc/snac.5 @@ -50,13 +50,11 @@ The following traditional ASCII emoticons or special strings are converted to related emojis: .Bd -literal :-) :-D X-D ;-) B-) :-( :-* <3 :-/ 8-o -%-) :_( :-| :facepalm: :shrug: :eyeroll: -:beer: :beers: :munch: :thumb: +%-) :_( :-| :facepalm: :shrug: :shrug2: +:eyeroll: :beer: :beers: :munch: :thumb: .Ed .El .Pp -HTML tags are not filtered on input. -.Pp .Ss Accepted HTML All HTML tags in entries are neutered except the following ones: .Bd -literal @@ -74,6 +72,10 @@ The base directory contains the following files and folders: Server configuration. .It Pa user/ Directory holding user subdirectories. +.It Pa object/ +Directory holding the ActivityPub objects. Filenames are hashes of each +message Id, stored in subdirectories starting with the first two letters +of the hash. .It Pa archive/ If this directory exists, all input and output messages are logged inside it, including HTTP headers. Only useful for debugging. May grow to enormous sizes. @@ -87,36 +89,31 @@ has the user id as name and contains the following subdirectories and files: User configuration file. .It Pa key.json SHA-1 secret/public key PEM data. -.It Pa actors/ -This subdirectory stores cached 'Person' ActivityPub messages as JSON files. Each -file name is an MD5 hash of the actor URL. -.It Pa timeline/ -This subdirectory stores the user's timeline. Everytime a valid message arrives, -it's stored in this directory as a JSON object. The file name spec is: a Unix -timestamp followed by a hyphen followed by an MD5 of the message Id. Additionally, -metadata for each message parent and children is stored under the '_snac' field; -parent messages with new children are renamed with an updated timestamp so that -the more recently updated thread is shown at the top. This directory is presented -in the web interface in reverse file name order up to a maximum, hardcoded limit. -These files are purged when they are considered old (this time can be changed by -tweaking the server configuration). -.It Pa local/ -This subdirectory stores all activities generated by this user as hardlinks to -their analogue entries in the -.Pa timeline/ -subdirectory. +.It Pa followers.idx +This file contains the list of followers as a list of hashed object identifiers. .It Pa followers/ -This subdirectory stores the 'Follow' ActivityPub message from each -Fediverse user that is following this user as a JSON file. Each file name is -an MD5 hash of the actor that is a follower of this user. +This directory stores hard links to the actor objects in the object storage. .It Pa following/ -This subdirectory stores the 'Follow' (not yet confirmed) or the 'Accept' -(confirmed) ActivityPub message for each actor that is being followed. Each file -name is an MD5 hash of the actor. +This directory stores the users being followed as hard links to the 'Follow' +or 'Accept' objects in the object storage. File names are the hashes of each +actor Id. +.It Pa private.idx +This file contains the list of timeline entries as a list of hashed +object identifiers. +.It Pa private/ +This directory stores hard links to the timeline entries in the object storage. +.It Pa public.idx +This file contains the list of public timeline entries as a list of hashed +object identifiers. +.It Pa public/ +This directory stores hard links to the public timeline entries in the object +storage. .It Pa muted/ -This directory contains files which names are MD5 hashes of muted actors. The +This directory contains files which names are hashes of muted actors. The content is a line containing the actor URL. Messages from these actors will be ignored on input and not shown in any timeline. +.It Pa hidden/ +This directory contains references to the hidden timeline entries. .It Pa queue/ This directory contains the output queue of messages generated by the user as JSON files. File names contain timestamps that indicate when the message will @@ -133,10 +130,6 @@ web interface. .It Pa history/ This directory contains generated HTML files. They may be snapshots of the local timeline in previous months or other cached data. -.It Pa archive/ -This directory is no longer used in version 2.x and later. It can be deleted. -.Nm -is run with a debug level >= 1. .El .Sh SEE ALSO .Xr snac 1 , diff --git a/doc/snac.8 b/doc/snac.8 index 60671a1..eca1420 100644 --- a/doc/snac.8 +++ b/doc/snac.8 @@ -29,7 +29,7 @@ link counts. Remember: is a very UNIXy program that loves hard links. .Ss Building and Installation A C compiler must be installed in the system, as well as the development -headers and libraries for OpenSSL and curl. To build +headers and libraries for OpenSSL (or compatible) and curl. To build .Nm , run .Bd -literal -offset indent @@ -40,7 +40,7 @@ And, after that, run as root .Bd -literal -offset indent make install .Ed -.Ss Database Initialization +.Ss Data storage Initialization Once .Nm is properly installed on the system, designate a directory where @@ -48,7 +48,7 @@ the server and user data are to be stored. This directory must not exist yet. .Nm must always be run as a regular user; you can create one for -it or use your own. To initialize the database, execute +it or use your own. To initialize the data storage, execute .Bd -literal -offset indent snac init $HOME/snac-data .Ed @@ -83,13 +83,14 @@ directory. For other operating systems, please read the appropriate documentation on how to install a daemon as a non-root service. .Ss Upgrading to a new version -Sometimes, the database disk layout changes between versions. If there +Sometimes, the data storage disk layout changes between versions. If there is such a change, .Nm will refuse to run and require an upgrade. Do this by running .Bd -literal -offset indent snac upgrade $HOME/snac-data .Ed +.Pp Take special care to execute this upgrade operation without any .Nm processes serving on the same folder. You can break everything. I know @@ -195,10 +196,7 @@ supports: Complete support, on input and output. .It Vt Undo For -.Vt Follow , -.Vt Like -and -.Vt Announce +.Vt Follow objects, on input and output. .It Vt Create For @@ -265,7 +263,7 @@ bloated and filled with redundant information. Using a filesystem with file compression enabled (like btrfs or zfs) will probably be a good choice to store the .Nm -database into. +data storage into. .Sh ENVIRONMENT .Bl -tag -width Ds .It Ev DEBUG