docs: Update doc to use absolute path for 'dedicated keytab file'
[sfrench/samba-autobuild/.git] / 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">4.6</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                 <arg choice="opt">-D|--delete acl</arg>
25                 <arg choice="opt">-M|--modify acl</arg>
26                 <arg choice="opt">-a|--add acl</arg>
27                 <arg choice="opt">-S|--set acl</arg>
28                 <arg choice="opt">-C|--chown name</arg>
29                 <arg choice="opt">-G|--chgrp name</arg>
30                 <arg choice="opt">-I allow|remove|copy</arg>
31                 <arg choice="opt">--numeric</arg>
32                 <arg choice="opt">-t</arg>
33                 <arg choice="opt">-U username</arg>
34                 <arg choice="opt">-d</arg>
35                 <arg choice="opt">-e</arg>
36                 <arg choice="opt">-m|--max-protocol LEVEL</arg>
37                 <arg choice="opt">--query-security-info FLAGS</arg>
38                 <arg choice="opt">--set-security-info FLAGS</arg>
39                 <arg choice="opt">--sddl</arg>
40                 <arg choice="opt">--domain-sid SID</arg>
41         </cmdsynopsis>
42 </refsynopsisdiv>
43
44 <refsect1>
45         <title>DESCRIPTION</title>
46
47         <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
48         <manvolnum>7</manvolnum></citerefentry> suite.</para>
49
50         <para>The <command>smbcacls</command> program manipulates NT Access Control
51         Lists (ACLs) on SMB file shares. An ACL is comprised zero or more Access
52         Control Entries (ACEs), which define access restrictions for a specific
53         user or group.</para>
54 </refsect1>
55
56
57 <refsect1>
58         <title>OPTIONS</title>
59
60         <para>The following options are available to the <command>smbcacls</command> program.  
61         The format of ACLs is described in the section ACL FORMAT </para>
62
63
64         <variablelist>
65                 <varlistentry>
66                 <term>-a|--add acl</term>
67                 <listitem><para>Add the entries specified to the ACL.  Existing
68                 access control entries are unchanged.</para></listitem>
69                 </varlistentry>
70                 
71                 
72                 
73                 <varlistentry>
74                 <term>-M|--modify acl</term>
75                 <listitem><para>Modify the mask value (permissions) for the ACEs
76                 specified on the command line.  An error will be printed for each 
77                 ACE specified that was not already present in the object's ACL.
78                 </para></listitem>
79                 </varlistentry>
80                 
81                 
82                 
83                 <varlistentry>
84                 <term>-D|--delete acl</term>
85                 <listitem><para>Delete any ACEs specified on the command line.
86                 An error will be printed for each ACE specified that was not
87                 already present in the object's ACL. </para></listitem>
88                 </varlistentry>
89                 
90                 
91                 
92                 <varlistentry>
93                 <term>-S|--set acl</term>
94                 <listitem><para>This command sets the ACL on the object with
95                 only what is specified on the command line.  Any existing ACL
96                 is erased. Note that the ACL specified must contain at least a revision,
97                 type, owner and group for the call to succeed. </para></listitem>
98                 </varlistentry>
99                 
100                 
101                 
102                 <varlistentry>
103                 <term>-C|--chown name</term>
104                 <listitem><para>The owner of a file or directory can be changed 
105                 to the name given using the <parameter>-C</parameter> option.  
106                 The name can be a sid in the form S-1-x-y-z or a name resolved 
107                 against the server specified in the first argument. </para>
108                 
109                 <para>This command is a shortcut for -M OWNER:name. 
110                 </para></listitem>
111                 </varlistentry>
112                 
113                 
114                 
115                 <varlistentry>
116                 <term>-G|--chgrp name</term>
117                 <listitem><para>The group owner of a file or directory can 
118                 be changed to the name given using the <parameter>-G</parameter> 
119                 option.  The name can be a sid in the form S-1-x-y-z or a name 
120                 resolved against the server specified n the first argument.
121                 </para>
122                 
123                 <para>This command is a shortcut for -M GROUP:name.</para></listitem>
124                 </varlistentry>
125                 
126                 
127                 
128                 <varlistentry>
129                 <term>-I|--inherit allow|remove|copy</term>
130                 <listitem><para>Set or unset the windows "Allow inheritable
131                 permissions" check box using the <parameter>-I</parameter>
132                 option.  To set the check box pass allow. To unset the check
133                 box pass either remove or copy. Remove will remove all
134                 inherited acls. Copy will copy all the inherited acls.
135                 </para></listitem>
136
137                 </varlistentry>
138
139
140                 <varlistentry>
141                 <term>--numeric</term>
142                 <listitem><para>This option displays all ACL information in numeric 
143                 format.  The default is to convert SIDs to names and ACE types 
144                 and masks to a readable string format.  </para></listitem>
145                 </varlistentry>
146                 
147                 <varlistentry>
148                 <term>-m|--max-protocol PROTOCOL_NAME</term>
149                 <listitem><para>This allows the user to select the
150                 highest SMB protocol level that smbcacls will use to
151                 connect to the server. By default this is set to
152                 NT1, which is the highest available SMB1 protocol.
153                 To connect using SMB2 or SMB3 protocol, use the
154                 strings SMB2 or SMB3 respectively. Note that to connect
155                 to a Windows 2012 server with encrypted transport selecting
156                 a max-protocol of SMB3 is required.
157                 </para></listitem>
158                 </varlistentry>
159
160                 <varlistentry>
161                 <term>-t|--test-args</term>
162                 <listitem><para>
163                 Don't actually do anything, only validate the correctness of 
164                 the arguments.
165                 </para></listitem>
166                 </varlistentry>
167
168                 <varlistentry>
169                 <term>--query-security-info FLAGS</term>
170                 <listitem><para>The security-info flags for queries.
171                 </para></listitem>
172                 </varlistentry>
173
174                 <varlistentry>
175                 <term>--set-security-info FLAGS</term>
176                 <listitem><para>The security-info flags for queries.
177                 </para></listitem>
178                 </varlistentry>
179
180                 <varlistentry>
181                 <term>--sddl</term>
182                 <listitem><para>Output and input acls in sddl format.
183                 </para></listitem>
184                 </varlistentry>
185
186                 <varlistentry>
187                 <term>--domain-sid SID</term>
188                 <listitem><para>SID used for sddl processing.
189                 </para></listitem>
190                 </varlistentry>
191
192                 &stdarg.server.debug;
193                 &popt.common.samba;
194                 &popt.common.credentials;
195                 &popt.common.connection;
196                 &popt.autohelp;
197         </variablelist>
198 </refsect1>
199
200
201 <refsect1>
202         <title>ACL FORMAT</title>
203
204         <para>The format of an ACL is one or more entries separated by
205         either commas or newlines.  An ACL entry is one of the following: </para>
206
207 <para><programlisting> 
208 REVISION:&lt;revision number&gt;
209 OWNER:&lt;sid or name&gt;
210 GROUP:&lt;sid or name&gt;
211 ACL:&lt;sid or name&gt;:&lt;type&gt;/&lt;flags&gt;/&lt;mask&gt;
212 </programlisting></para>
213   
214
215         <para>The revision of the ACL specifies the internal Windows 
216         NT ACL revision for the security descriptor.  
217         If not specified it defaults to 1.  Using values other than 1 may 
218         cause strange behaviour. </para>
219
220         <para>The owner and group specify the owner and group sids for the 
221         object.  If a SID in the format S-1-x-y-z is specified this is used, 
222         otherwise the name specified is resolved using the server on which 
223         the file or directory resides. </para>
224
225         <para>ACEs are specified with an "ACL:" prefix, and define permissions
226         granted to an SID.  The SID again can be specified in S-1-x-y-z format
227         or as a name in which case it is resolved against the server on which
228         the file or directory resides.  The type, flags and mask values
229         determine the type of access granted to the SID. </para>
230
231         <para>The type can be either ALLOWED or DENIED to allow/deny access 
232         to the SID. The flags values are generally zero for file ACEs and
233         either 9 or 2 for directory ACEs.  Some common flags are: </para>
234
235         <itemizedlist> 
236                 <listitem><para><constant>#define SEC_ACE_FLAG_OBJECT_INHERIT           0x1</constant></para></listitem>
237                 <listitem><para><constant>#define SEC_ACE_FLAG_CONTAINER_INHERIT        0x2</constant></para></listitem>
238                 <listitem><para><constant>#define SEC_ACE_FLAG_NO_PROPAGATE_INHERIT     0x4</constant></para></listitem>
239                 <listitem><para><constant>#define SEC_ACE_FLAG_INHERIT_ONLY             0x8</constant></para></listitem>
240         </itemizedlist>
241   
242         <para>At present, flags can only be specified as decimal or
243         hexadecimal values.</para>
244  
245         <para>The mask is a value which expresses the access right 
246         granted to the SID. It can be given as a decimal or hexadecimal value, 
247         or by using one of the following text strings which map to the NT 
248         file permissions of the same name. </para>
249
250         <itemizedlist>
251                 <listitem><para><emphasis>R</emphasis> - Allow read access </para></listitem>
252                 <listitem><para><emphasis>W</emphasis> - Allow write access</para></listitem>
253                 <listitem><para><emphasis>X</emphasis> - Execute permission on the object</para></listitem>
254                 <listitem><para><emphasis>D</emphasis> - Delete the object</para></listitem>
255                 <listitem><para><emphasis>P</emphasis> - Change permissions</para></listitem>
256                 <listitem><para><emphasis>O</emphasis> - Take ownership</para></listitem>
257         </itemizedlist>
258
259
260         <para>The following combined permissions can be specified:</para>
261
262
263         <itemizedlist>
264                 <listitem><para><emphasis>READ</emphasis> -  Equivalent to 'RX'
265                 permissions</para></listitem>
266                 <listitem><para><emphasis>CHANGE</emphasis> - Equivalent to 'RXWD' permissions
267                 </para></listitem>
268                 <listitem><para><emphasis>FULL</emphasis> - Equivalent to 'RWXDPO' 
269                 permissions</para></listitem>
270         </itemizedlist>
271         </refsect1>
272
273 <refsect1>
274         <title>EXIT STATUS</title>
275
276         <para>The <command>smbcacls</command> program sets the exit status 
277         depending on the success or otherwise of the operations performed.  
278         The exit status may be one of the following values. </para>
279
280         <para>If the operation succeeded, smbcacls returns and exit 
281         status of 0.  If <command>smbcacls</command> couldn't connect to the specified server, 
282         or there was an error getting or setting the ACLs, an exit status 
283         of 1 is returned.  If there was an error parsing any command line 
284         arguments, an exit status of 2 is returned. </para>
285 </refsect1>
286
287 <refsect1>
288         <title>VERSION</title>
289
290         <para>This man page is correct for version 4 of the Samba suite.</para>
291 </refsect1>
292
293 <refsect1>
294         <title>AUTHOR</title>
295         
296         <para>The original Samba software and related utilities 
297         were created by Andrew Tridgell. Samba is now developed
298         by the Samba Team as an Open Source project similar 
299         to the way the Linux kernel is developed.</para>
300         
301         <para><command>smbcacls</command> was written by Andrew Tridgell 
302         and Tim Potter.</para>
303         
304         <para>The conversion to DocBook for Samba 2.2 was done 
305         by Gerald Carter. The conversion to DocBook XML 4.2 for Samba 3.0 was done
306         by Alexander Bokovoy.</para>
307 </refsect1>
308
309 </refentry>