Update sample yaml

mar10 · Nov 17, 2021 · 44e1355 · 44e1355
1 parent e4c53c1
commit 44e1355
Show file tree

Hide file tree

Showing 2 changed files with 86 additions and 55 deletions.
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -7,20 +7,16 @@
 
 **Which web servers are supported?**
     WsgiDAV comes with a standalone server, to run out of the box.
-    There is also built-in support for CherryPy, Paste, and wsgiref servers, as
-    long as these packages are installed.
-    (Fast)CGI should be possible using `flup <http://trac.saddi.com/flup>`_.
-
-    Basically, it runs with all WSGI servers. Currently we tested with Pylons,
-    CherryPy, Paste server.
+    There is also built-in support for cheroot, ext-wsgiutils, gevent, gunicorn,
+    paste, uvicorn, and wsgiref.
 
     See :doc:`run-configure` for details.
 
 **Which configuration do you recommend?**
-    Currently CherryPy seems to be very robust. Also installing lxml is
+    Currently Cherroot seems to be very robust. Also installing lxml is
     recommended.
 
-    But since WsgiDAV is pretty new, please provide feedback on your experience.
+    But since servers are improved over time, please provide feedback on your experience.
 
 **Which WebDAV clients are supported?**
     Basically all WebDAV clients on all platforms, though some of them show odd

diff --git a/sample_wsgidav.yaml b/sample_wsgidav.yaml
@@ -1,26 +1,43 @@
 # WsgiDAV configuration file
 #
-# 1. Rename this file to `wsgidav.yaml`
-# 2. Adjust settings as appropriate
+# 1. Rename this file to `wsgidav.yaml`.
+# 2. Adjust settings as appropriate.
 # 3. Run `wsgidav` from the same directory or pass file path with `--config` option.
 #
-# See http://wsgidav.readthedocs.io/en/latest/user_guide_configure.html
+# See https://wsgidav.readthedocs.io/en/latest/user_guide_configure.html
 #
 # ============================================================================
 # SERVER OPTIONS
 
-server: "cheroot"
-
-# Server specific arguments, for example
-# cheroot: https://cheroot.cherrypy.org/en/latest/pkg/cheroot.wsgi.html#cheroot.wsgi.Server
-# server_args:
-#     numthreads: 50
-
+#: Run WsgiDAV inside this  WSGI server.
+#: Supported servers:
+#:     cheroot, ext-wsgiutils, gevent, gunicorn, paste, uvicorn, wsgiref
+#: 'wsgiref' and 'ext_wsgiutils' are simple builtin servers that should *not* be
+#: used in production.
+#: All other servers must have been installed before, e.g. `pip install cheroot`.
+#: (The binary MSI distribution already includes 'cheroot'.)
+#: Default: "cheroot", use the `--server` command line option to change this.
+
+server: cheroot
+
+#: Server specific arguments, passed to the server. For example cheroot:
+#:   https://cheroot.cherrypy.dev/en/latest/pkg/cheroot.wsgi.html#cheroot.wsgi.Server
+server_args:
+    # max: -1
+    # numthreads: 10
+    # request_queue_size: 5
+    # shutdown_timeout: 5
+    # timeout: 10
+    verbose: 0
+
+# Server hostname (default: localhost, use --host on command line)
 host: 0.0.0.0
+
+# Server port (default: 8080, use --port on command line)
 port: 8080
 
-# Add custom response headers (list of header-name / header-value tuples):
-#response_headers:
+#: Add custom response headers (list of header-name / header-value tuples):
+# response_headers:
 #    - ["Access-Control-Allow-Origin", "http://example.org"]
 
 # Transfer block size in bytes
@@ -41,7 +58,8 @@ hotfixes:
     #: The proper solution for dealing with the Windows WebDAV client is to use
     #: a persistent property manager. This setting is merely a work-around.
     #: NOTE: Works with Win10, can't work with Win7. Other versions untested.
-    emulate_win32_lastmod: true
+    emulate_win32_lastmod: false
+
     #: Re-encode PATH_INFO using UTF-8 (falling back to ISO-8859-1).
     #: This seems to be wrong, since per PEP 3333 PATH_INFO is always ISO-8859-1
     #: encoded (see https://www.python.org/dev/peps/pep-3333/#unicode-issues).
@@ -70,7 +88,9 @@ hotfixes:
 
 # ----------------------------------------------------------------------------
 
-#: Modify to customize the WSGI application stack:
+#: Modify to customize the WSGI application stack.
+#: See here for an example how to add custom middlewares:
+#:   https://wsgidav.readthedocs.io/en/latest/user_guide_configure.html#middleware-stack
 middleware_stack:
     - wsgidav.debug_filter.WsgiDavDebugFilter
     - wsgidav.error_printer.ErrorPrinter
