1: @c File mode bits
    2: 
    3: @c Copyright (C) 1994, 1996, 1999, 2000, 2001, 2003, 2004, 2005, 2006
    4: @c Free Software Foundation, Inc.
    5: 
    6: @c Permission is granted to copy, distribute and/or modify this document
    7: @c under the terms of the GNU Free Documentation License, Version 1.2 or
    8: @c any later version published by the Free Software Foundation; with no
    9: @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
   10: @c Texts.  A copy of the license is included in the ``GNU Free
   11: @c Documentation License'' file as part of this distribution.
   12: 
   13: Each file has a set of @dfn{file mode bits} that control the kinds of
   14: access that users have to that file.  They can be represented either in
   15: symbolic form or as an octal number.
   16: 
   17: @menu
   18: * Mode Structure::              Structure of file mode bits.
   19: * Symbolic Modes::              Mnemonic representation of file mode bits.
   20: * Numeric Modes::               File mode bits as octal numbers.
   21: * Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories.
   22: @end menu
   23: 
   24: @node Mode Structure
   25: @section Structure of File Mode Bits
   26: 
   27: The file mode bits have two parts: the @dfn{file permission bits},
   28: which control ordinary access to the file, and @dfn{special mode
   29: bits}, which affect only some files.
   30: 
   31: There are three kinds of permissions that a user can have for a file:
   32: 
   33: @enumerate
   34: @item
   35: @cindex read permission
   36: permission to read the file.  For directories, this means permission to
   37: list the contents of the directory.
   38: @item
   39: @cindex write permission
   40: permission to write to (change) the file.  For directories, this means
   41: permission to create and remove files in the directory.
   42: @item
   43: @cindex execute/search permission
   44: permission to execute the file (run it as a program).  For directories,
   45: this means permission to access files in the directory.
   46: @end enumerate
   47: 
   48: There are three categories of users who may have different permissions
   49: to perform any of the above operations on a file:
   50: 
   51: @enumerate
   52: @item
   53: the file's owner;
   54: @item
   55: other users who are in the file's group;
   56: @item
   57: everyone else.
   58: @end enumerate
   59: 
   60: @cindex owner, default
   61: @cindex group owner, default
   62: Files are given an owner and group when they are created.  Usually the
   63: owner is the current user and the group is the group of the directory
   64: the file is in, but this varies with the operating system, the
   65: file system the file is created on, and the way the file is created.  You
   66: can change the owner and group of a file by using the @command{chown} and
   67: @command{chgrp} commands.
   68: 
   69: In addition to the three sets of three permissions listed above, the
   70: file mode bits have three special components, which affect only
   71: executable files (programs) and, on most systems, directories:
   72: 
   73: @enumerate
   74: @item
   75: @cindex set-user-ID
   76: @cindex setuid
   77: Set the process's effective user ID to that of the file upon execution
   78: (called the @dfn{set-user-ID bit}, or sometimes the @dfn{setuid bit}).
   79: For directories on a few systems, give files created in the directory
   80: the same owner as the directory, no matter who creates them, and set
   81: the set-user-ID bit of newly-created subdirectories.
   82: @item
   83: @cindex set-group-ID
   84: @cindex setgid
   85: Set the process's effective group ID to that of the file upon execution
   86: (called the @dfn{set-group-ID bit}, or sometimes the @dfn{setgid bit}).
   87: For directories on most systems, give files created in the directory
   88: the same group as the directory, no matter what group the user who
   89: creates them is in, and set the set-group-ID bit of newly-created
   90: subdirectories.
   91: @item
   92: @cindex sticky
   93: @cindex swap space, saving text image in
   94: @cindex text image, saving in swap space
   95: @cindex restricted deletion flag
   96: Prevent unprivileged users from removing or renaming a file in a directory
   97: unless they own the file or the directory; this is called the
   98: @dfn{restricted deletion flag} for the directory, and is commonly
   99: found on world-writable directories like @file{/tmp}.
  100: 
  101: For regular files on some older systems, save the program's text image on the
  102: swap device so it will load more quickly when run; this is called the
  103: @dfn{sticky bit}.
  104: @end enumerate
  105: 
  106: In addition to the file mode bits listed above, there may be file attributes
  107: specific to the file system, e.g., access control lists (ACLs), whether a
  108: file is compressed, whether a file can be modified (immutability), and whether
  109: a file can be dumped.  These are usually set using programs
  110: specific to the file system.  For example:
  111: @c should probably say a lot more about ACLs... someday
  112: 
  113: @table @asis
  114: @item ext2
  115: On @acronym{GNU} and @acronym{GNU}/Linux the file attributes specific to
  116: the ext2 file system are set using @command{chattr}.
  117: 
  118: @item FFS
  119: On FreeBSD the file flags specific to the FFS
  120: file system are set using @command{chflags}.
  121: @end table
  122: 
  123: Even if a file's mode bits allow an operation on that file,
  124: that operation may still fail, because:
  125: 
  126: @itemize
  127: @item
  128: the file-system-specific attributes or flags do not permit it; or
  129: 
  130: @item
  131: the file system is mounted as read-only.
  132: @end itemize
  133: 
  134: For example, if the immutable attribute is set on a file,
  135: it cannot be modified, regardless of the fact that you
  136: may have just run @code{chmod a+w FILE}.
  137: 
  138: @node Symbolic Modes
  139: @section Symbolic Modes
  140: 
  141: @cindex symbolic modes
  142: @dfn{Symbolic modes} represent changes to files' mode bits as
  143: operations on single-character symbols.  They allow you to modify either
  144: all or selected parts of files' mode bits, optionally based on
  145: their previous values, and perhaps on the current @code{umask} as well
  146: (@pxref{Umask and Protection}).
  147: 
  148: The format of symbolic modes is:
  149: 
  150: @example
  151: @r{[}ugoa@dots{}@r{][}+-=@r{]}@var{perms}@dots{}@r{[},@dots{}@r{]}
  152: @end example
  153: 
  154: @noindent
  155: where @var{perms} is either zero or more letters from the set
  156: @samp{rwxXst}, or a single letter from the set @samp{ugo}.
  157: 
  158: The following sections describe the operators and other details of
  159: symbolic modes.
  160: 
  161: @menu
  162: * Setting Permissions::          Basic operations on permissions.
  163: * Copying Permissions::          Copying existing permissions.
  164: * Changing Special Mode Bits::   Special mode bits.
  165: * Conditional Executability::    Conditionally affecting executability.
  166: * Multiple Changes::             Making multiple changes.
  167: * Umask and Protection::              The effect of the umask.
  168: @end menu
  169: 
  170: @node Setting Permissions
  171: @subsection Setting Permissions
  172: 
  173: The basic symbolic operations on a file's permissions are adding,
  174: removing, and setting the permission that certain users have to read,
  175: write, and execute or search the file.  These operations have the following
  176: format:
  177: 
  178: @example
  179: @var{users} @var{operation} @var{permissions}
  180: @end example
  181: 
  182: @noindent
  183: The spaces between the three parts above are shown for readability only;
  184: symbolic modes cannot contain spaces.
  185: 
  186: The @var{users} part tells which users' access to the file is changed.
  187: It consists of one or more of the following letters (or it can be empty;
  188: @pxref{Umask and Protection}, for a description of what happens then).  When
  189: more than one of these letters is given, the order that they are in does
  190: not matter.
  191: 
  192: @table @code
  193: @item u
  194: @cindex owner of file, permissions for
  195: the user who owns the file;
  196: @item g
  197: @cindex group, permissions for
  198: other users who are in the file's group;
  199: @item o
  200: @cindex other permissions
  201: all other users;
  202: @item a
  203: all users; the same as @samp{ugo}.
  204: @end table
  205: 
  206: The @var{operation} part tells how to change the affected users' access
  207: to the file, and is one of the following symbols:
  208: 
  209: @table @code
  210: @item +
  211: @cindex adding permissions
  212: to add the @var{permissions} to whatever permissions the @var{users}
  213: already have for the file;
  214: @item -
  215: @cindex removing permissions
  216: @cindex subtracting permissions
  217: to remove the @var{permissions} from whatever permissions the
  218: @var{users} already have for the file;
  219: @item =
  220: @cindex setting permissions
  221: to make the @var{permissions} the only permissions that the @var{users}
  222: have for the file.
  223: @end table
  224: 
  225: The @var{permissions} part tells what kind of access to the file should
  226: be changed; it is normally zero or more of the following letters.  As with the
  227: @var{users} part, the order does not matter when more than one letter is
  228: given.  Omitting the @var{permissions} part is useful only with the
  229: @samp{=} operation, where it gives the specified @var{users} no access
  230: at all to the file.
  231: 
  232: @table @code
  233: @item r
  234: @cindex read permission, symbolic
  235: the permission the @var{users} have to read the file;
  236: @item w
  237: @cindex write permission, symbolic
  238: the permission the @var{users} have to write to the file;
  239: @item x
  240: @cindex execute/search permission, symbolic
  241: the permission the @var{users} have to execute the file,
  242: or search it if it is a directory.
  243: @end table
  244: 
  245: For example, to give everyone permission to read and write a regular file,
  246: but not to execute it, use:
  247: 
  248: @example
  249: a=rw
  250: @end example
  251: 
  252: To remove write permission for all users other than the file's
  253: owner, use:
  254: 
  255: @example
  256: go-w
  257: @end example
  258: 
  259: @noindent
  260: The above command does not affect the access that the owner of
  261: the file has to it, nor does it affect whether other users can
  262: read or execute the file.
  263: 
  264: To give everyone except a file's owner no permission to do anything with
  265: that file, use the mode below.  Other users could still remove the file,
  266: if they have write permission on the directory it is in.
  267: 
  268: @example
  269: go=
  270: @end example
  271: 
  272: @noindent
  273: Another way to specify the same thing is:
  274: 
  275: @example
  276: og-rwx
  277: @end example
  278: 
  279: @node Copying Permissions
  280: @subsection Copying Existing Permissions
  281: 
  282: @cindex copying existing permissions
  283: @cindex permissions, copying existing
  284: You can base a file's permissions on its existing permissions.  To do
  285: this, instead of using a series of @samp{r}, @samp{w}, or @samp{x}
  286: letters after the
  287: operator, you use the letter @samp{u}, @samp{g}, or @samp{o}.  For
  288: example, the mode
  289: 
  290: @example
  291: o+g
  292: @end example
  293: 
  294: @noindent
  295: adds the permissions for users who are in a file's group to the
  296: permissions that other users have for the file.  Thus, if the file
  297: started out as mode 664 (@samp{rw-rw-r--}), the above mode would change
  298: it to mode 666 (@samp{rw-rw-rw-}).  If the file had started out as mode
  299: 741 (@samp{rwxr----x}), the above mode would change it to mode 745
  300: (@samp{rwxr--r-x}).  The @samp{-} and @samp{=} operations work
  301: analogously.
  302: 
  303: @node Changing Special Mode Bits
  304: @subsection Changing Special Mode Bits
  305: 
  306: @cindex changing special mode bits
  307: In addition to changing a file's read, write, and execute/search permissions,
  308: you can change its special mode bits.  @xref{Mode Structure}, for a
  309: summary of these special mode bits.
  310: 
  311: To change the file mode bits to set the user ID on execution, use
  312: @samp{u} in the @var{users} part of the symbolic mode and
  313: @samp{s} in the @var{permissions} part.
  314: 
  315: To change the file mode bits to set the group ID on execution, use
  316: @samp{g} in the @var{users} part of the symbolic mode and
  317: @samp{s} in the @var{permissions} part.
  318: 
  319: To set both user and group ID on execution, omit the @var{users} part
  320: of the symbolic mode (or use @samp{a}) and use @samp{s} in the
  321: @var{permissions} part.
  322: 
  323: To change the file mode bits to set the restricted deletion flag or sticky bit,
  324: omit the @var{users} part of the symbolic mode (or use @samp{a}) and use
  325: @samp{t} in the @var{permissions} part.
  326: 
  327: For example, to set the set-user-ID mode bit of a program,
  328: you can use the mode:
  329: 
  330: @example
  331: u+s
  332: @end example
  333: 
  334: To remove both set-user-ID and set-group-ID mode bits from
  335: it, you can use the mode:
  336: 
  337: @example
  338: a-s
  339: @end example
  340: 
  341: To set the restricted deletion flag or sticky bit, you can use
  342: the mode:
  343: 
  344: @example
  345: +t
  346: @end example
  347: 
  348: The combination @samp{o+s} has no effect.  On @acronym{GNU} systems
  349: the combinations @samp{u+t} and @samp{g+t} have no effect, and
  350: @samp{o+t} acts like plain @samp{+t}.
  351: 
  352: The @samp{=} operator is not very useful with special mode bits.
  353: For example, the mode:
  354: 
  355: @example
  356: o=t
  357: @end example
  358: 
  359: @noindent
  360: does set the restricted deletion flag or sticky bit, but it also
  361: removes all read, write, and execute/search permissions that users not in the
  362: file's group might have had for it.
  363: 
  364: @xref{Directory Setuid and Setgid}, for additional rules concerning
  365: set-user-ID and set-group-ID bits and directories.
  366: 
  367: @node Conditional Executability
  368: @subsection Conditional Executability
  369: 
  370: @cindex conditional executability
  371: There is one more special type of symbolic permission: if you use
  372: @samp{X} instead of @samp{x}, execute/search permission is affected only if the
  373: file is a directory or already had execute permission.
  374: 
  375: For example, this mode:
  376: 
  377: @example
  378: a+X
  379: @end example
  380: 
  381: @noindent
  382: gives all users permission to search directories, or to execute files if
  383: anyone could execute them before.
  384: 
  385: @node Multiple Changes
  386: @subsection Making Multiple Changes
  387: 
  388: @cindex multiple changes to permissions
  389: The format of symbolic modes is actually more complex than described
  390: above (@pxref{Setting Permissions}).  It provides two ways to make
  391: multiple changes to files' mode bits.
  392: 
  393: The first way is to specify multiple @var{operation} and
  394: @var{permissions} parts after a @var{users} part in the symbolic mode.
  395: 
  396: For example, the mode:
  397: 
  398: @example
  399: og+rX-w
  400: @end example
  401: 
  402: @noindent
  403: gives users other than the owner of the file read permission and, if
  404: it is a directory or if someone already had execute permission
  405: to it, gives them execute/search permission; and it also denies them write
  406: permission to the file.  It does not affect the permission that the
  407: owner of the file has for it.  The above mode is equivalent to
  408: the two modes:
  409: 
  410: @example
  411: og+rX
  412: og-w
  413: @end example
  414: 
  415: The second way to make multiple changes is to specify more than one
  416: simple symbolic mode, separated by commas.  For example, the mode:
  417: 
  418: @example
  419: a+r,go-w
  420: @end example
  421: 
  422: @noindent
  423: gives everyone permission to read the file and removes write
  424: permission on it for all users except its owner.  Another example:
  425: 
  426: @example
  427: u=rwx,g=rx,o=
  428: @end example
  429: 
  430: @noindent
  431: sets all of the permission bits for the file explicitly.  (It
  432: gives users who are not in the file's group no permission at all for
  433: it.)
  434: 
  435: The two methods can be combined.  The mode:
  436: 
  437: @example
  438: a+r,g+x-w
  439: @end example
  440: 
  441: @noindent
  442: gives all users permission to read the file, and gives users who are in
  443: the file's group permission to execute/search it as well, but not permission
  444: to write to it.  The above mode could be written in several different
  445: ways; another is:
  446: 
  447: @example
  448: u+r,g+rx,o+r,g-w
  449: @end example
  450: 
  451: @node Umask and Protection
  452: @subsection The Umask and Protection
  453: 
  454: @cindex umask and modes
  455: @cindex modes and umask
  456: If the @var{users} part of a symbolic mode is omitted, it defaults to
  457: @samp{a} (affect all users), except that any permissions that are
  458: @emph{set} in the system variable @code{umask} are @emph{not affected}.
  459: The value of @code{umask} can be set using the
  460: @code{umask} command.  Its default value varies from system to system.
  461: 
  462: @cindex giving away permissions
  463: Omitting the @var{users} part of a symbolic mode is generally not useful
  464: with operations other than @samp{+}.  It is useful with @samp{+} because
  465: it allows you to use @code{umask} as an easily customizable protection
  466: against giving away more permission to files than you intended to.
  467: 
  468: As an example, if @code{umask} has the value 2, which removes write
  469: permission for users who are not in the file's group, then the mode:
  470: 
  471: @example
  472: +w
  473: @end example
  474: 
  475: @noindent
  476: adds permission to write to the file to its owner and to other users who
  477: are in the file's group, but @emph{not} to other users.  In contrast,
  478: the mode:
  479: 
  480: @example
  481: a+w
  482: @end example
  483: 
  484: @noindent
  485: ignores @code{umask}, and @emph{does} give write permission for
  486: the file to all users.
  487: 
  488: @node Numeric Modes
  489: @section Numeric Modes
  490: 
  491: @cindex numeric modes
  492: @cindex file mode bits, numeric
  493: @cindex octal numbers for file modes
  494: As an
  495: alternative to giving a symbolic mode, you can give an octal (base 8)
  496: number that represents the mode.
  497: This number is always interpreted in octal; you do not have to add a
  498: leading @samp{0}, as you do in C.  Mode @samp{0055} is the same as
  499: mode @samp{55}.
  500: 
  501: A numeric mode is usually shorter than the corresponding symbolic
  502: mode, but it is limited in that normally it cannot take into account the
  503: previous file mode bits; it can only set them absolutely.
  504: (As discussed in the next section, the set-user-ID and set-group-ID
  505: bits of directories are an exception to this general limitation.)
  506: 
  507: The permissions granted to the user,
  508: to other users in the file's group,
  509: and to other users not in the file's group each require three
  510: bits, which are represented as one octal digit.  The three special
  511: mode bits also require one bit each, and they are as a group
  512: represented as another octal digit.  Here is how the bits are arranged,
  513: starting with the lowest valued bit:
  514: 
  515: @example
  516: Value in  Corresponding
  517: Mode      Mode Bit
  518: 
  519:           Other users not in the file's group:
  520:    1      Execute/search
  521:    2      Write
  522:    4      Read
  523: 
  524:           Other users in the file's group:
  525:   10      Execute/search
  526:   20      Write
  527:   40      Read
  528: 
  529:           The file's owner:
  530:  100      Execute/search
  531:  200      Write
  532:  400      Read
  533: 
  534:           Special mode bits:
  535: 1000      Restricted deletion flag or sticky bit
  536: 2000      Set group ID on execution
  537: 4000      Set user ID on execution
  538: @end example
  539: 
  540: For example, numeric mode @samp{4755} corresponds to symbolic mode
  541: @samp{u=rwxs,go=rx}, and numeric mode @samp{664} corresponds to symbolic mode
  542: @samp{ug=rw,o=r}.  Numeric mode @samp{0} corresponds to symbolic mode
  543: @samp{a=}.
  544: 
  545: @node Directory Setuid and Setgid
  546: @section Directories and the Set-User-ID and Set-Group-ID Bits
  547: 
  548: On most systems, if a directory's set-group-ID bit is set, newly
  549: created subfiles inherit the same group as the directory, and newly
  550: created subdirectories inherit the set-group-ID bit of the parent
  551: directory.  On a few systems, a directory's set-user-ID bit has a
  552: similar effect on the ownership of new subfiles and the set-user-ID
  553: bits of new subdirectories.  These mechanisms let users share files
  554: more easily, by lessening the need to use @command{chmod} or
  555: @command{chown} to share new files.
  556: 
  557: These convenience mechanisms rely on the set-user-ID and set-group-ID
  558: bits of directories.  If commands like @command{chmod} and
  559: @command{mkdir} routinely cleared these bits on directories, the
  560: mechanisms would be less convenient and it would be harder to share
  561: files.  Therefore, a command like @command{chmod} does not affect the
  562: set-user-ID or set-group-ID bits of a directory unless the user
  563: specifically mentions them in a symbolic mode, or sets them in
  564: a numeric mode.  For example, on systems that support
  565: set-group-ID inheritance:
  566: 
  567: @example
  568: # These commands leave the set-user-ID and
  569: # set-group-ID bits of the subdirectories alone,
  570: # so that they retain their default values.
  571: mkdir A B C
  572: chmod 755 A
  573: chmod 0755 B
  574: chmod u=rwx,go=rx C
  575: mkdir -m 755 D
  576: mkdir -m 0755 E
  577: mkdir -m u=rwx,go=rx F
  578: @end example
  579: 
  580: If you want to try to set these bits, you must mention them
  581: explicitly in the symbolic or numeric modes, e.g.:
  582: 
  583: @example
  584: # These commands try to set the set-user-ID
  585: # and set-group-ID bits of the subdirectories.
  586: mkdir G H
  587: chmod 6755 G
  588: chmod u=rwx,go=rx,a+s H
  589: mkdir -m 6755 I
  590: mkdir -m u=rwx,go=rx,a+s J
  591: @end example
  592: 
  593: If you want to try to clear these bits, you must mention them
  594: explicitly in a symbolic mode, e.g.:
  595: 
  596: @example
  597: # This command tries to clear the set-user-ID
  598: # and set-group-ID bits of the directory D.
  599: chmod a-s D
  600: @end example
  601: 
  602: This behavior is a @acronym{GNU} extension.  Portable scripts should
  603: not rely on requests to set or clear these bits on directories, as
  604: @acronym{POSIX} allows implementations to ignore these requests.