asetkey list skips rxkad_krb5 keys
[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
173 ### Adding `/usr/afsws/bin` and `/usr/afs/bin` to the system path
174
175 [[Oracle
176 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
177 does not support a directory of profile fragments (such as Linux's
178 `/etc/profile.d`), so you will need to edit `/etc/profile` and `/etc/.login`
179 to add `/usr/afsws/bin` (and, on servers, `/usr/afs/bin`) to `$PATH`. Note
180 that, on servers, you may wish to not place `/usr/afs/bin` on the system path,
181 but instead have administrators add it to `$HOME/.profile` or `$HOME/.login`
182 as needed.
183
184 As a convenience while setting up the server, if you don't want to log out and
185 back in to pick up the new path, you can set it directly in your shell.
186
187 #### `csh` and `tcsh`
188
189     % set path=(/usr/afs/bin /usr/afsws/bin $path:q)
190
191 #### Older Solaris `/bin/sh`
192
193     $ PATH="/usr/afs/bin:/usr/afsws/bin:$PATH"
194     $ export PATH
195
196 #### Most other shells
197
198     $ export PATH="/usr/afs/bin:/usr/afsws/bin:$PATH"
199
200 (You're on your own if you are using a non-traditional shell such as `rc` or
201 `fish`.) These are also the commands you would add to `/etc/profile` and
202 `/etc/.login`.
203
204 ## Unpacking the distribution
205
206 Unlike the Linux packages, [[OpenAFS]] for [[Oracle
207 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
208 is distributed as a "dest" tree with minimal configuration. (An IPS package is
209 planned for the future; this will also use modern paths instead of the old
210 Transarc-style paths.)
211
212     cd /usr
213     gzip -dc sunx86_511.tar.gz | tar xf - # on SPARC, replace sunx86 with sun4x
214     # OpenIndiana and newer Solaris allow: tar xfz sunx86_511.tar.gz
215     mv sunx86_511/dest afsws
216     rmdir sunx86_511
217     cd afsws
218     mv root.client/usr/vice /usr/vice
219     rmdir -p root.client/usr
220     ln -s /usr/vice/etc/modload/afs.rc /etc/init.d/afs
221     ln -s ../init.d/afs /etc/rc2.d/S70afs
222     ln -s ../init.d/afs /etc/rc0.d/K66afs
223     cp /usr/vice/etc/modload/libafs64.nonfs.o /kernel/drv/amd64/afs
224
225 Two things about the final command:
226
227 1. On SPARC, both filenames need to be adjusted.
228
229 2. [[OpenAFS]] contains support for an AFS/NFS translator which allows an AFS
230 client (*not* server) to re-export part of AFS over NFS and will provide
231 limited authentication features and `@sys` translation for NFS clients
232 accessing the NFS share. This implementation requires that `libafs64.o` be
233 installed instead of `libafs64.nonfs.o`. However, the Translator is known not
234 to work properly with current [[Oracle
235 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
236 versions, so for practical purposes only the `nonfs` version should be
237 installed.
238
239 ## Setting up a client
240
241 The default client configuration assumes a traditional cell with a manually
242 populated `root.afs` volume and no need to support file managers. Modern cells
243 typically expect clients to use a dynamic root volume instead; additionally, a
244 number of file managers (Windows Explorer, Gnome's Nautilus, KDE's Dolphin,
245 Thunar, etc.) and various GUI file open/save dialogs have a certain tendency
246 to try to enumerate `/afs` as if it were a local filesystem, with unfortunate
247 results.
248
249     mkdir /usr/vice/etc/config
250     egrep '^(EXTRAOPTS|MEDIUM)=' /etc/init.d/afs |
251     sed 's/^[A-Z][A-Z]*="\(.*\)"$/\1/' >/usr/vice/etc/config/afsd.options
252
253 You may wish to replace `MEDIUM` with `SMALL` or `LARGE`; while the latter
254 uses a bit more memory, modern machines should not have an issue with it, and
255 client performance will be better.
256
257     echo ' -dynroot -fakestat' >>/usr/vice/etc/config/afsd.options
258
259 The quoting and leading space are so that you don't need to care about
260 [[which `echo` you're getting|http://everything2.com/title/The+UNIX+and+the+Echo]].
261
262 If you are going to make this machine a db or file server, continue with the
263 next section. Otherwise, skip ahead to
264 [[Basic client functionality|SolarisQuickStart#basicclient]].
265
266 ## Setting up a server
267
268 [[OpenAFS]] requires a number of databases: the Protection (`pt`) Database
269 records users and groups, and the Volume Location (`vl`) Database records the
270 file servers which hold copies of a volume. An AFS cell requires that at least
271 one (and preferably three; you should avoid having only *two* because of a
272 shortcoming in the quorum process) db server exist; each db server must
273 provide both prdb and vldb services. Most installations also provide KDCs on
274 the db hosts, because older versions of AFS included an additional Kerberos
275 Authentication (`ka`) database based on an older, now known to be insecure,
276 version of the Kerberos protocol. [[OpenAFS]] *does not* require that the
277 KDCs be on the db servers.
278
279     cd /usr
280     mv afsws/root.server/usr/afs afs
281     cd afs
282     mkdir etc db local logs
283     chown root . bin
284     chmod 700 local db
285
286 At this point, if you are adding a server to an *existing* cell, you should
287 copy the `KeyFile` and `rxkad.keytab` from an existing db server or file
288 server. (This file is highly sensitive, as servers use it to authenticate
289 to each other and administrators may use it to authenticate to servers;
290 use a secure copying protocol such as `scp`.) If this is a *new* cell,
291 you will need to create a cell principal: use `kadmin` as a principal with
292 [[Kerberos|KerberosV]] administrative rights.
293
294     kadmin: addprinc -randkey afs/cell
295     kadmin: ktadd -k /usr/afs/etc/rxkad.keytab afs/cell
296
297 The string `cell` above should be replaced with the name of the cell (note:
298 *not* the [[Kerberos|KerberosV]] realm or domain name as with most
299 [[Kerberos|KerberosV]] service principals!). It is also possible to use simply
300 `afs` as the cell principal, but this is not recommended for new
301 installations.
302
303 Current versions of OpenAFS require you to create an empty `KeyFile`.
304 (This was used for legacy DES authentication and should not be used in
305 modern installations. Later versions of OpenAFS may create it automatically
306 if `rxkad.keytab` is found.)
307
308     touch /usr/afs/etc/KeyFile
309
310 Once you have `rxkad.keytab` in place, you are ready to configure a server.
311
312 If this is an existing cell, you should copy the *server* `ThisCell`,
313 `CellServDB`, and `UserList` to `/usr/afs/etc`. (These will usually be in
314 `/usr/afs/etc` or `/etc/openafs/server` depending on how the existing server
315 is configured.) Otherwise:
316
317     /usr/afs/bin/bosserver
318     /usr/afs/bin/bos setcellname localhost cell -localauth
319     /usr/afs/bin/bos adduser localhost admin -localauth
320
321 As before, replace `cell` with the actual cell name. If this complains about
322 authentication, you will need to verify your [[Kerberos|KerberosV]]
323 configuration and that your `rxkad.keytab` matches the KDC.
324
325 If this machine is only to be a file server and not a db server, skip ahead to
326 [[Setting up a file server|SolarisQuickStart#fileserver]].
327
328 ## Setting up a db server
329
330 If you haven't already, start the Basic OverSeer (`bos`) service.
331
332     /usr/afs/bin/bosserver
333
334 If you are adding a new machine to an existing cell, register the machine as a
335 new db server:
336
337     /usr/afs/bin/bos addhost localhost fqdn -localauth
338
339 `fqdn` here is the fully qualified domain name of the local host. Note that
340 this will also need to be run (with *this* host's name) on the existing db
341 servers so that they will know about the new db server.
342
343     /usr/afs/bin/bos create localhost pt simple /usr/afs/bin/ptserver -localauth
344     /usr/afs/bin/bos create localhost vl simple /usr/afs/bin/vlserver -localauth
345
346 If this is an existing cell that uses `kaserver` then you will need to set
347 that up as well:
348
349     /usr/afs/bin/bos create localhost ka simple /usr/afs/bin/kaserver -localauth
350
351 If this is a *new* cell then you need to initialize the Protection Database
352 and create the `UserList`. Note that at this point you need a working client;
353 it is somewhat easier if this client is running on the new server, since a
354 remote client probably does not have an appropriate `rxkad.keytab` and it cannot
355 authenticate as the cell admin until *after* this command is run. If this is a
356 new db server in an existing cell, you are done except for doing the `bos
357 addhost` above on the existing db servers and waiting for the new server to
358 replicate the databases. (If it is a file server, you probably want to
359 continue with the next section and then skip ahead to
360 [[Setting up a file server|SolarisQuickStart#fileserver]].)
361
362 ## Basic client functionality
363 <a name="basicclient">
364
365 Configure the client `ThisCell` and `CellServDB`. If you are using DNS for
366 [[OpenAFS]] autoconfiguration, you don't absolutely need the `CellServDB`; if
367 you are using dynamic root, you may also want `CellAlias`. If this client is
368 in an existing cell, easiest is probably to copy these files from an existing
369 client. For a new cell, the cell setup above, as of [[OpenAFS]] 1.6.2, will
370 have created the client `ThisCell` from the server `ThisCell` and made
371 `CellServDB` a symlink to the server one. (Beware of this; naïvely copying
372 another `CellServDB` over this will overwrite the server `CellServDB`!)
373
374     cd /usr/vice/etc
375     mv CellServDB CellServDB.local
376     # copy an existing CellServDB, such as the grand.central.org master, to CellServDB.master
377     cat CellServDB.local CellServDB.master >CellServDB
378
379 If this is a server and you do not want to run a full client, this is all you
380 need to do; skip to [[Finishing new db server
381 configuration#SolarisQuickStart#finishing]] or
382 [[Setting up a file server|SolarisQuickStart#fileserver]] as
383 appropriate. If you want a full client, continue with the next section.
384
385 ## Final client configuration
386
387 If you are using `-fakestat`, you will want a `CellAlias` for the local cell,
388 and possibly sibling or other often used cells, so that they will be usable
389 with short names.
390
391     echo cell shortname >/usr/vice/etc/CellAlias
392     echo anothercell shortname >>/usr/vice/etc/CellAlias
393
394 `cell` is the full name of the local cell, and `shortname` is the alias
395 (e.g. `example.com example`).
396
397 Create the AFS mountpoint and cache directory.
398
399     mkdir /afs
400     mkdir -p /var/vice/cache
401
402 The cache should be on its own filesystem. Most modern [[Oracle
403 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
404 installations use
405 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]
406 "out of the box"; this is both blessing and curse, as
407 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]
408 makes partitioning easy but the current [[OpenAFS]] cache implementation plays
409 poorly with a
410 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]-based
411 cache; we therefore use a legacy cache partition:
412
413     zfs create -V size rpool/venus
414
415 `size` should be somewhat larger than the expected cache size. `rpool` is the
416 name that current [[Oracle
417 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
418 and [[OpenIndiana|http://openindiana.org]] use for the automatically created
419 initial
420 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]
421 pool; you may have additional, or differently named, pools — use `zpool list`
422 to see the available pools. (`venus` can be anything you want that isn't
423 already in use; historically, the AFS2 cache manager component was called
424 `venus`, so it is used as such here. Compare `vice` for server-related things,
425 in particular the server partitions.)
426
427 Create the cache filesystem. The example here uses a
428 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]
429 zvolume; if you are using a traditional slice, substitute its raw and block
430 device names.
431
432     newfs /dev/zvol/rdsk/rpool/venus # or e.g. /dev/rdsk/c0t0d0s4
433     mount /dev/zvol/dsk/rpool/venus /var/vice/cache # or e.g. /dev/dsk/c0t0d0s4
434
435 (You can use the block device for both; you can't mount the raw device, though.)
436
437 You will also need to add this to `/etc/vfstab` so that it will be mounted at
438 system startup. The entry to add to the end of `vfstab` will look something
439 like:
440
441     /dev/zvol/dsk/rpool/venus   /dev/zvol/rdsk/rpool/venus   /var/vice/cache   ufs   2   yes   -
442
443 The first entry is the block device; the second should be the raw device, for
444 `fsck`.
445
446 Create the `cacheinfo` file.
447
448     echo /afs:/var/vice/cache:size >/usr/vice/etc/cacheinfo
449
450 `size` is some size which is smaller than the actual cache partition size,
451 since the [[OpenAFS]] cache may temporarily grow beyond its defined size under
452 some circumstances.
453
454 And we should be ready to start the client:
455
456     /etc/init.d/afs start
457
458 Note that, in a new cell, `/afs` won't be usable just yet; we haven't set up a
459 file server, and there is no `root.cell` volume (or `root.afs` for traditional
460 non-dynamic root configurations), and accessing `/afs` or the local cell will
461 produce errors.
462
463 If this is a client instead of a server, you are now done! If it is a file
464 server, skip to [[Setting up a file server|SolarisQuickStart#fileserver]]. If
465 it is a database server, continue to the next section.
466
467 ## Finishing new db server configuration
468 <a name="finishing">
469
470 Now that we have a client, we can finish setting up the admin account:
471
472     /usr/afsws/bin/pts createuser admin -localauth
473     /usr/afsws/bin/pts adduser admin system:administrators -localauth
474
475 (It is somewhat odd that the client is needed here. Note that
476 `/usr/afs/bin/pts` also exists, but it is identical to the one in
477 `/usr/afsws/bin` and it uses the *client*, not server, configuration. If not
478 for this, we would not need to have the client set up yet.)
479
480 At this point, it should be possible to switch from using `-localauth` to
481 using an actual token.
482
483     kinit admin
484
485 Solaris `kinit` will likely pause here and spit out some complaints about
486 "`getpwnam failed for name=admin`"; it's trying to do NFSv4 initialization,
487 which we do not care about so the NFSv4 configuration it is looking for
488 has not been done.
489
490     aklog
491     pts examine admin
492
493 If things are working correctly, there should not be a complaint from
494 `libprot` here; if there is, then you should probably check your
495 [[Kerberos|KerberosV]] configuration.
496
497 At this point, you are done with the db server. If this machine should also be
498 a file server, continue with the next section; if not, you are done with this
499 server but you will want to set up another machine to be the cell's first file
500 server.
501
502 ## Setting up a file server
503 <a name="fileserver">
504
505 At this point, you should have at least working db server, and if this is the
506 first file server for a new cell then there should be a working client for the
507 cell somewhere.
508
509 [[OpenAFS]] file servers use dedicated partitions to hold volumes. The
510 partitions are *not* intended to be user accessible.
511
512 If you are using traditional disk slices, you should arrange for the server
513 partitions to be mounted as paths beginning with `/vicep`; in the examples
514 below, we use `/vicepa` and `/vicepb` as server partitions. If using
515 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]],
516 you may want a separate zpool for server partitions. The examples below use
517 the default zpool created by a basic [[Oracle
518 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
519 or [[OpenIndiana|http://openindiana.org]] install, which is called `rpool`.
520 (Note that ZFS works best with some tuning, which is not covered here.)
521
522     zfs create -o mountpoint=/vicepa rpool/vicepa
523     zfs create -o mountpoint=/vicepb rpool/vicepb
524     # or newfs and mount your traditional slices
525
526 ### File server tuning
527
528 The file server configurations below contain suggested tuning parameters. It is
529 not necessary to include these, but performance will generally be better with
530 them. You may want to look at
531 [[http://conferences.inf.ed.ac.uk/eakc2012/slides/AFS_Performance.pdf]]
532 for more information about performance tuning; detailed performance tuning is
533 beyond the scope of this document.
534
535 ### namei and inode file servers
536
537 As of [[OpenAFS]] 1.6, the standard binary [[OpenAFS]] distribution for
538 [[Oracle
539 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
540 uses the namei file server instead of the old, deprecated inode file
541 server. If you are replacing an old file server, be aware that you cannot use
542 a namei partition with an inode file server or vice versa. Keep the old file
543 server on line and `vos move` partitions to the new file server, instead of
544 trying to attach the old partitions directly to the new file server.
545
546 To check the format of a file server, look at one of the `/vicepx`
547 partitions. An inode server will (or should) appear to be empty. A namei
548 fileserver will have, at absolute minimum, a directory named `AFSIDat`.
549
550 (It is still possible to build [[OpenAFS]] from source with inode support, but
551 there is a bug in current [[OpenAFS]] versions that causes inode file servers
552 to not work correctly. As inode file servers have been deprecated for some
553 time now, inode file servers should be migrated to namei.)
554
555 #### [[Demand attach|DemandAttach]] file server
556
557 [[OpenAFS]] 1.6 includes a [[demand attach file server|DemandAttach]]. Initial
558 setup is slightly more cumbersome than the old file server, but performance is
559 better — especially when restarting a file server, as it does not need to
560 break callbacks before shutting down or check all volumes before coming back
561 up.
562
563 It is entirely possible to have both [[demand attach|DemandAttach]] and
564 traditional file servers in a cell, although a particular file server must be
565 one or the other.
566
567     bos create localhost fs dafs \
568         '/usr/afs/bin/dafileserver -p 123 -L -busyat 200 -rxpck 2000 -cb 4000000 -vattachpar 128 -vlruthresh 1440 -vlrumax 8 -vhashsize 11' \
569         '/usr/afs/bin/davolserver -p 64 -log' \
570         /usr/afs/bin/salvageserver \
571         '/usr/afs/bin/dasalvager -parallel all32' -localauth
572
573 #### Traditional file server
574
575     bos create localhost fs fs \
576         '/usr/afs/bin/fileserver -p 123 -L -busyat 200 -rxpck 2000 -cb 4000000' \
577         '/usr/afs/bin/volserver -p 127 -log' \
578         '/usr/afs/bin/salvager -parallel -all32' -localauth
579
580 If this is a new file server for an existing cell, you are done. If this is a
581 new cell, you still need to create the initial volumes; continue to the next
582 section.
583
584 ## The first file server
585
586 A new cell needs certain volumes to exist. If you will have any clients that
587 do not use dynamic root (`-dynroot`), then you will need a `root.afs` volume;
588 every cell needs a root volume, conventionally called `root.cell` (you can
589 change this, but there is an assumption that the root of remote cells is this
590 volume, so your cell will not be directly accessible from foreign cells
591 without manual configuration in those cells).
592
593 You do not, strictly, need an admin token to create these volumes; you do,
594 however, need one to set the initial Access Control List, so a token is used
595 below.
596
597 ### Creating `root.afs`
598
599 You need to do this on a client which does *not* have `-dynroot`, or else you
600 must arrange to mount `root.afs` somewhere else, as `/afs` cannot be used to
601 access the `root.afs` volume when `-dynroot` is in effect. If this is a new
602 cell, you won't have anywhere to mount this until after you create
603 `root.cell`... although you may be able to use `/afs/.:mount/cell:root.cell`
604 (replace the first `cell` with the name of your cell). If you are certain that
605 all possible clients will always use `-dynroot`, you can skip this step; this
606 is not recommended, however.
607
608 #### Without `-dynroot`
609
610     kinit admin
611     aklog
612     vos create localhost a root.afs 500
613     fs checkvolumes
614     # /afs should now be accessible but empty
615     sed -n 's/^>\([^ #]*\).*$/\1/p' /usr/vice/etc/CellservDB |
616     while read cell; do
617         echo "$cell"
618         fs mkmount "/afs/$cell" "${cell}:root.cell" -fast
619         fs mkmount "/afs/.$cell" "${cell}:root.cell" -rw -fast
620     done
621     # create symlinks to commonly used cells here
622     # one common convention is to make the cell name without any
623     # dots available as a symlink, for example:
624     for cell in ece andrew cs; do
625         ln -s $cell.cmu.edu /afs/$cell
626         ln -s .$cell.cmu.edu /afs/.$cell
627     done
628     fs setacl /afs system:anyuser
629     vos addsite localhost a root.afs
630     vos release root.afs
631     fs checkvolumes
632
633 #### With `-dynroot`
634
635     kinit admin
636     aklog
637     vos create localhost a root.afs 500
638     fs checkvolumes
639     sed -n 's/^>\([^ #]*\).*$/\1/p' /usr/vice/etc/CellservDB |
640     while read cell; do
641         echo "$cell"
642         fs mkmount "/afs/.:mount/thiscell:root.afs/$cell" "${cell}:root.cell" -fast
643         fs mkmount "/afs/.:mount/thiscell:root.afs/.$cell" "${cell}:root.cell" -rw -fast
644     done
645     # create symlinks to commonly used cells here
646     # one common convention is to make the cell name without any
647     # dots available as a symlink, for example:
648     for cell in ece andrew cs; do
649         ln -s "$cell.cmu.edu" "/afs/.:mount/thiscell:root.afs/$cell"
650         ln -s ".$cell.cmu.edu" "/afs/.:mount/thiscell:root.afs/.$cell"
651     done
652     fs setacl /afs/.:mount/thiscell:root.afs" system:anyuser
653     vos addsite localhost a root.afs
654     vos release root.afs
655     fs checkvolumes
656
657 Replace `thiscell` with the full name of this cell. Note that the only
658 difference is using the `.:mount` mechanism to access the volume, since with
659 `-dynroot` `/afs` does not reflect the contents of the `root.afs` volume.
660
661 ### Creating `root.cell`
662
663     vos create localhost a root.cell 10000
664     fs checkvolumes
665     fs setacl /afs/.cell system:anyuser rl
666     vos addsite localhost a root.cell
667     vos release root.cell
668     fs checkvolumes
669
670 ### Backup `root.afs` mountpoint
671
672 If you are using `-dynroot`, or if you need emergency access to `root.afs`
673 from somewhere else (this has happened; ask `geekosaur` about the first time
674 he had to add a cell to `ece.cmu.edu`'s `root.afs` sometime), you may want to
675 have an emergency mountpoint for `root.afs` in `root.cell`.
676
677     fs mkmount /afs/.cell/.cell cell:root.afs -rw
678     vos release root.cell
679
680 Replace *all* occurrences of `cell` in the `fs mkmount` line with the local
681 cell name (although you may choose to shorten the second, or if you want you
682 can even leave it as literally `cell`).  The command should end up looking
683 something like
684
685     fs mkmount /afs/.example.com/.example.com example.com:root.afs -rw
686
687 This is not absolutely necessary if there are clients with `-dynroot`, as they
688 will survive loss of `root.afs` and they can use the
689 `/afs/.:mount/`*cell*`:`*volume* syntax to access the read/write volume; but
690 if you are supporting `root.afs` for clients without `-dynroot`, you probably
691 also want a way to recover `root.afs` without assuming `-dynroot`.
692
693 Congratulations! You now have a working [[OpenAFS]] cell. You may want to
694 submit a `CellServDB` entry for inclusion in the master cell database at
695 `grand.central.org`.
696
697 ## Appendix: Boostrapping a KDC
698 <a name="krb5kdc">
699
700 If you do not have a KDC, you can use the one included with [[Oracle
701 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
702 or [[OpenIndiana|http://openindiana.org]]. There are some advantages to using
703 a standard [[MIT|http://web.mit.edu/kerberos/]] or [[Heimdal|http://h5l.org]]
704 installation instead, notably that there is more widely available
705 documentation and a better chance of compatibility with other programs, as
706 well as the ability to use LDAP for replication in place of the standard
707 replication mechanisms. (Standard [[Kerberos|KerberosV]] replication has a
708 number of shortcomings.)
709
710     pkg install pkg:/system/security/kerberos-5
711
712 This package is not installed by default. (Note that the client package *is*
713 installed; somewhat confusingly, this is `pkg:/service/security/kerberos-5`.)
714
715 (Additional note: if you let your fingers run on autopilot, you may
716 accidentally type `pkg://...` which will lead to a confusing error that
717 implies that the package exists but is prohibited from installation.)
718
719 Next you need to edit `/etc/krb5/kdc.conf` and `/etc/krb5/kadm5.acl`. In the
720 former you should subtitute the local realm for the placeholder; in the
721 latter, change the placeholder for the principal name. In this document, we
722 assume that the [[Kerberos|KerberosV]] and [[OpenAFS]] administrative
723 principals are the same and use `admin` for both; this is not necessarily the
724 best approach, but it is simple and you can introduce better administrative
725 identities for both later. (From experience, adding new [[OpenAFS]] users is
726 much more annoying if the [[Kerberos|KerberosV]] and [[OpenAFS]]
727 administrative principals are different; however, in larger organizations,
728 the [[Kerberos|KerberosV]] administrative domain may not be under the
729 [[OpenAFS]] administrator's control.)
730
731     /usr/sbin/kdb5_util create -s
732
733 This creates the [[Kerberos|KerberosV]] principal database and does basic
734 realm setup. It will ask for a realm master key. Write this down and store it
735 in a safe place; it is not necessary for normal realm operation (the `-s`
736 above creates a stash file that is used for nornal operation), but it may be
737 necessary in the case of disaster recovery. Also note that anyone with access
738 to this password or the generated key can decrypt the principal database; keep
739 it safe and keep it secret!
740
741 Next, we generate service keys and the administrative principal.
742
743     /usr/sbin/kadmin.local
744     kadmin.local: ktadd -k /etc/krb5/kadm5.keytab kadmin/hostname changepw/hostname kadmin/changepw
745     kadmin.local: addprinc -randkey host/hostname
746     kadmin.local: ktadd host/hostname
747     kadmin.local: addprinc admin
748
749 In the above, replace `hostname` with the fully qualified local host name.
750
751 You should now be able to bring up the KDC. There are slight differences
752 between [[Oracle
753 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
754 and [[OpenIndiana|http://openindiana.org]] here:
755
756 #### Oracle Solaris
757
758     svcadm enable -r network/security/krb5kdc
759     svcadm enable -r network/security/kadmin
760
761 #### OpenIndiana
762
763     svcadm enable -r security/services/krb5kdc
764     svcadm enable -r security/services/kadmin
765
766 (As of this writing, `kadmind` on [[OpenIndiana|http://openindiana.org]] will
767 not start up; `svcs -x` reports a core dump during initialization. For a
768 simple setup, `kadmin.local` can be used in place of `kadmin` for most
769 maintenance; diagnosis of the core dump is ongoing, but it does not appear
770 that any package updates have been made to
771 [[OpenIndiana|http://openindiana.org]] since October 2012 so there is not
772 likely to be a fix in the near future.)
773
774 Now you're ready to [[go back to the main
775 instructions|SolarisQuickStart#krb5]].