snac.8 (31208B)
1 .Dd $Mdocdate$ 2 .Dt SNAC 8 3 .Os 4 .Sh NAME 5 .Nm snac 6 .Nd snac administration 7 .Sh DESCRIPTION 8 The 9 .Nm 10 daemon processes messages from other servers in the Fediverse 11 using the ActivityPub protocol. 12 .Pp 13 This is the admin manual. For user operation, see 14 .Xr snac 1 . 15 For file and data formats, see 16 .Xr snac 5 . 17 .Ss Special cares about your snac you must know beforehand 18 .Nm 19 makes heavy use of hard links and link reference counts for its work, so 20 don't even think of using it on a filesystem that doesn't support this 21 feature. Most UNIX-like operating systems (Linux, the BSDs, the old DEC 22 Ultrix machine in your grandfather basement, probably MacOS) support hard 23 links on their native filesystems. Don't do fancy things like moving the 24 subdirectories to different filesystems. Also, if you move your 25 .Nm 26 installation to another server, do it with a tool that keeps hard 27 links, like 28 .Xr tar 1 29 or 30 .Xr rsync 1 31 with the -H switch. Remember: 32 .Nm 33 is a very UNIXy program that loves hard links. 34 .Ss Building and Installation 35 A C compiler must be installed in the system, as well as the development 36 headers and libraries for OpenSSL (or compatible) and curl. To build 37 .Nm , 38 run 39 .Bd -literal -offset indent 40 make 41 .Ed 42 .Pp 43 And, after that, run as root 44 .Bd -literal -offset indent 45 make install 46 .Ed 47 .Ss Data storage Initialization 48 Once 49 .Nm 50 is properly installed on the system, designate a directory where 51 the server and user data are to be stored. This directory 52 must not exist yet. 53 .Nm 54 must always be run as a regular user; you can create one for 55 it or use your own. To initialize the data storage, execute 56 .Bd -literal -offset indent 57 snac init $HOME/snac-data 58 .Ed 59 .Pp 60 A small set of questions will be asked regarding the installation, 61 specially the host name it will run under, the local network address 62 and port 63 .Nm 64 will listen to, the optional path prefix and possibly other things. 65 .Pp 66 Since version 2.57, if the 'network address' starts with /, it's 67 assumed to be a UNIX-like socket (please take note that the http proxy 68 must have full read and write access to this socket; this is a common 69 pitfall. Permissions will break your heart). 70 .Pp 71 You can launch the 72 .Nm 73 process by running 74 .Bd -literal -offset indent 75 snac httpd $HOME/snac-data 76 .Ed 77 .Pp 78 Log messages are sent to the standard error stream. By default, only 79 relevant information is written there. You can increase the debugging 80 level by editing the 'dbglevel' field in the 81 .Pa server.json 82 file or by setting a numeric value between 0 and 3 to the DEBUG 83 environment variable, see below. 84 .Pp 85 If you operate a Linux systemd-enabled system, OpenBSD, FreeBSD or NetBSD, there are 86 startup scripts and configuration data in the 87 .Pa examples 88 directory. 89 For other operating systems, please read the appropriate documentation 90 on how to install a daemon as a non-root service. 91 .Ss Upgrading to a new version 92 Sometimes, the data storage disk layout changes between versions. If there 93 is such a change, 94 .Nm 95 will refuse to run and require an upgrade. Do this by running 96 .Bd -literal -offset indent 97 snac upgrade $HOME/snac-data 98 .Ed 99 .Pp 100 Take special care to execute this upgrade operation without any 101 .Nm 102 processes serving on the same folder. You can break everything. I know 103 this because Tyler knows this. 104 .Pp 105 .Ss Server Setup 106 .Pp 107 An http server with TLS and proxying support must already be 108 installed and configured. 109 .Nm 110 runs as a daemon and listens on a TCP/IP socket, preferably 111 on a local interface. It can serve the full domain or only 112 a directory. The http server must be configured to route to the 113 .Nm 114 socket all related traffic and also the webfinger standard 115 address. The Host header must be propagated. 116 See the examples below. 117 .Ss Adding Users 118 .Pp 119 Users must be created from the command line. 120 You can do it by running 121 .Bd -literal -offset indent 122 snac adduser $HOME/snac-data 123 .Ed 124 .Pp 125 All needed data will be prompted for. There is no artificial limit 126 on the number of users that can be created. 127 .Ss Customization 128 The 129 .Pa server.json 130 configuration file allows some behaviour tuning: 131 .Bl -tag -width tenletters 132 .It Ic host 133 The host name. 134 .It Ic prefix 135 The URL path prefix. 136 .It Ic address 137 The listen network address. If it starts with /, it's assumed to be 138 a UNIX-like socket instead. 139 .It Ic port 140 The listen network port (unused if address is a UNIX socket). 141 .It Ic dbglevel 142 The debug level. An integer value, being 0 the less verbose (the default). 143 .It Ic layout 144 The disk storage layout version. Never touch this. 145 .It Ic queue_retry_max 146 Messages sent out are stored in a queue. If the posting of a messages fails, 147 it's re-enqueued for later. This integer configures the maximum count of 148 times the sending will be retried. 149 .It Ic queue_retry_minutes 150 The number of minutes to wait before the failed posting of a message is 151 retried. This is not linear, but multiplied by the number of retries 152 already done. 153 .It Ic queue_timeout 154 The maximum number of seconds to wait when sending a message from the queue. 155 .It Ic queue_timeout_2 156 The maximum number of seconds to wait when sending a message from the queue 157 to those servers that went timeout in the previous retry. If you want to 158 give slow servers a chance to receive your messages, you can increase this 159 value (but also take into account that processing the queue will take longer 160 while waiting for these molasses to respond). 161 .It Ic def_timeline_entries 162 This is the default timeline entries shown in the web interface. 163 .It Ic max_timeline_entries 164 This is the maximum timeline entries shown in the web interface. 165 .It Ic timeline_purge_days 166 Entries in the timeline older that this number of days are purged. 167 If you don't want any timeline purging and enjoy your data drives 168 fill up with old crap and finally burst in flames, you can disable 169 purging by setting this to 0. 170 .It Ic local_purge_days 171 Same as before, but for the user-generated entries in the local timeline. 172 .It Ic cssurls 173 This is a list of URLs to CSS files that will be inserted, in this order, 174 in the HTML before the user CSS. Use these files to configure the global 175 site layout. 176 .It Ic disable_cache 177 If set to true, timeline caching is not done. This is only useful for 178 debugging purposes; don't enable it unless you know what do you want, as 179 it makes everything slower. 180 .It Ic disable_openbsd_security 181 If running under OpenBSD, 182 .Nm 183 makes use of the enhanced security functions 184 .Xr unveil 2 185 and 186 .Xr pledge 2 . 187 Setting this to true disables their usage. These functions limit severely 188 what an intruder can do in case of a security vulnerability, so only enable 189 this option if something is very broken. 190 .It Ic num_threads 191 By setting this value, you can specify the exact number of threads 192 .Nm 193 will use when processing connections. Values lesser than 4 will be ignored. 194 .It Ic disable_email_notifications 195 By setting this to true, no email notification will be sent for any user. 196 .It Ic disable_inbox_collection 197 By setting this to true, no inbox collection is done. Inbox collection helps 198 being discovered from remote instances, but also increases network traffic. 199 .It Ic http_headers 200 If you need to add more HTTP response headers for whatever reason, you can 201 fill this object with the required header/value pairs. 202 .It Ic show_instance_timeline 203 If this is set to true, the instance base URL will show a timeline with the latest 204 user posts instead of the default greeting static page. If other information 205 fields are set (see below), they are also shown. 206 .It Ic admin_email 207 The email address of the instance administrator (optional). 208 .It Ic admin_account 209 The user name of the instance administrator (optional). 210 .It Ic short_description 211 A textual short description about the instance (optional). 212 .It Ic short_description_raw 213 Whether to interpret short_descript as raw string or convert to HTML (optional). 214 .It Ic fastcgi 215 If set to true, 216 .Nm 217 will use the FastCGI interface to communicate with the upper level 218 http server, that must be configured accordingly. 219 .It Ic disable_history 220 If set to true, history monthly snapshots are not served nor their links shown. 221 .It Ic shared_inboxes 222 This boolean value selects if shared inboxes are announced or not. Enabling 223 shared inboxes helps (somewhat) in optimizing incoming traffic for instances 224 with a large number of users. 225 .It Ic min_account_age 226 If this numeric value (in seconds) is set, any activity coming from an account 227 that was created more recently than that will be rejected. This may be used 228 to mitigate spam from automatically created accounts. 229 .It Ic protocol 230 This string value contains the protocol (schema) to be used in URLs. If not 231 set, it defaults to "https". If you run 232 .Nm 233 as part of a hidden network like Tor or I2P that doesn't have a TLS / 234 Certificate infrastructure, you need to set it to "http". Don't change it 235 unless you know what you are doing. 236 .It Ic hide_delete_post_button 237 If set to true, the button to delete a post is not shown. It's not very 238 useful and somewhat clutters the already crowded button space. 239 .It Ic disable_block_notifications 240 If set to true, notifications about 'Block' activities are never sent. 241 .It Ic strict_public_timelines 242 If set to true, public timelines only show posts and boosts originating 243 from an account (no conversation trees). 244 .It Ic proxy_media 245 If set to true, links to all image, audio or video media from other accounts' 246 posts will not be direct ones, but proxied by 247 .Nm . 248 This way, remote media servers will not see the user's IP, but the server one, 249 improving privacy. Please take note that this will increase the server's incoming 250 and outgoing traffic. 251 .It Ic badlogin_retries 252 If incorrect logins from a given IP address reach this count, subsequent attempts 253 from it are rejected until the lock expires (default: 5 retries). 254 .It Ic badlogin_expire 255 The number of seconds a blocked IP address is ignored in login attempts 256 (default: 300 seconds). 257 .It Ic disable_sandbox 258 This boolean toggle allows disabling Linux Landlock sandboxing. Confining a 259 program in a sandbox limits the directories and resources it can use, so it's 260 recommended for security. Support for Linux sandboxing must be compiled in, and you 261 need at least a Linux kernel version 5.13.0. 262 .It Ic max_public_entries 263 The maximum number of entries (posts) to be returned in user RSS feeds and outboxes 264 (default: 20). 265 .It Ic max_attachments 266 The maximum number of attachments per post (default: 4). 267 .It Ic enable_svg 268 Since version 2.73, SVG image attachments are hidden by default; you can enable 269 them by setting this value to true. 270 .It Ic smtp_url 271 Since version 2.76, email notifications can be sent via direct connection to an 272 SMTP server instead of the traditional behaviour of piping the message to 273 .Pa /usr/sbin/sendmail . 274 Set this value to the SMTP url to be used for sending email notifications 275 (for example, smtp://localhost). It may include a port number if it's not running on 276 the usual one, like in smtp://mail.example.com:587. 277 .It Ic smtp_user 278 .It Ic smtp_password 279 To be filled if the SMTP server defined by the previous directive needs credentials. 280 .It Ic rss_hashtag_poll_hours 281 The periodic number of hours hashtag RSS are polled (default: 4). It has a minimum 282 value of 1 to avoid hammering servers. 283 .It Ic disable_notify_webhook 284 Since version 2.78, users can set a webhook URL to receive notifications. Set this 285 to true if you don't want your users to have this privilege. 286 .El 287 .Pp 288 You must restart the server to make effective these changes. 289 .Pp 290 If a file named 291 .Pa greeting.html 292 is present in the server base directory, it will be returned whenever 293 the base URL of the server is requested. Fill it with whatever 294 information about the instance you want to supply to people 295 visiting the server, like sign up requirements, site policies 296 and such. The special %userlist% mark in the file will cause 297 the list of users in this instance to be inserted. 298 .Pp 299 Users can change a bit of information about themselves from the 300 web interface. See 301 .Xr snac 1 302 for details. Further, every user can have a private CSS file in their 303 .Pa static/style.css 304 that will be served instead of the server-wide one. 305 It's not modifiable from the web interface to avoid users 306 shooting themselves in the foot by destroying everything. 307 .Ss Custom Emojis 308 From version 2.51, support for customized Emojis in posts is available 309 (previously, they were hardcoded). Emojis are read from the 310 .Pa emojis.json 311 file in the instance base directory, as a JSON object of key / value 312 pairs (if this file does not exist, it will be created with 313 the predefined set). Each key in the object contains the text to be found (e.g., 314 the :-) for a smiling face), and its associated value, the text string that 315 will replace it (in this example case, the HTML entity for the Unicode codepoint 316 for the smiley or the Emoji itself as text). 317 .Pp 318 Emoji values can also be URLs to image files; in this case, they will not be 319 substituted in the post content, but added to the 'tag' array as an ActivityPub 320 standard 'Emoji' object (it's recommendable that the Emoji key be enclosed in 321 colons for maximum compatilibity with other ActivityPub implementations, like 322 e.g. :happydoggo:). These images can be served from an external source or from the 323 .Pa static 324 directory of the instance admin. 325 .Pp 326 If you want to disable any Emoji substitution, change the file to contain 327 just an empty JSON object ({}). 328 .Ss SPAM Mitigation 329 There have been some SPAM attacks on the Fediverse and, as too many 330 instances and server implementations out there still allow automatic 331 account creation, it will only get worse. 332 .Nm 333 includes some (not very strong) tools for trying to survive the SPAM 334 flood that will eventually happen. 335 .Pp 336 The 337 .Ic min_account_age 338 field in the main configuration file allows setting a minimum age (in 339 seconds) to consider too recently created accounts suspicious of being 340 a potential source of SPAM. This is a naïve assumption, because spammers 341 can create accounts, let them dormant for a while and then start to use 342 them. Also, some ActivityPub implementations don't even bother to return 343 a creation date for their accounts, so this is not very useful. 344 .Pp 345 From version 2.50, post content can be filtered out by regular expressions. 346 These weapons of mass destruction can be written into the 347 .Ic filter_reject.txt 348 file in the server base directory, one per line; if this file exists, 349 all posts' content will be matched (after being stripped of HTML tags) 350 against these regexes, one by one, and any match will make the post to 351 be rejected. Use lower case, the regex will be case insensitive by default. 352 If you don't know about regular expressions, don't use this 353 option (or learn about them inw some tutorial, there are gazillions of 354 them out there), as you and your users may start missing posts. Also, 355 given that every regular expression implementation supports a different 356 set of features, consider reading the documentation about the one 357 implemented in your system. 358 .Ss ActivityPub Support 359 These are the following activities and objects that 360 .Nm 361 supports: 362 .Bl -tag -width tenletters 363 .It Vt Follow 364 Complete support, on input and output. 365 .It Vt Undo 366 For 367 .Vt Follow , 368 .Vt Like 369 and 370 .Vt Announce 371 objects, on input and output. 372 .It Vt Create 373 For 374 .Vt Note , 375 .Vt Question , 376 .Vt Page , 377 .Vt Article , 378 .Vt Event 379 and 380 .Vt Video 381 objects on input, and for 382 .Vt Note 383 and 384 .Vt Question 385 on output. 386 .It Vt Accept 387 For 388 .Vt Follow 389 objects, on input and output. 390 .It Vt Like 391 For 392 .Vt Note 393 objects, on input and output. 394 .It Vt EmojiReact 395 For 396 .Vt Note 397 objects, on input. 398 .It Vt Announce 399 For 400 .Vt Note 401 objects, on input and output. 402 .It Vt Update 403 For 404 .Vt Note , 405 .Vt Question , 406 .Vt Page , 407 .Vt Article , 408 .Vt Event 409 and 410 .Vt Video 411 objects on input, and for 412 .Vt Note 413 on output. 414 .It Vt Delete 415 Supported for 416 .Vt Note 417 and 418 .Vt Tomsbtone 419 objects on input, and for 420 .Vt Note 421 objects on output. 422 .It Vt Move 423 For actor-like objects, for input and output. 424 .El 425 .Pp 426 The rest of activities and objects are dropped on input. 427 .Pp 428 There is partial support for 429 .Vt OrderedCollection 430 objects in the 431 .Pa /outbox 432 (with the last 20 entries of the local timeline shown). No pagination 433 is supported. Intentionally, the 434 .Pa /followers 435 and 436 .Pa /following 437 paths return empty lists. 438 .Ss Migrating from snac to Mastodon 439 Since version 2.60, you can migrate your 440 .Nm 441 account to other ActivityPub instances. What is described here is the process to do it from 442 .Nm 443 to Mastodon; on other software implementations, it will surely be somewhat different. All 444 the steps regarding your 445 .Nm 446 account must be done from the command line. For the sake of the example, let's 447 say that you want to migrate from an account named @origin@snac.example.org to 448 another one named @destination@mastodon.example.com and that both of them 449 already exist. I've used this very informative page as a guideline: 450 .Pp 451 .Lk https://fedi.tips/transferring-your-mastodon-account-to-another-server/ 452 .Pp 453 1. On your 454 .Nm 455 server, first export your data to CSV by running: 456 .Bd -literal -offset indent 457 snac export_csv $SNAC_BASEDIR origin 458 .Ed 459 .Pp 460 You'll find the following CSV files in the 461 .Pa export/ 462 subdirectory inside the user directory: 463 .Pa bookmarks.csv , 464 .Pa blocked_accounts.csv , 465 .Pa lists.csv , and 466 .Pa following_accounts.csv . 467 .Pp 468 2. In the web interface of your new Mastodon account, click on 469 .Vt Preferences 470 > 471 .Vt Import and Export 472 > 473 .Vt Import 474 and upload the CSV files one at a time. You must specify the type of 475 file you are uploading. 476 .Pp 477 3. Still in the web interface of your new Mastodon account, click on 478 .Vt Preferences 479 > 480 .Vt Account 481 > 482 .Vt Moving From a Different Account , 483 then click on 484 .Vt Create an account alias 485 and follow the instructions. (When it asks you to 486 write your old account’s handle, it needs to include the @ at the start 487 as well as the @ in the middle; as of our example, @origin@snac.example.org). 488 It seems this step is not performed immediately, you must wait an unspecified 489 number of minutes for this to be effective. 490 .Pp 491 4. Meanwhile, you must tell 492 .Nm 493 about your new account by creating an alias from your current one. 494 So, on your 495 .Nm 496 server, run 497 .Bd -literal -offset indent 498 snac alias $SNAC_BASEDIR origin "@destination@mastodon.example.com" 499 .Ed 500 .Pp 501 5. Finally, you must order 502 .Nm 503 to start the migration process, that will consist in iterating all the 504 people that follows your account and sending them a 505 .Vt Move 506 message, that acts as a suggestion to unfollow your old account 507 and follow the new one. The command is 508 .Bd -literal -offset indent 509 snac migrate $SNAC_BASEDIR origin 510 .Ed 511 .Pp 512 This process can be very long and unreliable; any destination server may be down, 513 too busy, disconnected or gone. I recommend you to read the document I linked 514 above to know about all the sorrows awaiting. 515 .Pp 516 Also, please take note that the 517 .Nm 518 account you migrated from is not disabled nor changed in any way, so can still 519 use it as it no migration was done. This behaviour may or may not match what other 520 ActivityPub implementations do. 521 .Pp 522 .Ss Migrating from Mastodon to snac 523 Since version 2.61, you can migrate accounts on other ActivityPub instances to your 524 .Nm 525 one. What is described here is the process to do it from 526 Mastodon; on other software implementations, it will surely be somewhat different. All 527 the steps regarding your 528 .Nm 529 account must be done from the command line. For the sake of the example, let's 530 say that you want to migrate from an account named @origin@mastodon.example.com to 531 another one named @destination@snac.example.org and that both of them 532 already exist. I've used this very informative page as a guideline: 533 .Pp 534 .Lk https://fedi.tips/transferring-your-mastodon-account-to-another-server/ 535 .Pp 536 1. On the web interface of your origin Mastodon account, click on 537 .Vt Preferences 538 > 539 .Vt Import and Export 540 > 541 .Vt Export 542 and download the CSV files under the "Follows", "Lists", "You Block" and "Bookmarks" 543 labels. After being downloaded, you should find the following files on your download 544 directory: 545 .Pa bookmarks.csv , 546 .Pa blocked_accounts.csv , 547 .Pa lists.csv , and 548 .Pa following_accounts.csv . 549 .Pp 550 2. Copy all those files to the 551 .Pa import/ 552 subdirectory of the user's directory inside the server base directory, and run 553 .Bd -literal -offset indent 554 snac import_csv $SNAC_BASEDIR destination 555 .Ed 556 .Pp 557 This process may take some time because it depends on the availability / responsiveness 558 of all the ActivityPub servers involved (webfinger, accounts, posts, etc.). Some errors 559 may be transient and retried later. Also, if 560 .Nm 561 complains that it can't find any of these files, please check that they are really 562 stored in the 563 .Pa import/ 564 subdirectory and that their names match exactly. Some of them may be 565 empty (for example, if you didn't create any list) and that's fine. 566 .Pp 567 3. Again on your 568 .Nm 569 server, run 570 .Bd -literal -offset indent 571 snac alias $SNAC_BASEDIR destination "@origin@mastodon.example.com" 572 .Ed 573 .Pp 574 Check that no errors were shown. If they do, the origin Mastodon server may be 575 busy or down; try again later. 576 .Pp 577 4. Move back to the web interface of the origin Mastodon account, go to 578 .Vt Preferences 579 > 580 .Vt Account 581 > 582 .Vt Move To A Different Account , 583 and follow the instructions there. Set the handle of the new account to your 584 .Nm 585 one; as of our example, @destination@snac.example.org. This will start the migration 586 process: it's the duty of your old Mastodon instance to send an automatic 587 .Vt Move 588 message to every one of your followers. Eventually, you will start receiving follow notifications to your 589 .Nm 590 account from all accounts that followed the Mastodon one. According to the great document 591 I linked above, this process may or may not start immediately, and its success may depend 592 heavily on how all the servers involved behave. Just cross your fingers and hope for the best. 593 .Pp 594 .Ss Instance blocking 595 Full instances can be blocked. This operation must be done from 596 the command-line tool. See 597 .Xr snac 1 . 598 .Pp 599 .Ss Bad login throttling 600 Since version 2.67, a simple logic to avoid brute force attacks against user passwords 601 has been implemented: if, from a given IP address, the number of failed logins reaches 602 a given threshold, further tries from that IP address are never successful until a timer 603 expires. The maximum number of retries can be configured in the 604 .Pa server.json 605 file by setting the 606 .Ic badlogin_retries 607 variable, and the number of seconds the IP address unlock timer expires, in 608 .Ic badlogin_expire . 609 Please take note that, for this system to work, you must setup your web server proxy 610 to pass the remote connection address in the 611 .Ic X-Forwarded-For 612 HTTP header (unless you use the FastCGI interface; if that's the case, you don't have 613 to do anything). 614 .Pp 615 .Ss Subscribing to Fediverse Relays 616 Since version 2.69, a 617 .Nm 618 instance can subscribe to LitePub (Pleroma-style) Fediverse Relays. Doing this improves 619 visibility and allows following hashtags. To do this, you must create a special user named 620 relay and, from it, follow the relay actor(s) like you do with regular actor URLs. This 621 special user will start receiving boosts from the relay server of posts from other instances 622 also following it. If any other user of the same 623 .Nm 624 instance follows any of the hashtags included in these boosted posts coming from the relay, 625 they will be received as if they were for them. 626 .Pp 627 Example: 628 .Bd -literal -offset indent 629 snac adduser $SNAC_BASEDIR relay # only needed once 630 snac follow $SNAC_BASEDIR relay https://relay.example.com/actor 631 .Ed 632 .Pp 633 Users on your instance do NOT need to follow the local relay user to benefit from following 634 hashtags. 635 .Pp 636 Please take note that subscribing to relays can increase the traffic towards your instance 637 significantly. In any case, lowering the "Maximum days to keep posts" value for the relay 638 special user is recommended (e.g. setting to just 1 day). 639 .Ss Web interface language 640 Since version 2.73, the web UI can be localized via simple .po files (they are directly 641 parsed, no support for gettext is needed). 642 .Pp 643 No language file is installed by default; the administrator must copy any desired .po files 644 to the 645 .Pa lang/ 646 subdirectory in the base directory. Once the server is restarted, users can select the 647 new language from the user settings. The 648 .Nm 649 source distribution may include .po files in the 650 .Pa po/ 651 subdirectory. You don't need to copy the English language one, as it's the default. 652 .Pp 653 To create new language files, create a copy of 654 .Pa po/en.po , 655 rename it to a reasonable value like 656 .Pa pl.po 657 or 658 .Pa pt_BR.po , 659 change the translator in the header to yourself and fill the msgstr strings with your 660 translation. If you have any doubt on how to modify .po files, there are many tutorials 661 out there. If you want your language file to be included in the standard 662 .Nm 663 distribution, please send me a link to it via the Fediverse to @grunfink@comam.es 664 or make a PR via the Git repository. 665 .Sh ENVIRONMENT 666 .Bl -tag -width Ds 667 .It Ev DEBUG 668 Overrides the debugging level from the server 'dbglevel' configuration 669 variable. Set it to an integer value. The higher, the deeper in meaningless 670 verbiage you'll find yourself into. 671 .El 672 .Sh EXAMPLES 673 You want to install the 674 .Nm 675 Fediverse daemon in the host example.com, that is correctly configured 676 with a valid TLS certificate and running the nginx httpd server. 677 The service will be installed under the 678 .Pa fedi 679 location. Two users, walter and jessie, will be hosted in the system. 680 Their Fediverse presence addresses will be 681 .Lk https://example.com/fedi/walter 682 and 683 .Lk https://example.com/fedi/jesse , 684 respectively. They will be known 685 in the Fediverse as @walter@example.com and @jesse@example.com. The 686 .Nm 687 daemon will run as the user snacusr in the system and listen to the 688 localhost:8001 network socket. All data will be stored in the 689 .Pa /home/snacusr/fedidata 690 directory. 691 .Pp 692 Log into the system as snacusr and execute: 693 .Bd -literal -offset indent 694 snac init /home/snacusr/fedidata 695 .Ed 696 .Pp 697 Answer "example.com" to the host name question, "/fedi" to the path 698 prefix question, "localhost" to the address and "8001" to the port. 699 .Pp 700 Create the users 701 .Bd -literal -offset indent 702 snac adduser /home/snacusr/fedidata walter 703 snac adduser /home/snacusr/fedidata jesse 704 .Ed 705 .Pp 706 Answer the questions with reasonable values. 707 .Pp 708 Execute the server: 709 .Bd -literal -offset indent 710 snac httpd /home/snacusr/fedidata 711 .Ed 712 .Pp 713 Edit the nginx configuration and add the following snippet to the 714 example.com server section: 715 .Bd -literal -offset indent 716 # nginx configuration example 717 718 # main web access point 719 location /fedi { 720 proxy_pass http://localhost:8001; 721 proxy_set_header Host $http_host; 722 proxy_set_header X-Forwarded-For $remote_addr; 723 } 724 # webfinger 725 location /.well-known/webfinger { 726 proxy_pass http://localhost:8001; 727 proxy_set_header Host $http_host; 728 proxy_set_header X-Forwarded-For $remote_addr; 729 } 730 # Mastodon API (entry points) 731 location /api/v1/ { 732 proxy_pass http://localhost:8001; 733 proxy_set_header Host $http_host; 734 proxy_set_header X-Forwarded-For $remote_addr; 735 } 736 location /api/v2/ { 737 proxy_pass http://localhost:8001; 738 proxy_set_header Host $http_host; 739 proxy_set_header X-Forwarded-For $remote_addr; 740 } 741 # Mastodon API (OAuth support) 742 location /oauth { 743 proxy_pass http://localhost:8001; 744 proxy_set_header Host $http_host; 745 proxy_set_header X-Forwarded-For $remote_addr; 746 } 747 # optional 748 location /.well-known/nodeinfo { 749 proxy_pass http://localhost:8001; 750 proxy_set_header Host $http_host; 751 proxy_set_header X-Forwarded-For $remote_addr; 752 } 753 # optional (needed by some Mastodon API clients) 754 location /.well-known/host-meta { 755 proxy_pass http://localhost:8001; 756 proxy_set_header Host $http_host; 757 proxy_set_header X-Forwarded-For $remote_addr; 758 } 759 # optional (Mastodon-like link share entrypoint) 760 location /share { 761 proxy_pass http://localhost:8001; 762 proxy_set_header Host $http_host; 763 proxy_set_header X-Forwarded-For $remote_addr; 764 } 765 # optional (Mastodon-like "authorize interaction" entrypoint) 766 location /authorize_interaction { 767 proxy_pass http://localhost:8001; 768 proxy_set_header Host $http_host; 769 proxy_set_header X-Forwarded-For $remote_addr; 770 } 771 .Ed 772 .Pp 773 Restart the nginx daemon and connect to 774 .Lk https://example.com/fedi/walter . 775 The empty, default screen will be shown. Enter the admin section with the 776 credentials defined for this user. Search people, start following 777 them, engage in arid discussions and generally enjoy the frustrating 778 experience of Social Media. 779 .Pp 780 This is an example of a similar configuration for the Apache2 web server: 781 .Bd -literal -offset indent 782 # apache2 configuration example 783 784 ProxyPreserveHost On 785 786 # Main web access point 787 <Location /fedi> 788 ProxyPass http://127.0.0.1:8001/social 789 </Location> 790 791 # WebFinger 792 <Location /.well-known/webfinger> 793 ProxyPass http://127.0.0.1:8001/.well-known/webfinger 794 </Location> 795 796 # Mastodon API (entry points) 797 <Location /api/v1/> 798 ProxyPass http://127.0.0.1:8001/api/v1/ 799 </Location> 800 801 <Location /api/v2/> 802 ProxyPass http://127.0.0.1:8001/api/v2/ 803 </Location> 804 805 # Mastodon API (OAuth support) 806 <Location /oauth> 807 ProxyPass http://127.0.0.1:8001/oauth 808 </Location> 809 810 # NodeInfo (optional) 811 <Location /.well-known/nodeinfo> 812 ProxyPass http://127.0.0.1:8001/.well-known/nodeinfo 813 </Location> 814 815 # host-meta (optional, needed for some Mastodon API clients) 816 <Location /.well-known/host-meta> 817 ProxyPass http://127.0.0.1:8001/.well-known/host-meta 818 </Location> 819 820 # optional (Mastodon-like link share entrypoint) 821 <Location /share> 822 ProxyPass http://127.0.0.1:8001/share 823 </Location> 824 825 # optional (Mastodon-like "authorize interaction" entrypoint) 826 <Location /authorize_interaction> 827 ProxyPass http://127.0.0.1:8001/share 828 </Location> 829 .Ed 830 .Pp 831 Since version 2.43, 832 .Nm 833 supports communicating from / to the front end http server using the FastCGI 834 protocol. There is no special advantage in using this, only that some servers 835 allow for simpler configuration. For example, in the case of nginx, you can 836 replace the two 'proxy_pass' and 'proxy_set_header' lines in the example 837 above with just 838 .Bd -literal -offset indent 839 fastcgi_pass localhost:8001; 840 .Ed 841 .Pp 842 The only thing to change on 843 .Nm 844 is to the set 'fastcgi' value to true in 845 .Pa server.json . 846 .Pp 847 Further, using the FastCGI interface allows a much simpler configuration 848 under OpenBSD's native httpd, given that it's natively implemented there 849 and you no longer need to configure the complicated relayd server. This is 850 an example: 851 .Bd -literal -offset indent 852 # OpenBSD httpd configuration example 853 854 # other server configuration 855 [...] 856 857 location "/fedi/*" { 858 fastcgi socket tcp "127.0.0.1" 8001 859 } 860 861 location "/.well-known/webfinger" { 862 fastcgi socket tcp "127.0.0.1" 8001 863 } 864 865 location "/oauth/*" { 866 fastcgi socket tcp "127.0.0.1" 8001 867 } 868 869 location "/api/v1/*" { 870 fastcgi socket tcp "127.0.0.1" 8001 871 } 872 873 location "/api/v2/*" { 874 fastcgi socket tcp "127.0.0.1" 8001 875 } 876 877 location "/.well-known/nodeinfo" { 878 fastcgi socket tcp "127.0.0.1" 8001 879 } 880 881 location "/.well-known/host-meta" { 882 fastcgi socket tcp "127.0.0.1" 8001 883 } 884 885 location "/share" { 886 fastcgi socket tcp "127.0.0.1" 8001 887 } 888 889 location "/authorize_interaction" { 890 fastcgi socket tcp "127.0.0.1" 8001 891 } 892 .Ed 893 .Sh SEE ALSO 894 .Xr snac 1 , 895 .Xr snac 5 896 .Sh AUTHORS 897 .An grunfink Lk https://comam.es/snac/grunfink @grunfink@comam.es 898 .Sh LICENSE 899 See the LICENSE file for details. 900 .Sh CAVEATS 901 JSON files are fragile when modified by hand. Take care.