From 813bfae677fa0b2e2833cb596928c556fe731921 Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:13:46 +0000 Subject: [PATCH] docs: preserve upstream English README --- README.en.md | 441 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 441 insertions(+) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..b1eb546 --- /dev/null +++ b/README.en.md @@ -0,0 +1,441 @@ +# Dufs + +[![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) +[![Docker Pulls](https://img.shields.io/docker/pulls/sigoden/dufs)](https://hub.docker.com/r/sigoden/dufs) + +Dufs is a distinctive utility file server that supports static serving, uploading, searching, accessing control, webdav... + +![demo](https://user-images.githubusercontent.com/4012553/220513063-ff0f186b-ac54-4682-9af4-47a9781dee0d.png) + +## Features + +- Serve static files +- Download folder as zip file +- Upload files and folders (Drag & Drop) +- Create/Edit/Search files +- Resumable/partial uploads/downloads +- Access control +- Support https +- Support webdav +- Easy to use with curl + +## Install + +### With cargo + +``` +cargo install dufs +``` + +### With docker + +``` +docker run -v `pwd`:/data -p 5000:5000 --rm sigoden/dufs /data -A +``` + +### With [Homebrew](https://brew.sh) + +``` +brew install dufs +``` + +### Binaries on macOS, Linux, Windows + +Download from [Github Releases](https://github.com/sigoden/dufs/releases), unzip and add dufs to your $PATH. + +## CLI + +``` +Dufs is a distinctive utility file server - https://github.com/sigoden/dufs + +Usage: dufs [OPTIONS] [serve-path] + +Arguments: + [serve-path] Specific path to serve [default: .] + +Options: + -c, --config Specify configuration file + -b, --bind Specify bind address or unix socket + -p, --port Specify port to listen on [default: 5000] + --path-prefix Specify a path prefix + --hidden Hide paths from directory listings, e.g. tmp,*.log,*.lock + -a, --auth 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 download folders as archive file + --allow-hash Allow ?hash query to get file sha256 hash + --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 Set the path to the assets directory for overriding the built-in assets + --log-format Customize http log format + --log-file Specify the file to save logs to, other than stdout/stderr + --compress Set zip compress level [default: low] [possible values: none, low, medium, high] + --completions Print shell completion script for [possible values: bash, elvish, fish, powershell, zsh] + --tls-cert Path to an SSL/TLS certificate to serve with HTTPS + --tls-key Path to the SSL/TLS certificate's private key + -h, --help Print help + -V, --version Print version +``` + +## Examples + +Serve current working directory in read-only mode + +``` +dufs +``` + +Allow all operations like upload/delete/search/create/edit... + +``` +dufs -A +``` + +Only allow upload operation + +``` +dufs --allow-upload +``` + +Serve a specific directory + +``` +dufs Downloads +``` + +Serve a single file + +``` +dufs linux-distro.iso +``` + +Serve a single-page application like react/vue + +``` +dufs --render-spa +``` + +Serve a static website with index.html + +``` +dufs --render-index +``` + +Require username/password + +``` +dufs -a admin:123@/:rw +``` + +Listen on specific host:ip + +``` +dufs -b 127.0.0.1 -p 80 +``` + +Listen on unix socket +``` +dufs -b /tmp/dufs.socket +``` + +Use https + +``` +dufs --tls-cert my.crt --tls-key my.key +``` + +## API + +Upload a file + +```sh +curl -T path-to-file http://127.0.0.1:5000/new-path/path-to-file +``` + +Download a file +```sh +curl http://127.0.0.1:5000/path-to-file # download the file +curl http://127.0.0.1:5000/path-to-file?hash # retrieve the sha256 hash of the file +``` + +Download a folder as zip file + +```sh +curl -o path-to-folder.zip http://127.0.0.1:5000/path-to-folder?zip +``` + +Delete a file/folder + +```sh +curl -X DELETE http://127.0.0.1:5000/path-to-file-or-folder +``` + +Create a directory + +```sh +curl -X MKCOL http://127.0.0.1:5000/path-to-folder +``` + +Move the file/folder to the new path + +```sh +curl -X MOVE http://127.0.0.1:5000/path -H "Destination: http://127.0.0.1:5000/new-path" +``` + +List/search directory contents + +```sh +curl http://127.0.0.1:5000?q=Dockerfile # search for files, similar to `find -name Dockerfile` +curl http://127.0.0.1:5000?simple # output names only, similar to `ls -1` +curl http://127.0.0.1:5000?json # output paths in json format +``` + +With authorization (Both basic or digest auth works) + +```sh +curl http://127.0.0.1:5000/file --user user:pass # basic auth +curl http://127.0.0.1:5000/file --user user:pass --digest # digest auth +``` + +Resumable downloads + +```sh +curl -C- -o file http://127.0.0.1:5000/file +``` + +Resumable uploads + +```sh +upload_offset=$(curl -I -s http://127.0.0.1:5000/file | tr -d '\r' | sed -n 's/content-length: //p') +dd skip=$upload_offset if=file status=none ibs=1 | \ + curl -X PATCH -H "X-Update-Range: append" --data-binary @- http://127.0.0.1:5000/file +``` + +Health checks + +```sh +curl http://127.0.0.1:5000/__dufs__/health +``` + +
+

