[PATCH] 3 x samba docs

Sat Mar 24 04:44:20 UTC 2018

I'm not used to submitting patches - first time on this list. If there's
anything more I need to do, please let me know.

These improve docs in 3 areas. I put them onto the github mirror, before
realising that this might not be what's needed?

Thanks and hope this is easy enough format.
Stilez




*=============================== PATCH #1: vfs_aio_pthread.8.xml
================================*


* Refactors existing paragraph, and fixes the disparity whereby this file
recommends 1024/1024 but smb.conf man page says the only valid values are 0
or 1. (Discussed on main samba list)*

--- docs-xml/manpages/vfs_aio_pthread.8.xml 2018-03-24 04:32:09.001353912
+0000
+++ docs-xml/manpages/vfs_aio_pthread.8.xml 2018-03-24 04:32:09.300833497
+0000
@@ -41,23 +41,26 @@
        descriptor which essentially makes Posix AIO useless on systems
        using the glibc implementation.</para>

-       <para>To work around all these limitations, the aio_pthread module
-       was written. It uses a pthread pool instead of the
-       internal Posix AIO interface to allow read and write calls
-       to be process asynchronously. A pthread pool is created
-       which expands dynamically by creating new threads as work is
-       given to it to a maximum of 100 threads per smbd process.
-       To change this limit see the "aio num threads" parameter
-       below. New threads are not created if idle threads are
-       available when a new read or write request is received,
-       the new work is given to an existing idle thread. Threads
-       terminate themselves if idle for one second.
+       <para>
+       To work around all these limitations, the aio_pthread module uses a
+       pthread pool instead of the internal Posix AIO interface. This
allows read
+       and write calls to be process asynchronously and more efficiently.
The
+       pthread pool expands dynamically by creating new threads as work is
+       given to it. A maximum of 100 threads per smbd process is set by
default;
+       this limit can be changed using the <command>aio max
threads</command>
+       or <command>aio_threads:aio num threads</command> parameter. If idle
+       threads are available when a new read or write request is received,
the
+       new work is given to an existing idle thread and a new thread is not
+       created. Threads terminate if idle for one second.
        </para>

        <para>
-       Note that the smb.conf parameters <command>aio read size</command>
-       and <command>aio write size</command> must also be set appropriately
-       for this module to be active.
+       Note that the smb.conf parameters <command>aio read size</command>
and
+       <command>aio write size</command> must also be set appropriately
for this
+       module to be active. Historically a value of 1024 was suggested for
each, to work
+       around a bug in MacOS SMB2 that prevented symlinks from being
written. As async
+       writes are now always handled correctly, the only reasonable values
are currently
+       0 (no async I/O) and 1 (always do async I/O).
        </para>

        <para>This module MUST be listed last in any module stack as



*=============================== PATCH #2: vetofiles.xml
================================*


*Important to note that although "veto files" stops the file being shown,
it does not prevent it being traversed.*

--- docs-xml/smbdotconf/filename/vetofiles.xml 2018-03-24
04:32:09.709073537 +0000
+++ docs-xml/smbdotconf/filename/vetofiles.xml 2018-03-24
04:32:09.955445296 +0000
@@ -6,7 +6,9 @@
        <para>
        This is a list of files and directories that are neither visible
nor accessible.  Each entry in
        the list must be separated by a '/', which allows spaces to be
included in the entry. '*' and '?'
-       can be used to specify multiple files or directories as in DOS
wildcards.
+       can be used to specify multiple files or directories as in DOS
wildcards. Note that directories in
+       the list can still be traversed, and their contents remain
accessible using symlinks (if enabled),
+       since the parameter does not affect the contents of a directory but
only the directory itself.
        </para>

        <para>





*=============================== PATCH #3: widelinks.xml
================================*

*The "wide links" parameter is not that clearly explained, in particular
how it relates to/overlaps with "follow symlinks" and "allow insecure wide
links", and its security aspects.*

--- docs-xml/smbdotconf/misc/widelinks.xml 2018-03-24 04:32:10.226783317
+0000
+++ docs-xml/smbdotconf/misc/widelinks.xml 2018-03-24 04:32:10.468730689
+0000
@@ -3,23 +3,27 @@
                  type="boolean"
                  xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
 <description>
-       <para>This parameter controls whether or not links
-       in the UNIX file system may be followed by the server. Links
-       that point to areas within the directory tree exported by the
-       server are always allowed; this parameter controls access only
-       to areas that are outside the directory tree being exported.</para>
-
-       <para>Note: Turning this parameter on when UNIX extensions are
enabled
-       will allow UNIX clients to create symbolic links on the share that
-       can point to files or directories outside restricted path exported
-       by the share definition. This can cause access to areas outside of
-       the share. Due to this problem, this parameter will be automatically
-       disabled (with a message in the log file) if the
-       <smbconfoption name="unix extensions"/> option is on.
+       <para>This parameter controls whether or not the server may follow
+       (but not create or modify) symbolic links that point to locations
+       outside the directory tree exported by the share definition.  It
+       extends the scope of the default <smbconfoption name="follow
symlinks"/>
+       option, which only allows symlinks to be created and followed within
+       the share directory tree, and is not subject to the security risks
+       of allowing a connected user to create and follow symlinks without
+       restriction to any destination.
+       </para>
+       <para>Note: Since UNIX extensions allow unrestricted creation of
+       symbolic links, turning this parameter on when UNIX extensions are
+       enabled would allow UNIX clients to create symbolic links within
+       the share that could point to any files or directories elsewhere in
+       the UNIX filing system. Due to security implications, this parameter
+       is therefore automatically disabled (with a message in the log file)
+       if the <smbconfoption name="unix extensions"/> option is enabled.
        </para>
        <para>
        See the parameter <smbconfoption name="allow insecure wide links"/>
-       if you wish to change this coupling between the two parameters.
+       if you wish to disable the coupling between these two parameters,
and
+       allow connected users to create and follow symbolic links to any
location.
        </para>
 </description>
