snac.8 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856
  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. .El
  268. .Pp
  269. You must restart the server to make effective these changes.
  270. .Pp
  271. If a file named
  272. .Pa greeting.html
  273. is present in the server base directory, it will be returned whenever
  274. the base URL of the server is requested. Fill it with whatever
  275. information about the instance you want to supply to people
  276. visiting the server, like sign up requirements, site policies
  277. and such. The special %userlist% mark in the file will cause
  278. the list of users in this instance to be inserted.
  279. .Pp
  280. Users can change a bit of information about themselves from the
  281. web interface. See
  282. .Xr snac 1
  283. for details. Further, every user can have a private CSS file in their
  284. .Pa static/style.css
  285. that will be served instead of the server-wide one.
  286. It's not modifiable from the web interface to avoid users
  287. shooting themselves in the foot by destroying everything.
  288. .Ss Custom Emojis
  289. From version 2.51, support for customized Emojis in posts is available
  290. (previously, they were hardcoded). Emojis are read from the
  291. .Pa emojis.json
  292. file in the instance base directory, as a JSON object of key / value
  293. pairs (if this file does not exist, it will be created with
  294. the predefined set). Each key in the object contains the text to be found (e.g.,
  295. the :-) for a smiling face), and its associated value, the text string that
  296. will replace it (in this example case, the HTML entity for the Unicode codepoint
  297. for the smiley or the Emoji itself as text).
  298. .Pp
  299. Emoji values can also be URLs to image files; in this case, they will not be
  300. substituted in the post content, but added to the 'tag' array as an ActivityPub
  301. standard 'Emoji' object (it's recommendable that the Emoji key be enclosed in
  302. colons for maximum compatilibity with other ActivityPub implementations, like
  303. e.g. :happydoggo:). These images can be served from an external source or from the
  304. .Pa static
  305. directory of the instance admin.
  306. .Pp
  307. If you want to disable any Emoji substitution, change the file to contain
  308. just an empty JSON object ({}).
  309. .Ss SPAM Mitigation
  310. There have been some SPAM attacks on the Fediverse and, as too many
  311. instances and server implementations out there still allow automatic
  312. account creation, it will only get worse.
  313. .Nm
  314. includes some (not very strong) tools for trying to survive the SPAM
  315. flood that will eventually happen.
  316. .Pp
  317. The
  318. .Ic min_account_age
  319. field in the main configuration file allows setting a minimum age (in
  320. seconds) to consider too recently created accounts suspicious of being
  321. a potential source of SPAM. This is a naïve assumption, because spammers
  322. can create accounts, let them dormant for a while and then start to use
  323. them. Also, some ActivityPub implementations don't even bother to return
  324. a creation date for their accounts, so this is not very useful.
  325. .Pp
  326. From version 2.50, post content can be filtered out by regular expressions.
  327. These weapons of mass destruction can be written into the
  328. .Ic filter_reject.txt
  329. file in the server base directory, one per line; if this file exists,
  330. all posts' content will be matched (after being stripped of HTML tags)
  331. against these regexes, one by one, and any match will make the post to
  332. be rejected. Use lower case, the regex will be case insensitive by default.
  333. If you don't know about regular expressions, don't use this
  334. option (or learn about them inw some tutorial, there are gazillions of
  335. them out there), as you and your users may start missing posts. Also,
  336. given that every regular expression implementation supports a different
  337. set of features, consider reading the documentation about the one
  338. implemented in your system.
  339. .Ss ActivityPub Support
  340. These are the following activities and objects that
  341. .Nm
  342. supports:
  343. .Bl -tag -width tenletters
  344. .It Vt Follow
  345. Complete support, on input and output.
  346. .It Vt Undo
  347. For
  348. .Vt Follow ,
  349. .Vt Like
  350. and
  351. .Vt Announce
  352. objects, on input and output.
  353. .It Vt Create
  354. For
  355. .Vt Note ,
  356. .Vt Question ,
  357. .Vt Page ,
  358. .Vt Article ,
  359. .Vt Event
  360. and
  361. .Vt Video
  362. objects on input, and for
  363. .Vt Note
  364. and
  365. .Vt Question
  366. on output.
  367. .It Vt Accept
  368. For
  369. .Vt Follow
  370. objects, on input and output.
  371. .It Vt Like
  372. For
  373. .Vt Note
  374. objects, on input and output.
  375. .It Vt EmojiReact
  376. For
  377. .Vt Note
  378. objects, on input.
  379. .It Vt Announce
  380. For
  381. .Vt Note
  382. objects, on input and output.
  383. .It Vt Update
  384. For
  385. .Vt Note ,
  386. .Vt Question ,
  387. .Vt Page ,
  388. .Vt Article ,
  389. .Vt Event
  390. and
  391. .Vt Video
  392. objects on input, and for
  393. .Vt Note
  394. on output.
  395. .It Vt Delete
  396. Supported for
  397. .Vt Note
  398. and
  399. .Vt Tomsbtone
  400. objects on input, and for
  401. .Vt Note
  402. objects on output.
  403. .It Vt Move
  404. For actor-like objects, for input and output.
  405. .El
  406. .Pp
  407. The rest of activities and objects are dropped on input.
  408. .Pp
  409. There is partial support for
  410. .Vt OrderedCollection
  411. objects in the
  412. .Pa /outbox
  413. (with the last 20 entries of the local timeline shown). No pagination
  414. is supported. Intentionally, the
  415. .Pa /followers
  416. and
  417. .Pa /following
  418. paths return empty lists.
  419. .Ss Migrating from snac to Mastodon
  420. Since version 2.60, you can migrate your
  421. .Nm
  422. account to other ActivityPub instances. What is described here is the process to do it from
  423. .Nm
  424. to Mastodon; on other software implementations, it will surely be somewhat different. All
  425. the steps regarding your
  426. .Nm
  427. account must be done from the command line. For the sake of the example, let's
  428. say that you want to migrate from an account named @origin@snac.example.org to
  429. another one named @destination@mastodon.example.com and that both of them
  430. already exist. I've used this very informative page as a guideline:
  431. .Pp
  432. .Lk https://fedi.tips/transferring-your-mastodon-account-to-another-server/
  433. .Pp
  434. 1. On your
  435. .Nm
  436. server, first export your data to CSV by running:
  437. .Bd -literal -offset indent
  438. snac export_csv $SNAC_BASEDIR origin
  439. .Ed
  440. .Pp
  441. You'll find the following CSV files in the
  442. .Pa export/
  443. subdirectory inside the user directory:
  444. .Pa bookmarks.csv ,
  445. .Pa blocked_accounts.csv ,
  446. .Pa lists.csv , and
  447. .Pa following_accounts.csv .
  448. .Pp
  449. 2. In the web interface of your new Mastodon account, click on
  450. .Vt Preferences
  451. >
  452. .Vt Import and Export
  453. >
  454. .Vt Import
  455. and upload the CSV files one at a time. You must specify the type of
  456. file you are uploading.
  457. .Pp
  458. 3. Still in the web interface of your new Mastodon account, click on
  459. .Vt Preferences
  460. >
  461. .Vt Account
  462. >
  463. .Vt Moving From a Different Account ,
  464. then click on
  465. .Vt Create an account alias
  466. and follow the instructions. (When it asks you to
  467. write your old account’s handle, it needs to include the @ at the start
  468. as well as the @ in the middle; as of our example, @origin@snac.example.org).
  469. It seems this step is not performed immediately, you must wait an unspecified
  470. number of minutes for this to be effective.
  471. .Pp
  472. 4. Meanwhile, you must tell
  473. .Nm
  474. about your new account by creating an alias from your current one.
  475. So, on your
  476. .Nm
  477. server, run
  478. .Bd -literal -offset indent
  479. snac alias $SNAC_BASEDIR origin "@destination@mastodon.example.com"
  480. .Ed
  481. .Pp
  482. 5. Finally, you must order
  483. .Nm
  484. to start the migration process, that will consist in iterating all the
  485. people that follows your account and sending them a
  486. .Vt Move
  487. message, that acts as a suggestion to unfollow your old account
  488. and follow the new one. The command is
  489. .Bd -literal -offset indent
  490. snac migrate $SNAC_BASEDIR origin
  491. .Ed
  492. .Pp
  493. This process can be very long and unreliable; any destination server may be down,
  494. too busy, disconnected or gone. I recommend you to read the document I linked
  495. above to know about all the sorrows awaiting.
  496. .Pp
  497. Also, please take note that the
  498. .Nm
  499. account you migrated from is not disabled nor changed in any way, so can still
  500. use it as it no migration was done. This behaviour may or may not match what other
  501. ActivityPub implementations do.
  502. .Pp
  503. .Ss Migrating from Mastodon to snac
  504. Since version 2.61, you can migrate accounts on other ActivityPub instances to your
  505. .Nm
  506. one. What is described here is the process to do it from
  507. Mastodon; on other software implementations, it will surely be somewhat different. All
  508. the steps regarding your
  509. .Nm
  510. account must be done from the command line. For the sake of the example, let's
  511. say that you want to migrate from an account named @origin@mastodon.example.com to
  512. another one named @destination@snac.example.org and that both of them
  513. already exist. I've used this very informative page as a guideline:
  514. .Pp
  515. .Lk https://fedi.tips/transferring-your-mastodon-account-to-another-server/
  516. .Pp
  517. 1. On the web interface of your origin Mastodon account, click on
  518. .Vt Preferences
  519. >
  520. .Vt Import and Export
  521. >
  522. .Vt Export
  523. and download the CSV files under the "Follows", "Lists", "You Block" and "Bookmarks"
  524. labels. After being downloaded, you should find the following files on your download
  525. directory:
  526. .Pa bookmarks.csv ,
  527. .Pa blocked_accounts.csv ,
  528. .Pa lists.csv , and
  529. .Pa following_accounts.csv .
  530. .Pp
  531. 2. Copy all those files to the
  532. .Pa import/
  533. subdirectory of the user's directory inside the server base directory, and run
  534. .Bd -literal -offset indent
  535. snac import_csv $SNAC_BASEDIR destination
  536. .Ed
  537. .Pp
  538. This process may take some time because it depends on the availability / responsiveness
  539. of all the ActivityPub servers involved (webfinger, accounts, posts, etc.). Some errors
  540. may be transient and retried later. Also, if
  541. .Nm
  542. complains that it can't find any of these files, please check that they are really
  543. stored in the
  544. .Pa import/
  545. subdirectory and that their names match exactly. Some of them may be
  546. empty (for example, if you didn't create any list) and that's fine.
  547. .Pp
  548. 3. Again on your
  549. .Nm
  550. server, run
  551. .Bd -literal -offset indent
  552. snac alias $SNAC_BASEDIR destination "@origin@mastodon.example.com"
  553. .Ed
  554. .Pp
  555. Check that no errors were shown. If they do, the origin Mastodon server may be
  556. busy or down; try again later.
  557. .Pp
  558. 4. Move back to the web interface of the origin Mastodon account, go to
  559. .Vt Preferences
  560. >
  561. .Vt Account
  562. >
  563. .Vt Move To A Different Account ,
  564. and follow the instructions there. Set the handle of the new account to your
  565. .Nm
  566. one; as of our example, @destination@snac.example.org. This will start the migration
  567. process: it's the duty of your old Mastodon instance to send an automatic
  568. .Vt Move
  569. message to every one of your followers. Eventually, you will start receiving follow notifications to your
  570. .Nm
  571. account from all accounts that followed the Mastodon one. According to the great document
  572. I linked above, this process may or may not start immediately, and its success may depend
  573. heavily on how all the servers involved behave. Just cross your fingers and hope for the best.
  574. .Pp
  575. .Ss Instance blocking
  576. Full instances can be blocked. This operation must be done from
  577. the command-line tool. See
  578. .Xr snac 1 .
  579. .Pp
  580. .Ss Bad login throttling
  581. Since version 2.67, a simple logic to avoid brute force attacks against user passwords
  582. has been implemented: if, from a given IP address, the number of failed logins reaches
  583. a given threshold, further tries from that IP address are never successful until a timer
  584. expires. The maximum number of retries can be configured in the
  585. .Pa server.json
  586. file by setting the
  587. .Ic badlogin_retries
  588. variable, and the number of seconds the IP address unlock timer expires, in
  589. .Ic badlogin_expire .
  590. Please take note that, for this system to work, you must setup your web server proxy
  591. to pass the remote connection address in the
  592. .Ic X-Forwarded-For
  593. HTTP header (unless you use the FastCGI interface; if that's the case, you don't have
  594. to do anything).
  595. .Pp
  596. .Ss Subscribing to Fediverse Relays
  597. Since version 2.69, a
  598. .Nm
  599. instance can subscribe to LitePub (Pleroma-style) Fediverse Relays. Doing this improves
  600. visibility and allows following hashtags. To do this, you must create a special user named
  601. relay and, from it, follow the relay actor(s) like you do with regular actor URLs. This
  602. special user will start receiving boosts from the relay server of posts from other instances
  603. also following it. If any other user of the same
  604. .Nm
  605. instance follows any of the hashtags included in these boosted posts coming from the relay,
  606. they will be received as if they were for them.
  607. .Pp
  608. Example:
  609. .Bd -literal -offset indent
  610. snac adduser $SNAC_BASEDIR relay # only needed once
  611. snac follow $SNAC_BASEDIR relay https://relay.example.com/actor
  612. .Ed
  613. .Pp
  614. Users on your instance do NOT need to follow the local relay user to benefit from following
  615. hashtags.
  616. .Pp
  617. Please take note that subscribing to relays can increase the traffic towards your instance
  618. significantly. In any case, lowering the "Maximum days to keep posts" value for the relay
  619. special user is recommended (e.g. setting to just 1 day).
  620. .Sh ENVIRONMENT
  621. .Bl -tag -width Ds
  622. .It Ev DEBUG
  623. Overrides the debugging level from the server 'dbglevel' configuration
  624. variable. Set it to an integer value. The higher, the deeper in meaningless
  625. verbiage you'll find yourself into.
  626. .El
  627. .Sh EXAMPLES
  628. You want to install the
  629. .Nm
  630. Fediverse daemon in the host example.com, that is correctly configured
  631. with a valid TLS certificate and running the nginx httpd server.
  632. The service will be installed under the
  633. .Pa fedi
  634. location. Two users, walter and jessie, will be hosted in the system.
  635. Their Fediverse presence addresses will be
  636. .Lk https://example.com/fedi/walter
  637. and
  638. .Lk https://example.com/fedi/jesse ,
  639. respectively. They will be known
  640. in the Fediverse as @walter@example.com and @jesse@example.com. The
  641. .Nm
  642. daemon will run as the user snacusr in the system and listen to the
  643. localhost:8001 network socket. All data will be stored in the
  644. .Pa /home/snacusr/fedidata
  645. directory.
  646. .Pp
  647. Log into the system as snacusr and execute:
  648. .Bd -literal -offset indent
  649. snac init /home/snacusr/fedidata
  650. .Ed
  651. .Pp
  652. Answer "example.com" to the host name question, "/fedi" to the path
  653. prefix question, "localhost" to the address and "8001" to the port.
  654. .Pp
  655. Create the users
  656. .Bd -literal -offset indent
  657. snac adduser /home/snacusr/fedidata walter
  658. snac adduser /home/snacusr/fedidata jesse
  659. .Ed
  660. .Pp
  661. Answer the questions with reasonable values.
  662. .Pp
  663. Execute the server:
  664. .Bd -literal -offset indent
  665. snac httpd /home/snacusr/fedidata
  666. .Ed
  667. .Pp
  668. Edit the nginx configuration and add the following snippet to the
  669. example.com server section:
  670. .Bd -literal -offset indent
  671. # nginx configuration example
  672. # main web access point
  673. location /fedi {
  674. proxy_pass http://localhost:8001;
  675. proxy_set_header Host $http_host;
  676. proxy_set_header X-Forwarded-For $remote_addr;
  677. }
  678. # webfinger
  679. location /.well-known/webfinger {
  680. proxy_pass http://localhost:8001;
  681. proxy_set_header Host $http_host;
  682. proxy_set_header X-Forwarded-For $remote_addr;
  683. }
  684. # Mastodon API (entry points)
  685. location /api/v1/ {
  686. proxy_pass http://localhost:8001;
  687. proxy_set_header Host $http_host;
  688. proxy_set_header X-Forwarded-For $remote_addr;
  689. }
  690. location /api/v2/ {
  691. proxy_pass http://localhost:8001;
  692. proxy_set_header Host $http_host;
  693. proxy_set_header X-Forwarded-For $remote_addr;
  694. }
  695. # Mastodon API (OAuth support)
  696. location /oauth {
  697. proxy_pass http://localhost:8001;
  698. proxy_set_header Host $http_host;
  699. proxy_set_header X-Forwarded-For $remote_addr;
  700. }
  701. # optional
  702. location /.well-known/nodeinfo {
  703. proxy_pass http://localhost:8001;
  704. proxy_set_header Host $http_host;
  705. proxy_set_header X-Forwarded-For $remote_addr;
  706. }
  707. # optional (needed by some Mastodon API clients)
  708. location /.well-known/host-meta {
  709. proxy_pass http://localhost:8001;
  710. proxy_set_header Host $http_host;
  711. proxy_set_header X-Forwarded-For $remote_addr;
  712. }
  713. # optional (Mastodon-like link share entrypoint)
  714. location /share {
  715. proxy_pass http://localhost:8001;
  716. proxy_set_header Host $http_host;
  717. proxy_set_header X-Forwarded-For $remote_addr;
  718. }
  719. # optional (Mastodon-like "authorize interaction" entrypoint)
  720. location /authorize_interaction {
  721. proxy_pass http://localhost:8001;
  722. proxy_set_header Host $http_host;
  723. proxy_set_header X-Forwarded-For $remote_addr;
  724. }
  725. .Ed
  726. .Pp
  727. Restart the nginx daemon and connect to
  728. .Lk https://example.com/fedi/walter .
  729. The empty, default screen will be shown. Enter the admin section with the
  730. credentials defined for this user. Search people, start following
  731. them, engage in arid discussions and generally enjoy the frustrating
  732. experience of Social Media.
  733. .Pp
  734. This is an example of a similar configuration for the Apache2 web server:
  735. .Bd -literal -offset indent
  736. # apache2 configuration example
  737. ProxyPreserveHost On
  738. # Main web access point
  739. <Location /fedi>
  740. ProxyPass http://127.0.0.1:8001/social
  741. </Location>
  742. # WebFinger
  743. <Location /.well-known/webfinger>
  744. ProxyPass http://127.0.0.1:8001/.well-known/webfinger
  745. </Location>
  746. # Mastodon API (entry points)
  747. <Location /api/v1/>
  748. ProxyPass http://127.0.0.1:8001/api/v1/
  749. </Location>
  750. <Location /api/v2/>
  751. ProxyPass http://127.0.0.1:8001/api/v2/
  752. </Location>
  753. # Mastodon API (OAuth support)
  754. <Location /oauth>
  755. ProxyPass http://127.0.0.1:8001/oauth
  756. </Location>
  757. # NodeInfo (optional)
  758. <Location /.well-known/nodeinfo>
  759. ProxyPass http://127.0.0.1:8001/.well-known/nodeinfo
  760. </Location>
  761. # host-meta (optional, needed for some Mastodon API clients)
  762. <Location /.well-known/host-meta>
  763. ProxyPass http://127.0.0.1:8001/.well-known/host-meta
  764. </Location>
  765. # optional (Mastodon-like link share entrypoint)
  766. <Location /share>
  767. ProxyPass http://127.0.0.1:8001/share
  768. </Location>
  769. # optional (Mastodon-like "authorize interaction" entrypoint)
  770. <Location /authorize_interaction>
  771. ProxyPass http://127.0.0.1:8001/share
  772. </Location>
  773. .Ed
  774. .Pp
  775. Since version 2.43,
  776. .Nm
  777. supports communicating from / to the front end http server using the FastCGI
  778. protocol. There is no special advantage in using this, only that some servers
  779. allow for simpler configuration. For example, in the case of nginx, you can
  780. replace the two 'proxy_pass' and 'proxy_set_header' lines in the example
  781. above with just
  782. .Bd -literal -offset indent
  783. fastcgi_pass localhost:8001;
  784. .Ed
  785. .Pp
  786. The only thing to change on
  787. .Nm
  788. is to the set 'fastcgi' value to true in
  789. .Pa server.json .
  790. .Pp
  791. Further, using the FastCGI interface allows a much simpler configuration
  792. under OpenBSD's native httpd, given that it's natively implemented there
  793. and you no longer need to configure the complicated relayd server. This is
  794. an example:
  795. .Bd -literal -offset indent
  796. # OpenBSD httpd configuration example
  797. # other server configuration
  798. [...]
  799. location "/fedi/*" {
  800. fastcgi socket tcp "127.0.0.1" 8001
  801. }
  802. location "/.well-known/webfinger" {
  803. fastcgi socket tcp "127.0.0.1" 8001
  804. }
  805. location "/oauth/*" {
  806. fastcgi socket tcp "127.0.0.1" 8001
  807. }
  808. location "/api/v1/*" {
  809. fastcgi socket tcp "127.0.0.1" 8001
  810. }
  811. location "/api/v2/*" {
  812. fastcgi socket tcp "127.0.0.1" 8001
  813. }
  814. location "/.well-known/nodeinfo" {
  815. fastcgi socket tcp "127.0.0.1" 8001
  816. }
  817. location "/.well-known/host-meta" {
  818. fastcgi socket tcp "127.0.0.1" 8001
  819. }
  820. location "/share" {
  821. fastcgi socket tcp "127.0.0.1" 8001
  822. }
  823. location "/authorize_interaction" {
  824. fastcgi socket tcp "127.0.0.1" 8001
  825. }
  826. .Ed
  827. .Sh SEE ALSO
  828. .Xr snac 1 ,
  829. .Xr snac 5
  830. .Sh AUTHORS
  831. .An grunfink Lk https://comam.es/snac/grunfink @grunfink@comam.es
  832. .Sh LICENSE
  833. See the LICENSE file for details.
  834. .Sh CAVEATS
  835. JSON files are fragile when modified by hand. Take care.