snac.8 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742
  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 respect hard
  27. link counts. Remember:
  28. .Nm
  29. is a very UNIXy program that loves hard links.
  30. .Ss Building and Installation
  31. A C compiler must be installed in the system, as well as the development
  32. headers and libraries for OpenSSL (or compatible) and curl. To build
  33. .Nm ,
  34. run
  35. .Bd -literal -offset indent
  36. make
  37. .Ed
  38. .Pp
  39. And, after that, run as root
  40. .Bd -literal -offset indent
  41. make install
  42. .Ed
  43. .Ss Data storage Initialization
  44. Once
  45. .Nm
  46. is properly installed on the system, designate a directory where
  47. the server and user data are to be stored. This directory
  48. must not exist yet.
  49. .Nm
  50. must always be run as a regular user; you can create one for
  51. it or use your own. To initialize the data storage, execute
  52. .Bd -literal -offset indent
  53. snac init $HOME/snac-data
  54. .Ed
  55. .Pp
  56. A small set of questions will be asked regarding the installation,
  57. specially the host name it will run under, the local network address
  58. and port
  59. .Nm
  60. will listen to, the optional path prefix and possibly other things.
  61. .Pp
  62. Since version 2.57, if the 'network address' starts with /, it's
  63. assumed to be a UNIX-like socket (please take note that the http proxy
  64. must have full read and write access to this socket; this is a common
  65. pitfall. Permissions will break your heart).
  66. .Pp
  67. You can launch the
  68. .Nm
  69. process by running
  70. .Bd -literal -offset indent
  71. snac httpd $HOME/snac-data
  72. .Ed
  73. .Pp
  74. Log messages are sent to the standard error stream. By default, only
  75. relevant information is written there. You can increase the debugging
  76. level by editing the 'dbglevel' field in the
  77. .Pa server.json
  78. file or by setting a numeric value between 0 and 3 to the DEBUG
  79. environment variable, see below.
  80. .Pp
  81. If you operate a Linux systemd-enabled system, OpenBSD, FreeBSD or NetBSD, there are
  82. startup scripts and configuration data in the
  83. .Pa examples
  84. directory.
  85. For other operating systems, please read the appropriate documentation
  86. on how to install a daemon as a non-root service.
  87. .Ss Upgrading to a new version
  88. Sometimes, the data storage disk layout changes between versions. If there
  89. is such a change,
  90. .Nm
  91. will refuse to run and require an upgrade. Do this by running
  92. .Bd -literal -offset indent
  93. snac upgrade $HOME/snac-data
  94. .Ed
  95. .Pp
  96. Take special care to execute this upgrade operation without any
  97. .Nm
  98. processes serving on the same folder. You can break everything. I know
  99. this because Tyler knows this.
  100. .Pp
  101. .Ss Server Setup
  102. .Pp
  103. An http server with TLS and proxying support must already be
  104. installed and configured.
  105. .Nm
  106. runs as a daemon and listens on a TCP/IP socket, preferably
  107. on a local interface. It can serve the full domain or only
  108. a directory. The http server must be configured to route to the
  109. .Nm
  110. socket all related traffic and also the webfinger standard
  111. address. The Host header must be propagated.
  112. See the examples below.
  113. .Ss Adding Users
  114. .Pp
  115. Users must be created from the command line.
  116. You can do it by running
  117. .Bd -literal -offset indent
  118. snac adduser $HOME/snac-data
  119. .Ed
  120. .Pp
  121. All needed data will be prompted for. There is no artificial limit
  122. on the number of users that can be created.
  123. .Ss Customization
  124. The
  125. .Pa server.json
  126. configuration file allows some behaviour tuning:
  127. .Bl -tag -width tenletters
  128. .It Ic host
  129. The host name.
  130. .It Ic prefix
  131. The URL path prefix.
  132. .It Ic address
  133. The listen network address. If it starts with /, it's assumed to be
  134. a UNIX-like socket instead.
  135. .It Ic port
  136. The listen network port (unused if address is a UNIX socket).
  137. .It Ic dbglevel
  138. The debug level. An integer value, being 0 the less verbose (the default).
  139. .It Ic layout
  140. The disk storage layout version. Never touch this.
  141. .It Ic queue_retry_max
  142. Messages sent out are stored in a queue. If the posting of a messages fails,
  143. it's re-enqueued for later. This integer configures the maximum count of
  144. times the sending will be retried.
  145. .It Ic queue_retry_minutes
  146. The number of minutes to wait before the failed posting of a message is
  147. retried. This is not linear, but multiplied by the number of retries
  148. already done.
  149. .It Ic queue_timeout
  150. The maximum number of seconds to wait when sending a message from the queue.
  151. .It Ic queue_timeout_2
  152. The maximum number of seconds to wait when sending a message from the queue
  153. to those servers that went timeout in the previous retry. If you want to
  154. give slow servers a chance to receive your messages, you can increase this
  155. value (but also take into account that processing the queue will take longer
  156. while waiting for these molasses to respond).
  157. .It Ic max_timeline_entries
  158. This is the maximum timeline entries shown in the web interface.
  159. .It Ic timeline_purge_days
  160. Entries in the timeline older that this number of days are purged.
  161. If you don't want any timeline purging and enjoy your data drives
  162. fill up with old crap and finally burst in flames, you can disable
  163. purging by setting this to 0.
  164. .It Ic local_purge_days
  165. Same as before, but for the user-generated entries in the local timeline.
  166. .It Ic cssurls
  167. This is a list of URLs to CSS files that will be inserted, in this order,
  168. in the HTML before the user CSS. Use these files to configure the global
  169. site layout.
  170. .It Ic disable_cache
  171. If set to true, timeline caching is not done. This is only useful for
  172. debugging purposes; don't enable it unless you know what do you want, as
  173. it makes everything slower.
  174. .It Ic disable_openbsd_security
  175. If running under OpenBSD,
  176. .Nm
  177. makes use of the enhanced security functions
  178. .Xr unveil 2
  179. and
  180. .Xr pledge 2 .
  181. Setting this to true disables their usage. These functions limit severely
  182. what an intruder can do in case of a security vulnerability, so only enable
  183. this option if something is very broken.
  184. .It Ic num_threads
  185. By setting this value, you can specify the exact number of threads
  186. .Nm
  187. will use when processing connections. Values lesser than 4 will be ignored.
  188. .It Ic disable_email_notifications
  189. By setting this to true, no email notification will be sent for any user.
  190. .It Ic disable_inbox_collection
  191. By setting this to true, no inbox collection is done. Inbox collection helps
  192. being discovered from remote instances, but also increases network traffic.
  193. .It Ic http_headers
  194. If you need to add more HTTP response headers for whatever reason, you can
  195. fill this object with the required header/value pairs. For example, for enhanced
  196. XSS security, you can set the "Content-Security-Policy" header to "script-src ;"
  197. to be totally sure that no JavaScript is executed.
  198. .It Ic show_instance_timeline
  199. If this is set to true, the instance base URL will show a timeline with the latest
  200. user posts instead of the default greeting static page. If other information
  201. fields are set (see below), they are also shown.
  202. .It Ic admin_email
  203. The email address of the instance administrator (optional).
  204. .It Ic admin_account
  205. The user name of the instance administrator (optional).
  206. .It Ic short_description
  207. A textual short description about the instance (optional).
  208. .It Ic fastcgi
  209. If set to true,
  210. .Nm
  211. will use the FastCGI interface to communicate with the upper level
  212. http server, that must be configured accordingly.
  213. .It Ic disable_history
  214. If set to true, history monthly snapshots are not served nor their links shown.
  215. .It Ic shared_inboxes
  216. This boolean value selects if shared inboxes are announced or not. Enabling
  217. shared inboxes helps (somewhat) in optimizing incoming traffic for instances
  218. with a large number of users.
  219. .It Ic min_account_age
  220. If this numeric value (in seconds) is set, any activity coming from an account
  221. that was created more recently than that will be rejected. This may be used
  222. to mitigate spam from automatically created accounts.
  223. .It Ic protocol
  224. This string value contains the protocol (schema) to be used in URLs. If not
  225. set, it defaults to "https". If you run
  226. .Nm
  227. as part of a hidden network like Tor or I2P that doesn't have a TLS /
  228. Certificate infrastructure, you need to set it to "http". Don't change it
  229. unless you know what you are doing.
  230. .It Ic hide_delete_post_button
  231. If set to true, the button to delete a post is not shown. It's not very
  232. useful and somewhat clutters the already crowded button space.
  233. .It Ic disable_block_notifications
  234. If set to true, notifications about 'Block' activities are never sent.
  235. .It Ic strict_public_timelines
  236. If set to true, public timelines only show posts and boosts originating
  237. from an account (no conversation trees).
  238. .El
  239. .Pp
  240. You must restart the server to make effective these changes.
  241. .Pp
  242. If a file named
  243. .Pa greeting.html
  244. is present in the server base directory, it will be returned whenever
  245. the base URL of the server is requested. Fill it with whatever
  246. information about the instance you want to supply to people
  247. visiting the server, like sign up requirements, site policies
  248. and such. The special %userlist% mark in the file will cause
  249. the list of users in this instance to be inserted.
  250. .Pp
  251. Users can change a bit of information about themselves from the
  252. web interface. See
  253. .Xr snac 1
  254. for details. Further, every user can have a private CSS file in their
  255. .Pa static/style.css
  256. that will be served instead of the server-wide one.
  257. It's not modifiable from the web interface to avoid users
  258. shooting themselves in the foot by destroying everything.
  259. .Ss Custom Emojis
  260. From version 2.51, support for customized Emojis in posts is available
  261. (previously, they were hardcoded). Emojis are read from the
  262. .Pa emojis.json
  263. file in the instance base directory, as a JSON object of key / value
  264. pairs (if this file does not exist, it will be created with
  265. the predefined set). Each key in the object contains the text to be found (e.g.,
  266. the :-) for a smiling face), and its associated value, the text string that
  267. will replace it (in this example case, the HTML entity for the Unicode codepoint
  268. for the smiley or the Emoji itself as text).
  269. .Pp
  270. Emoji values can also be URLs to image files; in this case, they will not be
  271. substituted in the post content, but added to the 'tag' array as an ActivityPub
  272. standard 'Emoji' object (it's recommendable that the Emoji key be enclosed in
  273. colons for maximum compatilibity with other ActivityPub implementations, like
  274. e.g. :happydoggo:). These images can be served from an external source or from the
  275. .Pa static
  276. directory of the instance admin.
  277. .Pp
  278. If you want to disable any Emoji substitution, change the file to contain
  279. just an empty JSON object ({}).
  280. .Ss SPAM Mitigation
  281. There have been some SPAM attacks on the Fediverse and, as too many
  282. instances and server implementations out there still allow automatic
  283. account creation, it will only get worse.
  284. .Nm
  285. includes some (not very strong) tools for trying to survive the SPAM
  286. flood that will eventually happen.
  287. .Pp
  288. The
  289. .Ic min_account_age
  290. field in the main configuration file allows setting a minimum age (in
  291. seconds) to consider too recently created accounts suspicious of being
  292. a potential source of SPAM. This is a naïve assumption, because spammers
  293. can create accounts, let them dormant for a while and then start to use
  294. them. Also, some ActivityPub implementations don't even bother to return
  295. a creation date for their accounts, so this is not very useful.
  296. .Pp
  297. From version 2.50, post content can be filtered out by regular expressions.
  298. These weapons of mass destruction can be written into the
  299. .Ic filter_reject.txt
  300. file in the server base directory, one per line; if this file exists,
  301. all posts' content will be matched (after being stripped of HTML tags)
  302. against these regexes, one by one, and any match will make the post to
  303. be rejected. If you don't know about regular expressions, don't use this
  304. option (or learn about them in some tutorial, there are gazillions of
  305. them out there), as you and your users may start missing posts. Also,
  306. given that every regular expression implementation supports a different
  307. set of features, consider reading the documentation about the one
  308. implemented in your system.
  309. .Ss ActivityPub Support
  310. These are the following activities and objects that
  311. .Nm
  312. supports:
  313. .Bl -tag -width tenletters
  314. .It Vt Follow
  315. Complete support, on input and output.
  316. .It Vt Undo
  317. For
  318. .Vt Follow ,
  319. .Vt Like
  320. and
  321. .Vt Announce
  322. objects, on input and output.
  323. .It Vt Create
  324. For
  325. .Vt Note ,
  326. .Vt Question ,
  327. .Vt Page ,
  328. .Vt Article ,
  329. .Vt Event
  330. and
  331. .Vt Video
  332. objects on input, and for
  333. .Vt Note
  334. and
  335. .Vt Question
  336. on output.
  337. .It Vt Accept
  338. For
  339. .Vt Follow
  340. objects, on input and output.
  341. .It Vt Like
  342. For
  343. .Vt Note
  344. objects, on input and output.
  345. .It Vt EmojiReact
  346. For
  347. .Vt Note
  348. objects, on input.
  349. .It Vt Announce
  350. For
  351. .Vt Note
  352. objects, on input and output.
  353. .It Vt Update
  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. on output.
  365. .It Vt Delete
  366. Supported for
  367. .Vt Note
  368. and
  369. .Vt Tomsbtone
  370. objects on input, and for
  371. .Vt Note
  372. objects on output.
  373. .It Vt Move
  374. For actor-like objects, for input and output.
  375. .El
  376. .Pp
  377. The rest of activities and objects are dropped on input.
  378. .Pp
  379. There is partial support for
  380. .Vt OrderedCollection
  381. objects in the
  382. .Pa /outbox
  383. (with the last 20 entries of the local timeline shown). No pagination
  384. is supported. Intentionally, the
  385. .Pa /followers
  386. and
  387. .Pa /following
  388. paths return empty lists.
  389. .Ss Migrating from snac to Mastodon
  390. Since version 2.60, you can migrate your
  391. .Nm
  392. account to other ActivityPub instances. What is described here is the process to do it from
  393. .Nm
  394. to Mastodon; on other software implementations, it will surely be somewhat different. All
  395. the steps regarding your
  396. .Nm
  397. account must be done from the command line. For the sake of the example, let's
  398. say that you want to migrate from an account named @origin@snac.example.org to
  399. another one named @destination@mastodon.example.com and that both of them
  400. already exist. I've used this very informative page as a guideline:
  401. .Pp
  402. .Lk https://fedi.tips/transferring-your-mastodon-account-to-another-server/
  403. .Pp
  404. 1. On your
  405. .Nm
  406. server, first export your data to CSV by running:
  407. .Bd -literal -offset indent
  408. snac export_csv $SNAC_BASEDIR origin
  409. .Ed
  410. .Pp
  411. You'll find the following CSV files in the current directory:
  412. .Pa bookmarks.csv ,
  413. .Pa blocked_accounts.csv ,
  414. .Pa lists.csv , and
  415. .Pa following_accounts.csv .
  416. .Pp
  417. 2. In the web interface of your new Mastodon account, click on
  418. .Vt Preferences
  419. >
  420. .Vt Import and Export
  421. >
  422. .Vt Import
  423. and upload the CSV files one at a time. You must specify the type of
  424. file you are uploading.
  425. .Pp
  426. 3. Still in the web interface of your new Mastodon account, click on
  427. .Vt Preferences
  428. >
  429. .Vt Account
  430. >
  431. .Vt Moving From a Different Account ,
  432. then click on
  433. .Vt Create an account alias
  434. and follow the instructions. (When it asks you to
  435. write your old account’s handle, it needs to include the @ at the start
  436. as well as the @ in the middle; as of our example, @origin@snac.example.org).
  437. It seems this step is not performed immediately, you must wait an unspecified
  438. number of minutes for this to be effective.
  439. .Pp
  440. 4. Meanwhile, you must tell
  441. .Nm
  442. about your new account by creating an alias from your current one.
  443. So, on your
  444. .Nm
  445. server, run
  446. .Bd -literal -offset indent
  447. snac alias $SNAC_BASEDIR origin "@destination@mastodon.example.com"
  448. .Ed
  449. .Pp
  450. 5. Finally, you must order
  451. .Nm
  452. to start the migration process, that will consist in iterating all the
  453. people that follows your account and sending them a
  454. .Vt Move
  455. message, that acts as a suggestion to unfollow your old account
  456. and follow the new one. The command is
  457. .Bd -literal -offset indent
  458. snac migrate $SNAC_BASEDIR origin
  459. .Ed
  460. .Pp
  461. This process can be very long and unreliable; any destination server may be down,
  462. too busy, disconnected or gone. I recommend you to read the document I linked
  463. above to know about all the sorrows awaiting.
  464. .Pp
  465. Also, please take note that the
  466. .Nm
  467. account you migrated from is not disabled nor changed in any way, so can still
  468. use it as it no migration was done. This behaviour may or may not match what other
  469. ActivityPub implementations do.
  470. .Ss Migrating from Mastodon to snac
  471. Since version 2.61, you can migrate accounts on other ActivityPub instances to your
  472. .Nm
  473. one. What is described here is the process to do it from
  474. Mastodon; on other software implementations, it will surely be somewhat different. All
  475. the steps regarding your
  476. .Nm
  477. account must be done from the command line. For the sake of the example, let's
  478. say that you want to migrate from an account named @origin@mastodon.example.com to
  479. another one named @destination@snac.example.org and that both of them
  480. already exist. I've used this very informative page as a guideline:
  481. .Pp
  482. .Lk https://fedi.tips/transferring-your-mastodon-account-to-another-server/
  483. .Pp
  484. 1. On the web interface of your origin Mastodon account, click on
  485. .Vt Preferences
  486. >
  487. .Vt Import and Export
  488. >
  489. .Vt Export
  490. and download the CSV files under the "Follows", "Lists", "You Block" and "Bookmarks"
  491. labels. After being downloaded, you should find the following files on your download
  492. directory:
  493. .Pa bookmarks.csv ,
  494. .Pa blocked_accounts.csv ,
  495. .Pa lists.csv , and
  496. .Pa following_accounts.csv .
  497. .Pp
  498. 2. From the directory where those files are stored, run
  499. .Bd -literal -offset indent
  500. snac import_csv $SNAC_BASEDIR destination
  501. .Ed
  502. .Pp
  503. This process may take some time because it depends on the availability / responsiveness
  504. of all the ActivityPub servers involved (webfinger, accounts, posts, etc.). Some errors
  505. may be transient and retried later. Also, if
  506. .Nm
  507. complains that it can't find any of these files, please check that they are really
  508. stored in the current directory and that their names match exactly. Some of them may be
  509. empty (for example, if you didn't create any list) and that's fine.
  510. .Pp
  511. 3. Again on your
  512. .Nm
  513. server, run
  514. .Bd -literal -offset indent
  515. snac alias $SNAC_BASEDIR destination "@origin@mastodon.example.com"
  516. .Ed
  517. .Pp
  518. Check that no errors were shown. If they do, the origin Mastodon server may be
  519. busy or down; try again later.
  520. .Pp
  521. 4. Move back to the web interface of the origin Mastodon account, go to
  522. .Vt Preferences
  523. >
  524. .Vt Account
  525. >
  526. .Vt Move To A Different Account ,
  527. and follow the instructions there. Set the handle of the new account to your
  528. .Nm
  529. one; as of our example, @destination@snac.example.org. This will start the migration
  530. process: it's the duty of your old Mastodon instance to send an automatic
  531. .Vt Move
  532. message to every one of your followers. Eventually, you will start receiving follow notifications to your
  533. .Nm
  534. account from all accounts that followed the Mastodon one. According to the great document
  535. I linked above, this process may or may not start immediately, and its success may depend
  536. heavily on how all the servers involved behave. Just cross your fingers and hope for the best.
  537. .Pp
  538. .Ss Instance blocking
  539. Full instances can be blocked. This operation must be done from
  540. the command-line tool. See
  541. .Xr snac 1 .
  542. .Sh ENVIRONMENT
  543. .Bl -tag -width Ds
  544. .It Ev DEBUG
  545. Overrides the debugging level from the server 'dbglevel' configuration
  546. variable. Set it to an integer value. The higher, the deeper in meaningless
  547. verbiage you'll find yourself into.
  548. .El
  549. .Sh EXAMPLES
  550. You want to install the
  551. .Nm
  552. Fediverse daemon in the host example.com, that is correctly configured
  553. with a valid TLS certificate and running the nginx httpd server.
  554. The service will be installed under the
  555. .Pa fedi
  556. location. Two users, walter and jessie, will be hosted in the system.
  557. Their Fediverse presence addresses will be
  558. .Lk https://example.com/fedi/walter
  559. and
  560. .Lk https://example.com/fedi/jesse ,
  561. respectively. They will be known
  562. in the Fediverse as @walter@example.com and @jesse@example.com. The
  563. .Nm
  564. daemon will run as the user snacusr in the system and listen to the
  565. localhost:8001 network socket. All data will be stored in the
  566. .Pa /home/snacusr/fedidata
  567. directory.
  568. .Pp
  569. Log into the system as snacusr and execute:
  570. .Bd -literal -offset indent
  571. snac init /home/snacusr/fedidata
  572. .Ed
  573. .Pp
  574. Answer "example.com" to the host name question, "/fedi" to the path
  575. prefix question, "localhost" to the address and "8001" to the port.
  576. .Pp
  577. Create the users
  578. .Bd -literal -offset indent
  579. snac adduser /home/snacusr/fedidata walter
  580. snac adduser /home/snacusr/fedidata jesse
  581. .Ed
  582. .Pp
  583. Answer the questions with reasonable values.
  584. .Pp
  585. Execute the server:
  586. .Bd -literal -offset indent
  587. snac httpd /home/snacusr/fedidata
  588. .Ed
  589. .Pp
  590. Edit the nginx configuration and add the following snippet to the
  591. example.com server section:
  592. .Bd -literal -offset indent
  593. # nginx configuration example
  594. # main web access point
  595. location /fedi {
  596. proxy_pass http://localhost:8001;
  597. proxy_set_header Host $http_host;
  598. }
  599. # webfinger
  600. location /.well-known/webfinger {
  601. proxy_pass http://localhost:8001;
  602. proxy_set_header Host $http_host;
  603. }
  604. # Mastodon API (entry points)
  605. location /api/v1/ {
  606. proxy_pass http://localhost:8001;
  607. proxy_set_header Host $http_host;
  608. }
  609. location /api/v2/ {
  610. proxy_pass http://localhost:8001;
  611. proxy_set_header Host $http_host;
  612. }
  613. # Mastodon API (OAuth support)
  614. location /oauth {
  615. proxy_pass http://localhost:8001;
  616. proxy_set_header Host $http_host;
  617. }
  618. # optional
  619. location /.well-known/nodeinfo {
  620. proxy_pass http://localhost:8001;
  621. proxy_set_header Host $http_host;
  622. }
  623. # optional (needed by some Mastodon API clients)
  624. location /.well-known/host-meta {
  625. proxy_pass http://localhost:8001;
  626. proxy_set_header Host $http_host;
  627. }
  628. .Ed
  629. .Pp
  630. Restart the nginx daemon and connect to
  631. .Lk https://example.com/fedi/walter .
  632. The empty, default screen will be shown. Enter the admin section with the
  633. credentials defined for this user. Search people, start following
  634. them, engage in arid discussions and generally enjoy the frustrating
  635. experience of Social Media.
  636. .Pp
  637. This is an example of a similar configuration for the Apache2 web server:
  638. .Bd -literal -offset indent
  639. # apache2 configuration example
  640. ProxyPreserveHost On
  641. # Main web access point
  642. <Location /fedi>
  643. ProxyPass http://127.0.0.1:8001/social
  644. </Location>
  645. # WebFinger
  646. <Location /.well-known/webfinger>
  647. ProxyPass http://127.0.0.1:8001/.well-known/webfinger
  648. </Location>
  649. # Mastodon API (entry points)
  650. <Location /api/v1/>
  651. ProxyPass http://127.0.0.1:8001/api/v1/
  652. </Location>
  653. <Location /api/v2/>
  654. ProxyPass http://127.0.0.1:8001/api/v2/
  655. </Location>
  656. # Mastodon API (OAuth support)
  657. <Location /oauth>
  658. ProxyPass http://127.0.0.1:8001/oauth
  659. </Location>
  660. # NodeInfo (optional)
  661. <Location /.well-known/nodeinfo>
  662. ProxyPass http://127.0.0.1:8001/.well-known/nodeinfo
  663. </Location>
  664. # host-meta (optional, needed for some Mastodon API clients)
  665. <Location /.well-known/host-meta>
  666. ProxyPass http://127.0.0.1:8001/.well-known/host-meta
  667. </Location>
  668. .Ed
  669. .Pp
  670. Since version 2.43,
  671. .Nm
  672. supports communicating from / to the front end http server using the FastCGI
  673. protocol. There is no special advantage in using this, only that some servers
  674. allow for simpler configuration. For example, in the case of nginx, you can
  675. replace the two 'proxy_pass' and 'proxy_set_header' lines in the example
  676. above with just
  677. .Bd -literal -offset indent
  678. fastcgi_pass localhost:8001;
  679. .Ed
  680. .Pp
  681. The only thing to change on
  682. .Nm
  683. is to the set 'fastcgi' value to true in
  684. .Pa server.json .
  685. .Pp
  686. Further, using the FastCGI interface allows a much simpler configuration
  687. under OpenBSD's native httpd, given that it's natively implemented there
  688. and you no longer need to configure the complicated relayd server. This is
  689. an example:
  690. .Bd -literal -offset indent
  691. # OpenBSD httpd configuration example
  692. # other server configuration
  693. [...]
  694. location "/fedi/*" {
  695. fastcgi socket tcp "127.0.0.1" 8001
  696. }
  697. location "/.well-known/webfinger" {
  698. fastcgi socket tcp "127.0.0.1" 8001
  699. }
  700. location "/oauth/*" {
  701. fastcgi socket tcp "127.0.0.1" 8001
  702. }
  703. location "/api/v1/*" {
  704. fastcgi socket tcp "127.0.0.1" 8001
  705. }
  706. location "/api/v2/*" {
  707. fastcgi socket tcp "127.0.0.1" 8001
  708. }
  709. location "/.well-known/nodeinfo" {
  710. fastcgi socket tcp "127.0.0.1" 8001
  711. }
  712. location "/.well-known/host-meta" {
  713. fastcgi socket tcp "127.0.0.1" 8001
  714. }
  715. .Ed
  716. .Sh SEE ALSO
  717. .Xr snac 1 ,
  718. .Xr snac 5
  719. .Sh AUTHORS
  720. .An grunfink Lk https://comam.es/snac/grunfink @grunfink@comam.es
  721. .Sh LICENSE
  722. See the LICENSE file for details.
  723. .Sh CAVEATS
  724. JSON files are fragile when modified by hand. Take care.