dufs/README.md

417 lines
11 KiB
Markdown
Raw Normal View History

2022-06-26 04:43:20 +00:00
# Dufs
2022-05-26 12:08:11 +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
Dufs is a distinctive utility file server that supports static serving, uploading, searching, accessing control, webdav...
2022-05-26 12:08:11 +00:00
2023-02-22 03:26:17 +00:00
![demo](https://user-images.githubusercontent.com/4012553/220513063-ff0f186b-ac54-4682-9af4-47a9781dee0d.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)
2023-02-21 08:10:51 +00:00
- Create/Edit/Search files
2022-06-02 22:51:50 +00:00
- Partial responses (Parallel/Resume download)
2023-06-01 23:16:43 +00:00
- Access control
- 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
```
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
```
### With [Homebrew](https://brew.sh)
```
brew install dufs
```
2022-05-26 12:08:11 +00:00
### Binaries on macOS, Linux, Windows
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
```
Dufs is a distinctive utility file server - https://github.com/sigoden/dufs
2022-06-02 22:51:50 +00:00
Usage: dufs [OPTIONS] [serve-path]
2022-11-11 13:46:07 +00:00
Arguments:
[serve-path] Specific path to serve [default: .]
2022-11-11 13:46:07 +00:00
Options:
-c, --config <config> Specify configuration file
-b, --bind <addrs> Specify bind address or unix socket
-p, --port <port> Specify port to listen on [default: 5000]
--path-prefix <path> Specify a path prefix
--hidden <value> Hide paths from directory listings, e.g. tmp,*.log,*.lock
2023-11-03 13:08:05 +00:00
-a, --auth <rules> Add auth roles, e.g. user:pass@/dir1:rw,/dir2
-A, --allow-all Allow all operations
--allow-upload Allow upload files/folders
--allow-delete Allow delete files/folders
--allow-search Allow search files/folders
--allow-symlink Allow symlink to files/folders outside root directory
--allow-archive Allow zip archive generation
--enable-cors Enable CORS, sets `Access-Control-Allow-Origin: *`
--render-index Serve index.html when requesting a directory, returns 404 if not found index.html
--render-try-index Serve index.html when requesting a directory, returns directory listing if not found index.html
--render-spa Serve SPA(Single Page Application)
--assets <path> Set the path to the assets directory for overriding the built-in assets
--log-format <format> Customize http log format
--completions <shell> Print shell completion script for <shell> [possible values: bash, elvish, fish, powershell, zsh]
--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
2023-06-01 23:16:43 +00:00
-h, --help Print help
-V, --version Print version
2022-06-02 22:51:50 +00:00
```
## Examples
2022-05-26 12:08:11 +00:00
2023-02-22 03:26:17 +00:00
Serve current working directory in readonly mode
2022-05-26 12:08:11 +00:00
```
dufs
2022-05-26 12:08:11 +00:00
```
2023-02-22 03:26:17 +00:00
Allow all operations like upload/delete/search/create/edit...
2022-05-26 12:08:11 +00:00
```
dufs -A
2022-05-26 12:08:11 +00:00
```
Only allow upload operation
2022-06-02 01:06:56 +00:00
2022-06-17 02:59:19 +00:00
```
dufs --allow-upload
```
2022-07-01 13:37:56 +00:00
Serve a specific directory
```
dufs Downloads
```
2022-07-08 14:36:16 +00:00
Serve a single file
```
dufs linux-distro.iso
```
2022-07-08 14:36:16 +00:00
Serve a single-page application like react/vue
```
2022-07-08 14:36:16 +00:00
dufs --render-spa
```
2022-07-08 14:36:16 +00:00
Serve a static website with index.html
```
2022-07-08 14:36:16 +00:00
dufs --render-index
```
2022-05-26 12:08:11 +00:00
Require username/password
```
dufs -a admin:123@/:rw
```
2022-11-11 00:57:44 +00:00
Listen on specific host:ip
```
2022-11-11 00:57:44 +00:00
dufs -b 127.0.0.1 -p 80
```
Listen on unix socket
```
dufs -b /tmp/dufs.socket
```
2022-06-03 03:18:46 +00:00
Use https
2022-06-02 03:06:41 +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
```
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
```
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
```
2023-02-21 08:10:51 +00:00
Create a directory
```
2023-02-21 08:10:51 +00:00
curl -X MKCOL https://127.0.0.1:5000/path-to-folder
```
2023-02-21 08:10:51 +00:00
Move the file/folder to the new path
```
curl -X MOVE https://127.0.0.1:5000/path -H "Destination: https://127.0.0.1:5000/new-path"
```
List/search directory contents
2023-02-21 08:10:51 +00:00
```
2023-02-22 03:26:17 +00:00
curl http://127.0.0.1:5000?simple # output names only, just like `ls -1`
curl http://127.0.0.1:5000?json # output paths in json format
curl http://127.0.0.1:5000?q=Dockerfile&simple # search for files, just like `find -name Dockerfile`
```
2023-02-21 08:10:51 +00:00
With authorization
```
curl http://192.168.8.10:5000/file --user user:pass # basic auth
curl http://192.168.8.10:5000/file --user user:pass --digest # digest auth
2023-02-21 08:10:51 +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
2023-06-01 23:16:43 +00:00
Dufs supports account based access control. You can control who can do what on which path with `--auth`/`-a`.
```
2023-11-03 13:08:05 +00:00
dufs -a user:pass@path1:rw,path2|user2:pass2@path1
dufs -a user:pass@path1:rw,path2 -a user2:pass2@path1
```
2023-06-18 00:55:42 +00:00
1. Multiple rules are separated by "|"
2. User and pass are the account name and password, if omitted, it is an anonymous user
3. One rule can set multiple paths, separated by ","
4. Add `:rw` after the path to indicate that the path has read and write permissions, otherwise the path has readonly permissions.
2022-08-06 00:30:19 +00:00
```
2023-06-01 23:16:43 +00:00
dufs -A -a admin:admin@/:rw
2022-08-06 00:30:19 +00:00
```
`admin` has all permissions for all paths.
2022-08-06 00:30:19 +00:00
```
2023-06-01 23:16:43 +00:00
dufs -A -a admin:admin@/:rw -a guest:guest@/
2022-08-06 00:30:19 +00:00
```
`guest` has readonly permissions for all paths.
```
2023-06-01 23:16:43 +00:00
dufs -A -a admin:admin@/:rw -a @/
2022-08-06 00:30:19 +00:00
```
All paths is public, everyone can view/download it.
```
2023-06-01 23:16:43 +00:00
dufs -A -a admin:admin@/:rw -a user1:pass1@/user1:rw -a user2:pass2@/user2
dufs -A -a "admin:admin@/:rw|user1:pass1@/user1:rw|user2:pass2@/user2"
```
`user1` has all permissions for `/user1/*` path.
`user2` has all permissions for `/user2/*` path.
```
dufs -A -a user:pass@/dir1:rw,/dir2:rw,dir3
```
2023-06-01 23:16:43 +00:00
`user` has all permissions for `/dir1/*` and `/dir2/*`, has readonly permissions for `/dir3/`.
2022-08-06 00:30:19 +00:00
```
2023-11-04 10:12:58 +00:00
dufs -A -a admin:admin@/
2022-08-06 00:30:19 +00:00
```
Since dufs only allows viewing/downloading, `admin` can only view/download files.
2023-11-04 11:47:13 +00:00
#### Hashed Password
2023-11-04 10:12:58 +00:00
DUFS supports the use of sha-512 hashed password.
Create hashed password
```
$ mkpasswd -m sha-512 -s
Password: 123456
$6$qCAVUG7yn7t/hH4d$BWm8r5MoDywNmDP/J3V2S2a6flmKHC1IpblfoqZfuK.LtLBZ0KFXP9QIfJP8RqL8MCw4isdheoAMTuwOz.pAO/
```
Use hashed password
```
dufs -A -a 'admin:$6$qCAVUG7yn7t/hH4d$BWm8r5MoDywNmDP/J3V2S2a6flmKHC1IpblfoqZfuK.LtLBZ0KFXP9QIfJP8RqL8MCw4isdheoAMTuwOz.pAO/@/:rw'
```
Two important things for hashed passwords:
1. Dufs only supports SHA-512 hashed passwords, so ensure that the password string always starts with `$6$`.
2. Digest auth does not work with hashed passwords.
2022-08-06 00:30:19 +00:00
### Hide Paths
2022-08-01 07:12:25 +00:00
Dufs supports hiding paths from directory listings via option `--hidden <glob>,...`.
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
```
> The glob used in --hidden only matches file and directory names, not paths. So `--hidden dir1/file` is invalid.
2022-08-01 07:12:25 +00:00
2022-08-06 00:30:19 +00:00
```sh
dufs --hidden '.*' # hidden dotfiles
dufs --hidden '*/' # hidden all folders
dufs --hidden '*.log,*.lock' # hidden by exts
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 |
| ------------ | ------------------------------------------------------------------------- |
| $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
## Environment variables
All options can be set using environment variables prefixed with `DUFS_`.
2023-06-01 23:16:43 +00:00
```
[serve-path] DUFS_SERVE_PATH=/dir
--config <path> DUFS_CONFIG=config.yaml
2023-06-01 23:16:43 +00:00
-b, --bind <addrs> DUFS_BIND=0.0.0.0
-p, --port <port> DUFS_PORT=5000
2023-07-19 22:33:17 +00:00
--path-prefix <path> DUFS_PATH_PREFIX=/path
2023-06-01 23:16:43 +00:00
--hidden <value> DUFS_HIDDEN=*.log
-a, --auth <rules> DUFS_AUTH="admin:admin@/:rw|@/"
-A, --allow-all DUFS_ALLOW_ALL=true
--allow-upload DUFS_ALLOW_UPLOAD=true
--allow-delete DUFS_ALLOW_DELETE=true
--allow-search DUFS_ALLOW_SEARCH=true
--allow-symlink DUFS_ALLOW_SYMLINK=true
--allow-archive DUFS_ALLOW_ARCHIVE=true
--enable-cors DUFS_ENABLE_CORS=true
--render-index DUFS_RENDER_INDEX=true
--render-try-index DUFS_RENDER_TRY_INDEX=true
--render-spa DUFS_RENDER_SPA=true
--assets <path> DUFS_ASSETS=/assets
--log-format <format> DUFS_LOG_FORMAT=""
2023-06-01 23:16:43 +00:00
--tls-cert <path> DUFS_TLS_CERT=cert.pem
--tls-key <path> DUFS_TLS_KEY=key.pem
```
## Configuration File
You can specify and use the configuration file by selecting the option `--config <path-to-config.yaml>`.
The following are the configuration items:
```yaml
2023-11-07 14:45:53 +00:00
serve-path: '.'
bind:
- 192.168.8.10
port: 5000
path-prefix: /dufs
hidden:
- tmp
- '*.log'
- '*.lock'
auth:
- admin:admin@/:rw
- user:pass@/src:rw,/share
allow-all: false
allow-upload: true
allow-delete: true
allow-search: true
allow-symlink: true
allow-archive: true
enable-cors: true
render-index: true
render-try-index: true
render-spa: true
assets: ./assets/
log-format: '$remote_addr "$request" $status $http_user_agent'
tls-cert: tests/data/cert.pem
tls-key: tests/data/key_pkcs1.pem
2023-06-01 23:16:43 +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-09 13:37:07 +00:00
dufs --assets my-assets-dir/
```
2022-09-09 13:43:40 +00:00
Your assets folder must contains a `index.html` file.
2022-09-09 13:43:40 +00:00
`index.html` can use the following placeholder variables to retrieve internal data.
- `__INDEX_DATA__`: directory listing data
2023-08-13 07:05:45 +00:00
- `__ASSETS_PREFIX__`: assets url prefix
2022-09-05 02:34:18 +00:00
</details>
2022-05-26 12:08:11 +00:00
## License
Copyright (c) 2022 dufs-developers.
2022-05-26 12:08:11 +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.