HTTP(1)

📦 version 2.6.0, in arch rolling

🌸 NAME 🌸

http — from HTTP(1) in the General Commands Manual — is a basic HTTP server for hosting a folder fast and simply. That’s the whole vibe: folder in, HTTP out, no drama. 💅

✨ SYNOPSIS ✨

http [OPTIONS] [DIRECTORY]

💖 DESCRIPTION 💖

Okay so real talk: this is Host These Things Please — a basic HTTP server for hosting a folder fast and simply. The name is literally doing the most and I love it. 🫶

The idea is to make a program that can compile down to a simple binary that can be used via Linux CLI to quickly take the current directory and serve it over HTTP. Everything should have sensible defaults such that you do not have to pass parameters like what port to use. Lowkey the dream: you type the command, it serves, you move on with your life. ✨

💅 OPTIONS 💅

[DIR] — directory to host. It must exist. Default: current working directory. If you don’t pass one, she just serves where you’re standing. 📁
-p, --port [PORT] — port to host the server on. Must be between 1 and 65'535. A value of 0 will assign a random port, chosen by the OS. Default: first free port from 8000 up. So like, she’ll find a spot if you don’t pick one. 🔌
-a, --address [ADDRESS] — IP to bind the server to. Default: 0.0.0.0. Classic “listen everywhere” energy. 🌐
-t, --temp-dir [TEMP] — temporary directory to use to store data to write. Only matters if --allow-write is also specified or --no-encode is not. Default: $TEMP. Basically the scratch space for when writing or encoding is in the mix. 🗂️
--ssl [TLS_IDENTITY_FILE] — TLS identity file to use to encrypt as. The password is taken from the HTTP_SSL_PASS environment variable, or empty if that variable doesn’t exist. Default: None. Secure-channel era, but only if you hand her the identity file. 🔐
--gen-ssl — generate a single-use self-signed TLS certificate with openssl and use it for this session. The password for the certificate is the empty string, except on MacOS, where it’s "password", since the platform libssl refuses to import passwordless certificates. Exclusive with --ssl. Default: false. One-session wonder cert, no cap. 🧚
--auth [USERNAME[:PASSWORD]] — data for global authentication. Equivalent to --path-auth with a root path and the same credentials. This argument is deprecated, and will be replaced with the current version of --path-auth on the next breaking release. Use --path-auth in new designs to avoid surprises. Default: None. Old reliable, but she’s got a “deprecated” sticker on her forehead. 🏷️
--gen-auth — generate a one-off username:password set for global authentication. Functions as if --auth was specified with the generated credentials. This argument is deprecated, and will be replaced with the current version of --gen-path-auth on the next breaking release. Use --gen-path-auth in new designs to avoid surprises. Exclusive with --auth. Default: false. Cute one-time login moment, but again: deprecated. 💀
--path-auth [PATH=[USERNAME[:PASSWORD]]] — data for per-path authentication. The specified PATH will require the specified credentials to access. If credentials are unspecified, the path will have authentication disabled, even if global or parent paths have authentication specified. These can be arbitrarily nested. PATH is slash-normalised stripped of leading and trailing slashes. Specifying more than one of the same PATH is erroneous. Default: empty. This is the “locked door but only for this hallway” option. 🔑
--gen-path-auth [PATH] — generate a one-off username:password set for authentication under PATH. The username consists of 6-12 random alphanumeric characters, whereas the password consists of 10-25 random characters from most of the ASCII printable set. Functions as if --path-auth was specified with PATH and the generated credentials. Exclusive with --path-auth with the equivalent PATH. Default: empty. Random creds, generated fresh, very “new phone who dis.” 🎲
--proxy [HEADER-NAME:CIDR] — treat HEADER-NAME as a proxy forwarded-for header when the request originates from an address inside the network specified by the CIDR. If the header is set but the request isn’t in the network, it’s ignored. Can be specified any amount of times. Default: none. Trust the header only when the request comes from the right neighborhood. 🏘️
--proxy-redir [HEADER-NAME:CIDR] — treat HEADER-NAME as a proxy X-Original-URL header when the request originates from an address inside the network specified by the CIDR: this used only for 303 See Other Location: headers when redirecting due to an index file. Can be specified any amount of times. Default: none. Redirect-flavored proxy trust, specifically for that index-file redirect moment. 🔁
-m, --mime-type [EXTENSION:MIME-TYPE] — return MIME-TYPE for files with EXTENSION. If EXTENSION is the empty string, return that MIME-TYPE for files with no extension. The default MIME type is as returned by the mime_guess crate, if any, otherwise "application/octet-stream" for binary files or "text/plain". Can be specified any amount of times. Default: none. Custom MIME mapping, iykyk. 🎀
--request-bandwidth [BYTES] — limit the band for each request to BYTES/second wide. Can be suffixed with [KMGTPE] binary prefixes or [kmgtpe] SI prefixes. Zero disables capping. Default: 0. Throttle era, if you need it. 🐢
-H, --header [NAME: VALUE]... — add the specified headers to all responses. VALUE is left-trimmed. Header glow-up for every response. ✨
-s, --no-follow-symlinks — don’t follow symlinks when requesting file access. If a symlink is requested and this flag is on it will be treated as if it didn’t exist. No sneaky link-following. 🚫
-r, --sandbox-symlinks — restrict/sandbox where symlinks lead to only the direct descendants of the hosted directory. If a file outside the direct descendancy of the hosted directory requested and this flag is on it will be treated as if it didn’t exist. Symlinks stay in their lane, periodt. 🧱
-w, --allow-write — allow for write operations. Currently supported write operations: PUT and DELETE. With PUTs, the X-Last-Modified/X-OC-MTime headers can be specified to milliseconds/seconds since epoch, and this will be set on the file’s st_mtim. This is false by default because it’s most likely not something you want to do. Write access is giving “handle with care,” bestie. ⚠️
-D, --convenient-webdav — allow MKCOL (create directory) and MOVE (rename) WebDAV requests. These are accessible from the web UI. These are write requests so this is a no-op unless -w. False by default. Convenient little WebDAV shortcuts. 🗂️
-d, --webdav — handle WebDAV requests:
- MKCOL (create directory)
- MOVE (rename)
- PROPFIND (open in WebDAV client)
- COPY (copy files, directories)
- PROPPATCH (set file properties after PUT-uploading)

