chmod/chmod.1

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