doc/man-pages/pod1/fs_listacl.pod

   1 =head1 NAME
   2
   3 fs_listacl - Displays ACLs
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<fs listacl> S<<< [B<-path> <I<dir/file path>>+] >>> [B<-id>] [B<-if>] [B<-cmd>] [B<-help>]
  11
  12 B<fs la> S<<< [B<-p> <I<dir/file path>>+] >>> [B<-id>] [B<-if>] [B<-cmd>] [B<-h>]
  13
  14 B<fs lista> S<<< [B<-p> <I<dir/file path>>+] >>> [B<-id>] [B<-if>] [B<-cmd>] [B<-h>]
  15
  16 =for html
  17 </div>
  18
  19 =head1 DESCRIPTION
  20
  21 The B<fs listacl> command displays the access control list (ACL)
  22 associated with each specified file, directory, or symbolic link. The
  23 specified element can reside in the DFS filespace if the issuer is using
  24 the AFS/DFS Migration Toolkit Protocol Translator to access DFS data (and
  25 DFS does implement per-file ACLs). To display the ACL of the current
  26 working directory, omit the B<-path> argument.
  27
  28 To alter an ACL, use the B<fs setacl> command. To copy an ACL from one
  29 directory to another, use the B<fs copyacl> command. To remove obsolete
  30 entries from an ACL, use the B<fs cleanacl> command.
  31
  32 =head1 CAUTIONS
  33
  34 Placing a user or group on the C<Negative rights> section of the ACL does
  35 not guarantee denial of permissions, if the C<Normal rights> section
  36 grants the permissions to members of the system:anyuser group. In that
  37 case, the user needs only to issue the B<unlog> command to obtain the
  38 permissions granted to the system:anyuser group.
  39
  40 =head1 OPTIONS
  41
  42 =over 4
  43
  44 =item B<-path> <I<dir/file path>>+
  45
  46 Names each directory or file for which to display the ACL. For AFS files,
  47 the output displays the ACL from the file's parent directory; DFS files do
  48 have their own ACL. Incomplete pathnames are interpreted relative to the
  49 current working directory, which is also the default value if this
  50 argument is omitted.
  51
  52 =item B<-id>
  53
  54 Displays the Initial Container ACL of each DFS directory. This argument is
  55 supported only on DFS directories accessed via the AFS/DFS Migration
  56 Toolkit Protocol Translator.
  57
  58 =item B<-if>
  59
  60 Displays the Initial Object ACL of each DFS directory. This argument is
  61 supported only on DFS directories accessed via the AFS/DFS Migration
  62 Toolkit Protocol Translator.
  63
  64 =item B<-cmd>
  65
  66 Outputs an B<fs setacl> command string that can be used to recreate
  67 the ACL applied to the specified file, directory or symbolic link.
  68
  69 =item B<-help>
  70
  71 Prints the online help for this command. All other valid options are
  72 ignored.
  73
  74 =back
  75
  76 =head1 OUTPUT
  77
  78 The first line of the output for each file, directory, or symbolic link
  79 reads as follows:
  80
  81    Access list for <directory> is
  82
  83 If the issuer used shorthand notation in the pathname, such as the period
  84 (C<.>) to represent the current current directory, that notation sometimes
  85 appears instead of the full pathname of the directory.
  86
  87 Next, the C<Normal rights> header precedes a list of users and groups who
  88 are granted the indicated permissions, with one pairing of user or group
  89 and permissions on each line. If negative permissions have been assigned
  90 to any user or group, those entries follow a C<Negative rights>
  91 header. The format of negative entries is the same as those on the
  92 C<Normal rights> section of the ACL, but the user or group is denied
  93 rather than granted the indicated permissions.
  94
  95 AFS does not implement per-file ACLs, so for a file the command displays
  96 the ACL on its directory. The output for a symbolic link displays the ACL
  97 that applies to its target file or directory, rather than the ACL on the
  98 directory that houses the symbolic link.
  99
 100 The permissions for AFS enable the possessor to perform the indicated
 101 action:
 102
 103 =over 4
 104
 105 =item a (administer)
 106
 107 Change the entries on the ACL.
 108
 109 =item d (delete)
 110
 111 Remove files and subdirectories from the directory or move them to other
 112 directories.
 113
 114 =item i (insert)
 115
 116 Add files or subdirectories to the directory by copying, moving or
 117 creating.
 118
 119 =item k (lock)
 120
 121 Set read locks or write locks on the files in the directory.
 122
 123 =item l (lookup)
 124
 125 List the files and subdirectories in the directory, stat the directory
 126 itself, and issue the B<fs listacl> command to examine the directory's
 127 ACL.
 128
 129 =item r (read)
 130
 131 Read the contents of files in the directory; issue the C<ls -l> command to
 132 stat the elements in the directory.
 133
 134 =item w (write)
 135
 136 Modify the contents of files in the directory, and issue the UNIX B<chmod>
 137 command to change their mode bits
 138
 139 =item A, B, C, D, E, F, G, H
 140
 141 Have no default meaning to the AFS server processes, but are made
 142 available for applications to use in controlling access to the directory's
 143 contents in additional ways. The letters must be uppercase.
 144
 145 =back
 146
 147 For DFS files and directories, the permissions are similar, except that
 148 the DFS C<x> (execute) permission replaces the AFS C<l> (lookup)
 149 permission, DFS C<c> (control) replaces AFS C<a> (administer), and there
 150 is no DFS equivalent to the AFS C<k> (lock) permission. The meanings of
 151 the various permissions also differ slightly, and DFS does not implement
 152 negative permissions. For a complete description of DFS permissions, see
 153 the DFS documentation.
 154
 155 =head1 EXAMPLES
 156
 157 The following command displays the ACL on the home directory of the user
 158 C<pat> (the current working directory), and on its C<private>
 159 subdirectory.
 160
 161    % fs listacl -path . private
 162    Access list for . is
 163    Normal rights:
 164       system:authuser rl
 165       pat rlidwka
 166       pat:friends rlid
 167    Negative rights:
 168       smith rlidwka
 169    Access list for private is
 170    Normal rights:
 171       pat rlidwka
 172
 173 The following command generates the B<fs setacl> command required to
 174 recreate the ACL on the home directory of the user
 175 C<pat> (the current working directory), and on its C<private>
 176 subdirectory.
 177
 178    % fs listacl -path . private -cmd
 179    fs setacl -dir . -acl system:authuser rl  pat rlidwka   pat:friends rlid
 180    fs setacl -dir . -acl smith rlidwka -negative
 181    fs setacl -dir private -acl pat rlidwka
 182
 183 =head1 PRIVILEGE REQUIRED
 184
 185 If the B<-path> argument names an AFS directory, the issuer must have the
 186 C<l> (lookup) permission on its ACL and the ACL for every directory that
 187 precedes it in the pathname.
 188
 189 If the B<-path> argument names an AFS file, the issuer must have the C<l>
 190 (lookup) and C<r> (read) permissions on the ACL of the file's directory,
 191 and the B<l> permission on the ACL of each directory that precedes it in
 192 the pathname.
 193
 194 If the B<-path> argument names a DFS directory or file, the issuer must
 195 have the C<x> (execute) permission on its ACL and on the ACL of each
 196 directory that precedes it in the pathname.
 197
 198 =head1 SEE ALSO
 199
 200 L<fs_cleanacl(1)>,
 201 L<fs_copyacl(1)>,
 202 L<fs_setacl(1)>
 203
 204 =head1 COPYRIGHT
 205
 206 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 207
 208 This documentation is covered by the IBM Public License Version 1.0.  It was
 209 converted from HTML to POD by software written by Chas Williams and Russ
 210 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.