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