enhance documentation

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
 

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)

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.

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`

doc/webfuse_provider.md

@@ -0,0 +1,30 @@
+# webfuse_provider command line options
+
+Inject a remote filesystem via webfuse.
+
+## Usage
+
+    webfuse_provider -u <url> [-p <path>] [-a <cert_path>]
+
+## 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`

src/provider_main.cpp

@@ -96,7 +96,7 @@ void print_usage()
 expose a local directory via webfuse2
 
 Usage:
-    webfuse-provider -u <url> [-p <path>] [-a <ca_path>]
+    webfuse_provider -u <url> [-p <path>] [-a <ca_path>]
 
 Options:
     --url, -u       set url of webfuse2 service