MKCOL and MOVE are accessible from the web UI, the rest enable mounting and file management via a WebDAV client. False by default. Supersedes -D. Full WebDAV mode activated. 🫶

-A, --archives — allow requesting tar and ZIP archives with

curl -H 'Accept: application/tar' ...

and by including a form in the generated indices.

This defines two APIs:

GET + Accept containing any of the following:
- application/tar application/x-tar => tar
- application/zip application/x-zip-compressed => ZIP
POST + sentinel values embedded into the generated index (POST is otherwise unsupported)

The results should be logically equivalent to "cd -L"ing to the requested path (subject to -s and -r), then "tar -c * .*" (so symbolic links are never followed, for example).

If a file or directory fails to open, it is skipped and does not abort archiving.

Files with st_nlink > 1 are detected and accrued for tar archives.

ZIPs only include regular files, directories, and symbolic links. Files that would be encoded if requesting them directly will be DEFLATEd (subject to -e).

If the requested path is a file, then a single-file archive is produced.

False by default. Archive girl summer. 🗜️

-l, --no-listings — do not generate directory listings. Here’s the behavior matrix of --no-listings with --no-indices:
- Path /has-index: Neither = index; -i = listing; -l = index; -l -i = 404
- Path /no-index: Neither = listing; -i = listing; -l = 404; -l -i = 404

This is false by default because it’s most likely for debugging purposes. Debug gremlin mode, but make it configurable. 🐛