Advanced Topics

 + +### Access Control + +Dufs supports account based access control. You can control who can do what on which path with `--auth`/`-a`. + +``` +dufs -a admin:admin@/:rw -a guest:guest@/ +dufs -a user:pass@/:rw,/dir1 -a @/ +``` + +1. Use `@` to separate the account and paths. No account means anonymous user. +2. Use `:` to separate the username and password of the account. +3. Use `,` to separate paths. +4. Use path suffix `:rw`/`:ro` set permissions: `read-write`/`read-only`. `:ro` can be omitted. + +- `-a admin:admin@/:rw`: `admin` has complete permissions for all paths. +- `-a guest:guest@/`: `guest` has read-only permissions for all paths. +- `-a user:pass@/:rw,/dir1`: `user` has read-write permissions for `/*`, has read-only permissions for `/dir1/*`. +- `-a @/`: All paths is publicly accessible, everyone can view/download it. + +**Auth permissions are restricted by dufs global permissions.** If dufs does not enable upload permissions via `--allow-upload`, then the account will not have upload permissions even if it is granted `read-write`(`:rw`) permissions. + +#### Hashed Password + +DUFS supports the use of sha-512 hashed password. + +Create hashed password: + +```sh +$ openssl passwd -6 123456 # or `mkpasswd -m sha-512 123456` +$6$tWMB51u6Kb2ui3wd$5gVHP92V9kZcMwQeKTjyTRgySsYJu471Jb1I6iHQ8iZ6s07GgCIO69KcPBRuwPE5tDq05xMAzye0NxVKuJdYs/ +``` + +Use hashed password: + +```sh +dufs -a 'admin:$6$tWMB51u6Kb2ui3wd$5gVHP92V9kZcMwQeKTjyTRgySsYJu471Jb1I6iHQ8iZ6s07GgCIO69KcPBRuwPE5tDq05xMAzye0NxVKuJdYs/@/:rw' +``` +> The hashed password contains `$6`, which can expand to a variable in some shells, so you have to use **single quotes** to wrap it. + +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 authentication does not function properly with hashed passwords. + + +### Hide Paths + +Dufs supports hiding paths from directory listings via option `--hidden ,...`. + +``` +dufs --hidden .git,.DS_Store,tmp +``` + +> The glob used in --hidden only matches file and directory names, not paths. So `--hidden dir1/file` is invalid. + +```sh +dufs --hidden '.*' # hidden dotfiles +dufs --hidden '*/' # hidden all folders +dufs --hidden '*.log,*.lock' # hidden by exts +dufs --hidden '*.log' --hidden '*.lock' +``` + +### Log Format + +Dufs supports customize http log format with option `--log-format`. + +The log format can use following variables. + +| 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 | + + +The default log format is `'$time_iso8601 $log_level - $remote_addr "$request" $status`. +``` +2022-08-06T06:59:31+08:00 INFO - 127.0.0.1 "GET /" 200 +``` + +A json log format is also supported. +``` +dufs --log-format '{"time":"$time_local","addr":"$remote_addr","uri":"$request_uri", "method":"$request_method","status":$status}' + +{"time":"2022-08-06T06:59:31+08:00","addr":"127.0.0.1","uri":"/", "method":"GET","status":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 +``` + +## Environment variables + +All options can be set using environment variables prefixed with `DUFS_`. + +``` +[serve-path] DUFS_SERVE_PATH="." + --config DUFS_CONFIG=config.yaml +-b, --bind DUFS_BIND=0.0.0.0 +-p, --port DUFS_PORT=5000 + --path-prefix DUFS_PATH_PREFIX=/dufs + --hidden DUFS_HIDDEN=tmp,*.log,*.lock +-a, --auth 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 + --allow-hash DUFS_ALLOW_HASH=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 DUFS_ASSETS=./assets + --log-format DUFS_LOG_FORMAT="" + --log-file DUFS_LOG_FILE=./dufs.log + --compress DUFS_COMPRESS=low + --tls-cert DUFS_TLS_CERT=cert.pem + --tls-key DUFS_TLS_KEY=key.pem +``` + +## Configuration File + +You can specify and use the configuration file by selecting the option `--config `. + +The following are the configuration items: + +```yaml +serve-path: '.' +bind: 0.0.0.0 +port: 5000 +path-prefix: /dufs +hidden: + - tmp + - '*.log' + - '*.lock' +auth: + - admin:admin@/:rw + - user:pass@/src:rw,/share + - '@/' # According to the YAML spec, quoting is required. +allow-all: false +allow-upload: true +allow-delete: true +allow-search: true +allow-symlink: true +allow-archive: true +allow-hash: 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' +log-file: ./dufs.log +compress: low +tls-cert: tests/data/cert.pem +tls-key: tests/data/key_pkcs1.pem +``` + +### Customize UI + +Dufs allows users to customize the UI with your own assets. + +``` +dufs --assets my-assets-dir/ +``` + +> If you only need to make slight adjustments to the current UI, you copy dufs's [assets](https://github.com/sigoden/dufs/tree/main/assets) directory and modify it accordingly. The current UI doesn't use any frameworks, just plain HTML/JS/CSS. As long as you have some basic knowledge of web development, it shouldn't be difficult to modify. + +Your assets folder must contains a `index.html` file. + +`index.html` can use the following placeholder variables to retrieve internal data. + +- `__INDEX_DATA__`: directory listing data +- `__ASSETS_PREFIX__`: assets url prefix + +> A customized 404.html page is also supported. + +Here are some Third-party customize UI project: + +- https://github.com/TransparentLC/dufs-material-assets +- https://github.com/cercky/dufs_web +- https://github.com/52funny/dufs-tabler-web + +
+ +## License + +Copyright (c) 2022-2024 dufs-developers. + +dufs is made available under the terms of either the MIT License or the Apache License 2.0, at your option. + +See the LICENSE-APACHE and LICENSE-MIT files for license details.