Commit | Line | Data |
---|---|---|
b7cfede0 BK |
1 | OpenAFS for Debian |
2 | ||
3 | Introduction | |
4 | ||
5 | For an OpenAFS client system, install openafs-client and a kernel | |
6 | module. See README.modules for information on how to build the kernel | |
7 | module for your system. Then, read /etc/openafs/afs.conf to understand | |
8 | the client configuration options. The openafs-client package will | |
9 | attempt to guess at a good cache configuration based on the size of your | |
10 | cache, but you may want to tune it further. There are also other | |
11 | options configured in that file you may want to consider. | |
12 | ||
13 | FAM does not work correctly with AFS except for directories that are | |
14 | world-readable since it does not run in the user's security context and | |
15 | therefore doesn't have the user's AFS tokens. If you are using FAM, | |
16 | you'll encounter errors from file managers such as Nautilus that use it | |
17 | if you browse restricted AFS directories. Instead of FAM, install | |
18 | gamin, which runs in the user's security context and works correctly | |
19 | with AFS. | |
20 | ||
21 | For information on how to set up an OpenAFS server, read README.servers. | |
22 | You will want the openafs-fileserver package for a file server and, | |
23 | additionally, the openafs-dbserver package for a database server. | |
24 | ||
25 | Documentation | |
26 | ||
27 | For the complete OpenAFS manual, install openafs-doc. This is the same | |
28 | documentation as found at <http://www.openafs.org/>, and is | |
29 | unfortunately outdated in several respects, but it's the best that we | |
30 | have at present. | |
31 | ||
32 | If want to set up a new cell, read README.servers and then look at the | |
33 | example session in configuration-transcript.txt.gz in this directory. | |
34 | The procedure outlined in these two files is much simpler and more | |
35 | secure than the one in the OpenAFS documentation, but the OpenAFS | |
36 | documentation provides useful background. | |
37 | ||
38 | Build Options | |
39 | ||
40 | The OpenAFS file server has been built with --enable-demand-attach-fs, | |
41 | which enables a new method of handling volume attachment. Volumes will | |
42 | be attached only when needed, and the file server will persist state to | |
43 | disk when shutting down for faster restarts. This file server mode is | |
44 | experimental and should not yet be used for production data. Please | |
45 | report any bugs you encounter. | |
46 | ||
47 | The OpenAFS servers have been built with --enable-supergroups, which | |
48 | permits nesting of PTS groups. Be aware that the PT database created by | |
49 | these packages is not compatible with servers not built with | |
50 | --enable-supergroups if nested PTS groups are used. In other words, if | |
51 | you need the openafs-dbserver package to interoperate with ptservers | |
52 | that aren't built with this option, don't use this capability. | |
53 | ||
54 | The OpenAFS client and kernel module have been built with | |
55 | --enable-disconnected, which enables experimental support for | |
56 | disconnected operations. This support is still experimental and known | |
57 | to have problems, but should not interfere with normal use of AFS. If | |
58 | you want to experiment with it, see fs help discon. | |
59 | ||
60 | Changes Relative to Stock OpenAFS | |
61 | ||
62 | Long-time AFS users may be confused by the directory layout. The files | |
63 | that normally go in /usr/vice/etc go in /etc/openafs. The cache should | |
64 | be mounted on /var/cache/openafs. The server files have been moved | |
65 | around even more; see README.servers for the details. | |
66 | ||
67 | The OpenAFS kernel module is named openafs, not libafs, to better match | |
68 | normal Linux kernel module naming standards. The Debian source package | |
69 | only builds one kernel module that matches the kernel source tree it is | |
70 | built against and does not attempt to build separate SMP and non-SMP | |
71 | modules against the same tree. Doing so does not work on all platforms. | |
72 | To distinguish between an SMP and a non-SMP kernel module package, use | |
73 | --append_to_version; see README.modules for more information. | |
74 | ||
75 | The AFS up utility is installed as afs-up, since the standard name is | |
76 | rather generic. | |
77 | ||
78 | The libopenafs-dev package only includes static libraries and there are | |
79 | no shared library packages. The shared libraries built by AFS are not | |
80 | compatible with Debian policy. They do not have a stable ABI or an | |
81 | appropriate SONAME. | |
82 | ||
83 | kaserver is not included. New AFS cells should use Kerberos v5 rather | |
84 | than the old K4-based kaserver KDC. | |
85 | ||
86 | Debugging and Bug Reporting | |
87 | ||
88 | The current OpenAFS installation process installs fileserver and | |
89 | volserver unstripped, since backtraces and other debugging information | |
90 | for those binaries are necessary to track down file server problems. | |
91 | For the Debian packages, the fileserver and volserver binaries in the | |
92 | openafs-fileserver package are stripped, but the debugging information | |
93 | is available in the openafs-dbg package, which can be installed | |
94 | separately. If it is installed, gdb will find that debugging | |
95 | information automatically. | |
96 | ||
97 | Eventually the openafs-dbg package will contain debugging information | |
98 | for all OpenAFS binaries. | |
99 | ||
100 | When reporting a bug in the OpenAFS client, please include your exact | |
101 | kernel version and architecture (reportbug will do this for you). Also, | |
102 | if the client caused a kernel oops or BUG, be sure to include the | |
103 | complete kernel output, including the lines before the oops. That's | |
104 | where the OpenAFS error message, if any, will be. | |
105 | ||
106 | When reporting a bug in the OpenAFS file server, please include | |
107 | backtrace information from a core dump, if any. If the file server is | |
108 | deadlocked, you can capture a core dump using the gcore script that | |
109 | comes with the gdb package. The file server is threaded, so use the | |
110 | command "thread apply all backtrace" in gdb to get a complete backtrace. | |
111 | It's also often useful to have the output of rxdebug <server> 7000 at | |
112 | the time of the problem and the FileLog from the file server. You can | |
113 | increase the logging level of the file server with kill -TSTP (and reset | |
114 | it to 0 with kill -HUP). | |
115 | ||
116 | You can report any bug in OpenAFS against the Debian package with | |
117 | reportbug and the OpenAFS package maintainers will forward the bug | |
118 | upstream as necessary. If you do want to report a bug directly | |
119 | upstream, see http://www.openafs.org/ for bug reporting instructions. | |
120 | ||
121 | PAM Authentication | |
122 | ||
123 | Any new OpenAFS cell is strongly encouraged to use Kerberos v5 for | |
124 | authentication. If you want PAM to automatically obtain AFS credentials | |
125 | and you are using Kerberos v5, you will want to install the libpam-krb5 | |
126 | and libpam-afs-session packages and then put something like the | |
127 | following in /etc/pam.d/common-auth: | |
128 | ||
129 | auth [success=ok default=1] pam_krb5.so ignore_root | |
130 | auth [default=done] pam_afs_session.so | |
131 | auth required pam_unix.so nullok_secure try_first_pass | |
132 | ||
133 | and something like the following in /etc/pam.d/common-session: | |
134 | ||
135 | session optional pam_krb5.so ignore_root | |
136 | session optional pam_afs_session.so | |
137 | session required pam_unix.so | |
138 | ||
139 | You'll probably also want the following in /etc/pam.d/common-account: | |
140 | ||
141 | account required pam_krb5.so ignore_root | |
142 | account required pam_unix.so | |
143 | ||
144 | There are, of course, many variations depending on what different | |
145 | mechanism you want to use and how you want to handle fallbacks. | |
146 | ||
147 | If you are still using Kerberos v4 and the OpenAFS kaserver (or a KDC | |
148 | that understands the same protocol) for authentication, you can instead | |
149 | use the libpam-openafs-kaserver package and a configuration like: | |
150 | ||
151 | auth sufficient pam_afs.so ignore_root | |
152 | auth required pam_unix.so nullok_secure try_first_pass | |
153 | ||
154 | in /etc/pam.d/common-auth and: | |
155 | ||
156 | session optional pam_afs.so | |
157 | session required pam_unix.so | |
158 | ||
159 | in /etc/pam.d/common-session. Use pam_afs.krb.so instead of pam_afs.so | |
160 | if you also want the PAM module to acquire a ticket cache for you. If | |
161 | using this configuration with sshd, you may need to disable privilege | |
162 | separation to get everything working properly. I've had mixed results | |
163 | with that. Obviously, converting to Kerberos v5 authentication is | |
164 | strongly preferred. | |
165 | ||
166 | If you are using the kaserver as your KDC, you may also want to install | |
167 | the openafs-kpasswd package to get the administrative utilities for | |
168 | managing those Kerberos accounts. | |
169 | ||
170 | -- Russ Allbery <rra@debian.org>, Tue, 6 Apr 2010 15:04:42 -0700 |