-i, --no-indices — do not automatically serve the index file for directories containing one. This is false by default because it’s most likely for debugging purposes. When generating an index file, look for file README in the directory being indexed; if it exists, read it, and inject it at the given position (default bottom), in the given format (plain will be <pre>-wrapped). The last option in a group takes effect. Any amount of READMEs can be added, and are reproduced in the order given. The entire index, with all the files embedded, is stored in memory. README injection is lowkey iconic. 📝
-e, --no-encode — do not encode filesystem files. Encoded files are stored in the temp directory rather than being kept in memory. This is false by default because it’s useful for reducing bandwidth usage. No encoding, no extra temp storage, simple as. 🌸
--encoded-filesystem FS_LIMIT, --encoded-generated GEN_LIMIT — consume at most FS_LIMIT space for encoded filesystem files (in TEMP) and at most GEN_LIMIT memory for encoded generated responses. The arguments are an integer, optionally followed by case-insensitive k (kilobyte), m (megabyte), g (gigabyte), t (terabyte), or p (petabyte), optionally followed by case-insensitive b. This quota may be exceeded temporarily while servicing a request. Limits are limits-ish, but not always instant. 📏
--encoded-prune MAX_AGE — prune cached encoded data older than MAX_AGE. The argument is given in seconds, optionally followed by case-insensitive s (seconds), m (minutes), h (hours), or d (days). Cleanup era for old encoded cache. 🧹
-x, --strip-extensions — allow stripping index extensions from served paths: a request to /file might get served by /file.[s]htm[l]. This is false by default. Fancy path matching, only if you opt in. ✨
--404 FALLBACK-FILE — when returning a 404 response to a GET, send FALLBACK-FILE, instead of a generated error page, as the body. FALLBACK-FILE is a filesystem path and is not subject to -s/-r restrictions. Custom 404 body, because sometimes the error page needs a personality. 🫶
-q, --quiet... — suppress increasing amounts of output. Specifying this flag N times will, for:
- N == 0 – show all output
- N >= 1 – suppress serving status lines ("IP was served something")
- N >= 2 – suppress startup except for auth data, if present
- N >= 3 – suppress all startup messages

Quiet mode has layers, bestie. 🤫

-Q, --quiet-time — don’t prepend log lines with the timestamp. Clean logs, no clock. ⏰
-c, --no-colour — don’t colourise log output. Monochrome log vibe, if that’s your thing. 🖤

📝 NOTES 📝

Okay bestie, real talk about ETags. When this thing returns files from the filesystem, the ETag it sends back is based on the filesystem, the i-node, and the precise modification time.

So obviously, if you're serving files from filesystems with coarse timestamps (like FAT with its 1s-resolution), changes can be hidden from ETag-using user agents. The manual's example is: if a file was modified at 2023-02-12T01:00:00.100000000, a UA requested and cached a response for 2023-02-12T01:00:00.000000000, then the file was modified again at 2023-02-12T01:00:00.900000000, subsequent requests with If-None-Match: 2023-02-12T01:00:00.000000000 will all return 304 Not Modified.

This isn't really much of an issue, don't use FAT as a High-Performance File System (or reload w/o cache), and If-Modified-Since is affected with this by design, on all back-ends.

✨ EXAMPLES ✨

These are the reference examples, bestie. The first one is the baseline, and the rest are like "same vibe, but with a twist."

🌸 `http`

Host the current directory on the first free port upwards of 8000, don't follow symlinks, don't allow writes.

Example output:

p:\Rust\http> http
Hosting "." on port 8000 without TLS and no authentication...
Ctrl-C to stop.

127.0.0.1:47880 was served directory listing for \\?\P:\Rust\http
127.0.0.1:47902 was served file \\?\P:\Rust\http\http.1.html as text/html
127.0.0.1:47916 was served file S:\Rust-target\doc\main.css as text/css
127.0.0.1:48049 asked for OPTIONS
127.0.0.1:47936 used disabled request method DELETE
127.0.0.1:48222 used disabled request method PUT
^C

Assuming that P:\Rust\http\target is a symlink to S:\Rust-target, the following requests have been made, in order:

GET /
GET /http.1.html
GET /target/doc/main.css
OPTIONS
DELETE <path doesn't matter>
PUT <path doesn't matter>

The above output snippet is used as a reference for other examples.

💅 `http -s`

As in the first example, but don't follow symlinks.

Example output change:

127.0.0.1:47916 requested to GET nonexistent entity S:\Rust-target\doc\main.css

🔥 `http -w`

As in the first example, but allow writes.

Example output change:

127.0.0.1:47936 deleted file \\?\P:\Rust\http\http.1.html
127.0.0.1:48222 created \\?\P:\Rust\http\index.html, size: 1033554B

Corresponding request:

DELETE /http.1.html
PUT /index.html with request body containing roughly 1MB of data

Another behavioral change is that, in this case, the folder (and file) named T:/-=- TEMP -=-/http-P-Rust-http/writes/ and T:/-=- TEMP -=-/http-P-Rust-http/writes/index.html were created while the file P:\Rust\http\http.1.html was deleted (also works on directories).

🎀 `http -w -t "../TEMP"`

As in the previous example, but use a different temp dir.

