feat: Manpage
This commit is contained in:
parent
146b2241f5
commit
ca9f8261bf
2 changed files with 344 additions and 0 deletions
183
feuille.1
Normal file
183
feuille.1
Normal file
|
|
@ -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.
|
||||||
|
<tom@heimdall.pm> 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. <tom@heimdall.pm>.
|
||||||
161
feuille.1.md
Normal file
161
feuille.1.md
Normal file
|
|
@ -0,0 +1,161 @@
|
||||||
|
% FEUILLE(1) feuille {VERSION}
|
||||||
|
% Tom MTT. <tom@heimdall.pm>
|
||||||
|
% 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. <tom@heimdall.pm>
|
||||||
|
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.
|
||||||
Reference in a new issue