1SMBCACLS(1)                      User Commands                     SMBCACLS(1)
2
3
4

NAME

6       smbcacls - Set or get ACLs on an NT file or directory names
7

SYNOPSIS

9       smbcacls {//server/share} {/filename} [-D|--delete=ACL]
10        [-M|--modify=ACL] [-a|--add=ACL] [-S|--set=ACLS] [-C|--chown=USERNAME]
11        [-G|--chgrp=GROUPNAME] [-I|--inherit=STRING] [--propagate-inheritance]
12        [--numeric] [--sddl] [--query-security-info=INT]
13        [--set-security-info=INT] [-t|--test-args] [--domain-sid=SID]
14        [-x|--maximum-access] [-?|--help] [--usage]
15        [-d|--debuglevel=DEBUGLEVEL] [--debug-stdout]
16        [--configfile=CONFIGFILE] [--option=name=value]
17        [-l|--log-basename=LOGFILEBASE] [--leak-report] [--leak-report-full]
18        [-R|--name-resolve=NAME-RESOLVE-ORDER]
19        [-O|--socket-options=SOCKETOPTIONS] [-m|--max-protocol=MAXPROTOCOL]
20        [-n|--netbiosname=NETBIOSNAME] [--netbios-scope=SCOPE]
21        [-W|--workgroup=WORKGROUP] [--realm=REALM]
22        [-U|--user=[DOMAIN/]USERNAME[%PASSWORD]] [-N|--no-pass]
23        [--password=STRING] [--pw-nt-hash] [-A|--authentication-file=FILE]
24        [-P|--machine-pass] [--simple-bind-dn=DN]
25        [--use-kerberos=desired|required|off] [--use-krb5-ccache=CCACHE]
26        [--use-winbind-ccache] [--client-protection=sign|encrypt|off]
27        [-V|--version]
28

DESCRIPTION

30       This tool is part of the samba(7) suite.
31
32       The smbcacls program manipulates NT Access Control Lists (ACLs) on SMB
33       file shares. An ACL is comprised zero or more Access Control Entries
34       (ACEs), which define access restrictions for a specific user or group.
35

OPTIONS

37       The following options are available to the smbcacls program. The format
38       of ACLs is described in the section ACL FORMAT
39
40       -a|--add acl
41           Add the entries specified to the ACL. Existing access control
42           entries are unchanged.
43
44       -M|--modify acl
45           Modify the mask value (permissions) for the ACEs specified on the
46           command line. An error will be printed for each ACE specified that
47           was not already present in the object's ACL.
48
49       -D|--delete acl
50           Delete any ACEs specified on the command line. An error will be
51           printed for each ACE specified that was not already present in the
52           object's ACL.
53
54       -S|--set acl
55           This command sets the ACL on the object with only what is specified
56           on the command line. Any existing ACL is erased. Note that the ACL
57           specified must contain at least a revision, type, owner and group
58           for the call to succeed.
59
60       -C|--chown name
61           The owner of a file or directory can be changed to the name given
62           using the -C option. The name can be a sid in the form S-1-x-y-z or
63           a name resolved against the server specified in the first argument.
64
65           This command is a shortcut for -M OWNER:name.
66
67       -G|--chgrp name
68           The group owner of a file or directory can be changed to the name
69           given using the -G option. The name can be a sid in the form
70           S-1-x-y-z or a name resolved against the server specified n the
71           first argument.
72
73           This command is a shortcut for -M GROUP:name.
74
75       -I|--inherit allow|remove|copy
76           Set or unset the windows "Allow inheritable permissions" check box
77           using the -I option. To set the check box pass allow. To unset the
78           check box pass either remove or copy. Remove will remove all
79           inherited ACEs. Copy will copy all the inherited ACEs.
80
81       --propagate-inheritance
82           Add, modify, delete or set ACEs on an entire directory tree
83           according to the inheritance flags. Refer to the INHERITANCE
84           section for details.
85
86       --numeric
87           This option displays all ACL information in numeric format. The
88           default is to convert SIDs to names and ACE types and masks to a
89           readable string format.
90
91       -m|--max-protocol PROTOCOL_NAME
92           This allows the user to select the highest SMB protocol level that
93           smbcacls will use to connect to the server. By default this is set
94           to NT1, which is the highest available SMB1 protocol. To connect
95           using SMB2 or SMB3 protocol, use the strings SMB2 or SMB3
96           respectively. Note that to connect to a Windows 2012 server with
97           encrypted transport selecting a max-protocol of SMB3 is required.
98
99       -t|--test-args
100           Don't actually do anything, only validate the correctness of the
101           arguments.
102
103       --query-security-info FLAGS
104           The security-info flags for queries.
105
106       --set-security-info FLAGS
107           The security-info flags for queries.
108
109       --sddl
110           Output and input acls in sddl format.
111
112       --domain-sid SID
113           SID used for sddl processing.
114
115       -x|--maximum-access
116           When displaying an ACL additionally query the server for effective
117           maximum permissions. Note that this is only supported with SMB
118           protocol version 2 or higher.
119
120       -?|--help
121           Print a summary of command line options.
122
123       --usage
124           Display brief usage message.
125
126       -d|--debuglevel=DEBUGLEVEL
127           level is an integer from 0 to 10. The default value if this
128           parameter is not specified is 1 for client applications.
129
130           The higher this value, the more detail will be logged to the log
131           files about the activities of the server. At level 0, only critical
132           errors and serious warnings will be logged. Level 1 is a reasonable
133           level for day-to-day running - it generates a small amount of
134           information about operations carried out.
135
136           Levels above 1 will generate considerable amounts of log data, and
137           should only be used when investigating a problem. Levels above 3
138           are designed for use only by developers and generate HUGE amounts
139           of log data, most of which is extremely cryptic.
140
141           Note that specifying this parameter here will override the log
142           level parameter in the smb.conf file.
143
144       --debug-stdout
145           This will redirect debug output to STDOUT. By default all clients
146           are logging to STDERR.
147
148       --configfile=<configuration file>
149           The file specified contains the configuration details required by
150           the client. The information in this file can be general for client
151           and server or only provide client specific like options such as
152           client smb encrypt. See smb.conf for more information. The default
153           configuration file name is determined at compile time.
154
155       --option=<name>=<value>
156           Set the smb.conf(5) option "<name>" to value "<value>" from the
157           command line. This overrides compiled-in defaults and options read
158           from the configuration file. If a name or a value includes a space,
159           wrap whole --option=name=value into quotes.
160
161       -l|--log-basename=logdirectory
162           Base directory name for log/debug files. The extension ".progname"
163           will be appended (e.g. log.smbclient, log.smbd, etc...). The log
164           file is never removed by the client.
165
166       --leak-report
167           Enable talloc leak reporting on exit.
168
169       --leak-report-full
170           Enable full talloc leak reporting on exit.
171
172       -V|--version
173           Prints the program version number.
174
175       -R|--name-resolve=NAME-RESOLVE-ORDER
176           This option is used to determine what naming services and in what
177           order to resolve host names to IP addresses. The option takes a
178           space-separated string of different name resolution options. The
179           best ist to wrap the whole --name-resolve=NAME-RESOLVE-ORDER into
180           quotes.
181
182           The options are: "lmhosts", "host", "wins" and "bcast". They cause
183           names to be resolved as follows:
184
185lmhosts: Lookup an IP address in the Samba lmhosts file.
186                      If the line in lmhosts has no name type attached to the
187                      NetBIOS name (see the lmhosts(5) for details) then any
188                      name type matches for lookup.
189
190host: Do a standard host name to IP address resolution,
191                      using the system /etc/hosts, NIS, or DNS lookups. This
192                      method of name resolution is operating system dependent,
193                      for instance on IRIX or Solaris this may be controlled
194                      by the /etc/nsswitch.conf file). Note that this method
195                      is only used if the NetBIOS name type being queried is
196                      the 0x20 (server) name type, otherwise it is ignored.
197
198wins: Query a name with the IP address listed in the
199                      wins server parameter. If no WINS server has been
200                      specified this method will be ignored.
201
202bcast: Do a broadcast on each of the known local
203                      interfaces listed in the interfaces parameter. This is
204                      the least reliable of the name resolution methods as it
205                      depends on the target host being on a locally connected
206                      subnet.
207
208           If this parameter is not set then the name resolve order defined in
209           the smb.conf file parameter (name resolve order) will be used.
210
211           The default order is lmhosts, host, wins, bcast. Without this
212           parameter or any entry in the name resolve order parameter of the
213           smb.conf file, the name resolution methods will be attempted in
214           this order.
215
216       -O|--socket-options=SOCKETOPTIONS
217           TCP socket options to set on the client socket. See the socket
218           options parameter in the smb.conf manual page for the list of valid
219           options.
220
221       -m|--max-protocol=MAXPROTOCOL
222           The value of the parameter (a string) is the highest protocol level
223           that will be supported by the client.
224
225           Note that specifying this parameter here will override the client
226           max protocol parameter in the smb.conf file.
227
228       -n|--netbiosname=NETBIOSNAME
229           This option allows you to override the NetBIOS name that Samba uses
230           for itself. This is identical to setting the netbios name parameter
231           in the smb.conf file. However, a command line setting will take
232           precedence over settings in smb.conf.
233
234       --netbios-scope=SCOPE
235           This specifies a NetBIOS scope that nmblookup will use to
236           communicate with when generating NetBIOS names. For details on the
237           use of NetBIOS scopes, see rfc1001.txt and rfc1002.txt. NetBIOS
238           scopes are very rarely used, only set this parameter if you are the
239           system administrator in charge of all the NetBIOS systems you
240           communicate with.
241
242       -W|--workgroup=WORKGROUP
243           Set the SMB domain of the username. This overrides the default
244           domain which is the domain defined in smb.conf. If the domain
245           specified is the same as the servers NetBIOS name, it causes the
246           client to log on using the servers local SAM (as opposed to the
247           Domain SAM).
248
249           Note that specifying this parameter here will override the
250           workgroup parameter in the smb.conf file.
251
252       -r|--realm=REALM
253           Set the realm for the domain.
254
255           Note that specifying this parameter here will override the realm
256           parameter in the smb.conf file.
257
258       -U|--user=[DOMAIN\]USERNAME[%PASSWORD]
259           Sets the SMB username or username and password.
260
261           If %PASSWORD is not specified, the user will be prompted. The
262           client will first check the USER environment variable (which is
263           also permitted to also contain the password seperated by a %), then
264           the LOGNAME variable (which is not permitted to contain a password)
265           and if either exists, the value is used. If these environmental
266           variables are not found, the username found in a Kerberos
267           Credentials cache may be used.
268
269           A third option is to use a credentials file which contains the
270           plaintext of the username and password. This option is mainly
271           provided for scripts where the admin does not wish to pass the
272           credentials on the command line or via environment variables. If
273           this method is used, make certain that the permissions on the file
274           restrict access from unwanted users. See the -A for more details.
275
276           Be cautious about including passwords in scripts or passing
277           user-supplied values onto the command line. For security it is
278           better to let the Samba client tool ask for the password if needed,
279           or obtain the password once with kinit.
280
281           While Samba will attempt to scrub the password from the process
282           title (as seen in ps), this is after startup and so is subject to a
283           race.
284
285       -N|--no-pass
286           If specified, this parameter suppresses the normal password prompt
287           from the client to the user. This is useful when accessing a
288           service that does not require a password.
289
290           Unless a password is specified on the command line or this
291           parameter is specified, the client will request a password.
292
293           If a password is specified on the command line and this option is
294           also defined the password on the command line will be silently
295           ignored and no password will be used.
296
297       --password
298           Specify the password on the commandline.
299
300           Be cautious about including passwords in scripts or passing
301           user-supplied values onto the command line. For security it is
302           better to let the Samba client tool ask for the password if needed,
303           or obtain the password once with kinit.
304
305           If --password is not specified, the tool will check the PASSWD
306           environment variable, followed by PASSWD_FD which is expected to
307           contain an open file descriptor (FD) number.
308
309           Finally it will check PASSWD_FILE (containing a file path to be
310           opened). The file should only contain the password. Make certain
311           that the permissions on the file restrict access from unwanted
312           users!
313
314           While Samba will attempt to scrub the password from the process
315           title (as seen in ps), this is after startup and so is subject to a
316           race.
317
318       --pw-nt-hash
319           The supplied password is the NT hash.
320
321       -A|--authentication-file=filename
322           This option allows you to specify a file from which to read the
323           username and password used in the connection. The format of the
324           file is:
325
326                                   username = <value>
327                                   password = <value>
328                                   domain   = <value>
329
330
331           Make certain that the permissions on the file restrict access from
332           unwanted users!
333
334       -P|--machine-pass
335           Use stored machine account password.
336
337       --simple-bind-dn=DN
338           DN to use for a simple bind.
339
340       --use-kerberos=desired|required|off
341           This parameter determines whether Samba client tools will try to
342           authenticate using Kerberos. For Kerberos authentication you need
343           to use dns names instead of IP addresses when connnecting to a
344           service.
345
346           Note that specifying this parameter here will override the client
347           use kerberos parameter in the smb.conf file.
348
349       --use-krb5-ccache=CCACHE
350           Specifies the credential cache location for Kerberos
351           authentication.
352
353           This will set --use-kerberos=required too.
354
355       --use-winbind-ccache
356           Try to use the credential cache by winbind.
357
358       --client-protection=sign|encrypt|off
359           Sets the connection protection the client tool should use.
360
361           Note that specifying this parameter here will override the client
362           protection parameter in the smb.conf file.
363
364           In case you need more fine grained control you can use:
365           --option=clientsmbencrypt=OPTION, --option=clientipcsigning=OPTION,
366           --option=clientsigning=OPTION.
367

