From 146b2241f5852d40b1f3dafb4a1610a1c9173cf9 Mon Sep 17 00:00:00 2001 From: Tom MTT Date: Mon, 21 Nov 2022 10:41:53 +0100 Subject: [PATCH] feat: README and LICENSE --- LICENSE | 29 ++++++ README.md | 291 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 320 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..baf9dd0 --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +Copyright (c) 2022 + Tom MTT. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED +TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..601ba8c --- /dev/null +++ b/README.md @@ -0,0 +1,291 @@ +# feuille + +**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. + +
+ Table of Contents +
    +
  1. Usage
    2. +
  2. + Installation + +
    3. +
  3. + Help + +
    4. +
  4. Authors
    5. +
  5. License
    6. +
  6. Acknowledgments
    7. +
+
+ +## Usage + +You'll need either `nc` or nmap's `ncat`. + +The former is probably already available on your system, but lacks +some features, which will make you wait for the timeout before +getting a link to the paste (usually 4 seconds). + +The latter will have to be installed manually but is more featureful +and will get a link instantly once everything is sent. It works the +exact same way as `nc`. + +*Choose your weapon wisely.* + +Assuming you're using my personal pastebin instance, +[heimdall.pm](https://bin.heimdall.pm/), you can upload text, code or +logs like this: + +```console +// sending text +$ echo Hello, World! | nc heimdall.pm 8888 +https://bin.heimdall.pm/abcd + +// sending files +$ cat feuille.c | nc heimdall.pm 8888 +https://bin.heimdall.pm/efgh +``` + +*This truly is the joy of Unix pipes.* + +Once you received the link to your paste, you can send it to someone, +browse it or `curl` it, like this: + +```console +$ curl https://bin.heimdall.pm/abcd +Hello, World! + +$ curl https://bin.heimdall.pm/efgh +/* + * feuille.c + * Main source file. +... +``` + +Want to push the concept further? You can send encrypted files, too! +You'll need `gpg` for this. `-c` means encryption using a password, +`-ao tmp.pgp` means ASCII output to file `tmp.pgp`. + +```console +$ cat secret.txt | gpg -cao tmp.pgp +$ cat tmp.pgp | nc heimdall.pm 8888 +https://bin.heimdall.pm/ijkl +``` + +You can then retrieve it and decrypt it using `curl` and `gpg` again, +like this: + +```console +$ curl https://bin.heimdall.pm/ijkl | gpg -d +``` + +(Obviously, you'll have to type the right password.) + +But, all those commands are really cumbersome, aren't they? +Guess what? We made aliases! + +Put those into your `~/.{ba,z,k}shrc`: + +```sh +alias pst="$NC heimdall.pm 8888" +alias spst="gpg -cao tmp.pgp && cat tmp.pgp | $NC heimdall.pm 8888 && rm tmp.pgp" +``` + +Now, you can use **feuille** like this: + +```console +// plain +$ echo Hello, World! | pst +https://bin.heimdall.pm/mnop + +// encrypted +$ echo da sup3r sekr1t | spst +https://bin.heimdall.pm/qrst +``` + +For a complete list of aliases, see +[here](https://basedwa.re/tmtt/feuille/src/branch/main/misc/aliases) +and either put those in your `~/.{ba,z,k}shrc` or source it. + +That sould be it. Have fun! + +## Description + +* Focuses on speed, + * Multi-threaded (using `fork`) + * Only does what it needs to do + +* code quality, + * Readable, documented code + * With future contributors / maintainers in mind + +* and security + * `chroot`s in the output folder + * Drops root privileges once they're no longer needed + * Uses OS-specific security measures (like OpenBSD's `pledge`) + +* Plenty of auxiliary files (see +[misc/](https://basedwa.re/tmtt/feuille/src/branch/main/misc), +[cgi/](https://basedwa.re/tmtt/feuille/src/branch/main/cgi) and +[cron/](https://basedwa.re/tmtt/feuille/src/branch/main/cron)) + * A list of aliases for your users' `~/.{ba,z,k}shrc` + * A CGI script that lets the user send pastes directly from your + website + * A sample HTML form for your CGI script + * A cron job that deletes expired pastes + * A cron job that runs **feuille** at startup + +* Lots of options (see [configuration](#configuration)) +* Works on nearly all POSIX-compliant OSes +* Can be run in the background and as a service +* IPv6-enabled + +## Installation + +### Dependencies + +You'll need a working *POSIX-compliant system* such as Linux, OpenBSD +or FreeBSD, a C99 compiler (GCC, Clang...) and a POSIX-Make +implementation. + +You'll probably want an HTTP / Gopher / Gemini / ... server to serve +the pastes on the web, such as OpenBSD's httpd or Apache. Just make +your server serve the folder feuille's using, there are plenty of +tutorials on the web. + +If you wish to make modifications to the manpage, you'll need pandoc +to convert the markdown file into a man-compatible format. + +### Build + +**feuille** needs to be built from source. + +To do so, you'll first need to clone the repository. + +```console +$ git clone https://basedwa.re/tmtt/feuille +$ cd feuille +``` + +Then, simply run: + +```console +$ make +$ sudo make install +``` + +If you wish to make a debug build, you can set `DEBUG` to whatever +comes to your mind. + +You can also set `CC` to the compiler of your liking, like `clang` or +`pcc`. + +```console +$ make DEBUG=yes CC=clang +``` + +In order to compile CGI script(s), run: + +```console +$ make cgi +``` + +`ADDR` and `PORT` can be set to the address and port on which +**feuille** listens, respectively. + +### Configuration + +For a complete list of options and examples, please see the manpage, +either on your computer by doing `man feuille` or on the +[online wiki](https://basedwa.re/tmtt/feuille/wiki/Manpage). + +## Help + +* [How do I make feuille run at startup?](#how-do-i-make-feuille-run-at-startup) +* [How do I remove expired pastes after some time?](#how-do-i-remove-expired-pastes-after-some-time) +* [How can I send pastes directly from my website (instead of using netcat)?](#how-can-i-send-pastes-directly-from-my-website-instead-of-using-netcat) + +### How do I make feuille run at startup? + +You can put that in your crontab (by doing `sudo crontab -e`). +It will start **feuille** every time the system starts. +No need for some fancy service file :DDD + +Obviously, you can put some options after `feuille`, like `-o +/var/feuille` or `-v`. + +``` +@reboot feuille +``` + +See +[cron/startup.cron](https://basedwa.re/tmtt/feuille/src/branch/main/cron/startup.cron) +if you'd like to download the cron job. + +### How do I remove expired pastes after some time? + +You can put that in your crontab (by doing `sudo crontab -e`). +It will delete all files in `/var/www/htdocs/feuille` that are at least 7 +days old. + +Don't forget to change the folder to the one **feuille**'s using and +eventually `+7` to the maximum file age you'd like to use. + +``` +0 0 * * * find /var/www/htdocs/feuille -type f -mtime +7 -exec rm {} + +``` + +See +[cron/purge.cron](https://basedwa.re/tmtt/feuille/src/branch/main/cron/purge.cron) +if you'd like to download the cron job. + +### How can I send pastes directly from my website (instead of using netcat)? + +We made a CGI script for that. First, you need to build it: + +```console +$ make cgi +``` + +`ADDR` and `PORT` can be set to the address and port on which +**feuille** listens, respectively. + +Once it's done, you can put `./web/cgi/feuille.cgi` in your website's +`cgi-bin` folder (usually somewhere like +`/var/www/htdocs/my.paste.bin/cgi-bin`) and configure your web server +to execute CGI scripts. + +You can then create an HTML form that will send a POST request to the +CGI script. The form must have `enctype="text/plain"` and must contain +only one input or textarea. See +[web/cgi/form.html](https://basedwa.re/tmtt/feuille/src/branch/main/cgi/form.html) +for a sample form. + +## Authors + +Tom MTT. + +## License + +Copyright © 2022 Tom MTT. +This program is free software, licensed under the 3-Clause BSD License. +See LICENSE for more information. + +## Acknowledgments + +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.