From 75905d64804ac3d01b7120cf7050bad2e1094b11 Mon Sep 17 00:00:00 2001 From: Falk Werner Date: Sun, 15 Jan 2023 21:00:10 +0100 Subject: [PATCH] enhance documentation --- README.md | 3 ++ doc/README.md | 3 ++ doc/authentication.md | 30 +++++++++++++++++ doc/webfuse.md | 74 +++++++++++++++++++++++++++++++++++++++++ doc/webfuse_provider.md | 30 +++++++++++++++++ src/provider_main.cpp | 2 +- 6 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 doc/authentication.md create mode 100644 doc/webfuse.md create mode 100644 doc/webfuse_provider.md diff --git a/README.md b/README.md index bf40528..c4d14e3 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,10 @@ Unlike webfuse, davfs2 mounts a remote filesystem locally, that is provided by a ## Further Documentation - [Build instructions](doc/build.md) +- [Webfuse command line options](webfuse.md) +- [Webfuse provider command line options](webfuse_provider.md) - [Webfuse Protocol](doc/protocol.md) +- [Authentication](authentication.md) ## webfuse legacy diff --git a/doc/README.md b/doc/README.md index f193966..4bd4579 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,4 +1,7 @@ # webfuse developer documentation - [Build instructions](build.md) +- [Webfuse command line options](webfuse.md) +- [Webfuse provider command line options](webfuse_provider.md) - [Webfuse2 protocol](protocol.md) +- [Authentication](authentication.md) diff --git a/doc/authentication.md b/doc/authentication.md new file mode 100644 index 0000000..2155e79 --- /dev/null +++ b/doc/authentication.md @@ -0,0 +1,30 @@ +# Authentication + +Webfuse supports token-based authentication using HTTP headers. To activate authentication, two command line option needs to be given: + +- `--wf-authenticator PATH` + allows to specify an executable used for authentication +- `--wf-auth-header HEADER` + allows to specify the HTTP header used for authentication + +## Authenticator + +An authenticator is an executable or script used for token-based +authentication. During HTTP handshake, webfuse will scan for the +configured HTTP header and invoke the authenticator. + + authenticator TOKEN + +The provided `token` contains the contents of the HTTP header. + +## Header restrictions + +Note that not any HTTP header can be specified using `--wf-auth-header` +option. The following headers are supported: + +- `X-Auth-Token` +- `Authorization` + +In addition to that, any non-standard header can be specified. + +Due to implementation limitation, most standard headers can not be used by now. Please let us know, when you intend to use a header that is not supported yet. Please create an issue in that case. diff --git a/doc/webfuse.md b/doc/webfuse.md new file mode 100644 index 0000000..1f2e23e --- /dev/null +++ b/doc/webfuse.md @@ -0,0 +1,74 @@ +# webfuse command line options + +In order to inject a remote filesystem, webfuse mounts a local +filesystem via fuse and exposes it's API via websockets. + +## Usage + + webfuse [options] <mountpoint> + +## Webfuse specific options + +| Option | Argument | Default | Description | +| ------------ | -------- | --------- | ----------- | +| --wf-port | port | 8081 | Specify the port of the websocket server | +| --wf-vhost | vhost | localhost | Specify the name of the websocket server's virtual host | +| --wf-cert | path | - | Optional. Specify the file path of the server's public certificate | +| --wf-key | path | - | Optional. Specify the file path of the server's private key | +| --wf- authenticator | path | - | Optional. Specify the file path of the authenticator executable | +| --wf-auth-header | name | - | Optional. Specify the name of the HTTP header used for authentication | + +## Fuse options + +| Option | Descripion | +| --------------------- | ---------- | +| -h, --help | print help | +| -V --version | print version | +| -d -o debug | enable debug output (implies -f) | +| -f | foreground operation | +| -s | disable multi-threaded operation | +| -o clone_fd | use separate fuse device fd for each thread | +| | (may improve performance) | +| -o max_idle_threads | the maximum number of idle worker threads | +| | allowed (default: 10) | +| -o kernel_cache | cache files in kernel | +| -o [no]auto_cache | enable caching based on modification times (off) | +| -o umask=M | set file permissions (octal) | +| -o uid=N | set file owner | +| -o gid=N | set file group | +| -o entry_timeout=T | cache timeout for names (1.0s) | +| -o negative_timeout=T | cache timeout for deleted names (0.0s) | +| -o attr_timeout=T | cache timeout for attributes (1.0s) | +| -o ac_attr_timeout=T | auto cache timeout for attributes (attr_timeout) | +| -o noforget | never forget cached inodes | +| -o remember=T | remember cached inodes for T seconds (0s) | +| -o modules=M1[:M2...] | names of modules to push onto filesystem stack | +| -o allow_other | allow access by all users | +| -o allow_root | allow access by root | +| -o auto_unmount | auto unmount on process termination | + +### Options for subdir module + +| Option | Descripion | +| --------------------- | ---------- | +| -o subdir=DIR | prepend this directory to all paths (mandatory) | +| -o [no]rellinks | transform absolute symlinks to relative | + +### Options for iconv module + +| Option | Descripion | +| --------------------- | ---------- | +| -o from_code=CHARSET | original encoding of file names (default: UTF-8) | +| -o to_code=CHARSET | new encoding of the file names (default: UTF-8) | + +## Examples + +- run webfuse in foreground on default port: + `webfuse -f /path/to/mointpoint` +- run webfuse in forground on port 8080: + `webfuse -f --wf-port 8080 /path/to/mountpoint` +- run webfuse using TLS: + `webfuse -f --wf-cert /path/to/cert --wf-key /path/to/key /path/to/mountpoint` +- run webfuse using authentication via `X-Auth-Token` header: + `webfuse -f --wf-authenticator /path/to/authenticator \` + ` --wf-auth-header X-Auth-Token /path/to/mountpoint` \ No newline at end of file diff --git a/doc/webfuse_provider.md b/doc/webfuse_provider.md new file mode 100644 index 0000000..3733a18 --- /dev/null +++ b/doc/webfuse_provider.md @@ -0,0 +1,30 @@ +# webfuse_provider command line options + +Inject a remote filesystem via webfuse. + +## Usage + + webfuse_provider -u [-p ] [-a ] + +## Options + +| Short Option | Long Option | Argument | Description | +| ------------ | ----------- | -------- | ----------- | +| -h | --help | - | print usage and exit | +| -v | --version | - | print version an exit | +| -p | --path | path | path of local filesystem to inject (default: .) | +| -u | --url | url | url of webfuse server | +| -a | --ca-path | path | path of ca file | + +## Examples + +- inject current directory: + `webfuse_provider -u ws://localhost/` +- inject a given directory: + `webfuse_provider -u ws://localhost/ -p /path/to/directory` +- inject current directory to port 8080: + `webfuse_provider -u ws://localhost:8080/` +- inject current directory via TLS: + `webfuse_provider -u wss://localhost/` +- inject current diectory via TLS using a specific ca: + `webfuse_provider -u wss://localhost/ -a /path/to/server-cert.pem` diff --git a/src/provider_main.cpp b/src/provider_main.cpp index c992ae2..6213ac7 100644 --- a/src/provider_main.cpp +++ b/src/provider_main.cpp @@ -96,7 +96,7 @@ void print_usage() expose a local directory via webfuse2 Usage: - webfuse-provider -u [-p ] [-a ] + webfuse_provider -u [-p ] [-a ] Options: --url, -u set url of webfuse2 service