gatling(8)

📦 version 0.16, in nixos 26.05, nixpkgs unstable

🌸 gatling(8) — high performance file server 🌸

okay bestie, this is the gatling(8) page from the System Manager's Manual, and it's literally about serving files to the world. Let's get into it 💖

✨ NAME ✨

gatling — high performance file server. It's giving main-character file-serving energy, no cap.

✨ SYNOPSIS ✨

gatling [-hHnvVtdDfFUlaEe] [-i bind-to-ip] [-p bind-to-port] [-T
seconds]
        [-u uid] [-c dir] [-w workgroup] [-P bytes] [-O
[f/]ip/port/regex]
        [-r redir-url] [-X timeout,sshd]

💅 DESCRIPTION 💅

gatling is a HTTP, FTP and SMB1 server. It will export the current working directory to the world. Vibe check your cwd before you run this, fr fr 🫶

🎀 the options, one by one 🎀

  • -i bind-to-ip — use this to bind only to a certain IP address. The page's example is -i 127.0.0.1.
  • -H — turn off HTTP. Bye HTTP 👋.
  • -S — turn off SMB1.
  • -p bind-to-port — bind HTTP to a different TCP port than 80; example: -p 81. Use -f -p 2100 to bind FTP to a different TCP port than 21. When running as non-root, the default ports are 8000 and 2121, respectively.
  • -u uid — run under a different UID than root; example: -u nobody. This is done after binding the server ports, so it is safe to use -u and still bind to port 80 — in fact, it is recommended not to run gatling as superuser. Use -u httpd,nobody to run gatling as user httpd, but run CGIs as user nobody (for example so a rogue CGI program cannot kill httpd, only itself and other CGI programs).

okay, UID lore time: when a user name is given (as opposed to a numeric UID), gatling will switch to that user and the default group for that user from /etc/passwd, but no supplementary groups from /etc/group. When a UID is given, gatling will only switch the UID, not the GID; but you can use UID.GID or UID:GID to also specify a GID. slay ✨

  • -c dir — chdir and chroot to another directory than the current working directory; example: -c /home/www. It is recommended to run gatling in a chroot environment to lessen the impact of possible future security problems.
  • -P bytes — activate prefetching mode; example: -P 2M. Gatling will then make sure this much data is prefetched. This can reduce disk activity and improve throughput dramatically if your OS I/O scheduler is not state of the art and you are serving several large files from the same hard disk to different downloaders. Without prefetching, the disk will otherwise waste time moving the disk head between the two large files.
  • -f — enable anonymous FTP. This is the default.
  • -F — disable anonymous FTP.
  • -U — disable uploads altogether. Normally gatling will allow file uploads.
  • -a — use this if you want uploaded files to be world readable. Otherwise they will not be world readable.

Gatling only allows uploads to world writable directories to prevent accidental upload permission, and the files will not be world readable (use -a if you want them world readable). Gatling will only allow downloads of world readable files, that's why this switch is important. These options are only available if gatling is compiled with SUPPORT_FTP defined.

  • -e — enable encryption support (https).
  • -E — disable encryption support (https).

These options are only available if gatling is compiled with SUPPORT_HTTPS defined.

  • -l — make gatling always ask for FTP passwords. Normally gatling does not, which confuses some stupid clients. This option makes gatling ask for (and ignore) a password.
  • -d — enable directory index generation for HTTP. Listing directories is always possible in FTP.
  • -D — disable directory index generation for HTTP.

It is harder to accidentally publish a document if the attacker can not find out the file name through directory listings.

  • -t — enable transparent proxy mode. Normally, gatling will replace the port in Host: HTTP headers and FTP virtual host names with the actual port the connection arrived at. This is important for security (in case you have a secret intranet web site on port 81, which is blocked at the firewall). However, when using a firewall to redirect connections to gatling, it may make more sense to keep the ports from the HTTP Host: headers for virtual hosting.
  • -v — enable virtual hosting mode.
  • -V — disable virtual hosting mode.

Normally, when a HTTP connection asks for /foo.html and carries a "Host: www.fefe.de:80" header, gatling will chdir to "www.fefe.de:80". If "www.fefe.de:80" does not exist, gatling will chdir to "default". If this also does not exist, and neither -v or -V are given, gatling will serve "foo.html" from the current working directory. Specifying -v will make sure that no file is ever served from the current working directory, only from the virtual host directories or from default. Specifying -V means that gatling will not try to chdir at all and always serve from the current working directory.

  • -T seconds — use -T 600 to set the timeout for HTTP and FTP data connections to 10 minutes (600 seconds, default is 23 seconds). Use -f -T 600 to set the timeout for FTP control connections (default is 600 seconds).
  • -r redir-url — if you use -r http://master.example.com/ on mirror.example.com, and someone asks for a file that does not exist, gatling will not create a 404 error but a redirect to the same file on master.example.com.
  • -X timeout,sshd — enable SSH passthrough mode. If someone connects on the SSL socket, but does not say anything for timeout (sane value: 2-10) seconds, then gatling will run an sshd in inetd mode with that socket. sshd is the full path name to sshd, plus the command line you want to give it, if any. gatling automatically appends -i, so use this for example for -u0 to disable DNS lookups.
  • -O [flag/]ip/port/regex — enable proxy mode, also used for SCGI and FastCGI. To use the proxy mode, there has to be a .proxy file in the root of the virtual host it is meant for. Specify ip and port to point to your app server, and give a regex to match the URI. Note: the regex needs to match the full file name, so use the extension for matching. If no flags are given, HTTP proxying is used. Otherwise, flags specifies the proxying mode: Use S for SCGI and F for FastCGI mode. See README.php for an example.
  • Unix Domain socket syntax — it is also possible to specify a Unix Domain socket, using the syntax --O [flag/]|filename|regex. Remember to put the argument in quotes when typing it in the shell.

🫶 synopsis-only flags, no invented lore 🫶

  • -h — appears in the synopsis; the page does not explain it further.
  • -n — appears in the synopsis; the page does not explain it further.
  • -w workgroup — appears in the synopsis; the page does not explain it further.
💀 real talk: I'm not gonna make up behavior for those, periodt.

🚨 SIGNALS 🚨

Sending gatling SIGHUP will make it close all the server sockets (so you can start a new gatling process with different options on the same ports). The old gatling process will continue serving the established connections until they are all finished.

👑 AUTHOR 👑

Initially written by Felix von Leitner <felix-gatling@fefe.de>.

📜 LICENSE 📜

GPLv2 (see http://www.gnu.org/copyleft/gpl.html) with an exception to allow linking against openssl.

that's the whole gatling(8) page from the <strong>System Manager's Manual</strong> — this copy didn't give a separate version or date, so here's your cute sign-off instead 💖🎀🦋 mwah 💅

📦 where this page comes from