tmtt/feuille
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

feat: README and LICENSE

Browse source
This commit is contained in:
Tom MTT. 2022-11-21 10:41:53 +01:00
commit 146b2241f5
2 changed files with 320 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
LICENSE Normal file
View file

@ -0,0 +1,29 @@
Copyright (c) 2022
Tom MTT. <tom@heimdall.pm>
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.

291
README.md Normal file
View file

@ -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.
<details>
<summary>Table of Contents</summary>
<ol>
<li><a href="#usage">Usage</a></li>
<li>
<a href="#installation">Installation</a>
<ul>
<li><a href="#dependencies">Dependencies</a></li>
<li><a href="#build">Build</a></li>
<li><a href="#configuration">Configuration</a></li>
</ul>
</li>
<li>
<a href="#help">Help</a>
<ul>
<li><a href="#how-do-i-make-feuille-run-at-startup">How do I make feuille run at startup?</a></li>
<li><a href="#how-do-i-remove-expired-pastes-after-some-time">How do I remove expired pastes after some time?</a></li>
<li><a href="#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)?</a></li>
</ul>
</li>
<li><a href="#authors">Authors</a></li>
<li><a href="#license">License</a></li>
<li><a href="#acknowledgments">Acknowledgments</a></li>
</ol>
</details>
## 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. <tom@heimdall.pm>
## License
Copyright © 2022 Tom MTT. <tom@heimdall.pm>
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.