devel/IPAccessControl.mdwn

   1 # IP Address-Based AFS Access Control for Fun and Profit
   2
   3 You may have heard that the Andrew File System --
   4 [AFS](http://www.openafs.org/) -- allows IP address-based entries for directory
   5 ACLs. The idea is that processes running on a machine with a given IP address
   6 can access protected directories without needing further authentication. You
   7 may have even tried it. If you're like me, you were frustrated. Now I've
   8 discovered the secrets, and I'm going to share them with you. You don't even
   9 have to bribe me.
  10
  11 Why would you want IP-based access? One scenario is that you have files whose
  12 access should be limited to certain machines. Maybe you have software that
  13 should only be run on certain machines because of legal or hardware
  14 limitations. Maybe authentication for certain processes is a drag to work out.
  15 Whatever your reason, this is pretty easy to do after you know the tricks, and
  16 seems to provide a moderate level of security.
  17
  18
  19 Some introductory information and relevant links:
  20
  21 These examples were created under AFS 3.4a and [Sun](http://www.sun.com)'s
  22 [Solaris](http://www.sun.com/software/solaris/) 2.6. <br /> Documentation links
  23 were to Transarc's documentation, until IBM [changed the links and made the
  24 version
  25 3.6](http://www-3.ibm.com/software/stormgmt/afs/manuals/Library/unix/en_US/HTML/AdminRef/auarf002.htm).
  26 Now my documentation links point to the open source version's site,
  27 [OpenAFS](http://www.openafs.org). <br /> Transarc, the original commercial
  28 developer of AFS, is now [IBM](http://www.ibm.com)'s Pittsburgh Lab.<br /> AFS
  29 was first developed at [Carnegie Mellon University](http://www.cmu.edu/) as
  30 part of the [ Andrew Project](http://www.cs.cmu.edu/~AUIS/). <br /> For more
  31 information about AFS, try reading the
  32 [FAQ](http://www.faqs.org/faqs/by-newsgroup/alt/alt.filesystems.afs.html) for
  33 the USENET newsgroup [alt.filesystems.afs](news:alt.filesystems.afs). <br />
  34
  35 All links in this web page should pop up in a single side window, so you won't
  36 have to flip back and forth between pages. I've tried to link every command to
  37 a relevant page, but other references may only be linked at their first
  38 instance.
  39
  40 ----
  41
  42 Ok, you'll be dealing with just an IP number for the machine that needs access.
  43 No DNS names: AFS wants just an IP address and none of your carefully
  44 thought-out, clever naming scheme. Yeah, I know -- no fun. You'll have to get
  45 over it. Sorry.
  46
  47 The IP number must be in your AFS
  48 [PTS](http://www.openafs.org/pages/doc/AdminReference/auarf210.htm#HDRPTS_INTRO)
  49 database, just like a user. I'll use your-machine.your-domain.com (1.2.3.4) as
  50 an example.
  51
  52 [Using klog, get an admin token](http://www.openafs.org/pages/doc/AdminReference/auarf200.htm#HDRKLOG) for your AFS cell.
  53
  54 Check to see if 1.2.3.4 is in your PTS database:
  55
  56 <pre>
  57      bash-2.02$ <a href="http://www.openafs.org/pages/doc/AdminReference/auarf217.htm#HDRPTS_EXAMINE" target="SIDEWINDOW">pts examine</a> 1.2.3.4
  58      pts: User or group doesn't exist so couldn't look up id for 1.2.3.4
  59 </pre>
  60
  61 It's not there. So create it:
  62
  63 <pre>
  64      bash-2.02$ <a href="http://www.openafs.org/pages/doc/AdminReference/auarf215.htm#HDRPTS_CREATEUSER" target="SIDEWINDOW">pts createuser</a> 1.2.3.4
  65      User 1.2.3.4 has id 2147418256
  66 </pre>
  67
  68 The AFS protection database server (PTS) assigns an AFS UID (the number after
  69 "User 1.2.3.4 has id ") to the machine. [ Accumulated wisdom
  70 recommends](http://www.openafs.org/pages/doc/AdminReference/auarf215.htm#HDRPTS_CREATEUSER)
  71 allowing that instead of trying to pick one, so don't use the -id flag unless
  72 you're sure know what you're doing and have consulted a [[SysAdmin]] quorum at
  73 your site.
  74
  75 You can wildcard/subnet these IP-based PTS entries. So you can get PTS ids for
  76 IP ranges denoted by, e.g.:
  77
  78          1.2.3.0
  79          1.2.0.0
  80          1.0.0.0
  81
  82 This is supposed to do what you'd think it would: grant privileges to machines
  83 within the IP range denoted by the leading non-zero elements. Now you can
  84 easily give thousands of people and machines access when you didn't mean to. If
  85 you get the idea of wildcarding everything, as in 0.0.0.0, use system:anyuser
  86 instead. God knows why you'd want that, and if you're reading this you really
  87 ought to know about system:anyuser anyway, but that's how to do it. I don't
  88 know what happens if you need to give access to a machine that has a zero as
  89 the last tuple of the IP address. Maybe you should get another IP address for
  90 that machine. :)
  91
  92 OK, now your-machine has an AFS PTS id. But don't put the IP number directly on
  93 the ACL. Instead, create an appropriate PTS group and add the machine to it.
  94 Don't mix IP and principal entries in the same group; create another group
  95 (more on this later).
  96
  97 I'll create a PTS group:
  98
  99 <pre>
 100      bash-2.02$ <a href="http://www.openafs.org/pages/doc/AdminReference/auarf214.htm#HDRPTS_CREATEGROUP" target="SIDEWINDOW">pts creategroup</a> your-stuff system:administrators
 101      group your-stuff has id -1723
 102 </pre>
 103
 104 Again, the number at the end is an ID assigned by AFS. I've chosen here to have group your-stuff owned by system:administrators, but ownership by another group or principal might be appropriate. Joe User -- a cousin of mine :) -- with login joeuser could only create groups starting "joeuser:". Administrators can create groups without this restriction.
 105
 106 What does the group your-stuff look like?
 107
 108 <pre>
 109      bash-2.02$ <a href="http://www.openafs.org/pages/doc/AdminReference/auarf217.htm#HDRPTS_EXAMINE" target="SIDEWINDOW">pts examine</a> your-stuff
 110      Name: your-stuff, id: -1723, owner: system:administrators, creator: admin,
 111         membership: 0, flags: S-M--, group quota: 0.
 112 </pre>
 113
 114 I'll ignore everything right now except the flags, which are an access control
 115 list for the PTS entry. What's above is my local default for groups. The "S"
 116 means anyone can run [pts
 117 examine](http://www.openafs.org/pages/doc/AdminReference/auarf217.htm#HDRPTS_EXAMINE)
 118 on the group. The "M" means anyone can run [pts
 119 membership](http://www.openafs.org/pages/doc/AdminReference/auarf222.htm#HDRPTS_MEMBERSHIP)
 120 on the group. The flags are
 121
 122          SOMAR
 123
 124 and affect the operation of the
 125 [pts](http://www.openafs.org/pages/doc/AdminReference/auarf210.htm#HDRPTS_INTRO)
 126 commands
 127 [examine](http://www.openafs.org/pages/doc/AdminReference/auarf217.htm#HDRPTS_EXAMINE),
 128 [listowned](http://www.openafs.org/pages/doc/AdminReference/auarf221.htm#HDRPTS_LISTOWNED),
 129 [membership](http://www.openafs.org/pages/doc/AdminReference/auarf222.htm#HDRPTS_MEMBERSHIP),
 130 [adduser](http://www.openafs.org/pages/doc/AdminReference/auarf211.htm#HDRPTS_ADDUSER),
 131 and
 132 [removeuser](http://www.openafs.org/pages/doc/AdminReference/auarf223.htm#HDRPTS_REMOVEUSER),
 133 respectively. The flags can generally have values of uppercase, lowercase, or
 134 hyphen. I won't go into the flags much here, but read the man page, and think
 135 carefully about what you want to be seen by whom. For instance, if the group is
 136 going to be for machines where users will be allowed to run certain software,
 137 you might want to make it easy for folks to discover what those machines are.
 138 If you're trying to keep users out, you might want to hide the membership from
 139 prying eyes. Pay as much attention to this as you would to any other ACL or
 140 permission.
 141
 142 By the way, [pts examine](http://www.openafs.org/pages/doc/AdminReference/auarf217.htm#HDRPTS_EXAMINE)
 143 works for any entity in the PTS database: groups, principals, and machines.
 144 E.g.:
 145
 146          bash-2.02$ pts examine 1.2.3.4
 147          Name: 1.2.3.4, id: 2147418256, owner: system:administrators, creator: admin,
 148            membership: 0, flags: S----, group quota: 20.
 149
 150 The above flags are my current local default for machine entries.
 151
 152 Since [ pts
 153 examine](http://www.openafs.org/pages/doc/AdminReference/auarf217.htm#HDRPTS_EXAMINE)
 154 works for three different types of entries -- machines, principals, and groups
 155 -- the man pages get confusing. The flags mean different things depending on
 156 what you're examining.
 157
 158 <center><strong> * When using pts examine, keep clearly in mind what type entry
 159 you're examining, and pay attention just to the parts of the manual page that
 160 speak to your type entry. If you do this and keep your mind clear of
 161 distraction, all will be well. :) * </strong></center>
 162
 163 I assume you'll want to add 1.2.3.4 to your-stuff:
 164
 165 <pre>
 166       bash-2.02$ <a href="http://www.openafs.org/pages/doc/AdminReference/auarf211.htm#HDRPTS_ADDUSER" target="SIDEWINDOW">pts adduser</a> 1.2.3.4 your-stuff
 167 </pre>
 168
 169 You'll get back just a prompt. So group your-stuff should now contain
 170
 171 <pre>
 172       bash-2.02$ <a href="http://www.openafs.org/pages/doc/AdminReference/auarf222.htm#HDRPTS_MEMBERSHIP" target="SIDEWINDOW">pts membership</a> your-stuff
 173       Members of your-stuff (id: -1723) are:
 174         1.2.3.4
 175 </pre>
 176
 177 By the way, it's really easy to confuse [pts
 178 adduser](http://www.openafs.org/pages/doc/AdminReference/auarf211.htm#HDRPTS_ADDUSER)
 179 and [pts
 180 createuser](http://www.openafs.org/pages/doc/AdminReference/auarf215.htm#HDRPTS_CREATEUSER).
 181 Just like the rest of the AFS command suite, there are too many commands that
 182 sound too much alike or don't do exactly what you'd think from the name. Read
 183 the man page. Query a local [[SysAdmin]] quorum.
 184
 185 You did have an AFS directory you wanted to protect, right? Let's say that
 186 directory's permissions currently look like
 187
 188 <pre>
 189       bash-2.02$ <a href="http://www.openafs.org/pages/doc/AdminReference/auarf148.htm#HDRFS_LISTACL" target="SIDEWINDOW">fs listacl</a> /afs/your-domain/your-dir
 190       Access list for /afs/your-domain/your-dir is
 191       Normal rights:
 192         system:administrators rlidwka
 193         system:anyuser rl
 194 </pre>
 195
 196 Set directory permissions with [fs setacl](http://www.openafs.org/pages/doc/AdminReference/auarf157.htm#HDRFS_SETACL):
 197
 198 <pre>
 199       bash-2.02$ <a href="http://www.openafs.org/pages/doc/AdminReference/auarf157.htm#HDRFS_SETACL" target="SIDEWINDOW">fs setacl</a> /afs/your-domain/your-dir your-stuff write
 200 </pre>
 201
 202 "write" is short for all perms except administer. Now [fs
 203 listacl](http://www.openafs.org/pages/doc/AdminReference/auarf148.htm#HDRFS_LISTACL)
 204 should return something like
 205
 206 <pre>
 207       bash-2.02$ <a href="http://www.openafs.org/pages/doc/AdminReference/auarf148.htm#HDRFS_LISTACL" target="SIDEWINDOW">fs listacl</a> /afs/your-domain/your-dir
 208       Access list for /afs/your-domain/your-dir is
 209       Normal rights:
 210         your-stuff rlidwk
 211         system:administrators rlidwka
 212         system:anyuser rl
 213 </pre>
 214
 215 So, you're set, right?
 216
 217 Wrong.
 218
 219 You put a file in your-dir. You get on other-machine.your-domain.com, and try to look at the file. You can't. That's good.
 220
 221 Then you get on your-machine.your-domain.com and try. You still can't look at the file. That's bad.
 222
 223 This has always been where I scratched my head and said "I don't get it." But I figured it out. I will now attempt to dispel confusion.
 224
 225 <center><strong>An AFS file server treats ACL IP entries differently from
 226 principal entries: <p>Changes to ACLs for principals are reflected almost right
 227 away.</p> <p>Changes to ACLs for IP entries are <strong>NOT</strong>.
 228 </p></strong></center>
 229
 230 There's a flag to the [fileserver](http://www.openafs.org/pages/doc/AdminReference/auarf129.htm#HDRFILESERVER) instance called -hr:
 231
 232 > ` -hr`
 233 >
 234 > > `Specifies how often the File Server refreshes its knowledge of the machines that belong to protection groups (its "host CPS"). The File Server must update this information to enable users from machines recently added to protection groups to access data for which those Machines now have the necessary ACL permissions. `
 235
 236 Farther down in both the IBM and [[OpenAFS]] documentation mentioned above for
 237 the fileserver instance, the default setting for this "-hr" parameter is given
 238 as two hours:
 239
 240 > > ` The File Server maintains a host current protection subgroup (host CPS) for each client machine from which it has received a data access request. Like the CPS for a user, a host CPS lists all of the Protection Database groups to which the machine belongs, and the File Server compares the host CPS to a directory's ACL to determine in what manner users on the machine are authorized to access the directory's contents. When the pts adduser or pts removeuser command is used to change the groups to which a machine belongs, the File Server must recompute the machine's host CPS in order to notice the change. By default, the File Server contacts the Protection Server every two hours to recompute host CPSs, implying that it can take that long for changed group memberships to become effective. To change this frequency, use the -hr argument. `
 241
 242 Maybe there's some overhead involved in these checks, so they're not done very
 243 often. Who knows? Maybe you'll want to diddle this flag for your site's
 244 fileserver instances, but probably not, or you'll never get to it, or you don't
 245 want to declare a downtime.
 246
 247 When I ran into this problem, one suggestion was
 248
 249 - Wait a while and it'll start working.
 250 I imagine those folks didn't know about the flag and didn't know how long to wait. I guess most folks would have to wait between 0 and 2 hours, depending on luck. I don't know about you, but I don't like waiting for a bus if I don't know when it's going to show up.
 251 Another suggestion was
 252 <br />
 253 - Restart the appropriate fileserver process.
 254 I guess those folks don't have any users they have to worry about pissing off, or only have two or three volumes on their file server.
 255 You can probably tell I didn't like either of the above suggestions.
 256 At that point I thought, "Gee, I bet if I move a volume onto a different file server with the ACL already in place, the new file server will need to grok all the volume's ACLs right then." And I was right. And the angels started to sing. :)
 257 So my hurry-up suggestion:
 258 <br />
 259 - [vos move](http://www.openafs.org/pages/doc/AdminReference/auarf268.htm#HDRVOS_MOVE) the affected volume to another file server.
 260
 261 You should now be working. That was easy, wasn't it? :)
 262
 263 A few caveats:
 264
 265 - Local users: Are there users on your-machine who should be kept away from the file? If so, this whole scheme may not work for you.
 266 - IP spoofing: If someone spoofed an IP address, ran an AFS client (probably in their own cell), and put your cell in their [[CellServDB]], maybe they could read your file. Bad.
 267 - Fileserver/client encryption: If a client's cache manager is configured to encrypt data transfer with fileservers (i.e., if fs setcrypt is on), the server and client use key exchange to set up the encryption. However, if access to the data is allowed with an IP-based ACL, then there's no key exchange, and the data is sent in the clear. If you're not encrypting traffic or don't care, then don't worry about it.
 268 - Correct regular Unix groups and permissions: I ran into someone recently who had followed my instructions, and was able to read his file correctly on some machines but not others. The problem was the regular Unix groups. Ideally this wouldn't happen, but some applications will stat a file and assume the user can't read it because the permission bits are set wrong. Forestall this by setting the regular Unix modes and groups appropriately. Yes, you shouldn't have to do it, but do it anyway.
 269 - Mixed groups: AFS documentation warns against administering groups containing both principals and IP addresses. They say use just principals or just IP addresses in a group. You can always make another group, but often you'll be adding principals directly to the ACL anyway with no intervening group. Maybe this restriction has to do with the posited overhead and only occasional checking by the fileserver instance on IP addresses in PTS groups. So remember: No miscegenation!
 270 - No group rights inheritance: Groups are owned by users or by other groups, but child groups do **not** inherit parent group rights, nor do parent groups get the rights their children have.
 271     For example: Group a:a owns group a:b. Group a:a is placed on an ACL. Members of group a:a have rights in that directory. Members of group a:b do not inherit those rights.
 272     If group a:b is on a directory's ACL, group a:a doesn't assume any rights in that directory either.
 273 - No hierarchical group membership: Groups are not **in** other groups, even if they're owned by another group. Only principals and PTS-registered IP addresses can be in a group. But please note "Update" below.
 274     -- Hypothetical portion --
 275 > This no-nested-groups arrangement is kind of unfortunate: it might be nice to have structures like, e.g., a group called
 276 >
 277 >             machines
 278 >
 279 >     consisting of
 280 >
 281 >             machines:servers
 282 >             machines:clients
 283 >             machines:other
 284 >
 285 >     with, say, machines:servers containing
 286 >
 287 >             machines:fileservers
 288 >             machines:loginservers
 289 >             machines:mailmachines
 290 >
 291 >     Somewhere at the bottom you'd have actual machines populating groups. This would be nice, but it doesn't work this way: you can't have a group as a member of a group. Groups can own other groups, but don't reside in groups. I've made this mistake over and over in my thinking -- enough for all of us, so please don't make it yourself.
 292 >
 293 >     I'm told someone at CMU has AFS/Solaris 2.6 code that lets groups be in other groups, which would allow this sort of hierarchical group structure. Alas, I can't find any information about it. I've also heard there's work (maybe at University of Michigan?) on similar code for [[OpenAFS]]. If anyone has any specific information about either, would you let me know? A URL referring to the work would be great.
 294 >
 295 >     Update -- it turns out that recent verions of [[OpenAFS]] now have a compile-time option for supergroups (groups that contain group). If I ever get any experience using this, I'll let you know.
 296     -- End hypothetical portion --
 297 - There's a newly exposed problem on some platforms with occasional loss of IP-based access. The problem is discussed on the [[OpenAFS]]-Devel mailing list in [this thread](https://lists.openafs.org/pipermail/openafs-devel/2006-June/013946.html). Please take a look if you're having problems. Derrick Brashear is currently (30 June 2006) testing a patch, which you can find at
 298          /afs/andrew.cmu.edu/usr/shadow/ubik-all.diff-2
 299
 300 Was this page useful, or even interesting? Please link to it: it's difficult to
 301 find.
 302
 303 Send comments, questions, bad links, &amp;c. to [me](mailto:jhvilas@gmail.com)
 304 if you like, or fix them -- this is a Wiki, after all. And to the many people
 305 who've sent comments: Thank you! Your feedback has helped!
 306