Improve documentation based on user feedback

Closes #4

src/vmod_slash.man.rst

@@ -439,6 +439,18 @@ block devices reside (e.g. on ``/dev/``). The environment variable
 ``slash_fellow_options`` can be set to contain ``skip-path-check``
 where, for whatever exotic reason, this check needs to be skipped.
 
+.. _jail: https://varnish-cache.org/docs/trunk/reference/varnishd.html#jail
+
+Permissions and ownership on *path* need to be set such that the
+``varnishd`` worker process has read/write access (see ``workuser`` in
+the `jail`_ option documentation). On a system where ``varnishd``
+starts as root with the default unix jail configuration (``vcache``
+workuser), the permissions can be set using::
+
+  my_fellow_path=...		# REPLACE ... with path
+  chown vcache $my_fellow_path
+  chmod 600 $my_fellow_path
+
 When a VCL-defined fellow storage goes out of scope because the last
 VCL referencing it is discarded, all of its objects are removed from
 the cache, but remain on disk. They can be loaded again by configuring
@@ -815,6 +827,23 @@ with :ref:`varnishlog(1)`::
 During startup, additional diagnostic information is written to
 standard error (stderr).
 
+Explanation of some commonly seen startup errors:
+
+* ``open(...) failed: Permission denied``
+
+  Permissions on the storage path are not set correctly. See
+  `slash.fellow()` for how to set them.
+
+* ``... is not a fellow file``
+
+  The first 4KB of the storage path are neither zero nor written by
+  fellow. This is a safeguard in order to avoid overwriting
+  potentially precious data. Either recreate the file/device or
+  overwrite the first 4KB with zeroes (as always, entirely at your own
+  risk, replace ``...`` with the fellow path)::
+
+    dd if=/dev/zero of=... bs=4096 count=1
+
 FELLOW CACHE LOADING
 ====================
 

src/vmod_slash.vcc

@@ -385,6 +385,18 @@ block devices reside (e.g. on ``/dev/``). The environment variable
 ``slash_fellow_options`` can be set to contain ``skip-path-check``
 where, for whatever exotic reason, this check needs to be skipped.
 
+.. _jail: https://varnish-cache.org/docs/trunk/reference/varnishd.html#jail
+
+Permissions and ownership on *path* need to be set such that the
+``varnishd`` worker process has read/write access (see ``workuser`` in
+the `jail`_ option documentation). On a system where ``varnishd``
+starts as root with the default unix jail configuration (``vcache``
+workuser), the permissions can be set using::
+
+  my_fellow_path=...		# REPLACE ... with path
+  chown vcache $my_fellow_path
+  chmod 600 $my_fellow_path
+
 When a VCL-defined fellow storage goes out of scope because the last
 VCL referencing it is discarded, all of its objects are removed from
 the cache, but remain on disk. They can be loaded again by configuring
@@ -736,6 +748,23 @@ with :ref:`varnishlog(1)`::
 During startup, additional diagnostic information is written to
 standard error (stderr).
 
+Explanation of some commonly seen startup errors:
+
+* ``open(...) failed: Permission denied``
+
+  Permissions on the storage path are not set correctly. See
+  `slash.fellow()` for how to set them.
+
+* ``... is not a fellow file``
+
+  The first 4KB of the storage path are neither zero nor written by
+  fellow. This is a safeguard in order to avoid overwriting
+  potentially precious data. Either recreate the file/device or
+  overwrite the first 4KB with zeroes (as always, entirely at your own
+  risk, replace ``...`` with the fellow path)::
+
+    dd if=/dev/zero of=... bs=4096 count=1
+
 FELLOW CACHE LOADING
 ====================