snac.1 (18270B)
1 .Dd $Mdocdate$ 2 .Dt SNAC 1 3 .Os 4 .Sh NAME 5 .Nm snac 6 .Nd A simple, minimalistic ActivityPub instance 7 .Sh SYNOPSIS 8 .Nm 9 .Cm command 10 .Ar basedir 11 .Op Ar option ... 12 .Sh DESCRIPTION 13 The 14 .Nm 15 daemon processes messages from other servers in the Fediverse 16 using the ActivityPub protocol. 17 .Pp 18 This is the user manual and expects an already running 19 .Nm 20 installation. For the administration manual, see 21 .Xr snac 8 . 22 For file and data formats, see 23 .Xr snac 5 . 24 .Ss Web Interface 25 The web interface provided by 26 .Nm 27 is split in two data streams: the public timeline and the 28 private timeline. There are no other feeds like the server-scoped 29 or the federated firehoses provided by other similar ActivityPub 30 implementations like Mastodon or Pleroma. 31 .Pp 32 The public timeline, also called the local timeline, is what an 33 external visitor sees about the activity of a 34 .Nm 35 user: that is, only the list of public notes, boosts and likes 36 the user generates or participates into. This is, obviously, 37 read-only, and not very remarkable, unless the user publishes 38 messages of staggering genious. A set of history links, grouped 39 by month, will also be available at the bottom of the page. 40 .Pp 41 The private timeline, or simply the timeline, is the private, 42 password-protected area of a 43 .Nm 44 server where the user really interacts with the rest of the 45 Fediverse. 46 .Pp 47 The top area of the timeline provides a big text area to write 48 notes for the public (i.e. for the user followers). As this is 49 the second most important activity on the Fediverse, this is 50 located in the most prominent area of the user page. You can 51 enter plain text, @user@host mentions and other things. See the 52 .Xr snac 5 53 manual for more information on the allowed markup. 54 .Pp 55 Other fields immediately below the big text one allow some control 56 about the post to be sent: 57 .Bl -tag -offset indent 58 .It Sensitive content 59 If you set this checkbox, your post will be marked with a 60 content warning. The immediately following, optional text box 61 allows you to write a description about why your content is 62 so sensitive. 63 .It Only for mentioned people 64 If you set this checkbox, your text will not be public, but only 65 sent to those people you mention in the post body. 66 .It Reply to (URL) 67 If you fill this optional text field with the URL of another one's 68 post, your text will be considered as a reply to it, not a 69 standalone one. 70 .El 71 .Pp 72 More options are hidden under a toggle control. They are the 73 following: 74 .Bl -tag -offset indent 75 .It Follow (by URL or user@host) 76 Fill the input area with a user 'actor' URL or a user@host 77 Fediverse identifier to follow. 78 .It Boost (by URL) 79 Fill the input area with the URL of a Fediverse note to be 80 boosted. 81 .It Like (by URL) 82 Fill the input area with the URL of a Fediverse note to be 83 liked. 84 .It User setup... 85 This option opens the user setup dialog. 86 .It Followed hashtags... 87 Enter here the list of hashtags you want to follow, one 88 per line, with or without the # symbol. Since version 2.78, 89 URLs to RSS feeds of ActivityPub objects are also allowed 90 (like e.g. https://mastodon.social/tags/bloomscrolling). 91 .It Blocked hashtags... 92 Enter here the list of hashtags you want to block, one 93 per line, with or without the # symbol. 94 .El 95 .Pp 96 The user setup dialog allows some user information to be 97 changed, specifically: 98 .Bl -tag -offset indent 99 .It User name 100 Your user name, or not really that. People like to include 101 emojis, flags and strange symbols for some reason. 102 .It Avatar URL 103 The URL of a picture to be used as your avatar in timelines 104 around the world. 105 .It Bio 106 Enter here a bunch of self-indulgent blurb about yourself. 107 The same markup options available for text notes apply here. 108 .It Always show sensitive content 109 By default, 110 .Nm 111 hides content marked as sensitive by their publishers. 112 If you check this option, sensitive content is always shown. 113 .It Email address for notifications 114 If this field is not empty, an email message will be sent 115 to this address whenever a post written by you is liked, 116 boosted or replied to. 117 .It Telegram notifications 118 To enable notifications via Telegram, fill the two provided 119 fields (Bot API key and Chat id). You need to create both 120 a Telegram channel and a bot for this; the process is rather 121 cumbersome but it's documented everywhere. The Bot API key 122 is a long string of alphanumeric characters and the chat id 123 is a big, negative number. 124 .It ntfy notifications 125 To enable notifications via ntfy (both self-hosted or 126 standard ntfy.sh server), fill the two provided 127 fields (ntfy server/topic and, if protected, the token). 128 You need to refer to the https://ntfy.sh web site for 129 more information on this process. 130 .It Notify webhook 131 If this is set to an URL, an HTTP POST will be sent to it 132 whenever a new notification happens (see the 'Webhook for 133 notifications' section below for more information). 134 .It Maximum days to keep posts 135 This numeric value specifies the number of days to pass before 136 posts (yours and others') will be purged. This value overrides 137 what the administrator defined in the global server settings 138 only if it's lesser (i.e. you cannot keep posts for longer 139 than what the admin desires). A value of 0 (the default) means 140 that the global server settings will apply to the posts in your 141 timeline. 142 .It Drop direct messages from people you don't follow 143 Just what it says in the tin. This is to mitigate spammers 144 coming from Fediverse instances with lax / open registration 145 processes. Please take note that this also avoids possibly 146 legitimate people trying to contact you. 147 .It This account is a bot 148 Set this checkbox if this account behaves like a bot (i.e. 149 posts are automatically generated). 150 .It Auto-boost all mentions to this account 151 If this toggle is set, all mentions to this account are boosted 152 to all followers. This can be used to create groups. 153 .It This account is private 154 If this toggle is set, posts are not published via the public 155 web interface, only via the ActivityPub protocol. 156 .It Collapse top threads by default 157 If this toggle is set, the private timeline will always show 158 conversations collapsed by default. This allows easier navigation 159 through long threads. 160 .It Follow requests must be approved 161 If this toggle is set, follow requests are not automatically 162 accepted, but notified and stored for later review. Pending 163 follow requests will be shown in the people page to be 164 approved or discarded. 165 .It Publish follower and following metrics 166 If this toggle is set, the number of followers and following 167 accounts are made public (this is only the number; the specific 168 lists of accounts are never published). 169 .It Web interface language 170 If the administrator has installed any language file, it 171 can be selected here. 172 .It Time zone 173 The time zone the user is on (default: UTC). Only 174 used for scheduled posts. 175 .It Password 176 Write the same string in these two fields to change your 177 password. Don't write anything if you don't want to do this. 178 .El 179 .Pp 180 The rest of the page contains your timeline in reverse 181 chronological order (i.e., newest interactions first). 182 .Nm 183 shows the conversations as nested trees, unlike other Fediverse 184 software; every time you contribute something to a conversation, 185 the full thread is bumped up, so new interactions are shown 186 always at the top of the page while the forgotten ones languish 187 at the bottom. 188 .Pp 189 Private notes (a.k.a. direct messages) are also shown in 190 the timeline as normal messages, but marked with a cute lock 191 to mark them as non-public. Replies to direct messages are 192 also private and cannot be liked nor boosted. 193 .Pp 194 For each entry in the timeline, a set of reasonable actions 195 in the form of buttons will be shown. These can be: 196 .Bl -tag -offset indent 197 .It Reply 198 Unveils a text area to write your intelligent and acute comment 199 to an uninformed fellow. This note is sent to the original 200 author as well as to your followers. The note can include 201 mentions in the @user@format; these people will also become 202 recipients of the message. If you reply to a boost or like, 203 you are really replying to the note, not to the admirer of it. 204 .It Like 205 Click this if you admire this post. The poster and your 206 followers will be informed. 207 .It Boost 208 Click this if you want to propagate this post to all your 209 followers. The original author will also be informed. 210 .It Bookmark 211 Click this to bookmark a post. 212 .It Follow 213 Click here if you want to start receiving all the shenanigans 214 the original author of the post will write in the future. 215 .It Unfollow 216 Click here if you are fed up of this fellow's activities. 217 .It Delete 218 Click here to send this post to the bin. If it's an activity 219 written by you, the appropriate message is sent to the rest 220 of involved parts telling them that you no longer want your 221 thing in their servers (not all implementations really obey 222 this kind of requirements, though). 223 .It MUTE 224 This is the most important button in 225 .Nm 226 and the Fediverse in general. Click it if you don't want 227 to read crap from this user again in the foreseeable future. 228 .It Hide 229 If a conversation is getting long and annoying but not enough 230 to MUTE its author forever, click this button to avoid seeing 231 the post and its children anymore. 232 .It Edit 233 Posts written by you on 234 .Nm 235 version 2.19 and later can be edited and resent to their 236 recipients. 237 .El 238 .Ss Command-line options 239 The command-line tool provide the following commands: 240 .Bl -tag -offset indent 241 .It Cm init Op basedir 242 Initializes the data storage. This is an interactive command; necessary 243 information will be prompted for. The 244 .Ar basedir 245 directory must not exist. 246 .It Cm upgrade Ar basedir 247 Upgrades the data storage after installing a new version. 248 Only necessary if 249 .Nm 250 complains and demands it. 251 .It Cm httpd Ar basedir 252 Starts the daemon. 253 .It Cm purge Ar basedir 254 Purges old data from the timeline of all users. 255 .It Cm adduser Ar basedir Op uid 256 Adds a new user to the server. This is an interactive command; 257 necessary information will be prompted for. 258 .It Cm deluser Ar basedir Ar uid 259 Deletes a user, unfollowing all accounts first. 260 .It Cm resetpwd Ar basedir Ar uid 261 Resets a user's password to a new, random one. 262 .It Cm queue Ar basedir Ar uid 263 Processes the output queue of the specified user, sending all 264 enqueued messages and re-enqueing the failing ones. This command 265 must not be executed if the server is running. 266 .It Cm follow Ar basedir Ar uid Ar actor 267 Sends a Follow message for the specified actor URL. 268 .It Cm request Ar basedir Ar uid Ar url 269 Requests an object and dumps it to stdout. This is a very low 270 level command that is not very useful to you. 271 .It Cm announce Ar basedir Ar uid Ar url 272 Announces (boosts) a post via its URL. 273 .It Cm note Ar basedir Ar uid Ar text Op file file ... 274 Enqueues a Create + Note message to all followers. If the 275 .Ar text 276 argument is -e, the external editor defined by the EDITOR 277 environment variable will be invoked to prepare a message; if 278 it's - (a lonely hyphen), the post content will be read from stdin. 279 The rest of command line arguments are treated as media files to be 280 attached to the post. The LANG environment variable (if defined) is used 281 as the post language. 282 .It Cm note_unlisted Ar basedir Ar uid Ar text Op file file ... 283 Like the previous one, but creates an "unlisted" (or "quiet public") post. 284 .It Cm note_mention Ar basedir Ar uid Ar text Op file file ... 285 Like the previous one, but creates a post only for accounts mentioned 286 in the post body. 287 .It Cm block Ar basedir Ar instance_url 288 Blocks a full instance, given its URL or domain name. All subsequent 289 incoming activities with identifiers from that instance will be immediately 290 blocked without further inspection. 291 .It Cm unblock Ar basedir Ar instance_url 292 Unblocks a previously blocked instance. 293 .It Cm verify_links Ar basedir Ar uid 294 Verifies all links or account handles stored as metadata for the given user. 295 This verification is done by downloading the link content and searching for 296 a link back to the 297 .Nm 298 user url that also contains a rel="me" attribute. These links are specially 299 marked as verified in the user's public timeline and also via the Mastodon API. 300 .It Cm export_csv Ar basedir Ar uid 301 Exports some account data as Mastodon-compatible CSV files. After executing 302 this command, the following files will be written to the 303 .Pa export/ 304 subdirectory inside the user directory: 305 .Pa bookmarks.csv , 306 .Pa blocked_accounts.csv , 307 .Pa lists.csv , and 308 .Pa following_accounts.csv . 309 .It Cm alias Ar basedir Ar uid Ar "@account@remotehost" 310 Sets an account as an alias of this one. This is a necessary step to migrate 311 an account to a remote Mastodon instance (see 312 .Xr snac 8 , 313 section 'Migrating from snac to Mastodon'). 314 .It Cm migrate Ar basedir Ar uid 315 Starts a migration from this account to the one set as an alias (see 316 .Xr snac 8 , 317 section 'Migrating from snac to Mastodon'). 318 .It Cm import_csv Ar basedir Ar uid 319 Imports CSV data files from a Mastodon export. This command expects the 320 following files to be inside the 321 .Pa import/ 322 subdirectory of a user's directory inside the server base directory: 323 .Pa bookmarks.csv , 324 .Pa blocked_accounts.csv , 325 .Pa lists.csv , and 326 .Pa following_accounts.csv . 327 .It Cm state Ar basedir 328 Dumps the current state of the server and its threads. For example: 329 .Bd -literal -offset indent 330 server: comam.es (snac/2.45-dev) 331 uptime: 0:03:09:52 332 job fifo size (cur): 45 333 job fifo size (peak): 1532 334 thread #0 state: input 335 thread #1 state: input 336 thread #2 state: waiting 337 thread #3 state: waiting 338 thread #4 state: output 339 thread #5 state: output 340 thread #6 state: output 341 thread #7 state: waiting 342 .Ed 343 .Pp 344 The job fifo size values show the current and peak sizes of the 345 in-memory job queue. The thread state can be: waiting (idle waiting 346 for a job to be assigned), input or output (processing I/O packets) 347 or stopped (not running, only to be seen while starting or stopping 348 the server). 349 .It Cm import_list Ar basedir Ar uid Ar file 350 Imports a Mastodon list in CSV format. The file must be stored inside the 351 .Pa import/ 352 subdirectory of a user's directory inside the server base directory. 353 This option can be used to import "Mastodon Follow Packs". 354 .It Cm import_block_list Ar basedir Ar uid Ar file 355 Imports a Mastodon list of accounts to be blocked in CSV format. The 356 file must be stored inside the 357 .Pa import/ 358 subdirectory of a user's directory inside the server base directory. 359 .It Cm lists Ar basedir Ar uid 360 Prints the name of the user created lists. 361 .It Cm list_members Ar basedir Ar uid Ar name 362 Prints the list of actors in the named list. 363 .It Cm create_list Ar basedir Ar uid Ar name 364 Creates a new list. 365 .It Cm delete_list Ar basedir Ar uid Ar name 366 Deletes an existing list. 367 .It Cm list_add Ar basedir Ar uid Ar name Ar account 368 Adds an account (by its @name@host handle or actor URL) to a list. 369 .It Cm list_del Ar basedir Ar uid Ar name Ar actor_url 370 Deletes an actor (by its actor URL) from a list. 371 .El 372 .Ss Migrating an account to/from Mastodon 373 See 374 .Xr snac 8 375 for details. 376 .Ss Using Mastodon-compatible apps 377 Since version 2.27, 378 .Nm 379 includes support for the Mastodon API, so you can use Mastodon-compatible 380 mobile and desktop applications to access your account. Given a correctly 381 configured server, the usage of these programs should be straightforward. 382 Please take note that they will show your timeline in a 'Mastodon fashion' 383 (i.e., as a plain list of posts), so you will lose the fancy, nested thread 384 post display with the most active threads at the top that the web interface of 385 .Nm 386 provides. 387 .Ss Implementing post bots 388 .Nm 389 makes very easy to post messages in a non-interactive manner. This example 390 posts a string: 391 .Bd -literal -offset indent 392 uptime | snac note $SNAC_BASEDIR $SNAC_USER - 393 .Ed 394 .Pp 395 You can setup a line like this from a 396 .Xr crontab 5 397 or similar. Take note that you need a) command-line access to the same machine 398 that hosts the 399 .Nm 400 instance, and b) write permissions to the storage directories and files. 401 .Pp 402 You can also post non-interactively using the Mastodon API and a command-line 403 http tool like 404 .Xr curl 1 405 or similar. This has the advantage that you can do it remotely from any host, 406 anywhere; the only thing you need is an API Token. This is an example: 407 .Bd -literal -offset indent 408 curl -X POST https://$SNAC_HOST/api/v1/statuses \\ 409 --header "Authorization: Bearer ${TOKEN}" -d "status=$(uptime)" 410 .Ed 411 .Pp 412 You can obtain an API Token by connecting to the following URL: 413 .Bd -literal -offset indent 414 https://$SNAC_HOST/oauth/x-snac-get-token 415 .Ed 416 .Pp 417 .Ss Webhook for notifications 418 Since version 2.78, users can set the URL to a webhook that will receive 419 an HTTP POST with every notification (in JSON format). This can be used to 420 implement some automation whenever a new activity happens, like autorepliers, 421 chatbots, interactive textual games or whatever. The 422 .Pa examples/ 423 subdirectory contains a tiny Python program that implements an auto-follower 424 for every new follow. The JSON notification object includes the following data: 425 .Bl -tag -offset indent 426 .It id 427 a unique notification identifier 428 .It actor 429 the origin actor id 430 .It target 431 the target actor id 432 .It date 433 the notification date 434 .It message 435 the full ActivityPub action JSON object 436 .It objid 437 the object identifier (extracted from message, may be null) 438 .It type 439 the action type (extracted from message) 440 .It utype 441 the action subtype (extracted from message, may be null) 442 .It uid 443 the user identifier (account name) 444 .It basedir 445 the server base directory 446 .It baseurl 447 the server base URL 448 .El 449 .Pp 450 .Sh ENVIRONMENT 451 .Bl -tag -width Ds 452 .It SNAC_BASEDIR 453 This optional environment variable can be set to the base directory of 454 your installation; if set, you don't have to add the base directory as an 455 argument to command-line operations. This may prove useful if you only 456 have one 457 .Nm 458 instance in you system (which is probably your case). 459 .It Ev DEBUG 460 Overrides the debugging level from the server 'dbglevel' configuration 461 variable. Set it to an integer value. The higher, the deeper in meaningless 462 verbiage you'll find yourself into. 463 .It Ev EDITOR 464 The user-preferred interactive text editor to prepare messages. 465 .It Ev LANG 466 The language of the post when sending messages. 467 .El 468 .Sh SEE ALSO 469 .Xr snac 5 , 470 .Xr snac 8 471 .Sh AUTHORS 472 .An grunfink Lk https://comam.es/snac/grunfink @grunfink@comam.es 473 .Sh LICENSE 474 See the LICENSE file for details. 475 .Sh CAVEATS 476 Use the Fediverse sparingly. Don't fear the MUTE button. 477 .Sh BUGS 478 Probably many. Some issues may be even documented in the TODO.md file.