6b7558933c99ec033abb5e8d7686ed916562aa78
[openafs-wiki.git] / SolarisQuickStart.mdwn
1 # Solaris 11 Quick Start
2
3 These instructions have been tested on [[Oracle
4 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
5 11 and on [[OpenIndiana|http://openindiana.org]] for X86. Aside from
6 slight changes to the [[Kerberos|KerberosV]] server appendix (as noted), there
7 is no difference between two. With minor changes they should work for SPARC as
8 well; mostly, this involves replacing `amd64` with `sparcv9` or the
9 appropriate platform.
10
11 It is believed that these instructions will work similarly on [[Oracle
12 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
13 10 (making sure you use the [[Oracle
14 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
15 10 version of the [[OpenAFS]] binary distribution), but this has not been
16 tested.
17
18 This is divided into tasks; several of these tasks interact with each other
19 (for example, if you are setting up a new cell then you are setting up a db
20 server and either you will also need to make it a client or you will need a
21 client available on some other machine that can authenticate to the new
22 cell; likewisem either it will also be a file server, or you will be setting
23 up a file server immediately afterward). This also means that the sections in
24 this document may appear to be a bit scrambled, because the final client steps
25 are embedded in the middle of server setup when a working client is needed
26 during cell setup.
27
28 [[!toc  startlevel=2]]
29
30 ## Initial steps
31
32 ### Choosing a realm and cell name
33
34 If you are setting up a new cell, you will need to choose a
35 [[Kerberos|KerberosV]] realm and [[OpenAFS]] cell name. By convention, these
36 are based on your DNS domain name: if your domain name is `example.com` then
37 your cell would be `example.com` and your realm is `EXAMPLE.COM`. Various
38 things will default to this if they cannot find any configuration telling them
39 otherwise, and in general it makes things easier when the names are related in
40 this way.
41
42 Some things to watch out for, though:
43
44 1. [[Active
45 Directory|http://technet.microsoft.com/en-us/library/cc782657(v=ws.10).aspx]]
46 domains are [[Kerberos|KerberosV]] realms, and export their
47 [[Kerberos|KerberosV]] services via DNS `SRV` records. It is best not to use
48 the same realm name as an existing [[Active
49 Directory|http://technet.microsoft.com/en-us/library/cc782657(v=ws.10).aspx]]
50 domain, as you will not be able to set up any cross-realm trusts with
51 it. (Also beware of someone setting up an [[Active
52 Directory|http://technet.microsoft.com/en-us/library/cc782657(v=ws.10).aspx]]
53 domain afterward that matches your realm.)
54
55 2. If your organization is a division of some larger organization, you should
56 coordinate with the rest of the organization so that you will be able to set
57 up cross-realm trust in the future. Even if the larger organization does not
58 use any form of [[Kerberos|KerberosV]] or [[OpenAFS]] as yet, there are both
59 technical and political reasons not to usurp the larger organization's
60 name. (Yes, this has happened.)
61
62 ### Fixing `/etc/hosts` on servers
63
64 After a default install of [[Oracle
65 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
66 or [[OpenIndiana|http://openindiana.org]], `/etc/hosts` contains a
67 configuration which is convenient for standalone notebook computers but which
68 is questionable for fixed desktops and actively damaging for servers. You
69 should edit `/etc/hosts` and remove all mentions of the local host name from
70 the loopback addresses (`::1` and `127.0.0.1`). For a server, you should add
71 the server's IP address(es) and assign the local host name to those addresses,
72 *making sure that the fully qualified domain name is listed first* (the
73 installer often lists the short name first, which results in a number of
74 network services not finding their proper host names). An [[OpenAFS]] file
75 server may also be misled into registering its volumes with the loopback
76 address, resulting in their being inaccessible if this is not corrected.
77
78 ### Configuring [[NTP|FurtherReading#NTP]]
79
80 [[OpenAFS]] requires time synchronization between all (server and client)
81 machines in a cell, both for [[Kerberos|KerberosV]] authentication and so that
82 file timestamps will be consistent. Most commonly, the [[Network Time Protocol
83 (NTP)|FurtherReading#NTP]] is used for this purpose, although other
84 arrangements are possible. This document describes the use of
85 [[NTP|FurtherReading#NTP]]; if you want to use some other mechanism, set that
86 up now and continue with the next step.
87
88 In many cases, you will want a local time server in your cell; this should
89 probably be a separate machine. Ideally, it is *not* a virtual machine,
90 because they are at the mercy of their host for their internal timekeeping
91 (that is, the VM cannot "see" time passing while another VM on the host or the
92 host itself is processing) and therefore do not keep time well enough to
93 provide time services for other machines. Additionally, for obvious reasons
94 you could not use it to provide time synchronization for its host.) For these
95 instructions, we are assuming that a time server has already been created or
96 selected for the cell.
97
98     cd /etc/inet
99     cp ntp.client ntp.conf
100     vi ntp.conf
101
102 Usually you will want to comment out the `multicastclient` directive (it's
103 enabled by default on [[OpenIndiana|http://openindiana.org]] but disabled on [[Oracle
104 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]])
105 and uncomment one or more `server` directives. The `iburst` parameter speeds
106 up initial synchronization after system startup and is
107 recommended. `multicastclient` is *not* recommended because it takes longer to
108 perform initial synchronization; this makes it "good enough" for many
109 desktops, but may result in unexpected authentication failures or "odd"
110 timestamps when using a network filesystem. (This is equally true when using
111 NFS or SMB network filesystems. Note that modern takes on both NFS and SMB
112 also use [[Kerberos|KerberosV]] and therefore require time synchronization for
113 authentication to work properly.)
114
115     svcadm enable network/ntp
116
117 ### Configuring [[Kerberos|KerberosV]]
118 <a name="krb5">
119
120 If you are setting up a new cell, you will want to set up at least one Key
121 Distribution Center (KDC); most commonly (and for historical reasons) these
122 are often run on the [[OpenAFS]] db server hosts. An
123 [[appendix|SolarisQuickStart#krb5kdc]] covers setting up a KDC for a new
124 cell using the [[Oracle
125 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
126 or [[OpenIndiana|http://openindiana.org]] bundled [[Kerberos|KerberosV]].
127
128 Newer [[Kerberos|KerberosV]] installations may use DNS for autoconfiguration,
129 in which case a local `krb5.conf` is not needed except to set defaults. This
130 is convenient, but may be subject to DNS spoofing attacks.
131
132 This document assumes that you are using the [[Kerberos|KerberosV]]
133 distributed along with [[Oracle
134 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
135 / [[OpenIndiana|http://openindiana.org]]. It is also possible to use other
136 [[Kerberos|KerberosV]] implementations, such as [[MIT
137 Kerberos|http://web.mit.edu/kerberos/]] or [[Heimdal|http://h5l.org]].
138
139     cd /etc/krb5
140     ln -s krb5/krb5.conf /etc/krb5.conf # for Solaris bundled Kerberos
141
142 The bundled [[Kerberos|KerberosV]] uses `/etc/krb5/krb5.conf` but many
143 [[Kerberos|KerberosV]] tools, including the `aklog` shipped with [[OpenAFS]],
144 assume that it is `/etc/krb5.conf`. The symlink lets these programs work
145 properly with the bundled [[Kerberos|KerberosV]].
146
147     vi krb5.conf
148
149 The stock `krb5.conf` has an example configuration which is commented out and
150 contains placeholders. You should uncomment the configuration and replace the
151 placeholders. In most cases, the [[Kerberos|KerberosV]] realm is the
152 [[OpenAFS]] cell name converted to uppercase; for example, for the cell
153 `example.com` the corresponding [[Kerberos|KerberosV]] realm is
154 `EXAMPLE.COM`. Remember to replace *all* of the placeholders!
155
156 Many sites will not need the `domain_realm` entries, as [[Kerberos|KerberosV]]
157 will automatically infer a realm from a domain name. This requires properly
158 configured DNS and that the domain name matches the realm. There is one
159 potential trap, however: if you (as is common) have a server whose name is the
160 domain name instead of that of a machine within the domain (compare
161 `www.example.com` and `example.com`), you would need to provide a
162 `domain_realm` mapping for `example.com` or [[Kerberos|KerberosV]] would infer
163 the realm `COM` for it! This is why typically you will see two entries in
164 `domain_realm`:
165
166     [domain_realm]
167     example.com = EXAMPLE.COM
168     .example.com = EXAMPLE.COM
169     # the second entry is not actually necessary if the domain and realm match
170     # the first is necessary
171
172 **IMPORTANT** One additional change is needed to `krb5.conf` for [[OpenAFS]]
173 to work. While work is ongoing on a modern encryption / security protocol
174 (`rxgk`), current [[OpenAFS]] versions are limited to an older, weaker
175 encryption scheme which modern [[Kerberos|KerberosV]] implementations disable by
176 default. You will need to add a line to the `libdefaults` section to re-enable
177 this scheme:
178
179     [libdefaults]
180     allow_weak_crypto = true
181
182 (We don't like this either, but there isn't anything to be done about it until
183 `rxgk` is ready.)
184
185 ### Adding `/usr/afsws/bin` and `/usr/afs/bin` to the system path
186
187 [[Oracle
188 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
189 does not support a directory of profile fragments (such as Linux's
190 `/etc/profile.d`), so you will need to edit `/etc/profile` and `/etc/.login`
191 to add `/usr/afsws/bin` (and, on servers, `/usr/afs/bin`) to `$PATH`. Note
192 that, on servers, you may wish to not place `/usr/afs/bin` on the system path,
193 but instead have administrators add it to `$HOME/.profile` or `$HOME/.login`
194 as needed.
195
196 As a convenience while setting up the server, if you don't want to log out and
197 back in to pick up the new path, you can set it directly in your shell.
198
199 #### `csh` and `tcsh`
200
201     % set path=(/usr/afs/bin /usr/afsws/bin $path:q)
202
203 #### Older Solaris `/bin/sh`
204
205     $ PATH="/usr/afs/bin:/usr/afsws/bin:$PATH"
206     $ export PATH
207
208 #### Most other shells
209
210     $ export PATH="/usr/afs/bin:/usr/afsws/bin:$PATH"
211
212 (You're on your own if you are using a non-traditional shell such as `rc` or
213 `fish`.) These are also the commands you would add to `/etc/profile` and
214 `/etc/.login`.
215
216 ## Unpacking the distribution
217
218 Unlike the Linux packages, [[OpenAFS]] for [[Oracle
219 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
220 is distributed as a "dest" tree with minimal configuration. (An IPS package is
221 planned for the future; this will also use modern paths instead of the old
222 Transarc-style paths.)
223
224     cd /usr
225     gzip -dc sunx86_511.tar.gz | tar xf - # on SPARC, replace sunx86 with sun4x
226     # OpenIndiana and newer Solaris allow: tar xfz sunx86_511.tar.gz
227     mv sunx86_511/dest afsws
228     rmdir sunx86_511
229     cd afsws
230     mv root.client/usr/vice /usr/vice
231     rmdir -p root.client/usr
232     ln -s /usr/vice/etc/modload/afs.rc /etc/init.d/afs
233     ln -s ../init.d/afs /etc/rc2.d/S70afs
234     ln -s ../init.d/afs /etc/rc0.d/K66afs
235     cp /usr/vice/etc/modload/libafs64.nonfs.o /kernel/drv/amd64/afs
236
237 Two things about the final command:
238
239 1. On SPARC, both filenames need to be adjusted.
240
241 2. [[OpenAFS]] contains support for an AFS/NFS translator which allows an AFS
242 client (*not* server) to re-export part of AFS over NFS and will provide
243 limited authentication features and `@sys` translation for NFS clients
244 accessing the NFS share. This implementation requires that `libafs64.o` be
245 installed instead of `libafs64.nonfs.o`. However, the Translator is known not
246 to work properly with current [[Oracle
247 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
248 versions, so for practical purposes only the `nonfs` version should be
249 installed.
250
251 ## Setting up a client
252
253 The default client configuration assumes a traditional cell with a manually
254 populated `root.afs` volume and no need to support file managers. Modern cells
255 typically expect clients to use a dynamic root volume instead; additionally, a
256 number of file managers (Windows Explorer, Gnome's Nautilus, KDE's Dolphin,
257 Thunar, etc.) and various GUI file open/save dialogs have a certain tendency
258 to try to enumerate `/afs` as if it were a local filesystem, with unfortunate
259 results.
260
261     mkdir /usr/vice/etc/config
262     egrep '^(EXTRAOPTS|MEDIUM)=' /etc/init.d/afs |
263     sed 's/^[A-Z][A-Z]*="\(.*\)"$/\1/' >/usr/vice/etc/config/afsd.options
264
265 You may wish to replace `MEDIUM` with `SMALL` or `LARGE`; while the latter
266 uses a bit more memory, modern machines should not have an issue with it, and
267 client performance will be better.
268
269     echo ' -dynroot -fakestat' >>/usr/vice/etc/config/afsd.options
270
271 The quoting and leading space are so that you don't need to care about
272 [[which `echo` you're getting|http://everything2.com/title/The+UNIX+and+the+Echo]].
273
274 If you are going to make this machine a db or file server, continue with the
275 next section. Otherwise, skip ahead to
276 [[Basic client functionality|SolarisQuickStart#basicclient]].
277
278 ## Setting up a server
279
280 [[OpenAFS]] requires a number of databases: the Protection (`pt`) Database
281 records users and groups, and the Volume Location (`vl`) Database records the
282 file servers which hold copies of a volume. An AFS cell requires that at least
283 one (and preferably three; you should avoid having only *two* because of a
284 shortcoming in the quorum process) db server exist; each db server must
285 provide both prdb and vldb services. Most installations also provide KDCs on
286 the db hosts, because older versions of AFS included an additional Kerberos
287 Authentication (`ka`) database based on an older, now known to be insecure,
288 version of the Kerberos protocol. [[OpenAFS]] *does not* require that the
289 KDCs be on the db servers, unless for some reason you must use `kaserver`
290 instead of [[Kerberos 5|KerberosV]] KDCs.
291
292 It is **very strongly** advised that you not use `kaserver` except in existing
293 `kaserver`-based installations, and that such installations be upgraded to use
294 [[Kerberos 5|KerberosV]] as soon as possible; the older Kerberos 4 protocol
295 has severe security issues, which are inherited by `kaserver`. Note that, as
296 these are protocol flaws, it is not possible to patch `kaserver` to fix them;
297 an (incompatible) new protocol is required.
298
299     cd /usr
300     mv afsws/root.server/usr/afs afs
301     cd afs
302     mkdir etc db local logs
303     chown root . bin
304     chmod 700 local db
305
306 At this point, if you are adding a server to an *existing* cell, you should
307 copy the `KeyFile` from an existing db server or file server. (This file is
308 highly sensitive, as servers use it to authenticate to each other and
309 administrators may use it to authenticate to servers; use a secure copying
310 protocol such as `scp`.) If this is a *new* cell, you will need to create a
311 cell principal: use `kadmin` as a principal with [[Kerberos|KerberosV]]
312 administrative rights.
313
314     kadmin: addprinc -randkey -e des-cbc-crc:normal afs/cell
315     kadmin: ktadd -k /usr/afs/etc/afs.keytab -e des-cbc-crc:normal afs/cell
316
317 The string `cell` above should be replaced with the name of the cell (note:
318 *not* the [[Kerberos|KerberosV]] realm or domain name as with most
319 [[Kerberos|KerberosV]] service principals!). It is also possible to use simply
320 `afs` as the cell principal, but this is not recommended for new
321 installations. Note the key version number reported by `ktadd`; you will
322 need this for `asetkey`. You will then need to use this
323 principal to create a `KeyFile`:
324
325     /usr/afs/bin/bosserver -noauth
326     /usr/afs/bin/asetkey add vno /usr/afs/etc/afs.keytab afs/cell
327     pkill bosserver
328
329 As above, replace `cell` with the cell name; also replace `vno` with the key
330 version number. (Again, if this appears to be `1` then you have probably
331 confused the `Key` with the `MKey`; use `ktutil`, or `getprinc` inside
332 `kadmin`, to get the correct key `vno`.) `bosserver` will create an initial
333 `ThisCell` and `CellServDB` (which `asetkey` requires even though it doesn't
334 use them).
335
336 Once you have a `KeyFile` in place, you are ready to configure a server.
337
338 If this is an existing cell, you should copy the *server* `ThisCell`,
339 `CellServDB`, and `UserList` to `/usr/afs/etc`. (These will usually be in
340 `/usr/afs/etc` or `/etc/openafs/server` depending on how the existing server
341 is configured.) Otherwise:
342
343     /usr/afs/bin/bosserver
344     /usr/afs/bin/bos setcellname localhost cell -localauth
345     /usr/afs/bin/bos adduser localhost admin -localauth
346
347 As before, replace `cell` with the actual cell name. If this complains about
348 authentication, you will need to verify your [[Kerberos|KerberosV]]
349 configuration and that your `KeyFile` matches the KDC.
350
351 If this machine is only to be a file server and not a db server, skip ahead to
352 [[Setting up a file server|SolarisQuickStart#fileserver]].
353
354 ## Setting up a db server
355
356 If you haven't already, start the Basic OverSeer (`bos`) service.
357
358     /usr/afs/bin/bosserver
359
360 If you are adding a new machine to an existing cell, register the machine as a
361 new db server:
362
363     /usr/afs/bin/bos addhost localhost fqdn -localauth
364
365 `fqdn` here is the fully qualified domain name of the local host. Note that
366 this will also need to be run (with *this* host's name) on the existing db
367 servers so that they will know about the new db server.
368
369     /usr/afs/bin/bos create localhost pt simple /usr/afs/bin/ptserver -localauth
370     /usr/afs/bin/bos create localhost vl simple /usr/afs/bin/vlserver -localauth
371
372 If this is an existing cell that uses `kaserver` then you will need to set
373 that up as well:
374
375     /usr/afs/bin/bos create localhost ka simple /usr/afs/bin/kaserver -localauth
376
377 If this is a *new* cell then you need to initialize the Protection Database
378 and create the `UserList`. Note that at this point you need a working client;
379 it is somewhat easier if this client is running on the new server, since a
380 remote client probably does not have an appropriate `KeyFile` and it cannot
381 authenticate as the cell admin until *after* this command is run. If this is a
382 new db server in an existing cell, you are done except for doing the `bos
383 addhost` above on the existing db servers and waiting for the new server to
384 replicate the databases. (If it is a file server, you probably want to
385 continue with the next section and then skip ahead to
386 [[Setting up a file server|SolarisQuickStart#fileserver]].)
387
388 ## Basic client functionality
389 <a name="basicclient">
390
391 Configure the client `ThisCell` and `CellServDB`. If you are using DNS for
392 [[OpenAFS]] autoconfiguration, you don't absolutely need the `CellServDB`; if
393 you are using dynamic root, you may also want `CellAlias`. If this client is
394 in an existing cell, easiest is probably to copy these files from an existing
395 client. For a new cell, the cell setup above, as of [[OpenAFS]] 1.6.2, will
396 have created the client `ThisCell` from the server `ThisCell` and made
397 `CellServDB` a symlink to the server one. (Beware of this; naïvely copying
398 another `CellServDB` over this will overwrite the server `CellServDB`!)
399
400     cd /usr/vice/etc
401     mv CellServDB CellServDB.local
402     # copy an existing CellServDB, such as the grand.central.org master, to CellServDB.master
403     cat CellServDB.local CellServDB.master >CellServDB
404
405 If this is a server and you do not want to run a full client, this is all you
406 need to do; skip to [[Finishing new db server
407 configuration#SolarisQuickStart#finishing]] or
408 [[Setting up a file server|SolarisQuickStart#fileserver]] as
409 appropriate. If you want a full client, continue with the next section.
410
411 ## Final client configuration
412
413 If you are using `-fakestat`, you will want a `CellAlias` for the local cell,
414 and possibly sibling or other often used cells, so that they will be usable
415 with short names.
416
417     echo cell shortname >/usr/vice/etc/CellAlias
418     echo anothercell shortname >>/usr/vice/etc/CellAlias
419
420 `cell` is the full name of the local cell, and `shortname` is the alias
421 (e.g. `example.com example`).
422
423 Create the AFS mountpoint and cache directory.
424
425     mkdir /afs
426     mkdir -p /var/vice/cache
427
428 The cache should be on its own filesystem. Most modern [[Oracle
429 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
430 installations use
431 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]
432 "out of the box"; this is both blessing and curse, as
433 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]
434 makes partitioning easy but the current [[OpenAFS]] cache implementation plays
435 poorly with a
436 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]-based
437 cache; we therefore use a legacy cache partition:
438
439     zfs create -V size rpool/venus
440
441 `size` should be somewhat larger than the expected cache size. `rpool` is the
442 name that current [[Oracle
443 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
444 and [[OpenIndiana|http://openindiana.org]] use for the automatically created
445 initial
446 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]
447 pool; you may have additional, or differently named, pools — use `zpool list`
448 to see the available pools. (`venus` can be anything you want that isn't
449 already in use; historically, the AFS2 cache manager component was called
450 `venus`, so it is used as such here. Compare `vice` for server-related things,
451 in particular the server partitions.)
452
453 Create the cache filesystem. The example here uses a
454 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]
455 zvolume; if you are using a traditional slice, substitute its raw and block
456 device names.
457
458     newfs /dev/zvol/rdsk/rpool/venus # or e.g. /dev/rdsk/c0t0d0s4
459     mount /dev/zvol/dsk/rpool/venus /var/vice/cache # or e.g. /dev/dsk/c0t0d0s4
460
461 (You can use the block device for both; you can't mount the raw device, though.)
462
463 You will also need to add this to `/etc/vfstab` so that it will be mounted at
464 system startup. The entry to add to the end of `vfstab` will look something
465 like:
466
467     /dev/zvol/dsk/rpool/venus   /dev/zvol/rdsk/rpool/venus   /var/vice/cache   ufs   2   yes   -
468
469 The first entry is the block device; the second should be the raw device, for
470 `fsck`.
471
472 Create the `cacheinfo` file.
473
474     echo /afs:/var/vice/cache:size >/usr/vice/etc/cacheinfo
475
476 `size` is some size which is smaller than the actual cache partition size,
477 since the [[OpenAFS]] cache may temporarily grow beyond its defined size under
478 some circumstances.
479
480 And we should be ready to start the client:
481
482     /etc/init.d/afs start
483
484 Note that, in a new cell, `/afs` won't be usable just yet; we haven't set up a
485 file server, and there is no `root.cell` volume (or `root.afs` for traditional
486 non-dynamic root configurations), and accessing `/afs` or the local cell will
487 produce errors.
488
489 If this is a client instead of a server, you are now done! If it is a file
490 server, skip to [[Setting up a file server|SolarisQuickStart#fileserver]]. If
491 it is a database server, continue to the next section.
492
493 ## Finishing new db server configuration
494 <a name="finishing">
495
496 Now that we have a client, we can finish setting up the admin account:
497
498     /usr/afsws/bin/pts createuser admin -localauth
499     /usr/afsws/bin/pts adduser admin system:administrators -localauth
500
501 (It is somewhat odd that the client is needed here. Note that
502 `/usr/afs/bin/pts` also exists, but it is identical to the one in
503 `/usr/afsws/bin` and it uses the *client*, not server, configuration. If not
504 for this, we would not need to have the client set up yet.)
505
506 At this point, it should be possible to switch from using `-localauth` to
507 using an actual token.
508
509     kinit admin
510
511 Solaris `kinit` will likely pause here and spit out some complaints about
512 "`getpwnam failed for name=admin`"; it's trying to do NFSv4 initialization,
513 which we do not care about so the necessary NFSv4 configuration has not been
514 done.
515
516     aklog
517     pts examine admin
518
519 If things are working correctly, there should not be a complaint from
520 `libprot` here; if there is, then you should probably check your
521 [[Kerberos|KerberosV]] configuration.
522
523 At this point, you are done with the db server. If this machine should also be
524 a file server, continue with the next section; if not, you are done with this
525 server but you will want to set up another machine to be the cell's first file
526 server.
527
528 ## Setting up a file server
529 <a name="fileserver">
530
531 At this point, you should have at least working db server, and if this is the
532 first file server for a new cell then there should be a working client for the
533 cell somewhere.
534
535 [[OpenAFS]] file servers use dedicated partitions to hold volumes. The
536 partitions are *not* intended to be user accessible.
537
538 If you are using traditional disk slices, you should arrange for the server
539 partitions to be mounted as paths beginning with `/vicep`; in the examples
540 below, we use `/vicepa` and `/vicepb` as server partitions. If using
541 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]],
542 you may want a separate zpool for server partitions. The examples below use
543 the default zpool created by a basic [[Oracle
544 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
545 or [[OpenIndiana|http://openindiana.org]] install, which is called `rpool`.
546 (Note that ZFS works best with some tuning, which is not covered here.)
547
548     zfs create -o mountpoint=/vicepa rpool/vicepa
549     zfs create -o mountpoint=/vicepb rpool/vicepb
550     # or newfs and mount your traditional slices
551
552 ### File server tuning
553
554 The file server configurations below contain suggested tuning parameters. It is
555 not necessary to include these, but performance will generally be better with
556 them. You may want to look at
557 [[http://conferences.inf.ed.ac.uk/eakc2012/slides/AFS_Performance.pdf]]
558 for more information about performance tuning; detailed performance tuning is
559 beyond the scope of this document.
560
561 ### namei and inode file servers
562
563 As of [[OpenAFS]] 1.6, the standard binary [[OpenAFS]] distribution for
564 [[Oracle
565 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
566 uses the namei file server instead of the old, deprecated inode file
567 server. If you are replacing an old file server, be aware that you cannot use
568 a namei partition with an inode file server or vice versa. Keep the old file
569 server on line and `vos move` partitions to the new file server, instead of
570 trying to attach the old partitions directly to the new file server.
571
572 To check the format of a file server, look at one of the `/vicepx`
573 partitions. An inode server will (or should) appear to be empty. A namei
574 fileserver will have, at absolute minimum, a directory named `AFSIDat`.
575
576 (It is still possible to build [[OpenAFS]] from source with inode support, but
577 there is a bug in current [[OpenAFS]] versions that causes inode file servers
578 to not work correctly. As inode file servers have been deprecated for some
579 time now, inode file servers should be migrated to namei.)
580
581 #### [[Demand attach|DemandAttach]] file server
582
583 [[OpenAFS]] 1.6 includes a [[demand attach file server|DemandAttach]]. Initial
584 setup is slightly more cumbersome than the old file server, but performance is
585 better — especially when restarting a file server, as it does not need to
586 break callbacks before shutting down or check all volumes before coming back
587 up.
588
589 It is entirely possible to have both [[demand attach|DemandAttach]] and
590 traditional file servers in a cell, although a particular file server must be
591 one or the other.
592
593     bos create localhost fs dafs \
594         '/usr/afs/bin/dafileserver -p 123 -L -busyat 200 -rxpck 2000 -cb 4000000 -vattachpar 128 -vlruthresh 1440 -vlrumax 8 -vhashsize 11' \
595         '/usr/afs/bin/davolserver -p 64 -log' \
596         /usr/afs/bin/salvageserver \
597         '/usr/afs/bin/dasalvager -parallel all32' -localauth
598
599 #### Traditional file server
600
601     bos create localhost fs fs \
602         '/usr/afs/bin/fileserver -p 123 -L -busyat 200 -rxpck 2000 -cb 4000000' \
603         '/usr/afs/bin/volserver -p 127 -log' \
604         '/usr/afs/bin/salvager -parallel -all32' -localauth
605
606 If this is a new file server for an existing cell, you are done. If this is a
607 new cell, you still need to create the initial volumes; continue to the next
608 section.
609
610 ## The first file server
611
612 A new cell needs certain volumes to exist. If you will have any clients that
613 do not use dynamic root (`-dynroot`), then you will need a `root.afs` volume;
614 every cell needs a root volume, conventionally called `root.cell` (you can
615 change this, but there is an assumption that the root of remote cells is this
616 volume, so your cell will not be directly accessible from foreign cells
617 without manual configuration in those cells).
618
619 You do not, strictly, need an admin token to create these volumes; you do,
620 however, need one to set the initial Access Control List, so a token is used
621 below.
622
623 ### Creating `root.afs`
624
625 You need to do this on a client which does *not* have `-dynroot`, or else you
626 must arrange to mount `root.afs` somewhere else, as `/afs` cannot be used to
627 access the `root.afs` volume when `-dynroot` is in effect. If this is a new
628 cell, you won't have anywhere to mount this until after you create
629 `root.cell`... although you may be able to use `/afs/.:mount/cell:root.cell`
630 (replace the first `cell` with the name of your cell). If you are certain that
631 all possible clients will always use `-dynroot`, you can skip this step; this
632 is not recommended, however.
633
634 #### Without `-dynroot`
635
636     kinit admin
637     aklog
638     vos create localhost a root.afs 500
639     fs checkvolumes
640     # /afs should now be accessible but empty
641     sed -n 's/^>\([^ #]*\).*$/\1/p' /usr/vice/etc/CellservDB |
642     while read cell; do
643         echo "$cell"
644         fs mkmount "/afs/$cell" "${cell}:root.cell" -fast
645         fs mkmount "/afs/.$cell" "${cell}:root.cell" -rw -fast
646     done
647     # create symlinks to commonly used cells here
648     # one common convention is to make the cell name without any
649     # dots available as a symlink, for example:
650     for cell in ece andrew cs; do
651         ln -s $cell.cmu.edu /afs/$cell
652         ln -s .$cell.cmu.edu /afs/.$cell
653     done
654     fs setacl /afs system:anyuser
655     vos addsite localhost a root.afs
656     vos release root.afs
657     fs checkvolumes
658
659 #### With `-dynroot`
660
661     kinit admin
662     aklog
663     vos create localhost a root.afs 500
664     fs checkvolumes
665     sed -n 's/^>\([^ #]*\).*$/\1/p' /usr/vice/etc/CellservDB |
666     while read cell; do
667         echo "$cell"
668         fs mkmount "/afs/.:mount/thiscell:root.afs/$cell" "${cell}:root.cell" -fast
669         fs mkmount "/afs/.:mount/thiscell:root.afs/.$cell" "${cell}:root.cell" -rw -fast
670     done
671     # create symlinks to commonly used cells here
672     # one common convention is to make the cell name without any
673     # dots available as a symlink, for example:
674     for cell in ece andrew cs; do
675         ln -s "$cell.cmu.edu" "/afs/.:mount/thiscell:root.afs/$cell"
676         ln -s ".$cell.cmu.edu" "/afs/.:mount/thiscell:root.afs/.$cell"
677     done
678     fs setacl /afs/.:mount/thiscell:root.afs" system:anyuser
679     vos addsite localhost a root.afs
680     vos release root.afs
681     fs checkvolumes
682
683 Replace `thiscell` with the full name of this cell. Note that the only
684 difference is using the `.:mount` mechanism to access the volume, since with
685 `-dynroot` `/afs` does not reflect the contents of the `root.afs` volume.
686
687 ### Creating `root.cell`
688
689     vos create localhost a root.cell 10000
690     fs checkvolumes
691     fs setacl /afs/.cell system:anyuser rl
692     vos addsite localhost a root.cell
693     vos release root.cell
694     fs checkvolumes
695
696 ### Backup `root.afs` mountpoint
697
698 If you are using `-dynroot`, or if you need emergency access to `root.afs`
699 from somewhere else (this has happened; ask `geekosaur` about the first time
700 he had to add a cell to `ece.cmu.edu`'s `root.afs` sometime), you may want to
701 have an emergency mountpoint for `root.afs` in `root.cell`.
702
703     fs mkmount /afs/.cell/.cell cell:root.afs -rw
704     vos release root.cell
705
706 Replace *all* occurrences of `cell` in the `fs mkmount` line with the local
707 cell name (although you may choose to shorten the second, or if you want you
708 can even leave it as literally `cell`).  The command should end up looking
709 something like
710
711     fs mkmount /afs/.example.com/.example.com example.com:root.afs -rw
712
713 This is not absolutely necessary if there are clients with `-dynroot`, as they
714 will survive loss of `root.afs` and they can use the
715 `/afs/.:mount/`*cell*`:`*volume* syntax to access the read/write volume; but
716 if you are supporting `root.afs` for clients without `-dynroot`, you probably
717 also want a way to recover `root.afs` without assuming `-dynroot`.
718
719 Congratulations! You now have a working [[OpenAFS]] cell. You may want to
720 submit a `CellServDB` entry for inclusion in the master cell database at
721 `grand.central.org`.
722
723 ## Appendix: Boostrapping a KDC
724 <a name="krb5kdc">
725
726 If you do not have a KDC, you can use the one included with [[Oracle
727 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
728 or [[OpenIndiana|http://openindiana.org]]. There are some advantages to using
729 a standard [[MIT|http://web.mit.edu/kerberos/]] or [[Heimdal|http://h5l.org]]
730 installation instead, notably that there is more widely available
731 documentation and a better chance of compatibility with other programs, as
732 well as the ability to use LDAP for replication in place of the standard
733 replication mechanisms. (Standard [[Kerberos|KerberosV]] replication has a
734 number of shortcomings.)
735
736     pkg install pkg:/system/security/kerberos-5
737
738 This package is not installed by default. (Note that the client package *is*
739 installed; somewhat confusingly, this is `pkg:/service/security/kerberos-5`.)
740
741 (Additional note: if you let your fingers run on autopilot, you may
742 accidentally type `pkg://...` which will lead to a confusing error that
743 implies that the package exists but is prohibited from installation.)
744
745 Next you need to edit `/etc/krb5/kdc.conf` and `/etc/krb5/kadm5.acl`. In the
746 former you should subtitute the local realm for the placeholder; in the
747 latter, change the placeholder for the principal name. In this document, we
748 assume that the [[Kerberos|KerberosV]] and [[OpenAFS]] administrative
749 principals are the same and use `admin` for both; this is not necessarily the
750 best approach, but it is simple and you can introduce better administrative
751 identities for both later. (From experience, adding new [[OpenAFS]] users is
752 much more annoying if the [[Kerberos|KerberosV]] and [[OpenAFS]]
753 administrative principals are different; however, in larger organizations,
754 the [[Kerberos|KerberosV]] administrative domain may not be under the
755 [[OpenAFS]] administrator's control.)
756
757     /usr/sbin/kdb5_util create -s
758
759 This creates the [[Kerberos|KerberosV]] principal database and does basic
760 realm setup. It will ask for a realm master key. Write this down and store it
761 in a safe place; it is not necessary for normal realm operation (the `-s`
762 above creates a stash file that is used for nornal operation), but it may be
763 necessary in the case of disaster recovery. Also note that anyone with access
764 to this password or the generated key can decrypt the principal database; keep
765 it safe and keep it secret!
766
767 Next, we generate service keys and the administrative principal.
768
769     /usr/sbin/kadmin.local
770     kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kadmin/hostname changepw/hostname kadmin/changepw
771     kadmin.local: addprinc -randkey host/hostname
772     kadmin.local: ktadd host/hostname
773     kadmin.local: addprinc admin
774
775 In the above, replace `hostname` with the fully qualified local host name.
776
777 You should now be able to bring up the KDC. There are slight differences
778 between [[Oracle
779 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
780 and [[OpenIndiana|http://openindiana.org]] here:
781
782 #### Oracle Solaris
783
784     svcadm enable -r network/security/krb5kdc
785     svcadm enable -r network/security/kadmin
786
787 #### OpenIndiana
788
789     svcadm enable -r security/services/krb5kdc
790     svcadm enable -r security/services/kadmin
791
792 (As of this writing, `kadmind` on [[OpenIndiana|http://openindiana.org]] will
793 not start up; `svcs -x` reports a core dump during initialization. For a
794 simple setup, `kadmin.local` can be used in place of `kadmin` for most
795 maintenance; diagnosis of the core dump is ongoing, but it does not appear
796 that any package updates have been made to
797 [[OpenIndiana|http://openindiana.org]] since October 2012 so there is not
798 likely to be a fix in the near future.)
799
800 Now you're ready to [[go back to the main
801 instructions|SolarisQuickStart#krb5]].