Behavioral changes: the created folder and file are named P:/Rust/TEMP/http-P-Rust-http/writes/ and P:/Rust/TEMP/http-P-Rust-http/writes/index.html.

🍓 `http -p 6969`

As in the first example, but host on port 6969.

Assuming the port is free, example output change:

Hosting "." on port 6969 without TLS and no authentication...

If the port is taken, example output change:

Starting server failed: port taken.
<EOF>

🦋 `http -a 192.168.65.1`

As in the first example, but listen on address 192.168.65.1.

Assuming the address can be used, example output change:

Hosting "." on port 8000 under address 192.168.65.1 without TLS and no authentication...

If the address is inaccessible or doesn't exist, example output change:

Starting server failed: The requested address is not valid in its context.
(os error 10049).
<EOF>

🔐 `HTTP_SSL_PASS=pwd http --ssl cert/http8k.p12`

As in the first example, but encrypt with the identity file cert/http8k.p12 unlocked with password "pwd".

Assuming password is correct, example output change:

Hosting "." on port 8000 TLS certificate from "cert/http8k.p12"
and no authentication...

🧚 `http --gen-ssl`

As in the first example, but encrypt with a newly created self-signed identity file.

Example output change:

Hosting "." on port 8000 with TLS certificate from
"$TEMP/http-P-Rust-http/tls/tls.p12" and no authentication...

👑 `http --path-auth /=Pirate`

As in the first example, but require all clients to log in with the username "Pirate".

Example output change:

Hosting "." on port 8000 without TLS and basic authentication...
Basic authentication credentials:
Path  Username  Password
/     Pirate

On unauthed request:

127.0.0.1:15141 requested to GET http://127.0.0.1:8005/ without authorisation

Invalid credentials supplied:

127.0.0.1:15142 requested to GET http://127.0.0.1:8005/ with invalid credentials
"Pirate:memelord11"

Valid credentials supplied:

127.0.0.1:15142 correctly authorised to GET http://127.0.0.1:8005/
127.0.0.1:15142 was served directory listing for \\?\P:\Rust\http

🌈 `http --path-auth /=Pirate:memelord42`

As in the first example, but require all clients to log in with the username "Pirate" and password "memelord42".

Example output change:

Hosting "." on port 8000 without TLS and basic authentication...
Basic authentication credentials:
Path  Username  Password
/     Pirate    memelord42

See above for log messages when performing requests.

🫶 `http --gen-path-auth /`

As in the first example, but generate a username:password pair and require all clients to log in therewith.

Example output change:

Hosting "." on port 8000 without TLS and basic authentication...
Basic authentication credentials:
Path  Username  Password
/     jOvm8yCp  &gK=h&$-$HElLPb9HO%

See above for log messages when performing requests.

🛡️ multi-path auth (the long one)

This is the big one:

http --path-auth /=admin:admin --gen-path-auth /target/debug --path-auth
target/doc= --path-auth target/.rustc_info.json= --path-auth
target/release/=releases

As in the first example, but allow unauthenticated access to /target/doc and /target/.rustc_info.json, require username "releases" and no password to access /target/release, require a randomly-generated username:password pair to access /target/debug, and lock all other paths behind "admin:admin".

Example output change:

Hosting "." on port 8000 without TLS and basic authentication...
Basic authentication credentials:
Path                      Username  Password
/                         admin     admin
/target/.rustc_info.json
/target/debug             PYld448   l=Z~vdp,zAt^<uvRyU.T<F
/target/doc
/target/release           releases

See above for log messages when performing requests.

⭐ `http -r`

As in the first example, but restrict accessible paths to direct descendants of the hosted directory.

Example output change:

127.0.0.1:47916 requested to GET nonexistent entity S:\Rust-target\doc\main.css

💜 `http --proxy ...` and `http --proxy-redir ...`

The full command is:

http --proxy X-Forwarded-For:127.0.0.1 --proxy
X-Proxied-For:192.168.1.0/24 --proxy-redir X-Original-URL:127.0.0.1

As in the first example, but treat the X-Forwarded-For and X-Proxied-For as proxy headers for requests from localhost and the 192.168.1.0/24 network, respectively.

When redirecting, trust 127.0.0.1 to know how to redirect.

Given, that requests from 127.0.0.1, 192.168.1.109, and 93.184.216.34 have the following headers set:

