docs-xml/manpages/smbcacls.1.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="smbcacls.1">
   4
   5 <refmeta>
   6         <refentrytitle>smbcacls</refentrytitle>
   7         <manvolnum>1</manvolnum>
   8         <refmiscinfo class="source">Samba</refmiscinfo>
   9         <refmiscinfo class="manual">User Commands</refmiscinfo>
  10         <refmiscinfo class="version">&doc.version;</refmiscinfo>
  11 </refmeta>
  12
  13
  14 <refnamediv>
  15         <refname>smbcacls</refname>
  16         <refpurpose>Set or get ACLs on an NT file or directory names</refpurpose>
  17 </refnamediv>
  18
  19 <refsynopsisdiv>
  20         <cmdsynopsis>
  21                 <command>smbcacls</command>
  22                 <arg choice="req">//server/share</arg>
  23                 <arg choice="req">/filename</arg>
  24
  25                 <arg choice="opt">-D|--delete=ACL</arg>
  26                 <arg choice="opt">-M|--modify=ACL</arg>
  27                 <arg choice="opt">-a|--add=ACL</arg>
  28                 <arg choice="opt">-S|--set=ACLS</arg>
  29                 <arg choice="opt">-C|--chown=USERNAME</arg>
  30                 <arg choice="opt">-G|--chgrp=GROUPNAME</arg>
  31                 <arg choice="opt">-I|--inherit=STRING</arg>
  32                 <arg choice="opt">--recurse</arg>
  33                 <arg choice="opt">--propagate-inheritance</arg>
  34                 <arg choice="opt">--save=savefile</arg>
  35                 <arg choice="opt">--restore=restorefile</arg>
  36                 <arg choice="opt">--numeric</arg>
  37                 <arg choice="opt">--sddl</arg>
  38                 <arg choice="opt">--query-security-info=INT</arg>
  39                 <arg choice="opt">--set-security-info=INT</arg>
  40                 <arg choice="opt">-t|--test-args</arg>
  41                 <arg choice="opt">--domain-sid=SID</arg>
  42                 <arg choice="opt">-x|--maximum-access</arg>
  43                 <arg choice="opt">-?|--help</arg>
  44                 <arg choice="opt">--usage</arg>
  45                 <arg choice="opt">-d|--debuglevel=DEBUGLEVEL</arg>
  46                 <arg choice="opt">--debug-stdout</arg>
  47                 <arg choice="opt">--configfile=CONFIGFILE</arg>
  48                 <arg choice="opt">--option=name=value</arg>
  49                 <arg choice="opt">-l|--log-basename=LOGFILEBASE</arg>
  50                 <arg choice="opt">--leak-report</arg>
  51                 <arg choice="opt">--leak-report-full</arg>
  52                 <arg choice="opt">-R|--name-resolve=NAME-RESOLVE-ORDER</arg>
  53                 <arg choice="opt">-O|--socket-options=SOCKETOPTIONS</arg>
  54                 <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
  55                 <arg choice="opt">-n|--netbiosname=NETBIOSNAME</arg>
  56                 <arg choice="opt">--netbios-scope=SCOPE</arg>
  57                 <arg choice="opt">-W|--workgroup=WORKGROUP</arg>
  58                 <arg choice="opt">--realm=REALM</arg>
  59                 <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
  60                 <arg choice="opt">-N|--no-pass</arg>
  61                 <arg choice="opt">--password=STRING</arg>
  62                 <arg choice="opt">--pw-nt-hash</arg>
  63                 <arg choice="opt">-A|--authentication-file=FILE</arg>
  64                 <arg choice="opt">-P|--machine-pass</arg>
  65                 <arg choice="opt">--simple-bind-dn=DN</arg>
  66                 <arg choice="opt">--use-kerberos=desired|required|off</arg>
  67                 <arg choice="opt">--use-krb5-ccache=CCACHE</arg>
  68                 <arg choice="opt">--use-winbind-ccache</arg>
  69                 <arg choice="opt">--client-protection=sign|encrypt|off</arg>
  70                 <arg choice="opt">-V|--version</arg>
  71         </cmdsynopsis>
  72 </refsynopsisdiv>
  73
  74 <refsect1>
  75         <title>DESCRIPTION</title>
  76
  77         <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
  78         <manvolnum>7</manvolnum></citerefentry> suite.</para>
  79
  80         <para>The <command>smbcacls</command> program manipulates NT Access Control
  81         Lists (ACLs) on SMB file shares. An ACL comprises zero or more Access
  82         Control Entries (ACEs), which define access restrictions for a specific
  83         user or group.</para>
  84 </refsect1>
  85
  86
  87 <refsect1>
  88         <title>OPTIONS</title>
  89
  90         <para>The following options are available to the <command>smbcacls</command> program.
  91         The format of ACLs is described in the section ACL FORMAT </para>
  92
  93
  94         <variablelist>
  95                 <varlistentry>
  96                 <term>-a|--add acl</term>
  97                 <listitem><para>Add the entries specified to the ACL.  Existing
  98                 access control entries are unchanged.</para></listitem>
  99                 </varlistentry>
 100
 101
 102
 103                 <varlistentry>
 104                 <term>-M|--modify acl</term>
 105                 <listitem><para>Modify the mask value (permissions) for the ACEs
 106                 specified on the command line.  An error will be printed for each
 107                 ACE specified that was not already present in the object's ACL.
 108                 </para></listitem>
 109                 </varlistentry>
 110
 111
 112
 113                 <varlistentry>
 114                 <term>-D|--delete acl</term>
 115                 <listitem><para>Delete any ACEs specified on the command line.
 116                 An error will be printed for each ACE specified that was not
 117                 already present in the object's ACL. </para></listitem>
 118                 </varlistentry>
 119
 120
 121
 122                 <varlistentry>
 123                 <term>-S|--set acl</term>
 124                 <listitem><para>This command sets the ACL on the object with
 125                 only what is specified on the command line.  Any existing ACL
 126                 is erased. Note that the ACL specified must contain at least a revision,
 127                 type, owner and group for the call to succeed. </para></listitem>
 128                 </varlistentry>
 129
 130
 131
 132                 <varlistentry>
 133                 <term>-C|--chown name</term>
 134                 <listitem><para>The owner of a file or directory can be changed
 135                 to the name given using the <parameter>-C</parameter> option.
 136                 The name can be a sid in the form S-1-x-y-z or a name resolved
 137                 against the server specified in the first argument. </para>
 138
 139                 <para>This command is a shortcut for -M OWNER:name.
 140                 </para></listitem>
 141                 </varlistentry>
 142
 143
 144
 145                 <varlistentry>
 146                 <term>-G|--chgrp name</term>
 147                 <listitem><para>The group owner of a file or directory can
 148                 be changed to the name given using the <parameter>-G</parameter>
 149                 option.  The name can be a sid in the form S-1-x-y-z or a name
 150                 resolved against the server specified n the first argument.
 151                 </para>
 152
 153                 <para>This command is a shortcut for -M GROUP:name.</para></listitem>
 154                 </varlistentry>
 155
 156
 157
 158                 <varlistentry>
 159                 <term>-I|--inherit allow|remove|copy</term>
 160                 <listitem><para>Set or unset the windows "Allow inheritable
 161                 permissions" check box using the <parameter>-I</parameter>
 162                 option.  To set the check box pass allow. To unset the check
 163                 box pass either remove or copy. Remove will remove all
 164                 inherited ACEs. Copy will copy all the inherited ACEs.
 165                 </para></listitem>
 166
 167                 </varlistentry>
 168
 169                 <varlistentry>
 170                 <term>--propagate-inheritance</term>
 171                 <listitem><para>Add, modify, delete or set ACEs on an entire
 172                 directory tree according to the inheritance flags. Refer to the
 173                 INHERITANCE section for details.
 174                 </para></listitem>
 175                 </varlistentry>
 176
 177                 <varlistentry>
 178                 <term>--save savefile</term>
 179                 <listitem><para> stores the DACLs in sddl format
 180                 of the specified file or folder for later use with restore.
 181                 SACLS, owner or integrity labels are not stored.
 182                 </para></listitem>
 183                 </varlistentry>
 184
 185                 <varlistentry>
 186                 <term>--restore savefile</term>
 187                 <listitem><para> applies the stored DACLS to files in
 188                 directory.
 189                 </para></listitem>
 190                 </varlistentry>
 191
 192                 <varlistentry>
 193                 <term>--recurse</term>
 194                 <listitem><para> indicates the operation is performed on
 195                 directory and all files/directories below. (only applies
 196                 to save option)
 197                 </para></listitem>
 198                 </varlistentry>
 199
 200                 <varlistentry>
 201                 <term>--numeric</term>
 202                 <listitem><para>This option displays all ACL information in numeric
 203                 format.  The default is to convert SIDs to names and ACE types
 204                 and masks to a readable string format.  </para></listitem>
 205                 </varlistentry>
 206
 207                 <varlistentry>
 208                 <term>-m|--max-protocol PROTOCOL_NAME</term>
 209                 <listitem><para>This allows the user to select the
 210                 highest SMB protocol level that smbcacls will use to
 211                 connect to the server. By default this is set to
 212                 NT1, which is the highest available SMB1 protocol.
 213                 To connect using SMB2 or SMB3 protocol, use the
 214                 strings SMB2 or SMB3 respectively. Note that to connect
 215                 to a Windows 2012 server with encrypted transport selecting
 216                 a max-protocol of SMB3 is required.
 217                 </para></listitem>
 218                 </varlistentry>
 219
 220                 <varlistentry>
 221                 <term>-t|--test-args</term>
 222                 <listitem><para>
 223                 Don't actually do anything, only validate the correctness of
 224                 the arguments.
 225                 </para></listitem>
 226                 </varlistentry>
 227
 228                 <varlistentry>
 229                 <term>--query-security-info FLAGS</term>
 230                 <listitem><para>The security-info flags for queries.
 231                 </para></listitem>
 232                 </varlistentry>
 233
 234                 <varlistentry>
 235                 <term>--set-security-info FLAGS</term>
 236                 <listitem><para>The security-info flags for queries.
 237                 </para></listitem>
 238                 </varlistentry>
 239
 240                 <varlistentry>
 241                 <term>--sddl</term>
 242                 <listitem><para>Output and input acls in sddl format.
 243                 </para></listitem>
 244                 </varlistentry>
 245
 246                 <varlistentry>
 247                 <term>--domain-sid SID</term>
 248                 <listitem><para>SID used for sddl processing.
 249                 </para></listitem>
 250                 </varlistentry>
 251
 252                 <varlistentry>
 253                 <term>-x|--maximum-access</term>
 254                 <listitem><para>When displaying an ACL additionally query
 255                 the server for effective maximum permissions. Note that this
 256                 is only supported with SMB protocol version 2 or higher.
 257                 </para></listitem>
 258                 </varlistentry>
 259
 260                 &popt.autohelp;
 261                 &cmdline.common.samba.client;
 262                 &cmdline.common.connection;
 263                 &cmdline.common.credentials;
 264         </variablelist>
 265 </refsect1>
 266
 267
 268 <refsect1>
 269         <title>ACL FORMAT</title>
 270
 271         <para>The format of an ACL is one or more entries separated by
 272         either commas or newlines.  An ACL entry is one of the following: </para>
 273
 274 <para><programlisting>
 275 REVISION:&lt;revision number&gt;
 276 OWNER:&lt;sid or name&gt;
 277 GROUP:&lt;sid or name&gt;
 278 ACL:&lt;sid or name&gt;:&lt;type&gt;/&lt;flags&gt;/&lt;mask&gt;
 279 </programlisting></para>
 280
 281         <para>Control bits related to automatic inheritance</para>
 282
 283
 284         <itemizedlist>
 285                 <listitem><para><emphasis>OD</emphasis> - "Owner Defaulted" - Indicates that the SID of the owner of the security descriptor was provided by a default mechanism.</para></listitem>
 286                 <listitem><para><emphasis>GD</emphasis> - "Group Defaulted" - Indicates that the SID of the security descriptor group was provided by a default mechanism.</para></listitem>
 287                 <listitem><para><emphasis>DP</emphasis> - "DACL Present" - Indicates a security descriptor that has a discretionary access control list (DACL).</para></listitem>
 288                 <listitem><para><emphasis>DD</emphasis> - "DACL Defaulted" - Indicates a security descriptor with a default DACL.</para></listitem>
 289                 <listitem><para><emphasis>SP</emphasis> - "SACL Present" - Indicates a security descriptor that has a system access control list (SACL).</para></listitem>
 290                 <listitem><para><emphasis>SD</emphasis> - "SACL Defaulted" - A default mechanism, rather than the original provider of the security descriptor, provided the SACL.</para></listitem>
 291                 <listitem><para><emphasis>DT</emphasis> - "DACL Trusted"</para></listitem>
 292                 <listitem><para><emphasis>SS</emphasis> - "Server Security"</para></listitem>
 293                 <listitem><para><emphasis>DR</emphasis> - "DACL Inheritance Required" - Indicates a required security descriptor in which the DACL is set up to support automatic propagation of inheritable access control entries (ACEs) to existing child objects.</para></listitem>
 294                 <listitem><para><emphasis>SR</emphasis> - "SACL Inheritance Required" - Indicates a required security descriptor in which the SACL is set up to support automatic propagation of inheritable ACEs to existing child objects.</para></listitem>
 295                 <listitem><para><emphasis>DI</emphasis> - "DACL Auto Inherited" - Indicates a security descriptor in which the DACL is set up to support automatic propagation of inheritable access control entries (ACEs) to existing child objects.</para></listitem>
 296                 <listitem><para><emphasis>SI</emphasis> - "SACL Auto Inherited" - Indicates a security descriptor in which the SACL is set up to support automatic propagation of inheritable ACEs to existing child objects.</para></listitem>
 297                 <listitem><para><emphasis>PD</emphasis> - "DACL Protected" - Prevents the DACL of the security descriptor from being modified by inheritable ACEs.</para></listitem>
 298                 <listitem><para><emphasis>PS</emphasis> - "SACL Protected" - Prevents the SACL of the security descriptor from being modified by inheritable ACEs.</para></listitem>
 299                 <listitem><para><emphasis>RM</emphasis> - "RM Control Valid" - Indicates that the resource manager control is valid.</para></listitem>
 300                 <listitem><para><emphasis>SR</emphasis> - "Self Relative" - Indicates a self-relative security descriptor.</para></listitem>
 301         </itemizedlist>
 302
 303         <para>The revision of the ACL specifies the internal Windows
 304         NT ACL revision for the security descriptor.
 305         If not specified it defaults to 1.  Using values other than 1 may
 306         cause strange behaviour. </para>
 307
 308         <para>The owner and group specify the owner and group sids for the
 309         object.  If a SID in the format S-1-x-y-z is specified this is used,
 310         otherwise the name specified is resolved using the server on which
 311         the file or directory resides. </para>
 312
 313         <para>ACEs are specified with an "ACL:" prefix, and define permissions
 314         granted to an SID.  The SID again can be specified in S-1-x-y-z format
 315         or as a name in which case it is resolved against the server on which
 316         the file or directory resides.  The type, flags and mask values
 317         determine the type of access granted to the SID. </para>
 318
 319         <para>The type can be either ALLOWED or DENIED to allow/deny access
 320         to the SID.</para>
 321
 322         <para>The flags field defines how the ACE should be considered when
 323         performing inheritance. <command>smbcacls</command> uses these flags
 324         when run with <parameter>--propagate-inheritance</parameter>.</para>
 325
 326         <para>Flags can be specified as decimal or hexadecimal values, or with
 327         the respective (XX) aliases, separated by a vertical bar "|".</para>
 328
 329         <itemizedlist>
 330                 <listitem><para><emphasis>(OI)</emphasis> Object Inherit        0x1</para></listitem>
 331                 <listitem><para><emphasis>(CI)</emphasis> Container Inherit     0x2</para></listitem>
 332                 <listitem><para><emphasis>(NP)</emphasis> No Propagate Inherit  0x4</para></listitem>
 333                 <listitem><para><emphasis>(IO)</emphasis> Inherit Only          0x8</para></listitem>
 334                 <listitem><para><emphasis>(I)</emphasis> ACE was inherited     0x10</para></listitem>
 335         </itemizedlist>
 336
 337
 338         <para>The mask is a value which expresses the access right
 339         granted to the SID. It can be given as a decimal or hexadecimal value,
 340         or by using one of the following text strings which map to the NT
 341         file permissions of the same name. </para>
 342
 343         <itemizedlist>
 344                 <listitem><para><emphasis>R</emphasis> - Allow read access </para></listitem>
 345                 <listitem><para><emphasis>W</emphasis> - Allow write access</para></listitem>
 346                 <listitem><para><emphasis>X</emphasis> - Execute permission on the object</para></listitem>
 347                 <listitem><para><emphasis>D</emphasis> - Delete the object</para></listitem>
 348                 <listitem><para><emphasis>P</emphasis> - Change permissions</para></listitem>
 349                 <listitem><para><emphasis>O</emphasis> - Take ownership</para></listitem>
 350         </itemizedlist>
 351
 352
 353         <para>The following combined permissions can be specified:</para>
 354
 355
 356         <itemizedlist>
 357                 <listitem><para><emphasis>READ</emphasis> -  Equivalent to 'RX'
 358                 permissions</para></listitem>
 359                 <listitem><para><emphasis>CHANGE</emphasis> - Equivalent to 'RXWD' permissions
 360                 </para></listitem>
 361                 <listitem><para><emphasis>FULL</emphasis> - Equivalent to 'RWXDPO'
 362                 permissions</para></listitem>
 363         </itemizedlist>
 364         </refsect1>
 365
 366 <refsect1>
 367         <title>INHERITANCE</title>
 368
 369         <para>Per-ACE inheritance flags can be set in the ACE flags field. By
 370         default, inheritable ACEs e.g. those marked for object inheritance (OI)
 371         or container inheritance (CI), are not propagated to sub-files or
 372         folders. However, with the
 373         <parameter>--propagate-inheritance</parameter> argument specified, such
 374         ACEs are automatically propagated according to some inheritance
 375         rules.
 376         <itemizedlist>
 377                 <listitem><para>Inheritable (OI)(OI) ACE flags can only be
 378                 applied to folders. </para></listitem>
 379                 <listitem><para>Any inheritable ACEs applied to sub-files or
 380                 folders are marked with the inherited (I) flag. Inheritable
 381                 ACE(s) are applied to folders unless the no propagation (NP)
 382                 flag is set. </para>
 383                 </listitem>
 384                 <listitem><para>When an ACE with the (OI) flag alone set is
 385                 propagated to a child folder the inheritance only flag (IO) is
 386                 also applied. This indicates the permissions associated with
 387                 the ACE don't apply to the folder itself (only to it's
 388                 child files). When applying the ACE to a child file the ACE is
 389                 inherited as normal.</para></listitem>
 390                 <listitem><para>When an ace with the (CI) flag alone set is
 391                 propagated to a child file there is no effect, when propagated
 392                 to a child folder it is inherited as normal.
 393                 </para></listitem>
 394                 <listitem><para>When an ACE that has both (OI) &amp; (CI) flags
 395                 set the ACE is inherited as normal by both folders and
 396                 files.</para></listitem>
 397         </itemizedlist></para>
 398 <para>(OI)(READ) added to parent folder</para>
 399 <para><programlisting>
 400 +-parent/        (OI)(READ)
 401 | +-file.1       (I)(READ)
 402 | +-nested/      (OI)(IO)(I)(READ)
 403   |   +-file.2   (I)(READ)
 404 </programlisting></para>
 405 <para>(CI)(READ) added to parent folder</para>
 406 <para><programlisting>
 407 +-parent/        (CI)(READ)
 408 | +-file.1
 409 | +-nested/      (CI)(I)(READ)
 410   |   +-file.2
 411 </programlisting></para>
 412 <para>(OI)(CI)(READ) added to parent folder</para>
 413 <para><programlisting>
 414 +-parent/        (OI)(CI)(READ)
 415 | +-file.1       (I)(READ)
 416 | +-nested/      (OI)(CI)(I)(READ)
 417   |   +-file.2   (I)(READ)
 418 </programlisting></para>
 419 <para>(OI)(NP)(READ) added to parent folder</para>
 420 <para><programlisting>
 421 +-oi_dir/        (OI)(NP)(READ)
 422 | +-file.1       (I)(READ)
 423 | +-nested/
 424 |   +-file.2
 425 </programlisting></para>
 426 <para>(CI)(NP)(READ) added to parent folder</para>
 427 <para><programlisting>
 428 +-oi_dir/        (CI)(NP)(READ)
 429 | +-file.1
 430 | +-nested/      (I)(READ)
 431 |   +-file.2
 432 </programlisting></para>
 433 <para>(OI)(CI)(NP)(READ) added to parent folder</para>
 434 <para><programlisting>
 435 +-parent/        (CI)(OI)(NP)(READ)
 436 | +-file.1       (I)(READ)
 437 | +-nested/      (I)(READ)
 438 |   +-file.2
 439 </programlisting></para>
 440         <para>Files and folders with protected ACLs do not allow inheritable
 441         permissions (set with <parameter>-I</parameter>). Such objects will
 442         not receive ACEs flagged for inheritance with (CI) or (OI).</para>
 443
 444 </refsect1>
 445
 446 <refsect1>
 447         <title>EXIT STATUS</title>
 448
 449         <para>The <command>smbcacls</command> program sets the exit status
 450         depending on the success or otherwise of the operations performed.
 451         The exit status may be one of the following values. </para>
 452
 453         <para>If the operation succeeded, smbcacls returns and exit
 454         status of 0.  If <command>smbcacls</command> couldn't connect to the specified server,
 455         or there was an error getting or setting the ACLs, an exit status
 456         of 1 is returned.  If there was an error parsing any command line
 457         arguments, an exit status of 2 is returned. </para>
 458 </refsect1>
 459
 460 <refsect1>
 461         <title>VERSION</title>
 462
 463         <para>This man page is part of version &doc.version; of the Samba suite.</para>
 464 </refsect1>
 465
 466 <refsect1>
 467         <title>AUTHOR</title>
 468
 469         <para>The original Samba software and related utilities
 470         were created by Andrew Tridgell. Samba is now developed
 471         by the Samba Team as an Open Source project similar
 472         to the way the Linux kernel is developed.</para>
 473
 474         <para><command>smbcacls</command> was written by Andrew Tridgell
 475         and Tim Potter.</para>
 476
 477         <para>The conversion to DocBook for Samba 2.2 was done
 478         by Gerald Carter. The conversion to DocBook XML 4.2 for Samba 3.0 was done
 479         by Alexander Bokovoy.</para>
 480 </refsect1>
 481
 482 </refentry>