docs-xml/manpages/vfs_zfsacl.8.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <ns:Root xmlns:xi="http://www.w3.org/2003/XInclude"
   4     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   5     xmlns:ns="urn:TestNamespace">
   6 <refentry id="vfs_zfsacl.8">
   7
   8 <refmeta>
   9         <refentrytitle>vfs_zfsacl</refentrytitle>
  10         <manvolnum>8</manvolnum>
  11         <refmiscinfo class="source">Samba</refmiscinfo>
  12         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
  13         <refmiscinfo class="version">&doc.version;</refmiscinfo>
  14 </refmeta>
  15
  16
  17 <refnamediv>
  18         <refname>vfs_zfsacl</refname>
  19         <refpurpose>ZFS ACL samba module</refpurpose>
  20 </refnamediv>
  21
  22 <refsynopsisdiv>
  23         <cmdsynopsis>
  24                 <command>vfs objects = zfsacl</command>
  25         </cmdsynopsis>
  26 </refsynopsisdiv>
  27
  28 <refsect1>
  29         <title>DESCRIPTION</title>
  30
  31         <para>This VFS module is part of the
  32         <citerefentry><refentrytitle>samba</refentrytitle>
  33         <manvolnum>7</manvolnum></citerefentry> suite.</para>
  34
  35         <para>The <command>zfsacl</command> VFS module is the home
  36         for all ACL extensions that Samba requires for proper integration
  37         with ZFS.
  38         </para>
  39
  40         <para>Currently the zfsacl vfs module provides extensions in following areas :
  41         <itemizedlist>
  42         <listitem><para>NFSv4 ACL Interfaces with configurable options for ZFS</para></listitem>
  43         </itemizedlist>
  44         </para>
  45
  46         <para><command>NOTE:</command>This module follows the posix-acl behaviour
  47         and hence allows permission stealing via chown. Samba might allow at a later
  48         point in time, to restrict the chown via this module as such restrictions
  49         are the responsibility of the underlying filesystem than of Samba.
  50         </para>
  51
  52         <para>This module makes use of the smb.conf parameter
  53         <smbconfoption name="acl map full control">acl map full control</smbconfoption>
  54         When set to yes (the default), this parameter will add in the FILE_DELETE_CHILD
  55         bit on a returned ACE entry for a file (not a directory) that already
  56         contains all file permissions except for FILE_DELETE and FILE_DELETE_CHILD.
  57         This can prevent Windows applications that request GENERIC_ALL access
  58         from getting ACCESS_DENIED errors when running against a filesystem
  59         with NFSv4 compatible ACLs.
  60         </para>
  61
  62         <para>ZFS has multiple dataset configuration parameters that determine ACL behavior.
  63         Although the nuances of these parameters are outside the scope of this manpage, the
  64         "aclmode" and "aclinherit" are of particular importance for samba shares.
  65         For datasets that are intended solely as Samba shares, "aclmode = restricted"
  66         and "aclinherit = passthrough" provide inheritance behavior most consistent with NTFS ACLs.
  67         A "restricted" aclmode prevents chmod() on files that have a non-trivial ACL (one that
  68         cannot be expressed as a POSIX mode without loss of information). Consult the relevant ZFS
  69         manpages for further information.
  70         </para>
  71
  72         <para>This module is stackable.</para>
  73
  74         <para>Since Samba 4.0 all options are per share options.</para>
  75
  76 </refsect1>
  77
  78
  79 <refsect1>
  80         <title>OPTIONS</title>
  81
  82         <xi:include href="nfs4.xml.include" xpointer="xpointer(*/*)" />
  83
  84         <variablelist>
  85
  86                 <varlistentry>
  87                 <term>zfsacl:denymissingspecial = [yes|no]</term>
  88                 <listitem>
  89                 <para>Prevent users from setting an ACL that lacks NFSv4 special entries
  90                 (owner@, group@, everyone@). ZFS will automatically generate these these entries
  91                 when calculating the inherited ACL of new files if the ACL of the parent directory
  92                 lacks an inheriting special entry. This may result in user confusion and unexpected
  93                 change in permissions of files and directories as the inherited ACL is generated.</para>
  94                 <itemizedlist>
  95                 <listitem><para><command>yes</command></para></listitem>
  96                 <listitem><para><command>no (default)</command></para></listitem>
  97                 </itemizedlist>
  98                 </listitem>
  99                 </varlistentry>
 100
 101                 <varlistentry>
 102                 <term>zfsacl:block_special = [yes|no]</term>
 103                 <listitem>
 104                 <para>Prevent ZFS from automatically adding NFSv4 special
 105                 entries (owner@, group@, everyone@).  ZFS will automatically
 106                 generate these these entries when calculating the inherited ACL
 107                 of new files if the ACL of the parent directory lacks an
 108                 inheriting special entry. This may result in user confusion and
 109                 unexpected change in permissions of files and directories as the
 110                 inherited ACL is generated. Blocking this behavior is achieved
 111                 by setting an inheriting everyone@ that grants no permissions
 112                 and not adding the entry to the file's Security
 113                 Descriptor</para>
 114                 <itemizedlist>
 115                 <listitem><para><command>yes (default)</command></para></listitem>
 116                 <listitem><para><command>no</command></para></listitem>
 117                 </itemizedlist>
 118                 </listitem>
 119                 </varlistentry>
 120
 121                 <varlistentry>
 122                 <term>zfsacl:map_dacl_protected = [yes|no]</term>
 123                 <listitem>
 124                 <para>If enabled and the ZFS ACL on the underlying filesystem does not contain
 125                 any inherited access control entries, then set the SEC_DESC_DACL_PROTECTED flag
 126                 on the Security Descriptor returned to SMB clients.
 127                 This ensures correct Windows client behavior when disabling inheritance on
 128                 directories.</para>
 129
 130                 <para>Following is the behaviour of Samba for different values : </para>
 131                 <itemizedlist>
 132                 <listitem><para><command>yes</command> - Enable mapping to
 133                 SEC_DESC_DACL_PROTECTED</para></listitem>
 134                 <listitem><para><command>no (default)</command></para></listitem>
 135                 </itemizedlist>
 136                 </listitem>
 137                 </varlistentry>
 138
 139
 140         </variablelist>
 141 </refsect1>
 142
 143 <refsect1>
 144         <title>EXAMPLES</title>
 145
 146         <para>A ZFS mount can be exported via Samba as follows :</para>
 147
 148 <programlisting>
 149         <smbconfsection name="[samba_zfs_share]"/>
 150         <smbconfoption name="vfs objects">zfsacl</smbconfoption>
 151         <smbconfoption name="path">/test/zfs_mount</smbconfoption>
 152         <smbconfoption name="nfs4: mode">simple</smbconfoption>
 153         <smbconfoption name="nfs4: acedup">merge</smbconfoption>
 154 </programlisting>
 155 </refsect1>
 156
 157 <refsect1>
 158         <title>VERSION</title>
 159         <para>This man page is part of version &doc.version; of the Samba suite.
 160         </para>
 161 </refsect1>
 162
 163 <refsect1>
 164         <title>AUTHOR</title>
 165
 166         <para>The original Samba software and related utilities
 167         were created by Andrew Tridgell. Samba is now developed
 168         by the Samba Team as an Open Source project similar
 169         to the way the Linux kernel is developed.</para>
 170 </refsect1>
 171
 172 </refentry>
 173 </ns:Root>