README.md
1<p align="center">
2 <img src="data/logo.svg" alt="miniserve - a CLI tool to serve files and dirs over HTTP"><br>
3</p>
4
5# miniserve - a CLI tool to serve files and dirs over HTTP
6
7[](https://github.com/svenstaro/miniserve/actions)
8[](https://cloud.docker.com/repository/docker/svenstaro/miniserve/)
9[](https://crates.io/crates/miniserve)
10[](https://github.com/svenstaro/miniserve/blob/master/LICENSE)
11[](https://github.com/svenstaro/miniserve/stargazers)
12[](https://github.com/svenstaro/miniserve/releases)
13[](https://github.com/svenstaro/miniserve)
14
15**For when you really just want to serve some files over HTTP right now!**
16
17**miniserve** is a small, self-contained cross-platform CLI tool that allows you to just grab the binary and serve some file(s) via HTTP.
18Sometimes this is just a more practical and quick way than doing things properly.
19
20## Screenshot
21
22
23
24## How to use
25
26### Serve a directory:
27
28 miniserve linux-distro-collection/
29
30### Serve a single file:
31
32 miniserve linux-distro.iso
33
34### Require username/password:
35
36 miniserve --auth joe:123 unreleased-linux-distros/
37
38### Require username/password as hash:
39
40 pw=$(echo -n "123" | sha256sum | cut -f 1 -d ' ')
41 miniserve --auth joe:sha256:$pw unreleased-linux-distros/
42
43### Generate random 6-hexdigit URL:
44
45 miniserve -i 192.168.0.1 --random-route /tmp
46 # Serving path /private/tmp at http://192.168.0.1/c789b6
47
48### Bind to multiple interfaces:
49
50 miniserve -i 192.168.0.1 -i 10.13.37.10 -i ::1 /tmp/myshare
51
52### Start with TLS:
53
54 miniserve --tls-cert my.cert --tls-key my.key /tmp/myshare
55
56### Upload a file using `curl`:
57
58 # in one terminal
59 miniserve -u .
60 # in another terminal
61 curl -F "path=@$FILE" http://localhost:8080/upload\?path\=/
62
63(where `$FILE` is the path to the file. This uses miniserve's default port of 8080)
64
65## Features
66
67- Easy to use
68- Just works: Correct MIME types handling out of the box
69- Single binary drop-in with no extra dependencies required
70- Authentication support with username and password (and hashed password)
71- Mega fast and highly parallel (thanks to [Rust](https://www.rust-lang.org/) and [Actix](https://actix.rs/))
72- Folder download (compressed on the fly as `.tar.gz` or `.zip`)
73- File uploading
74- Pretty themes (with light and dark theme support)
75- Scan QR code for quick access
76- Shell completions
77- Sane and secure defaults
78- TLS (for supported architectures)
79
80## Usage
81
82 miniserve 0.18.0
83
84 Sven-Hendrik Haase <svenstaro@gmail.com>, Boastful Squirrel <boastful.squirrel@gmail.com>
85
86 For when you really just want to serve some files over HTTP right now!
87
88 USAGE:
89 miniserve [FLAGS] [OPTIONS] [--] [PATH]
90
91 ARGS:
92 <PATH>
93 Which path to serve
94
95 FLAGS:
96 -D, --dirs-first
97 List directories first
98
99 -F, --hide-version-footer
100 Hide version footer
101
102 -g, --enable-tar-gz
103 Enable gz-compressed tar archive generation
104
105 -h, --help
106 Print help information
107
108 -H, --hidden
109 Show hidden files
110
111 -o, --overwrite-files
112 Enable overriding existing files during file upload
113
114 -P, --no-symlinks
115 Do not follow symbolic links
116
117 -q, --qrcode
118 Enable QR code display
119
120 -r, --enable-tar
121 Enable uncompressed tar archive generation
122
123 --random-route
124 Generate a random 6-hexdigit route
125
126 -u, --upload-files
127 Enable file uploading
128
129 -v, --verbose
130 Be verbose, includes emitting access logs
131
132 -V, --version
133 Print version information
134
135 -W, --show-wget-footer
136 If enabled, display a wget command to recursively download the current directory
137
138 -z, --enable-zip
139 Enable zip archive generation
140
141 WARNING: Zipping large directories can result in out-of-memory exception because zip
142 generation is done in memory and cannot be sent on the fly
143
144 OPTIONS:
145 -a, --auth <AUTH>...
146 Set authentication. Currently supported formats: username:password,
147 username:sha256:hash, username:sha512:hash (e.g. joe:123,
148 joe:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3)
149
150 -c, --color-scheme <COLOR_SCHEME>
151 Default color scheme [default: squirrel] [possible values: squirrel, archlinux,
152 zenburn, monokai]
153
154 -d, --color-scheme-dark <COLOR_SCHEME_DARK>
155 Default color scheme [default: archlinux] [possible values: squirrel, archlinux,
156 zenburn, monokai]
157
158 --header <HEADER>...
159 Set custom header for responses
160
161 -i, --interfaces <INTERFACES>...
162 Interface to listen on
163
164 --index <index_file>
165 The name of a directory index file to serve, like "index.html"
166
167 Normally, when miniserve serves a directory, it creates a listing for that
168 directory. However, if a directory contains this file, miniserve will serve that
169 file instead.
170
171 -p, --port <PORT>
172 Port to use [default: 8080]
173
174 --print-completions <shell>
175 Generate completion file for a shell [possible values: bash, elvish, fish,
176 powershell, zsh]
177
178 -t, --title <TITLE>
179 Shown instead of host in page title and heading
180
181 --tls-cert <TLS_CERT>
182 TLS certificate to use
183
184 --tls-key <TLS_KEY>
185 TLS private key to use
186
187## How to install
188
189<a href="https://repology.org/project/miniserve/versions"><img align="right" src="https://repology.org/badge/vertical-allrepos/miniserve.svg" alt="Packaging status"></a>
190
191**On Linux**: Download `miniserve-linux` from [the releases page](https://github.com/svenstaro/miniserve/releases) and run
192
193 chmod +x miniserve-linux
194 ./miniserve-linux
195
196Alternatively, if you are on **Arch Linux**, you can do
197
198 pacman -S miniserve
199
200On [Termux](https://termux.com/)
201
202 pkg install miniserve
203
204**On OSX**: Download `miniserve-osx` from [the releases page](https://github.com/svenstaro/miniserve/releases) and run
205
206 chmod +x miniserve-osx
207 ./miniserve-osx
208
209Alternatively install with [Homebrew](https://brew.sh/).
210
211 brew install miniserve
212 miniserve
213
214**On Windows**: Download `miniserve-win.exe` from [the releases page](https://github.com/svenstaro/miniserve/releases) and run
215
216 miniserve-win.exe
217
218**With Cargo**: Make sure you have a recent version of Rust. Then you can run
219
220 cargo install miniserve
221 miniserve
222
223**With Docker:** If you prefer using Docker for this, run
224
225 docker run -v /tmp:/tmp -p 8080:8080 --rm -it svenstaro/miniserve /tmp
226
227## Shell completions
228
229If you'd like to make use of the built-in shell completion support, you need to run `miniserve
230--print-completions <your-shell>` and put the completions in the correct place for your shell. A
231few examples with common paths are provided below:
232
233 # For bash
234 miniserve --print-completions bash > ~/.local/share/bash-completion/completions/miniserve
235 # For zsh
236 miniserve --print-completions zsh > /usr/local/share/zsh/site-functions/_miniserve
237 # For fish
238 miniserve --print-completions fish > ~/.config/fish/completions/miniserve.fish
239
240## systemd
241
242A hardened systemd-compatible unit file can be found in `packaging/miniserve@.service`. You could
243install this to `/etc/systemd/system/miniserve@.service` and start and enable `miniserve` as a
244daemon on a specific serve path `/my/serve/path` like this:
245
246 systemctl enable --now miniserve@-my-serve-path
247
248Keep in mind that you'll have to use `systemd-escape` to properly escape a path for this usage.
249
250In case you want to customize the particular flags that miniserve launches with, you can use
251
252 systemctl edit miniserve@-my-serve-path
253
254and set the `[Service]` part in the resulting `override.conf` file. For instance:
255
256 [Service]
257 ExecStart=/usr/bin/miniserve --enable-tar --enable-zip --no-symlinks --verbose -i ::1 -p 1234 --title hello --color-scheme monokai --color-scheme-dark monokai -- %I
258
259Make sure to leave the `%I` at the very end in place or the wrong path might be served. You
260might additionally have to override `IPAddressAllow` and `IPAddressDeny` if you plan on making
261miniserve directly available on a public interface.
262
263## Binding behavior
264
265For convenience reasons, miniserve will try to bind on all interfaces by default (if no `-i` is provided).
266It will also do that if explicitly provided with `-i 0.0.0.0` or `-i ::`.
267In all of the aforementioned cases, it will bind on both IPv4 and IPv6.
268If provided with an explicit non-default interface, it will ONLY bind to that interface.
269You can provide `-i` multiple times to bind to multiple interfaces at the same time.
270
271## Why use this over alternatives?
272
273- darkhttpd: Not easily available on Windows and it's not as easy as download-and-go.
274- Python built-in webserver: Need to have Python installed, it's low performance, and also doesn't do correct MIME type handling in some cases.
275- netcat: Not as convenient to use and sending directories is [somewhat involved](https://nakkaya.com/2009/04/15/using-netcat-for-file-transfers/).
276
277## Releasing
278
279This is mostly a note for me on how to release this thing:
280
281- Make sure `CHANGELOG.md` is up to date.
282- `cargo release --dry-run <version>`
283- `cargo release <version>`
284- Releases will automatically be deployed by Github Actions.
285- Docker images will automatically be built by Docker Hub.
286- Update Arch package.
287
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
