Ted Unangst
5 years ago
parent
7830694baa
commit
0a262dbc96
@ -1,54 +0,0 @@
|
||||
|
||||
Honk administration guide.
|
||||
|
||||
This is the admin manual. Please refer to manual.txt for user documentation.
|
||||
|
||||
-- css
|
||||
|
||||
Custom CSS may be provided by creating a views/local.css file.
|
||||
|
||||
-- message
|
||||
|
||||
A custom server message may be set adding a ('servermsg', 'message') entry to
|
||||
the config table using sqlite3.
|
||||
|
||||
-- emus and memes
|
||||
|
||||
Custom emus may be provided by creating and populating the emus directory.
|
||||
emus may be referenced when composing a honk via colon wrapping. How pleasant.
|
||||
This :example: will be replaced by emus/example.png.
|
||||
|
||||
To save disk space and avoid repeated uploads, the memes directory may be
|
||||
prepopulated with bandwidth wasting reactions and referenced by meme: filename.
|
||||
|
||||
A list of available emus and memes appears in the funzone.
|
||||
|
||||
-- cleanup
|
||||
|
||||
One should occasionally run `honk cleanup` to free up internal space in the
|
||||
database. This deletes honks older than 30 days, but not those posted by a
|
||||
user. `honk cleanup [days]` may be used to adjust the timeframe.
|
||||
|
||||
One may also run `honk cleanup [honker]` to delete honks older than 3 days.
|
||||
This is useful to reduce the space requirements from following image bots.
|
||||
|
||||
(Neither command runs vacuum, so the file size will not immediately shrink.)
|
||||
|
||||
-- add user
|
||||
|
||||
Running `honk adduser` can add additional users. This is discouraged.
|
||||
|
||||
-- proxy
|
||||
|
||||
honk requires a TLS terminating reverse proxy be configured. It communicates
|
||||
with other servers via https URLs.
|
||||
|
||||
If the proxy is configured to support caching, be mindful of the fact that
|
||||
ActivityPub requests vary based on the Accept and Content-Type headers.
|
||||
|
||||
ActivityPub in practice uses HTTP signatures to verify requests. In order for
|
||||
this to work, the backend server must receive certain header fields
|
||||
unmodified. In particular, the Host header and the message content cannot be
|
||||
altered.
|
||||
|
||||
Specifically, for nginx: `proxy_set_header Host $http_host;`
|
||||
@ -1,110 +0,0 @@
|
||||
|
||||
Instructions for using honk.
|
||||
|
||||
This is the user manual. Please refer to admin.txt for administration.
|
||||
|
||||
-- posting
|
||||
|
||||
Should work as expected.
|
||||
|
||||
Limited markdown support:
|
||||
**bold** and *italics*
|
||||
`code` and ```code block```
|
||||
> quote
|
||||
|
||||
Large images are rescaled and reduced.
|
||||
|
||||
The honk back button will prefill the forms for replies.
|
||||
|
||||
-- sensitive honks
|
||||
|
||||
A honk that begins with the danger zone indication, DZ:, will be marked
|
||||
sensitive, using the first line as a summary (spoiler text).
|
||||
|
||||
-- following
|
||||
|
||||
In order to follow somebody, you need to enter one of two identifiers.
|
||||
|
||||
The easiest is probably their handle, the thing that resembles an email.
|
||||
@name@example.com for example.
|
||||
|
||||
Alternatively, one may directly enter the actor ID, which is a URL that looks
|
||||
like https://example.com/users/name.
|
||||
|
||||
Followed honkers may be assigned to combos, listing all their honks together.
|
||||
|
||||
Followed honkers will appear on the main feedtube unless silenced. Honkers may
|
||||
be silenced by adding them to a combo named "-". (One dash.)
|
||||
|
||||
Selecting just peeping won't actually follow them. (Incomplete feature.)
|
||||
Can be useful for managing as part of a combo, however.
|
||||
|
||||
-- xzone
|
||||
|
||||
Individual honks may be manually fetched via the xzone.
|
||||
|
||||
Additionally, entering a honker URL will fetch all their recent honks.
|
||||
|
||||
A list of recently known honkers will appear as well.
|
||||
|
||||
-- zonking
|
||||
|
||||
You can zonk anything you like (or dislike), either your own honk or
|
||||
those of others that you're tired of seeing. Be advised that deletion
|
||||
works poorly in a federated environment. It's more like please disregard.
|
||||
|
||||
-- privacy
|
||||
|
||||
Posted honks are public. The federated environment lacks robust privacy
|
||||
controls.
|
||||
|
||||
Received messages are only visible when logged in, regardless of addressing.
|
||||
Content from outside is not publicly rehosted, unless bonked.
|
||||
|
||||
Received messages that are less than public are tagged with a red border.
|
||||
As a special exception to the public honking rule, replies to limited messages
|
||||
will be restricted as much as possible. Note that ActivityPub leaks. Do
|
||||
not use honk for posting truly private information.
|
||||
|
||||
-- emus and memes
|
||||
|
||||
A list of available emus and memes appears in the funzone.
|
||||
|
||||
Emus such as :example: will be inlined into posts.
|
||||
|
||||
Memes such as `meme: example.mp4` will be appended to posts.
|
||||
|
||||
-- hoots
|
||||
|
||||
Link and inline a hoot and replies from that other bird site.
|
||||
hoot: https://twitter.com/tedunangst/status/839169710675611658
|
||||
|
||||
-- cleanup
|
||||
|
||||
One should occasionally run `honk cleanup` to free up internal space in the
|
||||
database. This deletes honks older than 30 days, but not those posted by a
|
||||
user.
|
||||
|
||||
One may also run `honk reduce [honker]` to delete honks older than 3 days.
|
||||
This is useful to reduce the space requirements from following image bots.
|
||||
|
||||
(Neither command runs vacuum, so the file size will not immediately shrink.)
|
||||
|
||||
-- add user
|
||||
|
||||
Running `honk adduser` can add additional users. This is discouraged.
|
||||
|
||||
-- proxy
|
||||
|
||||
honk requires a TLS terminating reverse proxy be configured. It communicates
|
||||
with other servers via https URLs.
|
||||
|
||||
If the proxy is configured to support caching, be mindful of the fact that
|
||||
ActivityPub requests vary based on the Accept and Content-Type headers.
|
||||
|
||||
ActivityPub in practice uses HTTP signatures to verify requests. In order for
|
||||
this to work, the backend server must receive certain header fields
|
||||
unmodified. In particular, the Host header and the message content cannot be
|
||||
altered.
|
||||
|
||||
Specifically, for nginx: `proxy_set_header Host $http_host;`
|
||||
@ -1,25 +0,0 @@
|
||||
|
||||
Some notes about security.
|
||||
|
||||
honk is not currently hardened against SSRF, server side request forgery. Be
|
||||
mindful of what else may be reachable on localhost or the local network if
|
||||
it's not generally accessible.
|
||||
|
||||
Key and signature verification is best effort, but some forgeries may sneak
|
||||
past. In particular, tying together key name, key owner, actor, object, etc.
|
||||
is incomplete.
|
||||
|
||||
How are user keys supposed to be rotated? Expired? Revoked?
|
||||
|
||||
The current answer is never, never, never.
|
||||
|
||||
If the key is only used for signing http requests, it can be be changed
|
||||
basically at will. Change the key in the actor, give it a new name (to avoid
|
||||
conflict with any cached keys), carry on.
|
||||
|
||||
Since keynames in practice don't change, honk will simply discard a key after
|
||||
a signature failure and attempt to get a fresh key.
|
||||
|
||||
Using keys to sign json is more complicated. The current practice is to name
|
||||
keys with URL fragments. example.com/user#key. If the keyname is changed to
|
||||
#newkey, how does one fetch the old key to verify existing data?
|
||||
@ -1,75 +0,0 @@
|
||||
honk spec
|
||||
|
||||
-- references
|
||||
|
||||
See security.txt for some notes on security.
|
||||
|
||||
See ping.txt for a proposed Ping extension to ActivityPub.
|
||||
|
||||
-- retries
|
||||
|
||||
If a message can't be delivered, we backoff and retry.
|
||||
|
||||
1 - five minutes later in case the servce restarted
|
||||
2 - one hour later in case the server rebooted
|
||||
3 - 12 more hours later in case the server was upgraded
|
||||
4 - 24 more hours later in case there was a catastrophe
|
||||
5 - it's dead.
|
||||
|
||||
A random drift of up to 10% is added to each delay to avoid swarming.
|
||||
|
||||
-- federating
|
||||
|
||||
Messages are transformed for federation and display. Some transformations
|
||||
occur send side and some occur receive side because it's more exciting that
|
||||
way. @mentions and *markdown* are converted to HTML before transmission.
|
||||
Message :emoji: are converted to inline images after receiving.
|
||||
|
||||
Up to four parents of a reply will be fetched.
|
||||
|
||||
Attachments for received messages are rescaled before saving.
|
||||
|
||||
-- schema
|
||||
|
||||
Some notes on the database schema. Mostly for development, but maybe useful
|
||||
for administration as well.
|
||||
|
||||
The config table contains settings, some of which may not be editable via the
|
||||
normal interface.
|
||||
|
||||
For development purposes, adding a config value ('debug', 1) to the database
|
||||
will disable caching and hot reload the templates. It's not meant to be
|
||||
harmful in production, just less efficient.
|
||||
|
||||
We don't use null, only empty strings. This is easier to work with on the go
|
||||
side.
|
||||
|
||||
The main table is honks. This stores both locally created honks and incoming
|
||||
ActivityPub notes converted to honks. It is important to differentiate the two
|
||||
cases so that we don't accidentally publish external honks in the public web
|
||||
view. The whofore column value of 2 indiciates a public honk.
|
||||
|
||||
The what column further refines the type of honk.
|
||||
|
||||
Attachments are physically saved as files, and logically joined to honks via
|
||||
the donks table. Emus are saved as donks as well.
|
||||
|
||||
The honkers table is used to manage follows and followers. The flavor column
|
||||
describes what. 'sub' is a follow. We have subscribed to their newsletter.
|
||||
'dub' is a follower. They get dubbed whenever we honk.
|
||||
|
||||
The xonkers table stores info about external accounts that we may interact
|
||||
with. Their keys, their inboxes, etc. Not user visible.
|
||||
|
||||
The zonkers table stores things we do not wish to see, per the wherefore
|
||||
column. Also used for tombstones for deleted honks to prevent refetching.
|
||||
|
||||
The xid column generally corresponds to ActivityPub id.
|
||||
|
||||
Note that some logical seeming joins won't work. The honker column of honks
|
||||
may not have a corresponding entry in the honkers table, since we frequently
|
||||
receive messages from people we don't follow. Should we track everybody whose
|
||||
identity crosses our path? This seems unnecessary. The honkers table is more
|
||||
like a mapping of active relationships, not a directory of all peoples.
|
||||
|
||||
Some deduping of honks is performed. This may not be perfect.
|
||||
Loading…
Reference in new issue