chmod/chmod.1

   1 .\"-
   2 .\" Copyright (c) 1989, 1990, 1993, 1994
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to Berkeley by
   6 .\" the Institute of Electrical and Electronics Engineers, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)chmod.1     8.4 (Berkeley) 3/31/94
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd January 7, 2017
  36 .Dt CHMOD 1
  37 .Os
  38 .Sh NAME
  39 .Nm chmod
  40 .Nd change file modes or Access Control Lists
  41 .Sh SYNOPSIS
  42 .Nm chmod
  43 .Op Fl fv
  44 .Op Fl R Op Fl H | L | P
  45 .Ar mode
  46 .Ar
  47 .Nm chmod
  48 .Op Fl fv
  49 .Op Fl R Op Fl H | L | P
  50 .Op -a | +a | =a
  51 .Ar ACE
  52 .Ar
  53 .Nm chmod
  54 .Op Fl fhv
  55 .Op Fl R Op Fl H | L | P
  56 .Op Fl E
  57 .Ar
  58 .Nm chmod
  59 .Op Fl fhv
  60 .Op Fl R Op Fl H | L | P
  61 .Op Fl C
  62 .Ar
  63 .Nm chmod
  64 .Op Fl fhv
  65 .Op Fl R Op Fl H | L | P
  66 .Op Fl N
  67 .Ar
  68 .Sh DESCRIPTION
  69 The
  70 .Nm chmod
  71 utility modifies the file mode bits of the listed files
  72 as specified by the
  73 .Ar mode
  74 operand. It may also be used to modify the Access Control
  75 Lists (ACLs) associated with the listed files.
  76 .Pp
  77 The generic options are as follows:
  78 .Bl -tag -width indent
  79 .It Fl f
  80 Do not display a diagnostic message if
  81 .Nm chmod
  82 could not modify the mode for
  83 .Va file ,
  84 nor modify the exit status to reflect such failures.
  85 .It Fl H
  86 If the
  87 .Fl R
  88 option is specified, symbolic links on the command line are followed
  89 and hence unaffected by the command.
  90 (Symbolic links encountered during tree traversal are not followed.)
  91 .It Fl h
  92 If the file is a symbolic link, change the mode of the link itself
  93 rather than the file that the link points to.
  94 .It Fl L
  95 If the
  96 .Fl R
  97 option is specified, all symbolic links are followed.
  98 .It Fl P
  99 If the
 100 .Fl R
 101 option is specified, no symbolic links are followed.
 102 This is the default.
 103 .It Fl R
 104 Change the modes of the file hierarchies rooted in the files,
 105 instead of just the files themselves.
 106 Beware of unintentionally matching the
 107 .Dq Pa ".."
 108 hard link to the parent directory when using wildcards like
 109 .Dq Li ".*" .
 110 .It Fl v
 111 Cause
 112 .Nm chmod
 113 to be verbose, showing filenames as the mode is modified.
 114 If the
 115 .Fl v
 116 flag is specified more than once, the old and new modes of the file
 117 will also be printed, in both octal and symbolic notation.
 118 .El
 119 .Pp
 120 The
 121 .Fl H ,
 122 .Fl L
 123 and
 124 .Fl P
 125 options are ignored unless the
 126 .Fl R
 127 option is specified.
 128 In addition, these options override each other and the
 129 command's actions are determined by the last one specified.
 130 .Pp
 131 If
 132 .Nm chmod
 133 receives a
 134 .Dv SIGINFO
 135 signal (see the
 136 .Cm status
 137 argument for
 138 .Xr stty 1 ) ,
 139 then the current filename as well as the old and new modes are displayed.
 140 .Pp
 141 Only the owner of a file or the super-user is permitted to change
 142 the mode of a file.
 143 .Sh EXIT STATUS
 144 .Ex -std
 145 .Sh MODES
 146 Modes may be absolute or symbolic.
 147 An absolute mode is an octal number constructed from the sum of
 148 one or more of the following values:
 149 .Pp
 150 .Bl -tag -width 6n -compact -offset indent
 151 .It Li 4000
 152 (the setuid bit).
 153 Executable files with this bit set
 154 will run with effective uid set to the uid of the file owner.
 155 Directories with this bit set will force all files and
 156 sub-directories created in them to be owned by the directory owner
 157 and not by the uid of the creating process, if the underlying file
 158 system supports this feature: see
 159 .Xr chmod 2
 160 and the
 161 .Cm suiddir
 162 option to
 163 .Xr mount 8 .
 164 .It Li 2000
 165 (the setgid bit).
 166 Executable files with this bit set
 167 will run with effective gid set to the gid of the file owner.
 168 .It Li 1000
 169 (the sticky bit).
 170 See
 171 .Xr chmod 2
 172 and
 173 .Xr sticky 7 .
 174 .It Li 0400
 175 Allow read by owner.
 176 .It Li 0200
 177 Allow write by owner.
 178 .It Li 0100
 179 For files, allow execution by owner.
 180 For directories, allow the owner to
 181 search in the directory.
 182 .It Li 0040
 183 Allow read by group members.
 184 .It Li 0020
 185 Allow write by group members.
 186 .It Li 0010
 187 For files, allow execution by group members.
 188 For directories, allow
 189 group members to search in the directory.
 190 .It Li 0004
 191 Allow read by others.
 192 .It Li 0002
 193 Allow write by others.
 194 .It Li 0001
 195 For files, allow execution by others.
 196 For directories allow others to
 197 search in the directory.
 198 .El
 199 .Pp
 200 For example, the absolute mode that permits read, write and execute by
 201 the owner, read and execute by group members, read and execute by
 202 others, and no set-uid or set-gid behaviour is 755
 203 (400+200+100+040+010+004+001).
 204 .Pp
 205 The symbolic mode is described by the following grammar:
 206 .Bd -literal -offset indent
 207 mode         ::= clause [, clause ...]
 208 clause       ::= [who ...] [action ...] action
 209 action       ::= op [perm ...]
 210 who          ::= a | u | g | o
 211 op           ::= + | \- | =
 212 perm         ::= r | s | t | w | x | X | u | g | o
 213 .Ed
 214 .Pp
 215 The
 216 .Ar who
 217 symbols ``u'', ``g'', and ``o'' specify the user, group, and other parts
 218 of the mode bits, respectively.
 219 The
 220 .Ar who
 221 symbol ``a'' is equivalent to ``ugo''.
 222 .Pp
 223 The
 224 .Ar perm
 225 symbols represent the portions of the mode bits as follows:
 226 .Pp
 227 .Bl -tag -width Ds -compact -offset indent
 228 .It r
 229 The read bits.
 230 .It s
 231 The set-user-ID-on-execution and set-group-ID-on-execution bits.
 232 .It t
 233 The sticky bit.
 234 .It w
 235 The write bits.
 236 .It x
 237 The execute/search bits.
 238 .It X
 239 The execute/search bits if the file is a directory or any of the
 240 execute/search bits are set in the original (unmodified) mode.
 241 Operations with the
 242 .Ar perm
 243 symbol ``X'' are only meaningful in conjunction with the
 244 .Ar op
 245 symbol ``+'', and are ignored in all other cases.
 246 .It u
 247 The user permission bits in the original mode of the file.
 248 .It g
 249 The group permission bits in the original mode of the file.
 250 .It o
 251 The other permission bits in the original mode of the file.
 252 .El
 253 .Pp
 254 The
 255 .Ar op
 256 symbols represent the operation performed, as follows:
 257 .Bl -tag -width 4n
 258 .It +
 259 If no value is supplied for
 260 .Ar perm ,
 261 the ``+'' operation has no effect.
 262 If no value is supplied for
 263 .Ar who ,
 264 each permission bit specified in
 265 .Ar perm ,
 266 for which the corresponding bit in the file mode creation mask
 267 (see
 268 .Xr umask 2 )
 269 is clear, is set.
 270 Otherwise, the mode bits represented by the specified
 271 .Ar who
 272 and
 273 .Ar perm
 274 values are set.
 275 .It \&\-
 276 If no value is supplied for
 277 .Ar perm ,
 278 the ``\-'' operation has no effect.
 279 If no value is supplied for
 280 .Ar who ,
 281 each permission bit specified in
 282 .Ar perm ,
 283 for which the corresponding bit in the file mode creation mask
 284 is set, is cleared.
 285 Otherwise, the mode bits represented by the specified
 286 .Ar who
 287 and
 288 .Ar perm
 289 values are cleared.
 290 .It =
 291 The mode bits specified by the
 292 .Ar who
 293 value are cleared, or, if no
 294 .Ar who
 295 value is specified, the owner, group
 296 and other mode bits are cleared.
 297 Then, if no value is supplied for
 298 .Ar who ,
 299 each permission bit specified in
 300 .Ar perm ,
 301 for which the corresponding bit in the file mode creation mask
 302 is clear, is set.
 303 Otherwise, the mode bits represented by the specified
 304 .Ar who
 305 and
 306 .Ar perm
 307 values are set.
 308 .El
 309 .Pp
 310 Each
 311 .Ar clause
 312 specifies one or more operations to be performed on the mode
 313 bits, and each operation is applied to the mode bits in the
 314 order specified.
 315 .Pp
 316 Operations upon the other permissions only (specified by the symbol
 317 ``o'' by itself), in combination with the
 318 .Ar perm
 319 symbols ``s'' or ``t'', are ignored.
 320 .Pp
 321 The ``w'' permission on directories will permit file creation, relocation,
 322 and copy into that directory.
 323 Files created within the directory itself will inherit its group ID.
 324 .Sh EXAMPLES OF VALID MODES
 325 .Bl -tag -width "u=rwx,go=u-w" -compact
 326 .It Li 644
 327 make a file readable by anyone and writable by the owner only.
 328 .Pp
 329 .It Li go-w
 330 deny write permission to group and others.
 331 .Pp
 332 .It Li =rw,+X
 333 set the read and write permissions to the usual defaults, but
 334 retain any execute permissions that are currently set.
 335 .Pp
 336 .It Li +X
 337 make a directory or file searchable/executable by everyone if it is
 338 already searchable/executable by anyone.
 339 .Pp
 340 .It Li 755
 341 .It Li u=rwx,go=rx
 342 .It Li u=rwx,go=u-w
 343 make a file readable/executable by everyone and writable by the owner only.
 344 .Pp
 345 .It Li go=
 346 clear all mode bits for group and others.
 347 .Pp
 348 .It Li g=u-w
 349 set the group bits equal to the user bits, but clear the group write bit.
 350 .El
 351 .Sh ACL MANIPULATION OPTIONS
 352 ACLs are manipulated using extensions to the symbolic mode
 353 grammar.  Each file has one ACL, containing an ordered list of entries.
 354 Each entry refers to a user or group, and grants or denies a set of
 355 permissions.
 356 In cases where a user and a group exist with the same name, the
 357 user/group name can be prefixed with "user:" or "group:" in order to
 358 specify the type of name.
 359 .Pp
 360 If the user or group name contains spaces you can use ':' as the delimiter
 361 between name and permission.
 362 .Pp
 363 The following permissions are applicable to all filesystem objects:
 364 .Bl -tag -width 6n -compact -offset indent
 365 .It delete
 366 Delete the item.  Deletion may be granted by either this permission
 367 on an object or the delete_child right on the containing directory.
 368 .It readattr
 369 Read an object's basic attributes.  This is implicitly granted if
 370 the object can be looked up and not explicitly denied.
 371 .It writeattr
 372 Write an object's basic attributes.
 373 .It readextattr
 374 Read extended attributes.
 375 .It writeextattr
 376 Write extended attributes.
 377 .It readsecurity
 378 Read an object's extended security information (ACL).
 379 .It writesecurity
 380 Write an object's security information (ownership, mode, ACL).
 381 .It chown
 382 Change an object's ownership.
 383 .El
 384 .Pp
 385 The following permissions are applicable to directories:
 386 .Bl -tag -width 6n -compact -offset indent
 387 .It list
 388 List entries.
 389 .It search
 390 Look up files by name.
 391 .It add_file
 392 Add a file.
 393 .It add_subdirectory
 394 Add a subdirectory.
 395 .It delete_child
 396 Delete a contained object.  See the file delete permission above.
 397 .El
 398 .Pp
 399 The following permissions are applicable to non-directory filesystem objects:
 400 .Bl -tag -width 6n -compact -offset indent
 401 .It read
 402 Open for reading.
 403 .It write
 404 Open for writing.
 405 .It append
 406 Open for writing, but in a fashion that only allows writes into areas of
 407 the file not previously written.
 408 .It execute
 409 Execute the file as a script or program.
 410 .El
 411 .Pp
 412 ACL inheritance is controlled with the following permissions words, which
 413 may only be applied to directories:
 414 .Bl -tag -width 6n -compact -offset indent
 415 .It file_inherit
 416 Inherit to files.
 417 .It directory_inherit
 418 Inherit to directories.
 419 .It limit_inherit
 420 This flag is only relevant to entries inherited by subdirectories; it
 421 causes the directory_inherit flag to be cleared in the entry that is
 422 inherited, preventing further nested subdirectories from also
 423 inheriting the entry.
 424 .It only_inherit
 425 The entry is inherited by created items but not considered when processing
 426 the ACL.
 427 .El
 428 .Pp
 429 The ACL manipulation options are as follows:
 430 .Bl -tag -width Ds
 431 .It \fB+a\fR
 432 The +a mode parses a new ACL entry from the next argument on
 433 the commandline and inserts it into the canonical location in the
 434 ACL. If the supplied entry refers to an identity already listed, the
 435 two entries are combined.
 436 .Pp
 437 \fBExamples\fR
 438  # ls -le
 439  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 440  # chmod +a "admin allow write" file1
 441  # ls -le
 442  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 443    owner: juser
 444    1: admin allow write
 445  # chmod +a "guest deny read" file1
 446  # ls -le
 447  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 448    owner: juser
 449    1: guest deny read
 450    2: admin allow write
 451  # chmod +a "admin allow delete" file1
 452  # ls -le
 453  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 454    owner: juser
 455    1: guest deny read
 456    2: admin allow write,delete
 457  # chmod +a "User 1:allow:read" file
 458  # ls -le
 459  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 460    owner: juser
 461    1: guest deny read
 462    2: User 1 allow read
 463    3: admin allow write,delete
 464 .Pp
 465 The +a mode strives to maintain correct canonical form for the ACL.
 466                  local deny
 467                  local allow
 468                  inherited deny
 469                  inherited allow
 470 .Pp
 471 By default, chmod adds entries to the top of the local deny and local
 472 allow lists. Inherited entries are added by using the +ai mode.
 473 .Pp
 474 \fBExamples\fR
 475  # ls -le
 476  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 477    owner: juser
 478    1: guest deny read
 479    2: admin allow write,delete
 480    3: juser inherited deny delete
 481    4: admin inherited allow delete
 482    5: backup inherited deny read
 483    6: admin inherited allow write-security
 484  # chmod +ai "others allow read" file1
 485  # ls -le
 486  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 487    owner: juser
 488    1: guest deny read
 489    2: admin allow write,delete
 490    3: juser inherited deny delete
 491    4: others inherited allow read
 492    5: admin inherited allow delete
 493    6: backup inherited deny read
 494    7: admin inherited allow write-security
 495 .It \fB+a#\fR
 496 When a specific ordering is required, the exact location at which an
 497 entry will be inserted is specified with the +a# mode.
 498 .Pp
 499 \fBExamples\fR
 500  # ls -le
 501  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 502    owner: juser
 503    1: guest deny read
 504    2: admin allow write
 505  # chmod +a# 2 "others deny read" file1
 506  # ls -le
 507  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 508    owner: juser
 509    1: guest deny read
 510    2: others deny read
 511    3: admin allow write
 512 .Pp
 513 The +ai# mode may be used to insert inherited entries at a specific
 514 location. Note that these modes allow non-canonical ACL ordering to
 515 be constructed.
 516 .It Fl a
 517 The -a mode is used to delete ACL entries. All entries exactly
 518 matching the supplied entry will be deleted. If the entry lists a
 519 subset of rights granted by an entry, only the rights listed are
 520 removed. Entries may also be deleted by index using the -a# mode.
 521 .Pp
 522 \fBExamples\fR
 523  # ls -le
 524  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 525    owner: juser
 526    1: guest deny read
 527    2: admin allow write,delete
 528  # chmod -a# 1 file1
 529  # ls -le
 530  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 531    owner: juser
 532    1: admin allow write,delete
 533  # chmod -a "admin allow write" file1
 534  # ls -le
 535  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 536    owner: juser
 537    1: admin allow delete
 538 .Pp
 539 Inheritance is not considered when processing the -a mode; rights and
 540 entries will be removed regardless of their inherited state.
 541 .Pp
 542 If the user or group name contains spaces you can use ':' as the delimiter
 543 .Pp
 544 \fBExample\fR
 545  # chmod +a "User 1:allow:read" file
 546 .It \fB=a#\fR
 547 Individual entries are rewritten using the =a# mode.
 548 .Pp
 549 \fBExamples\fR
 550  # ls -le
 551  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 552    owner: juser
 553    1: admin allow delete
 554  # chmod =a# 1 "admin allow write,chown"
 555  # ls -le
 556  -rw-r--r--+ 1 juser  wheel  0 Apr 28 14:06 file1
 557    owner: juser
 558    1: admin allow write,chown
 559 .Pp
 560 This mode may not be used to add new entries.
 561 .It Fl E
 562 Reads the ACL information from stdin, as a sequential list
 563 of ACEs, separated by newlines.  If the information parses correctly,
 564 the existing information is replaced.
 565 .It Fl C
 566 Returns false if any of the named files have ACLs in non-canonical order.
 567 .It Fl i
 568 Removes the 'inherited' bit from all entries in the named file(s) ACLs.
 569 .It Fl I
 570 Removes all inherited entries from the named file(s) ACL(s).
 571 .It Fl N
 572 Removes the ACL from the named file(s).
 573 .El
 574 .Sh COMPATIBILITY
 575 The
 576 .Fl v
 577 option is non-standard and its use in scripts is not recommended.
 578 .Sh SEE ALSO
 579 .Xr chflags 1 ,
 580 .Xr install 1 ,
 581 .Xr chmod 2 ,
 582 .Xr stat 2 ,
 583 .Xr umask 2 ,
 584 .Xr fts 3 ,
 585 .Xr setmode 3 ,
 586 .Xr sticky 7 ,
 587 .Xr symlink 7 ,
 588 .Xr chown 8 ,
 589 .Xr mount 8
 590 .Sh STANDARDS
 591 The
 592 .Nm chmod
 593 utility is expected to be
 594 .St -p1003.2
 595 compatible with the exception of the
 596 .Ar perm
 597 symbol
 598 .Dq t
 599 which is not included in that standard.
 600 .Sh HISTORY
 601 A
 602 .Nm chmod
 603 command appeared in
 604 .At v1 .