ACL FORMAT

369       The format of an ACL is one or more entries separated by either commas
370       or newlines. An ACL entry is one of the following:
371
372           REVISION:<revision number>
373           OWNER:<sid or name>
374           GROUP:<sid or name>
375           ACL:<sid or name>:<type>/<flags>/<mask>
376
377       Control bits related to automatic inheritance
378
379OD - "Owner Defaulted" - Indicates that the SID of the owner
380                  of the security descriptor was provided by a default
381                  mechanism.
382
383GD - "Group Defaulted" - Indicates that the SID of the
384                  security descriptor group was provided by a default
385                  mechanism.
386
387DP - "DACL Present" - Indicates a security descriptor that
388                  has a discretionary access control list (DACL).
389
390DD - "DACL Defaulted" - Indicates a security descriptor with
391                  a default DACL.
392
393SP - "SACL Present" - Indicates a security descriptor that
394                  has a system access control list (SACL).
395
396SD - "SACL Defaulted" - A default mechanism, rather than the
397                  original provider of the security descriptor, provided the
398                  SACL.
399
400DT - "DACL Trusted"
401
402SS - "Server Security"
403
404DR - "DACL Inheritance Required" - Indicates a required
405                  security descriptor in which the DACL is set up to support
406                  automatic propagation of inheritable access control entries
407                  (ACEs) to existing child objects.
408
409SR - "SACL Inheritance Required" - Indicates a required
410                  security descriptor in which the SACL is set up to support
411                  automatic propagation of inheritable ACEs to existing child
412                  objects.
413
414DI - "DACL Auto Inherited" - Indicates a security descriptor
415                  in which the DACL is set up to support automatic propagation
416                  of inheritable access control entries (ACEs) to existing
417                  child objects.
418
419SI - "SACL Auto Inherited" - Indicates a security descriptor
420                  in which the SACL is set up to support automatic propagation
421                  of inheritable ACEs to existing child objects.
422
423PD - "DACL Protected" - Prevents the DACL of the security
424                  descriptor from being modified by inheritable ACEs.
425
426PS - "SACL Protected" - Prevents the SACL of the security
427                  descriptor from being modified by inheritable ACEs.
428
429RM - "RM Control Valid" - Indicates that the resource
430                  manager control is valid.
431
432SR - "Self Relative" - Indicates a self-relative security
433                  descriptor.
434
435
436       The revision of the ACL specifies the internal Windows NT ACL revision
437       for the security descriptor. If not specified it defaults to 1. Using
438       values other than 1 may cause strange behaviour.
439
440       The owner and group specify the owner and group sids for the object. If
441       a SID in the format S-1-x-y-z is specified this is used, otherwise the
442       name specified is resolved using the server on which the file or
443       directory resides.
444
445       ACEs are specified with an "ACL:" prefix, and define permissions
446       granted to an SID. The SID again can be specified in S-1-x-y-z format
447       or as a name in which case it is resolved against the server on which
448       the file or directory resides. The type, flags and mask values
449       determine the type of access granted to the SID.
450
451       The type can be either ALLOWED or DENIED to allow/deny access to the
452       SID.
453
454       The flags field defines how the ACE should be considered when
455       performing inheritance.  smbcacls uses these flags when run with
456       --propagate-inheritance.
457
458       Flags can be specified as decimal or hexadecimal values, or with the
459       respective (XX) aliases, separated by a vertical bar "|".
460
461(OI) Object Inherit 0x1
462
463(CI) Container Inherit 0x2
464
465(NP) No Propagate Inherit 0x4
466
467(IO) Inherit Only 0x8
468
469(I) ACE was inherited 0x10
470
471
472       The mask is a value which expresses the access right granted to the
473       SID. It can be given as a decimal or hexadecimal value, or by using one
474       of the following text strings which map to the NT file permissions of
475       the same name.
476
477R - Allow read access
478
479W - Allow write access
480
481X - Execute permission on the object
482
483D - Delete the object
484
485P - Change permissions
486
487O - Take ownership
488
489
490       The following combined permissions can be specified:
491
492READ - Equivalent to 'RX' permissions
493
494CHANGE - Equivalent to 'RXWD' permissions
495
496FULL - Equivalent to 'RWXDPO' permissions
497