@@ -158,11 +178,55 @@ pam_dc:
     encoding: "utf-8"
     resetcreds: true
 
+# ----------------------------------------------------------------------------
+# Property Manager
+# null: (default) no support for dead properties
+# true: Use wsgidav.prop_man.property_manager.PropertyManager
+#       which is an in-memory property manager (NOT persistent)
+property_manager: true
+
+# Example:
+# Use PERSISTENT shelve based property manager
+# from wsgidav.prop_man.property_manager import ShelvePropertyManager
+# property_manager: ShelvePropertyManager("wsgidav-props.shelve")
+
+#: Optional additional live property modification
+#: Note: by default live properties like file size and last-modified time are
+#: read-only, but that can be overriden here if the underlying DAV provider
+#: supports it. For now only the FileSystemProvider supports it and only namely
+#: changes to the last-modified timestamp. Enable it with the mutable_live_props
+#: list as below to allow clients to use the utime system call or e.g. the
+#: touch or cp / rsync commands with the preserve-timestamp flags on a mounted
+#: DAV share.
+#: Please note that the timestamp is set on the actual file or directory, so it
+#: is persistent even for in-memory property managers. It should also be noted
+#: that mutable last-modified may not be compliant with the RFC 4918.
+mutable_live_props:
+    # Enable to allow clients to use e.g. the touch or cp / rsync commands with the
+    # preserve-timestamp flags in a mounted DAV share (may be RFC4918 incompliant)
+    - "{DAV:}getlastmodified"
+
+# ----------------------------------------------------------------------------
+# Lock Manager
+#
+# Default:        true, i.e. use wsgidav.lock_storage.LockStorageDict
+# Also available: wsgidav.lock_storage.LockStorageShelve
+#
+# Check the documentation on how to develop custom lock managers.
+# Note that the default LockStorageDict works in-memory, so it is NOT
+# persistent.
+# Example:
+#   Use PERSISTENT shelve based lock manager
+#   from wsgidav.lock_storage import LockStorageShelve
+#   lock_manager = LockStorageShelve("wsgidav-locks.shelve")
+lock_manager: true
+
+
 
 # ==============================================================================
 # DEBUGGING
 
-#: Set verbosity level (but will be overridden by -v or -q arguments)
+#: Set verbosity level (can be overridden by -v or -q arguments)
 verbose: 3
 
 logging:
@@ -174,8 +238,8 @@ logging:
     # logger_date_format: ""%Y-%m-%d %H:%M:%S"
     # logger_format: "%(asctime)s.%(msecs)03d - <%(thread)05d> %(name)-27s %(levelname)-8s: %(message)s"
 
-    # Enable specific module loggers
-    # E.g. ["lock_manager", "property_manager", "http_authenticator", ...]
+    #: Enable specific module loggers
+    #: E.g. ["lock_manager", "property_manager", "http_authenticator", ...]
     # enable_loggers: ["http_authenticator", ]
 
     # Enable max. logging for certain http methods
@@ -216,38 +280,9 @@ dir_browser:
     #:   https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ff407576(v%3Doffice.14)
     #: - Otherwise the Office URL prefix is used (e.g. 'ms-word:ofe|u|http://server/path/file.docx')
     ms_sharepoint_support: true
-    #:
+    #: Invoke Libre Office documents for editing using WebDAV
     libre_office_support: true
-    #:
     #: The path to the directory that contains template.html and associated
     #: assets.
     #: The default is the htdocs directory within the dir_browser directory.
     htdocs_path: null
-
-
-# ----------------------------------------------------------------------------
-# Property Manager
-# null: (default) Don't support dead properties
-# true: Use in-memory property manager (NOT persistent)
-property_manager: true
-
-# Example:
-# Use PERSISTENT shelve based property manager
-# from wsgidav.prop_man.property_manager import ShelvePropertyManager
-# property_manager: ShelvePropertyManager("wsgidav-props.shelve")
-
-# Optional additional live property modification
-mutable_live_props:
-    # Enable to allow clients to use e.g. the touch or cp / rsync commands with the
-    # preserve-timestamp flags in a mounted DAV share (may be RFC4918 incompliant)
-    - "{DAV:}getlastmodified"
-
-# ----------------------------------------------------------------------------
-# Lock Manager
-
-lock_manager: true
-
-# Example:
-# Use PERSISTENT shelve based lock manager
-# from wsgidav.lock_storage import LockStorageShelve
-# lock_manager = LockStorageShelve("wsgidav-locks.shelve")