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 <refentry id="vfs_zfsacl.8">
   4
   5 <refmeta>
   6         <refentrytitle>vfs_zfsacl</refentrytitle>
   7         <manvolnum>8</manvolnum>
   8         <refmiscinfo class="source">Samba</refmiscinfo>
   9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
  10         <refmiscinfo class="version">&doc.version;</refmiscinfo>
  11 </refmeta>
  12
  13
  14 <refnamediv>
  15         <refname>vfs_zfsacl</refname>
  16         <refpurpose>ZFS ACL samba module</refpurpose>
  17 </refnamediv>
  18
  19 <refsynopsisdiv>
  20         <cmdsynopsis>
  21                 <command>vfs objects = zfsacl</command>
  22         </cmdsynopsis>
  23 </refsynopsisdiv>
  24
  25 <refsect1>
  26         <title>DESCRIPTION</title>
  27
  28         <para>This VFS module is part of the
  29         <citerefentry><refentrytitle>samba</refentrytitle>
  30         <manvolnum>7</manvolnum></citerefentry> suite.</para>
  31
  32         <para>The <command>zfsacl</command> VFS module is the home
  33         for all ACL extensions that Samba requires for proper integration
  34         with ZFS.
  35         </para>
  36
  37         <para>Currently the zfsacl vfs module provides extensions in following areas :
  38         <itemizedlist>
  39         <listitem><para>NFSv4 ACL Interfaces with configurable options for ZFS</para></listitem>
  40         </itemizedlist>
  41         </para>
  42
  43         <para><command>NOTE:</command>This module follows the posix-acl behaviour
  44         and hence allows permission stealing via chown. Samba might allow at a later
  45         point in time, to restrict the chown via this module as such restrictions
  46         are the responsibility of the underlying filesystem than of Samba.
  47         </para>
  48
  49         <para>This module makes use of the smb.conf parameter
  50         <smbconfoption name="acl map full control">acl map full control</smbconfoption>
  51         When set to yes (the default), this parameter will add in the FILE_DELETE_CHILD
  52         bit on a returned ACE entry for a file (not a directory) that already
  53         contains all file permissions except for FILE_DELETE and FILE_DELETE_CHILD.
  54         This can prevent Windows applications that request GENERIC_ALL access
  55         from getting ACCESS_DENIED errors when running against a filesystem
  56         with NFSv4 compatible ACLs.
  57         </para>
  58
  59         <para>ZFS has mutiple dataset configuration parameters that determine ACL behavior.
  60         Although the nuances of these parameters are outside the scope of this manpage, the
  61         "aclmode" and "aclinherit" are of particular importance for samba shares.
  62         For datasets that are intended solely as Samba shares, "aclmode = restricted"
  63         and "aclinherit = passthrough" provide inheritance behavior most consistent with NTFS ACLs.
  64         A "restricted" aclmode prevents chmod() on files that have a non-trivial ACL (one that
  65         cannot be expressed as a POSIX mode without loss of information). Consult the relevant ZFS
  66         manpages for further information.
  67         </para>
  68
  69         <para>This module is stackable.</para>
  70
  71         <para>Since Samba 4.0 all options are per share options.</para>
  72
  73 </refsect1>
  74
  75
  76 <refsect1>
  77         <title>OPTIONS</title>
  78
  79         <variablelist>
  80
  81                 <varlistentry>
  82
  83                 <term>nfs4:mode = [ simple | special ]</term>
  84                 <listitem>
  85                 <para>
  86                 Controls substitution of special IDs (OWNER@ and GROUP@) on ZFS.
  87                 The use of mode simple is recommended.
  88                 In this mode only non inheriting ACL entries for the file owner
  89                 and group are mapped to special IDs.
  90                 </para>
  91
  92                 <para>The following MODEs are understood by the module:</para>
  93                 <itemizedlist>
  94                 <listitem><para><command>simple(default)</command> - use OWNER@ and GROUP@ special IDs for non inheriting ACEs only.</para></listitem>
  95                 <listitem><para><command>special(deprecated)</command> - use OWNER@ and GROUP@ special IDs in ACEs for all file owner and group ACEs.</para></listitem>
  96                 </itemizedlist>
  97                 </listitem>
  98
  99                 </varlistentry>
 100
 101
 102                 <varlistentry>
 103                 <term>nfs4:acedup = [dontcare|reject|ignore|merge]</term>
 104                 <listitem>
 105                 <para>
 106                 This parameter configures how Samba handles duplicate ACEs encountered in ZFS ACLs.
 107                 ZFS allows/creates duplicate ACE for different bits for same ID.
 108                 </para>
 109
 110                 <para>Following is the behaviour of Samba for different values :</para>
 111                 <itemizedlist>
 112                 <listitem><para><command>dontcare (default)</command> - copy the ACEs as they come</para></listitem>
 113                 <listitem><para><command>reject (deprecated)</command> - stop operation and exit with error on ACL set op</para></listitem>
 114                 <listitem><para><command>ignore (deprecated)</command> - don't include the second matching ACE</para></listitem>
 115                 <listitem><para><command>merge</command> - bitwise OR the 2 ace.flag fields and 2 ace.mask fields of the 2 duplicate ACEs into 1 ACE</para></listitem>
 116                 </itemizedlist>
 117                 </listitem>
 118                 </varlistentry>
 119
 120
 121                 <varlistentry>
 122                 <term>nfs4:chown = [yes|no]</term>
 123                 <listitem>
 124                 <para>This parameter allows enabling or disabling the chown supported
 125                 by the underlying filesystem. This parameter should be enabled with
 126                 care as it might leave your system insecure.</para>
 127                 <para>Some filesystems allow chown as a) giving b) stealing. It is the latter
 128                 that is considered a risk.</para>
 129
 130                 <para>Following is the behaviour of Samba for different values : </para>
 131                 <itemizedlist>
 132                 <listitem><para><command>yes</command> - Enable chown if as supported by the under filesystem</para></listitem>
 133                 <listitem><para><command>no (default)</command> - Disable chown</para></listitem>
 134                 </itemizedlist>
 135                 </listitem>
 136                 </varlistentry>
 137
 138                 <varlistentry>
 139                 <term>zfsacl:denymissingspecial = [yes|no]</term>
 140                 <listitem>
 141                 <para>Prevent users from setting an ACL that lacks NFSv4 special entries
 142                 (owner@, group@, everyone@). ZFS will automatically generate these these entries
 143                 when calculating the inherited ACL of new files if the ACL of the parent directory
 144                 lacks an inheriting special entry. This may result in user confusion and unexpected
 145                 change in permissions of files and directories as the inherited ACL is generated.</para>
 146                 <itemizedlist>
 147                 <listitem><para><command>yes</command></para></listitem>
 148                 <listitem><para><command>no (default)</command></para></listitem>
 149                 </itemizedlist>
 150                 </listitem>
 151                 </varlistentry>
 152
 153                 <varlistentry>
 154                 <term>zfsacl:block_special = [yes|no]</term>
 155                 <listitem>
 156                 <para>Prevent ZFS from automatically adding NFSv4 special
 157                 entries (owner@, group@, everyone@).  ZFS will automatically
 158                 generate these these entries when calculating the inherited ACL
 159                 of new files if the ACL of the parent directory lacks an
 160                 inheriting special entry. This may result in user confusion and
 161                 unexpected change in permissions of files and directories as the
 162                 inherited ACL is generated. Blocking this behavior is achieved
 163                 by setting an inheriting everyone@ that grants no permissions
 164                 and not adding the entry to the file's Security
 165                 Descriptor</para>
 166                 <itemizedlist>
 167                 <listitem><para><command>yes (default)</command></para></listitem>
 168                 <listitem><para><command>no</command></para></listitem>
 169                 </itemizedlist>
 170                 </listitem>
 171                 </varlistentry>
 172
 173                 <varlistentry>
 174                 <term>zfsacl:map_dacl_protected = [yes|no]</term>
 175                 <listitem>
 176                 <para>If enabled and the ZFS ACL on the underlying filesystem does not contain
 177                 any inherited access control entires, then set the SEC_DESC_DACL_PROTECTED flag
 178                 on the Security Descriptor returned to SMB clients.
 179                 This ensures correct Windows client behavior when disabling inheritance on
 180                 directories.</para>
 181
 182                 <para>Following is the behaviour of Samba for different values : </para>
 183                 <itemizedlist>
 184                 <listitem><para><command>yes</command> - Enable mapping to
 185                 SEC_DESC_DACL_PROTECTED</para></listitem>
 186                 <listitem><para><command>no (default)</command></para></listitem>
 187                 </itemizedlist>
 188                 </listitem>
 189                 </varlistentry>
 190
 191
 192         </variablelist>
 193 </refsect1>
 194
 195 <refsect1>
 196         <title>EXAMPLES</title>
 197
 198         <para>A ZFS mount can be exported via Samba as follows :</para>
 199
 200 <programlisting>
 201         <smbconfsection name="[samba_zfs_share]"/>
 202         <smbconfoption name="vfs objects">zfsacl</smbconfoption>
 203         <smbconfoption name="path">/test/zfs_mount</smbconfoption>
 204         <smbconfoption name="nfs4: mode">simple</smbconfoption>
 205         <smbconfoption name="nfs4: acedup">merge</smbconfoption>
 206 </programlisting>
 207 </refsect1>
 208
 209 <refsect1>
 210         <title>VERSION</title>
 211         <para>This man page is part of version &doc.version; of the Samba suite.
 212         </para>
 213 </refsect1>
 214
 215 <refsect1>
 216         <title>AUTHOR</title>
 217
 218         <para>The original Samba software and related utilities
 219         were created by Andrew Tridgell. Samba is now developed
 220         by the Samba Team as an Open Source project similar
 221         to the way the Linux kernel is developed.</para>
 222 </refsect1>
 223
 224 </refentry>