131 lines
5.7 KiB
Markdown
131 lines
5.7 KiB
Markdown
# Why use this WebDAV Nginx server?
|
|
This server is a single Nginx module attempting to be a fully-fledged WebDAV server in C. It's a fork of existing projects aiming to fix issues they had and merge the codebases. Specifically the goals of this project are:
|
|
|
|
[x] extremely easy setup configuration
|
|
|
|
[x] don't ruin the filesystem, the server filesystem looks like just as it does as a WebDAV mount, copy your files in or out and you're good to go
|
|
|
|
[x] APIs lenient enough to work with all clients in contrast to the native Nginx webdav module
|
|
|
|
[ ] WebDAV PROPPATCH method
|
|
|
|
[ ] WebDAV SEARCH method through xapian(?)
|
|
|
|
[ ] etag checksums for more robust client syncing
|
|
|
|
[ ] optional thumbnailing though cron jobs
|
|
|
|
[ ] optional filesystem indexing for WebDAV SEARCH with cron jobs that uses noninvasive and compatible .index files
|
|
|
|
[ ] optional locking and unlocking in redis
|
|
|
|
[x] functional testing suite
|
|
|
|
# Was this written from zero?
|
|
The native nginx dav_module has been integrated with a few changes for client compatibility. This solves some very difficult problems with client compatibility:
|
|
|
|
- trailing slash issues for DELETE requests uris
|
|
|
|
- trailing slash issues for MOVE and COPY requests uris and destination headers
|
|
|
|
- trailing slash issues for MKCOL request uris
|
|
|
|
The community [nginx_dav_ext_module](https://github.com/MkfsSion/nginx-dav-ext-module) is integrated as well for proper full WebDAV support.
|
|
|
|
# Usage
|
|
There are a few reasonable ways of setting it up.
|
|
1. Standalone mode with authentication
|
|
|
|
```
|
|
location / {
|
|
auth_basic "My closed site, go away!";
|
|
auth_basic_user_file /usr/share/nginx/htpasswd;
|
|
|
|
client_body_temp_path /var/nginx/webdav_client_temp;
|
|
webdav_methods PUT DELETE MKCOL COPY MOVE PROPFIND OPTIONS LOCK UNLOCK;
|
|
create_full_put_path on;
|
|
webdav_access all:rw;
|
|
webdav_lock zone=foo;
|
|
|
|
root /var/nginx/webdav;
|
|
index index.html index.htm;
|
|
}
|
|
```
|
|
|
|
2. Managed mode with subrequest full cloud functionality with [starfields-cloud](https://git.vickys-corner.xyz/StarFields/starfields-cloud)
|
|
|
|
```
|
|
location / {
|
|
auth_request /cloud/auth/;
|
|
|
|
client_body_temp_path /var/nginx/webdav_client_temp;
|
|
dav_ext_methods PUT DELETE MKCOL COPY MOVE PROPFIND OPTIONS LOCK UNLOCK;
|
|
create_full_put_path on;
|
|
dav_access all:rw;
|
|
dav_ext_lock zone=foo;
|
|
|
|
root /var/nginx/webdav;
|
|
index index.html index.htm;
|
|
}
|
|
|
|
location = /cloud/auth/ {
|
|
internal;
|
|
|
|
proxy_pass_request_headers on;
|
|
proxy_pass_request_body on;
|
|
proxy_set_header X-Original-Method $request_method;
|
|
proxy_set_header X-Original-URI $request_uri;
|
|
proxy_pass http://localhost:8000/api/v1/cloud/auth/;
|
|
|
|
# OR
|
|
# uwsgi_pass_request_headers on;
|
|
# uwsgi_pass_request_body on;
|
|
# uwsgi_param X-Original-Method $request_uri;
|
|
# uwsgi_param X-Original-URI $request_uri;
|
|
# uwsgi_pass unix:/path/to/my/django.sock;
|
|
}
|
|
```
|
|
|
|
# Directives
|
|
| Directive | Specification | Context | Description |
|
|
| --------- | ------------- | ------- | ----------- |
|
|
| webdav_methods | [GET] [PUT] [MKCOL] [DELETE] [PROPFIND] [OPTIONS] [LOCK] [UNLOCK]| http, server, location | Allowed HTTP methods |
|
|
| create_full_put_path | (on \| off) | http, server, location | Whether to allow creating all needed intermediate directories during an PUT request |
|
|
| webdav_access | users:permissions | http, server, location | Sets access permissions for newly created files and directories |
|
|
| min_delete_depth number | (0 \| 1 \| 2 \| ...) | http, server, location | Allows the DELETE method to remove files provided that the number of elements in a request path is not less than the specified number |
|
|
| webdav_lock | dav_ext_lock zone=NAME | http, server, location | Enables WebDAV locking in the specified scope |
|
|
| webdav_lock_zone | zone=NAME:SIZE [timeout=TIMEOUT] | http | Defines a shared zone for WebDAV locks with specified NAME and SIZE. Also, defines a lock expiration TIMEOUT. Default lock timeout value is 1 minute. |
|
|
|
|
|
|
|
|
# Building
|
|
1) After cloning this repository in $gitdir clone the nginx source code in $gitdir/nginx
|
|
|
|
2) cd $gitdir/nginx
|
|
|
|
3) ./configure --add-dynamic-module=../../nginx-sf-webdav-module/' --with-compat
|
|
|
|
4) make
|
|
|
|
5) then the module is in $gitdir/nginx/objs/ngx_http_webdav_module.so
|
|
|
|
to compile the module statically just replace --add-dynamic-module with --add-module
|
|
|
|
# Requirements
|
|
|
|
- nginx version >= 1.13.4
|
|
|
|
- libxml2 + libxslt
|
|
|
|
The libxslt library is technically redundant and is only required since this combination is supported by nginx for the xslt module. Using builtin nginx mechanisms for linking against third-party libraries brings certain compatibility benefits. However this redundancy can be easily eliminated in the config file.
|
|
|
|
# Locking
|
|
|
|
- Only the exclusive write locks are supported, which is the only type of locks described in the WebDAV specification.
|
|
|
|
- All currently held locks are kept in a list. Checking if an object is constrained by a lock requires O(n) operations. A huge number of simultaneously held locks may degrade performance. Thus it is not recommended to have a large lock timeout which would increase the number of locks.
|
|
|
|
|
|
# Testing
|
|
TODO
|