1 # Solaris 11 Quick Start
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
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
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
32 ### Choosing a realm and cell name
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
42 Some things to watch out for, though:
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.)
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.)
62 ### Fixing `/etc/hosts` on servers
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.
78 ### Configuring [[NTP|FurtherReading#NTP]]
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.
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.
99 cp ntp.client ntp.conf
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.)
115 svcadm enable network/ntp
117 ### Configuring [[Kerberos|KerberosV]]
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]].
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.
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]].
140 ln -s krb5/krb5.conf /etc/krb5.conf # for Solaris bundled Kerberos
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]].
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!
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
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
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
180 allow_weak_crypto = true
182 (We don't like this either, but there isn't anything to be done about it until
185 ### Adding `/usr/afsws/bin` and `/usr/afs/bin` to the system path
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`
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.
199 #### `csh` and `tcsh`
201 % set path=(/usr/afs/bin /usr/afsws/bin $path:q)
203 #### Older Solaris `/bin/sh`
205 $ PATH="/usr/afs/bin:/usr/afsws/bin:$PATH"
208 #### Most other shells
210 $ export PATH="/usr/afs/bin:/usr/afsws/bin:$PATH"
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
216 ## Unpacking the distribution
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.)
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
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
237 Two things about the final command:
239 1. On SPARC, both filenames need to be adjusted.
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
251 ## Setting up a client
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
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
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.
269 echo ' -dynroot -fakestat' >>/usr/vice/etc/config/afsd.options
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]].
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]].
278 ## Setting up a server
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.
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.
300 mv afsws/root.server/usr/afs afs
302 mkdir etc db local logs
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.
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
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`:
325 /usr/afs/bin/bosserver -noauth
326 /usr/afs/bin/asetkey add vno /usr/afs/etc/afs.keytab afs/cell
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
336 Once you have a `KeyFile` in place, you are ready to configure a server.
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:
343 /usr/afs/bin/bosserver
344 /usr/afs/bin/bos setcellname localhost cell -localauth
345 /usr/afs/bin/bos adduser localhost admin -localauth
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.
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]].
354 ## Setting up a db server
356 If you haven't already, start the Basic OverSeer (`bos`) service.
358 /usr/afs/bin/bosserver
360 If you are adding a new machine to an existing cell, register the machine as a
363 /usr/afs/bin/bos addhost localhost fqdn -localauth
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.
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
372 If this is an existing cell that uses `kaserver` then you will need to set
375 /usr/afs/bin/bos create localhost ka simple /usr/afs/bin/kaserver -localauth
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]].)
388 ## Basic client functionality
389 <a name="basicclient">
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`!)
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
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.
411 ## Final client configuration
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
417 echo cell shortname >/usr/vice/etc/CellAlias
418 echo anothercell shortname >>/usr/vice/etc/CellAlias
420 `cell` is the full name of the local cell, and `shortname` is the alias
421 (e.g. `example.com example`).
423 Create the AFS mountpoint and cache directory.
426 mkdir -p /var/vice/cache
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]]
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
436 [[ZFS|http://www.oracle.com/technetwork/server-storage/solaris11/technologies/zfs-338092.html]]-based
437 cache; we therefore use a legacy cache partition:
439 zfs create -V size rpool/venus
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
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.)
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
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
461 (You can use the block device for both; you can't mount the raw device, though.)
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
467 /dev/zvol/dsk/rpool/venus /dev/zvol/rdsk/rpool/venus /var/vice/cache ufs 2 yes -
469 The first entry is the block device; the second should be the raw device, for
472 Create the `cacheinfo` file.
474 echo /afs:/var/vice/cache:size >/usr/vice/etc/cacheinfo
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
480 And we should be ready to start the client:
482 /etc/init.d/afs start
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
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.
493 ## Finishing new db server configuration
496 Now that we have a client, we can finish setting up the admin account:
498 /usr/afsws/bin/pts createuser admin -localauth
499 /usr/afsws/bin/pts adduser admin system:administrators -localauth
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.)
506 At this point, it should be possible to switch from using `-localauth` to
507 using an actual token.
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
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.
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
528 ## Setting up a file server
529 <a name="fileserver">
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
535 [[OpenAFS]] file servers use dedicated partitions to hold volumes. The
536 partitions are *not* intended to be user accessible.
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.)
548 zfs create -o mountpoint=/vicepa rpool/vicepa
549 zfs create -o mountpoint=/vicepb rpool/vicepb
550 # or newfs and mount your traditional slices
552 ### File server tuning
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.
561 ### namei and inode file servers
563 As of [[OpenAFS]] 1.6, the standard binary [[OpenAFS]] distribution for
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.
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`.
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.)
581 #### [[Demand attach|DemandAttach]] file server
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
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
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
599 #### Traditional file server
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
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
610 ## The first file server
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).
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
623 ### Creating `root.afs`
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.
634 #### Without `-dynroot`
638 vos create localhost a root.afs 500
640 # /afs should now be accessible but empty
641 sed -n 's/^>\([^ #]*\).*$/\1/p' /usr/vice/etc/CellservDB |
644 fs mkmount "/afs/$cell" "${cell}:root.cell" -fast
645 fs mkmount "/afs/.$cell" "${cell}:root.cell" -rw -fast
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
654 fs setacl /afs system:anyuser
655 vos addsite localhost a root.afs
663 vos create localhost a root.afs 500
665 sed -n 's/^>\([^ #]*\).*$/\1/p' /usr/vice/etc/CellservDB |
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
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"
678 fs setacl /afs/.:mount/thiscell:root.afs" system:anyuser
679 vos addsite localhost a root.afs
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.
687 ### Creating `root.cell`
689 vos create localhost a root.cell 10000
691 fs setacl /afs/.cell system:anyuser rl
692 vos addsite localhost a root.cell
693 vos release root.cell
696 ### Backup `root.afs` mountpoint
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`.
703 fs mkmount /afs/.cell/.cell cell:root.afs -rw
704 vos release root.cell
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
711 fs mkmount /afs/.example.com/.example.com example.com:root.afs -rw
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`.
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
723 ## Appendix: Boostrapping a KDC
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.)
736 pkg install pkg:/system/security/kerberos-5
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`.)
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.)
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.)
757 /usr/sbin/kdb5_util create -s
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!
767 Next, we generate service keys and the administrative principal.
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
775 In the above, replace `hostname` with the fully qualified local host name.
777 You should now be able to bring up the KDC. There are slight differences
779 Solaris|http://www.oracle.com/us/products/servers-storage/solaris/overview/index.html]]
780 and [[OpenIndiana|http://openindiana.org]] here:
784 svcadm enable -r network/security/krb5kdc
785 svcadm enable -r network/security/kadmin
789 svcadm enable -r security/services/krb5kdc
790 svcadm enable -r security/services/kadmin
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.)
800 Now you're ready to [[go back to the main
801 instructions|SolarisQuickStart#krb5]].