From 0742b805e2ac6667d5942c57c2d00b942a508db4 Mon Sep 17 00:00:00 2001 From: noury Date: Fri, 14 Jul 2023 14:21:25 +0200 Subject: [PATCH] preserve original README as README.original --- README.original | 128 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 README.original diff --git a/README.original b/README.original new file mode 100644 index 0000000..d8fbe69 --- /dev/null +++ b/README.original @@ -0,0 +1,128 @@ +# jaf - Just Another Fileshare +jaf is a simple Go program to handle file uploads. +If you also want to serve the uploaded files, consider a web server like [nginx](https://nginx.org/en/). + +## Installation +**Clone** the directory: +```bash +git clone https://github.com/leon-richardt/jaf.git +``` +**Build** the executable: +```bash +go build +``` +Run **tests** (optional): +```bash +go test +``` + +If you plan on using a systemd service or another init system, you might want to move the `jaf` executable to a different directory (e.g. `/opt`) at this point; you know your setup best. + +## Configuration +### jaf +There are just a few parameters that need to be configured for jaf. +Refer to the `example.conf` file: +``` +Port: 4711 +# a comment +LinkPrefix: https://jaf.example.com/ +FileDir: /var/www/jaf/ +LinkLength: 5 +ScrubExif: true +# Both IDs also refer to the "Orientation" tag, included for illustrative purposes only +ExifAllowedIds: 0x0112 274 +ExifAllowedPaths: IFD/Orientation +ExifAbortOnError: true +``` + +Option | Use +------------------ | ------------------------------------------------------------------- +`Port` | the port number jaf will listen on +`LinkPrefix` | a string that will be prepended to the file name generated by jaf +`FileDir` | path to the directory jaf will save uploaded files in +`LinkLength` | the number of characters the generated file name is allowed to have +`ScrubExif` | whether to remove EXIF tags from uploaded JPEG and PNG images (`true` or `false`) +`ExifAllowedIds` | a space-separated list of EXIF tag IDs that should be preserved through EXIF scrubbing (only relevant if `ScrubExif` is `true`) +`ExifAllowedPaths` | a space-separated list of EXIF tag paths that should be preserved through EXIF scrubbing (only relevant if `ScrubExif` is `true`) +`ExifAbortOnError` | whether to abort JPEG and PNG uploads if an error occurs during EXIF scrubbing (only relevant if `ScrubExif` is `true`) + + +Make sure the user running jaf has suitable permissions to read, and write to, `FileDir`. +Also note that `LinkLength` directly relates to the number of files that can be saved. +Since jaf only uses alphanumeric characters for file name generation, a maximum of `(26 + 26 + 10)^LinkLength` names can be generated. + +#### A Note on EXIF Scrubbing +EXIF scrubbing can be enabled via the `ScrubExif` config key. +When enabled, all standard EXIF tags are removed on uploaded JPEG and PNG images per default. +It is meant as a last-line "defense mechanism" against leaking PII, such as GPS information on pictures. +**If possible, you should always prefer disabling capturing potentially sensitive EXIF tags when creating the images!** + +Obviously, EXIF tags serve a purpose and you may want to keep _some_ of the information, e.g., image orientation. +The `ExifAllowedIds` and `ExifAllowedPaths` config keys can be used to selectively allow specific tags to survive the scrubbing. +The IDs for standard tags can be found in [1]. +You may specify tag IDs in decimal and hexadecimal notation. +(In the latter case, the ID _must_ start with `0x`.) + +The path specification for `ExifAllowedPaths` relies on the format implemented in [`go-exif`](https://github.com/dsoprea/go-exif) which is "documented" in machine-readable format in [2]. +Multiple paths can be specified, separated by a space. +The path format is as follows: + +1. For tags in the main section: `IFD//`. + Examples: `IFD/Orientation`, `IFD/Exif/Flash`, `IFD/GPSInfo/GPSTimeStamp`. + You will probably want to use both [1] and [2] in combination if you plan to specify allowed tags by path. + +2. Tags in the thumbnail section follow the same format but paths start with `IFD1/` instead of `IFD`. + +### nginx +If you use a reverse-proxy to forward requests to jaf, make sure to correctly forward the original request headers. +For nginx, this is achieved via the `proxy_pass_request_headers on;` option. + +If you want to limit access to jaf (e.g. require basic authentication), you will also need to do this via your reverse-proxy. + +## Running +After adjusting the configuration file to your needs, run: +```bash +jaf -configFile example.conf +``` +Of course, you can also write a init system script to handle this for you. + +### Running from Docker +Running it from the GitHub Container Registry +```bash +docker run \ + -p 4712:4711 \ + -v /path/to/your/config.conf:/app/jaf.conf \ + -v /path/to/local/filedir:/var/www/jaf \ + ghcr.io/leon-richardt/jaf:latest +``` + +Building the Docker image and running it locally +```bash +docker build -t jaf . +docker run \ + -p 4712:4711 \ + -v /path/to/your/config.conf:/app/jaf.conf \ + -v /path/to/local/filedir:/var/www/jaf \ + jaf +``` + +Port 4711 is the default port for the server in `example.conf`, if you've changed this in your config you'll need to change this in the `docker run` invocations above too. +The above runs forwards the jaf port from 4711 in the container to 4712 on your local system. + +## Usage +You can use jaf with any application that can send POST requests (e.g. ShareX/ShareNix or just `curl`). +Make sure the file you want to upload is attached as a `multipart/form-data` field named `file`. +In `curl`, a request to upload the file `/home/alice/foo.txt` could look like this: +```bash +curl -L -F "file=@/home/alice/foo.txt" jaf.example.com/upload +``` +The response will include a link to the newly uploaded content. +Note that you may have to add additional header fields to the request, e.g. if you have basic authentication enabled. + +## Inspiration +- [i](https://github.com/fourtf/i) by [fourtf](https://github.com/fourtf) – a project very similar in scope and size +- [filehost](https://github.com/nuuls/filehost) by [nuuls](https://github.com/nuuls) – a more integrated, fully-fledged solution that offers a web interface and also serves the files + + +[1]: https://exiv2.org/tags.html +[2]: https://github.com/dsoprea/go-exif/blob/a6301f85c82b0de82ceb8501f3c4a73ea7df01c2/assets/tags.yaml