diff --git a/feuille.1 b/feuille.1 new file mode 100644 index 0000000..7d7498f --- /dev/null +++ b/feuille.1 @@ -0,0 +1,183 @@ +.\" Automatically generated by Pandoc 2.17.1.1 +.\" +.\" Define V font for inline verbatim, using C font in formats +.\" that render this, and otherwise B font. +.ie "\f[CB]x\f[]"x" \{\ +. ftr V B +. ftr VI BI +. ftr VB B +. ftr VBI BI +.\} +.el \{\ +. ftr V CR +. ftr VI CI +. ftr VB CB +. ftr VBI CBI +.\} +.TH "FEUILLE" "1" "November 2022" "feuille 0.1.0" "" +.hy +.SH NAME +.PP +\f[B]feuille\f[R] - socket-based pastebin +.SH SYNOPSYS +.PP +\f[B]feuille\f[R] [-abfhiopstuUvVw] +.SH DESCRIPTION +.PP +\f[B]feuille\f[R] is a fast, dead-simple socket-based pastebin that +allows a user to send text, logs or code to your server. +It focuses on speed, code quality, and security. +.SH OPTIONS +.TP +\f[B]-a address\f[R] +Sets the address that \f[B]feuille\f[R] will listen on. +If set to \f[V]*\f[R], \f[B]feuille\f[R] will listen on the IPv6 address +\f[V]::\f[R] and enable dual-stack mode, which makes \f[B]feuille\f[R] +listen on both IPv4 and IPv6 addresses (won\[cq]t work on OpenBSD). +Default: \f[V]0.0.0.0\f[R] +.TP +\f[B]-b bytes\f[R] +Sets the buffer size (in bytes) used to receive data from a client. +A smaller buffer means more memory allocations and exchanges with the +connection, while a larger buffer induces less memory allocations but +more loss if not filled completely. +The difference is minimal, no need to worry about it. +Default: \f[V]131072\f[R]B (128KiB) +.TP +\f[B]-f\f[R] +Makes \f[B]feuille\f[R] run in the forground. +Default: runs in the background +.TP +\f[B]-h\f[R] +Displays **feuille*\[cq]s help page. +.TP +\f[B]-i length\f[R] +Sets the minimum ID length in characters. +If a paste with the same ID exists, the length will be increased (for +that paste only). +Default: \f[V]4\f[R] (Maximum: \f[V]254\f[R]) +.TP +\f[B]-p port\f[R] +Sets the port that \f[B]feuille\f[R] will listen on. +Default: \f[V]8888\f[R] +.TP +\f[B]-o path\f[R] +Sets the path where \f[B]feuille\f[R] will output the pastes (and +chroot, if possible). +Default: \f[V]/var/www/htdocs/feuille\f[R] +.TP +\f[B]-s bytes\f[R] +Sets the maximum size for every paste (in bytes). +Default: 2097152B (2MiB) +.TP +\f[B]-t seconds\f[R] +Sets the timeout for the client to send the paste (in seconds). +If set to zero, no timeout is set. +(Not recommended.) +Default: \f[V]4\f[R]s +.TP +\f[B]-u\f[R] +Sets the user that will be used when dropping root privileges. +\f[B]Warning\f[R]: requires root privileges. +Default: \f[V]www\f[R] +.TP +\f[B]-U\f[R] +Sets the base URL which will be prepended to the ID and sent to the +client. +You do not need to put a slash at the end. +Default: \f[V]https://my.paste.bin\f[R] +.TP +\f[B]-v\f[R] +Enables verbose mode. +.TP +\f[B]-V\f[R] +Displays \f[B]feuille\f[R]\[cq]s version and authors. +.TP +\f[B]-w\f[R] +Sets the number of processes that will be spawned to handle the +connections. +Those are \f[I]real\f[R] processes, not green / posix threads, you might +not want to set this to a huge number. +Default: the number of threads configured on your machine. +.SH EXAMPLES +.TP +\f[B]sudo feuille\f[R] +Runs feuille in the background, chrooting into +\f[V]/var/www/htdocs/feuille\f[R], dropping root privileges and spawning +worker processes to accept incoming connections. +.TP +\f[B]feuille -p 1337\f[R] +Runs feuille in the background \f[I]without\f[R] root privileges on port +\f[V]1337\f[R]. +\f[B]feuille\f[R] won\[cq]t be able to chroot or switch to another user, +and might not be able to write to the default output folder. +.TP +\f[B]feuille -P ./pastebins/\f[R] +Same as before, but this time with a different path: +\f[V]./pastebins/\f[R]. +If the folder doesn\[cq]t exist, it is created with the right +permissions. +.TP +\f[B]sudo feuille -U \[lq]https://bin.heimdall.pm\[rq]\f[R] +Runs feuille and sets the base address to +\f[V]https://bin.heimdall.pm\f[R]. +.TP +\f[B]sudo feuille -w 1\f[R] +Runs feuille \[lq]single-threaded\[rq]. +(Actually, there\[cq]s a main thread that does nothing and a thread that +does the actual work.) +.TP +\f[B]sudo feuille -fvP debug_pastes/\f[R] +Runs feuille in the foreground, with verbose mode enabled, and makes it +output its pastes to the \f[V]debug_pastes/\f[R] folder. +Useful for debugging purposes. +.TP +\f[B]sudo feuille -u nobody\f[R] +Runs feuille using the user \f[V]nobody\f[R], instead of user +\f[V]www\f[R]. +.TP +\f[B]sudo feuille -s 8388608\f[R] +Runs feuille with a maximum file size of 8388608 bytes (8MiB). +.TP +\f[B]sudo feuille -t 2\f[R] +Runs feuille with a timeout of 2 seconds. +.SH LOGS +.PP +By default, \f[B]feuille\f[R] runs in the background. +The logs should be located at \f[V]/var/log/messages\f[R], if using a +standard syslog daemon. +\f[B]feuille\f[R] doesn\[cq]t log much, be ready to use the verbose mode +for debugging purposes. +.SH EXIT VALUES +.TP +\f[B]0\f[R] +Success +.TP +\f[B]1\f[R] +Unspecified error +.TP +\f[B]34\f[R] +Specified number is out of range +.TP +\f[B]Other\f[R] +Error has been set by a C function +.SH BUGS +.PP +IPs aren\[cq]t logged. +It\[cq]s not a bug, it\[cq]s a feature. +.PP +Apart from that, none at the moment, as far as I know. +.SH COPYRIGHT +.PP +Copyright \[co] 2022 Tom MTT. + This program is free software, licensed under the +3-Clause BSD License. +See LICENSE for more information. +.SH APPENDICES +.PP +Heavily inspired by fiche (https://github.com/solusipse/fiche). +.PP +I entirely \[lq]rewrote\[rq] fiche from scratch because I wasn\[cq]t +happy with some of its features and its overall code quality. +.SH AUTHORS +Tom MTT. . diff --git a/feuille.1.md b/feuille.1.md new file mode 100644 index 0000000..4cf8019 --- /dev/null +++ b/feuille.1.md @@ -0,0 +1,161 @@ +% FEUILLE(1) feuille {VERSION} +% Tom MTT. +% November 2022 + +# NAME +**feuille** - socket-based pastebin + +# SYNOPSYS +**feuille** [-abfhiopstuUvVw] + +# DESCRIPTION +**feuille** is a fast, dead-simple socket-based pastebin that allows a +user to send text, logs or code to your server. It focuses on speed, +code quality, and security. + +# OPTIONS +**-a address** +: Sets the address that **feuille** will listen on. +: If set to `*`, **feuille** will listen on the IPv6 address `::` and +enable dual-stack mode, which makes **feuille** listen on both IPv4 +and IPv6 addresses (won't work on OpenBSD). +: Default: `0.0.0.0` + +**-b bytes** +: Sets the buffer size (in bytes) used to receive data from a client. +: A smaller buffer means more memory allocations and exchanges with + the connection, while a larger buffer induces less memory allocations + but more loss if not filled completely. +: The difference is minimal, no need to worry about it. +: Default: `131072`B (128KiB) + +**-f** +: Makes **feuille** run in the forground. +: Default: disabled + +**-h** +: Displays **feuille*'s help page. + +**-i length** +: Sets the minimum ID length in characters. +: If a paste with the same ID exists, the length will be increased +(for that paste only). +: Default: `4` (Maximum: `254`) + +**-p port** +: Sets the port that **feuille** will listen on. +: Default: `8888` + +**-o path** +: Sets the path where **feuille** will output the pastes (and chroot, +if possible). +: Default: `/var/www/htdocs/feuille` + +**-s bytes** +: Sets the maximum size for every paste (in bytes). +: Default: `2097152`B (2MiB) + +**-t seconds** +: Sets the timeout for the client to send the paste (in seconds). +: If set to zero, no timeout is set. (Not recommended.) +: Default: `4`s + +**-u** +: Sets the user that will be used when dropping root privileges. +: **Warning**: requires root privileges. +: Default: `www` + +**-U** +: Sets the base URL which will be prepended to the ID and sent to the +client. +: You do not need to put a slash at the end. +: Default: `http://localhost` + +**-v** +: Adds 1 to the verbose level. +: Default: `0` + +**-V** +: Displays **feuille**'s version and authors. + +**-w** +: Sets the number of processes that will be spawned to handle the +connections. +: Those are *real* processes, not green / posix threads, +you might not want to set this to a huge number. +: Default: the number of threads configured on your machine. + +# EXAMPLES + +**sudo feuille** +: Runs feuille in the background, chrooting into `/var/www/htdocs/feuille`, +dropping root privileges and spawning worker processes to accept +incoming connections. + +**feuille -p 1337** +: Runs feuille in the background *without* root privileges on port +`1337`. +: **feuille** won't be able to chroot or switch to another user, and +might not be able to write to the default output folder. + +**feuille -P ./pastebins/** +: Same as before, but this time with a different path: `./pastebins/`. +: If the folder doesn't exist, it is created with the right +permissions. + +**sudo feuille -U "https://bin.heimdall.pm"** +: Runs feuille and sets the base address to `https://bin.heimdall.pm`. + +**sudo feuille -w 1** +: Runs feuille "single-threaded". +: (Actually, there's a main thread that does nothing and a thread +that does the actual work.) + +**sudo feuille -fvP debug_pastes/** +: Runs feuille in the foreground, with verbose mode enabled, and +makes it output its pastes to the `debug_pastes/` folder. +: Useful for debugging purposes. + +**sudo feuille -u nobody** +: Runs feuille using the user `nobody`, instead of user `www`. + +**sudo feuille -s 8388608** +: Runs feuille with a maximum file size of 8388608 bytes (8MiB). + +**sudo feuille -t 2** +: Runs feuille with a timeout of 2 seconds. + +# LOGS +By default, **feuille** runs in the background. The logs should be +located at `/var/log/messages`, if using a standard syslog daemon. +**feuille** doesn't log much, be ready to use the verbose mode for +debugging purposes. + +# EXIT VALUES +**0** +: Success + +**1** +: Unspecified error + +**34** +: Specified number is out of range + +**Other** +: Error has been set by a C function + +# BUGS +IPs aren't logged. It's not a bug, it's a feature. + +Apart from that, none at the moment, as far as I know. + +# COPYRIGHT +Copyright © 2022 Tom MTT. +This program is free software, licensed under the 3-Clause BSD License. +See LICENSE for more information. + +# APPENDICES +Heavily inspired by [fiche](https://github.com/solusipse/fiche). + +I entirely "rewrote" fiche from scratch because I wasn't happy with +some of its features and its overall code quality.