INHERITANCE

499       Per-ACE inheritance flags can be set in the ACE flags field. By
500       default, inheritable ACEs e.g. those marked for object inheritance (OI)
501       or container inheritance (CI), are not propagated to sub-files or
502       folders. However, with the --propagate-inheritance argument specified,
503       such ACEs are automatically propagated according to some inheritance
504       rules.
505
506              •   Inheritable (OI)(OI) ACE flags can only be applied to
507                  folders.
508
509              •   Any inheritable ACEs applied to sub-files or folders are
510                  marked with the inherited (I) flag. Inheritable ACE(s) are
511                  applied to folders unless the no propagation (NP) flag is
512                  set.
513
514              •   When an ACE with the (OI) flag alone set is progagated to a
515                  child folder the inheritance only flag (IO) is also applied.
516                  This indicates the permissions associated with the ACE don't
517                  apply to the folder itself (only to it's child files). When
518                  applying the ACE to a child file the ACE is inherited as
519                  normal.
520
521              •   When an ace with the (CI) flag alone set is propagated to a
522                  child file there is no effect, when propagated to a child
523                  folder it is inherited as normal.
524
525              •   When an ACE that has both (OI) & (CI) flags set the ACE is
526                  inherited as normal by both folders and files.
527
528
529       (OI)(READ) added to parent folder
530
531           +-parent/        (OI)(READ)
532           | +-file.1       (I)(READ)
533           | +-nested/      (OI)(IO)(I)(READ)
534             |   +-file.2   (I)(READ)
535
536       (CI)(READ) added to parent folder
537
538           +-parent/        (CI)(READ)
539           | +-file.1
540           | +-nested/      (CI)(I)(READ)
541             |   +-file.2
542
543       (OI)(CI)(READ) added to parent folder
544
545           +-parent/        (OI)(CI)(READ)
546           | +-file.1       (I)(READ)
547           | +-nested/      (OI)(CI)(I)(READ)
548             |   +-file.2   (I)(READ)
549
550       (OI)(NP)(READ) added to parent folder
551
552           +-oi_dir/        (OI)(NP)(READ)
553           | +-file.1       (I)(READ)
554           | +-nested/
555           |   +-file.2
556
557       (CI)(NP)(READ) added to parent folder
558
559           +-oi_dir/        (CI)(NP)(READ)
560           | +-file.1
561           | +-nested/      (I)(READ)
562           |   +-file.2
563
564       (OI)(CI)(NP)(READ) added to parent folder
565
566           +-parent/        (CI)(OI)(NP)(READ)
567           | +-file.1       (I)(READ)
568           | +-nested/      (I)(READ)
569           |   +-file.2
570
571       Files and folders with protected ACLs do not allow inheritable
572       permissions (set with -I). Such objects will not receive ACEs flagged
573       for inheritance with (CI) or (OI).
574

EXIT STATUS

576       The smbcacls program sets the exit status depending on the success or
577       otherwise of the operations performed. The exit status may be one of
578       the following values.
579
580       If the operation succeeded, smbcacls returns and exit status of 0. If
581       smbcacls couldn't connect to the specified server, or there was an
582       error getting or setting the ACLs, an exit status of 1 is returned. If
583       there was an error parsing any command line arguments, an exit status
584       of 2 is returned.
585

VERSION

587       This man page is part of version 4.16.2 of the Samba suite.
588

AUTHOR

590       The original Samba software and related utilities were created by
591       Andrew Tridgell. Samba is now developed by the Samba Team as an Open
592       Source project similar to the way the Linux kernel is developed.
593
594       smbcacls was written by Andrew Tridgell and Tim Potter.
595
596       The conversion to DocBook for Samba 2.2 was done by Gerald Carter. The
597       conversion to DocBook XML 4.2 for Samba 3.0 was done by Alexander
598       Bokovoy.
599
600
601
602Samba 4.16.2                      06/13/2022                       SMBCACLS(1)
Impressum