2022-06-26 04:43:20 +00:00
# Dufs
2022-05-26 12:08:11 +00:00
2022-06-19 14:53:51 +00:00
[![CI ](https://github.com/sigoden/dufs/actions/workflows/ci.yaml/badge.svg )](https://github.com/sigoden/dufs/actions/workflows/ci.yaml)
[![Crates ](https://img.shields.io/crates/v/dufs.svg )](https://crates.io/crates/dufs)
2022-05-26 12:08:11 +00:00
2022-06-20 11:40:09 +00:00
Dufs is a distinctive utility file server that supports static serving, uploading, searching, accessing control, webdav...
2022-05-26 12:08:11 +00:00
2022-09-09 13:37:07 +00:00
![demo ](https://user-images.githubusercontent.com/4012553/189362357-b2f7aa6b-9df0-4438-a57c-c8f92850fc4f.png )
2022-05-26 12:08:11 +00:00
## Features
- Serve static files
2022-05-28 10:58:43 +00:00
- Download folder as zip file
2022-06-02 01:06:56 +00:00
- Upload files and folders (Drag & Drop)
2022-06-04 11:08:18 +00:00
- Search files
2022-06-02 22:51:50 +00:00
- Partial responses (Parallel/Resume download)
2022-06-19 03:26:03 +00:00
- Path level access control
2022-06-04 05:01:17 +00:00
- Support https
2022-06-04 04:51:56 +00:00
- Support webdav
2022-05-26 12:53:05 +00:00
- Easy to use with curl
2022-05-26 12:08:11 +00:00
## Install
### With cargo
```
2022-06-19 14:53:51 +00:00
cargo install dufs
2022-05-26 12:08:11 +00:00
```
2022-06-03 03:18:46 +00:00
### With docker
```
2022-07-08 14:36:16 +00:00
docker run -v `pwd` :/data -p 5000:5000 --rm -it sigoden/dufs /data -A
2022-06-03 03:18:46 +00:00
```
2022-05-26 12:08:11 +00:00
### Binaries on macOS, Linux, Windows
2022-06-19 14:53:51 +00:00
Download from [Github Releases ](https://github.com/sigoden/dufs/releases ), unzip and add dufs to your $PATH.
2022-05-26 12:08:11 +00:00
2022-06-02 22:51:50 +00:00
## CLI
```
2022-06-20 11:40:09 +00:00
Dufs is a distinctive utility file server - https://github.com/sigoden/dufs
2022-06-02 22:51:50 +00:00
USAGE:
2022-09-05 02:30:45 +00:00
dufs [OPTIONS] [--] [root]
2022-06-02 22:51:50 +00:00
ARGS:
2022-09-05 02:30:45 +00:00
< root > Specific path to serve [default: .]
2022-06-02 22:51:50 +00:00
OPTIONS:
2022-06-20 07:11:39 +00:00
-b, --bind < addr > ... Specify bind address
-p, --port < port > Specify port to listen on [default: 5000]
2022-07-07 07:44:25 +00:00
--path-prefix < path > Specify a path prefix
2022-09-09 13:30:27 +00:00
--hidden < value > Hide paths from directory listings, separated by `,`
2022-06-20 07:11:39 +00:00
-a, --auth < rule > ... Add auth for path
2022-06-20 11:40:09 +00:00
--auth-method < value > Select auth method [default: digest] [possible values: basic, digest]
2022-06-20 07:11:39 +00:00
-A, --allow-all Allow all operations
--allow-upload Allow upload files/folders
--allow-delete Allow delete files/folders
2022-06-20 23:23:20 +00:00
--allow-search Allow search files/folders
2022-06-20 07:11:39 +00:00
--allow-symlink Allow symlink to files/folders outside root directory
--enable-cors Enable CORS, sets `Access-Control-Allow-Origin: *`
2022-06-20 11:40:09 +00:00
--render-index Serve index.html when requesting a directory, returns 404 if not found index.html
2022-06-25 00:15:16 +00:00
--render-try-index Serve index.html when requesting a directory, returns directory listing if not found index.html
2022-06-20 11:40:09 +00:00
--render-spa Serve SPA(Single Page Application)
2022-09-05 02:30:45 +00:00
--assets < path > Use custom assets to override builtin assets
2022-06-20 07:11:39 +00:00
--tls-cert < path > Path to an SSL/TLS certificate to serve with HTTPS
--tls-key < path > Path to the SSL/TLS certificate's private key
2022-07-31 00:27:09 +00:00
--log-format < format > Customize http log format
--completions < shell > Print shell completion script for < shell > [possible values: bash, elvish, fish, powershell, zsh]
2022-06-20 07:11:39 +00:00
-h, --help Print help information
-V, --version Print version information
2022-06-02 22:51:50 +00:00
```
## Examples
2022-05-26 12:08:11 +00:00
2022-06-20 11:40:09 +00:00
Serve current working directory
2022-05-26 12:08:11 +00:00
```
2022-06-19 14:53:51 +00:00
dufs
2022-05-26 12:08:11 +00:00
```
2022-07-08 14:36:16 +00:00
Allow all operations like upload/delete/search...
2022-05-26 12:08:11 +00:00
```
2022-06-19 14:53:51 +00:00
dufs -A
2022-05-26 12:08:11 +00:00
```
2022-06-20 11:40:09 +00:00
Only allow upload operation
2022-06-02 01:06:56 +00:00
2022-06-17 02:59:19 +00:00
```
2022-06-20 11:40:09 +00:00
dufs --allow-upload
```
2022-07-01 13:37:56 +00:00
Serve a specific directory
2022-06-20 11:40:09 +00:00
```
dufs Downloads
```
2022-07-08 14:36:16 +00:00
Serve a single file
2022-06-20 11:40:09 +00:00
```
dufs linux-distro.iso
2022-05-31 00:38:30 +00:00
```
2022-07-08 14:36:16 +00:00
Serve a single-page application like react/vue
2022-06-20 11:40:09 +00:00
```
2022-07-08 14:36:16 +00:00
dufs --render-spa
2022-06-20 11:40:09 +00:00
```
2022-07-08 14:36:16 +00:00
Serve a static website with index.html
2022-05-31 00:38:30 +00:00
```
2022-07-08 14:36:16 +00:00
dufs --render-index
2022-05-31 00:38:30 +00:00
```
2022-05-26 12:08:11 +00:00
2022-06-20 11:40:09 +00:00
Require username/password
```
dufs -a /@admin:123
```
Listen on a specific port
```
dufs -p 80
```
2022-06-03 03:18:46 +00:00
Use https
2022-06-02 03:06:41 +00:00
```
2022-06-19 14:53:51 +00:00
dufs --tls-cert my.crt --tls-key my.key
2022-06-02 03:06:41 +00:00
```
2022-06-02 09:10:15 +00:00
## API
2022-05-26 12:53:05 +00:00
2022-07-08 14:36:16 +00:00
Upload a file
```
curl -T path-to-file http://127.0.0.1:5000/new-path/path-to-file
```
2022-05-26 12:53:05 +00:00
Download a file
```
2022-06-19 03:26:03 +00:00
curl http://127.0.0.1:5000/path-to-file
2022-05-26 12:53:05 +00:00
```
2022-05-28 10:58:43 +00:00
Download a folder as zip file
2022-05-28 11:03:50 +00:00
```
2022-06-19 03:26:03 +00:00
curl -o path-to-folder.zip http://127.0.0.1:5000/path-to-folder?zip
2022-05-28 11:03:50 +00:00
```
2022-05-28 10:58:43 +00:00
2022-05-26 12:53:05 +00:00
Delete a file/folder
2022-05-26 12:08:11 +00:00
```
2022-07-08 14:36:16 +00:00
curl -X DELETE http://127.0.0.1:5000/path-to-file-or-folder
2022-05-26 12:08:11 +00:00
```
2022-08-01 07:12:25 +00:00
< details >
2022-08-16 23:41:02 +00:00
< summary > < h2 > Advanced topics< / h2 > < / summary >
2022-08-01 07:12:25 +00:00
2022-08-01 23:07:53 +00:00
### Access Control
2022-06-19 07:30:42 +00:00
2022-06-20 23:52:45 +00:00
Dufs supports path level access control. You can control who can do what on which path with `--auth` /`-a`.
2022-06-19 03:26:03 +00:00
```
2022-08-06 00:30:19 +00:00
dufs -a < path > @< readwrite >
dufs -a < path > @< readwrite > @< readonly >
dufs -a < path > @< readwrite > @*
2022-06-19 03:26:03 +00:00
```
2022-06-25 01:57:58 +00:00
- `<path>` : Protected url path
2022-08-06 00:30:19 +00:00
- `<readwrite>` : Account with readwrite permissions. If dufs is run with `dufs --allow-all` , the permissions are upload/delete/search/view/download. If dufs is run with `dufs --allow-upload` , the permissions are upload/view/download.
- `<readonly>` : Account with readonly permissions. The permissions are search/view/download if dufs allow search, otherwise view/download..
2022-06-19 03:26:03 +00:00
2022-08-06 00:30:19 +00:00
```
dufs -A -a /@admin:admin
```
`admin` has all permissions for all paths.
2022-06-19 03:26:03 +00:00
2022-08-06 00:30:19 +00:00
```
dufs -A -a /@admin:admin@guest:guest
```
`guest` has readonly permissions for all paths.
```
dufs -A -a /@admin:admin@*
```
All paths is public, everyone can view/download it.
2022-06-19 03:26:03 +00:00
```
2022-08-06 00:30:19 +00:00
dufs -A -a /@admin:admin -a /user1@user1:pass1 -a /user2@pass2:user2
2022-06-19 03:26:03 +00:00
```
2022-08-06 00:30:19 +00:00
`user1` has all permissions for `/user1*` path.
`user2` has all permissions for `/user2*` path.
2022-06-19 03:26:03 +00:00
2022-08-06 00:30:19 +00:00
```
dufs -a /@admin:admin
```
Since dufs only allows viewing/downloading, `admin` can only view/download files.
2022-07-31 00:27:09 +00:00
2022-08-06 00:30:19 +00:00
### Hide Paths
2022-08-01 07:12:25 +00:00
2022-08-03 00:58:52 +00:00
Dufs supports hiding paths from directory listings via option `--hidden` .
2022-07-31 00:27:09 +00:00
2022-08-01 07:12:25 +00:00
```
2022-08-06 00:30:19 +00:00
dufs --hidden .git,.DS_Store,tmp
2022-08-01 07:12:25 +00:00
```
2022-07-31 00:27:09 +00:00
2022-08-06 00:30:19 +00:00
`--hidden` also supports a variant glob:
2022-07-31 00:27:09 +00:00
2022-08-01 07:12:25 +00:00
- `?` matches any single character
- `*` matches any (possibly empty) sequence of characters
2022-08-06 00:30:19 +00:00
- `**` , `[..]` , `[!..]` is not supported
2022-08-01 07:12:25 +00:00
2022-08-06 00:30:19 +00:00
```sh
2022-08-01 07:12:25 +00:00
dufs --hidden '.*'
2022-08-06 00:30:19 +00:00
dufs --hidden '*.log,*.lock'
2022-08-01 07:12:25 +00:00
```
2022-08-01 23:07:53 +00:00
### Log Format
2022-08-01 07:12:25 +00:00
2022-08-06 00:30:19 +00:00
Dufs supports customize http log format with option `--log-format` .
2022-08-01 07:12:25 +00:00
2022-08-06 00:30:19 +00:00
The log format can use following variables.
2022-08-01 07:12:25 +00:00
| variable | description |
2022-07-31 00:27:09 +00:00
| ------------ | ------------------------------------------------------------------------- |
| $remote_addr | client address |
| $remote_user | user name supplied with authentication |
| $request | full original request line |
| $status | response status |
| $http_ | arbitrary request header field. examples: $http_user_agent, $http_referer |
2022-08-06 00:30:19 +00:00
The default log format is `'$remote_addr "$request" $status'` .
```
2022-08-06T06:59:31+08:00 INFO - 127.0.0.1 "GET /" 200
```
Disable http log
```
dufs --log-format=''
```
Log user-agent
```
dufs --log-format '$remote_addr "$request" $status $http_user_agent'
```
```
2022-08-06T06:53:55+08:00 INFO - 127.0.0.1 "GET /" 200 Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36
```
Log remote-user
```
dufs --log-format '$remote_addr $remote_user "$request" $status' -a /@admin:admin -a /folder1@user1:pass1
```
```
2022-08-06T07:04:37+08:00 INFO - 127.0.0.1 admin "GET /" 200
```
2022-08-01 07:12:25 +00:00
2022-09-05 02:30:45 +00:00
### Customize UI
2022-09-09 13:43:40 +00:00
Dufs allows users to customize the UI with your own assets.
2022-09-05 02:30:45 +00:00
```
2022-09-09 13:37:07 +00:00
dufs --assets my-assets-dir/
2022-09-05 02:30:45 +00:00
```
2022-09-09 13:43:40 +00:00
Your assets folder must contains a `index.html` file.
2022-09-05 02:30:45 +00:00
2022-09-09 13:43:40 +00:00
`index.html` can use the following placeholder variables to retrieve internal data.
2022-09-05 02:30:45 +00:00
- `__INDEX_DATA__` : directory listing data
- `__ASSERTS_PREFIX__` : assets url prefix
2022-09-05 02:34:18 +00:00
< / details >
2022-05-26 12:08:11 +00:00
## License
2022-06-19 14:53:51 +00:00
Copyright (c) 2022 dufs-developers.
2022-05-26 12:08:11 +00:00
2022-06-19 14:53:51 +00:00
dufs is made available under the terms of either the MIT License or the Apache License 2.0, at your option.
2022-05-26 12:08:11 +00:00
2022-08-16 23:41:02 +00:00
See the LICENSE-APACHE and LICENSE-MIT files for license details.