X-Forwarded-For: OwO
X-Proxied-For: UwU
X-Original-URL: https://reversely.proxied/jpegs

Then the output will be as follows:

Hosting "." on port 8000 without TLS and no authentication...
Trusted proxies:
Header           Network
X-Forwarded-For  127.0.0.1
X-Proxied-For    192.168.1.0/24
Ctrl-C to stop.

[2020-02-17 17:48:41] 127.0.0.1:1392 for OwO was served directory listing for \\?\P:\Rust\http
[2020-02-17 17:49:12] 192.168.1.109:1403 for UwU was served directory listing for \\?\P:\Rust\http
[2020-02-17 17:49:29] 93.184.216.34:1397 was served directory listing for \\?\P:\Rust\http
[2020-02-17 17:48:41] Redirecting 127.0.0.1:1393 for OwO to https://reversely.proxied/jpegs/ - found index file index.html

🎨 `http --mime-type ...`

The command:

http --mime-type css:text/css;charset=utf-8 --mime-type :image/jpeg

As in the first example, but send .css with the charset=utf8 attribute and treat files with no extension as JPEGs.

Then the output will be as follows:

Hosting "." on port 8000 without TLS and no authentication...
Serving files with no extension as image/jpeg.
Serving files with .css extension as text/css; charset=utf-8.
Ctrl-C to stop.

[2020-07-20 12:32:24] 127.0.0.1:47916 was served file \\?\S:\Rust-target\doc\main.css as text/css; charset=utf-8
[2020-07-20 12:32:25] 127.0.0.1:2803 was served file \\?\P:\121D800E\http\DSC_6505 as image/jpeg

🚀 `http --request-bandwidth 4K`

As in the first example, but limit each request to 4096 bytes per second.

Example output change:

Hosting "." on port 8000 without TLS and no authentication...
Requests limited to 4096B/s.
Ctrl-C to stop.

👑 AUTHOR 👑

Written by thecoshman <rust@thecoshman.com>, nabijaczleweli <nabijaczleweli@nabijaczleweli.xyz>, pheki, Adrian Herath <adrianisuru@gmail.com>, cyqsimon, jim4067, Orhun Parmaksız <orhunparmaksiz@gmail.com>, Kian-Meng Ang <kianmeng@cpan.org>, Theodore Ni, and Thorbjørn Lindeijer <bjorn@lindeijer.nl>.

🐛 REPORTING BUGS 🐛

Bugs go here: <https://github.com/thecoshman/http/issues>.

🦋 SEE ALSO 🦋

Peep the project at <https://github.com/thecoshman/http>.

This iconic page is the HTTP(1) manpage from the http developers, dated July 2026. Byeee bestie 💅✨

📦 where this page comes from

arch rolling: httplz 2.6.0-1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

HTTP(1)

🌸 NAME 🌸

✨ SYNOPSIS ✨

💖 DESCRIPTION 💖

💅 OPTIONS 💅

📝 NOTES 📝

✨ EXAMPLES ✨

🌸 http

💅 http -s

🔥 http -w

🎀 http -w -t "../TEMP"

🍓 http -p 6969

🦋 http -a 192.168.65.1

🔐 HTTP_SSL_PASS=pwd http --ssl cert/http8k.p12

🧚 http --gen-ssl

👑 http --path-auth /=Pirate

🌈 http --path-auth /=Pirate:memelord42

🫶 http --gen-path-auth /

🛡️ multi-path auth (the long one)

⭐ http -r

💜 http --proxy ... and http --proxy-redir ...

🎨 http --mime-type ...

🚀 http --request-bandwidth 4K

👑 AUTHOR 👑

🐛 REPORTING BUGS 🐛

🦋 SEE ALSO 🦋

🌸 `http`

💅 `http -s`

🔥 `http -w`

🎀 `http -w -t "../TEMP"`

🍓 `http -p 6969`

🦋 `http -a 192.168.65.1`

🔐 `HTTP_SSL_PASS=pwd http --ssl cert/http8k.p12`

🧚 `http --gen-ssl`

👑 `http --path-auth /=Pirate`

🌈 `http --path-auth /=Pirate:memelord42`

🫶 `http --gen-path-auth /`

⭐ `http -r`

💜 `http --proxy ...` and `http --proxy-redir ...`

🎨 `http --mime-type ...`

🚀 `http --request-bandwidth 4K`