opr: fix generated target
[openafs.git] / README
1 Copyright 2000, International Business Machines Corporation and others.
2 All Rights Reserved.
3
4 This software has been released under the terms of the IBM Public
5 License.  For details, see the LICENSE file in the top-level source
6 directory or online at http://www.openafs.org/dl/license10.html
7
8 Short instructions for sites upgrading from a previous version of AFS:
9 % ./configure --enable-transarc-paths
10 % make
11 % make dest
12
13 will create a Transarc-style dest tree in ${SYS_NAME}/dest where
14 ${SYS_NAME} is the AFS sysname of the system you built for.
15 This assumes if you're building for Linux that your kernel source is
16 in /usr/src/linux.
17
18 Otherwise, please read on.
19
20 Building OpenAFS on UNIX and Linux
21 ----------------------------------
22
23 A  Configuring
24
25    Uncompress the source into a directory of your choice. A directory
26    in afs space is also valid. In the directory that you uncompressed the
27    source in, you will only have an src/ directory.
28
29    1. Pick a system to build for, and note its default AFS sys_name.
30       A directory will be automatically created for binaries to be written 
31       into with this name when you build.
32
33       alpha_dux40, alpha_dux50, alpha_dux51 (client does not work)
34       alpha_linux22, alpha_linux24, alpha_linux26
35       alpha_nbsd15, alpha_nbsd16
36       amd64_fbsd_53 (client does not work)
37       amd64_linux24, amd64_linux26
38       amd64_nbsd20, amd64_nbsd30, amd64_nbsd40
39       arm_linux24, arm_linux26
40       hp_ux11i, hp_ux110, hp_ux1123 (See notes below for information on
41          getting missing header)
42       hp_ux102 (Client port possible, but db servers and utilities work)
43       i386_fbsd_50, i386_fbsd_51, i386_fbsd_52, i386_fbsd_53,
44          i386_fbsd_60, i386_fbsd_61, i386_fbsd_62, i386_fbsd_70,
45          i386_fbsd_80, i386_fbsd_81, i386_fbsd_90, amd64_fbsd_50,
46          amd64_fbsd_51, amd64_fbsd_52, amd64_fbsd_53, amd64_fbsd_60,
47          amd64_fbsd_61, amd64_fbsd_62, amd64_fbsd_70, amd64_fbsd_80,
48          amd64_fbsd_81, amd64_fbsd_90
49          (client may work on 70 and later)
50       i386_linux22, i386_linux24, i386_linux26
51       i386_nbsd15, i386_nbsd16, i386_nbsd20, i386_nbsd21, i386_nbsd30,
52          i386_nbsd40
53       i386_obsd31, i386_obsd32, i386_obsd33, i386_obsd34, i386_obsd35,
54          i386_obsd36, i386_obsd37, i386_obsd38, i386_obsd39, i386_obsd40,
55          i386_obsd41
56       i386_umlinux22, i386_umlinux24, i386_umlinux26
57       ia64_hpux1122, ia64_hpux1123
58       ia64_linux24, ia64_linux26
59       parisc_linux24
60       ppc64_linux24, ppc64_linux26
61       ppc_darwin_12, ppc_darwin_13, ppc_darwin_14, ppc_darwin_60,
62          ppc_darwin_70, ppc_darwin_80, ppc_darwin_90
63       ppc_linux22, ppc_linux24, ppc_linux26
64       ppc_nbsd16, ppc_nbsd20
65       rs_aix42, rs_aix51, rs_aix52, rs_aix53, rs_aix61
66       s390_linux22, s390_linux24, s390_linux26
67       s390x_linux24, s390x_linux26
68       sgi_62, sgi_63, sgi_64, sgi_65 (file server not tested)
69       sparc64_linux22, sparc64_linux24, sparc64_linux26
70       sparc_linux22, sparc_linux24
71       sun4_413 (No client support, no fileserver support, db servers only)
72       sun4x_58, sun4x_59, sun4x_510, sun4x_511
73          (logging UFS not supported for mixed-use partitions containing
74          client cache)
75       sunx86_58, sunx86_59, sunx86_510, sunx86_511
76          (logging UFS not supported for mixed-use partitions containing
77          client cache)
78       x86_darwin_80, x86_darwin90
79
80    2. Using configure in the top level directory, configure for your
81       AFS system type, providing the necessary flags:
82
83       % ./configure --with-afs-sysname=sun4x_58 --enable-transarc-paths
84
85       If you do not have the "configure" script, or if you modify the
86       source files, you can re-create it by running regen.sh.  You will
87       need autoconf to do this.
88
89       For some systems you need also provide the path in which your kernel
90       headers for your configured kernel can be found.  See the
91       system-specific Notes sections below for details.  If you want to
92       build only the user-space programs and servers and not the kernel
93       module, specify the --disable-kernel-module option on the
94       ./configure command line.
95
96       All binaries, except for the 'fileserver' and 'volserver'
97       executables and their 'da' variants, are stripped of their symbol
98       table information by default.  To enable a debugging build, specify
99       the --enable-debug option on the ./configure command line.  This
100       builds with debugging compiler options and disables stripping of
101       binaries.
102
103       You can also use different combinations of --enable-debug and
104       --enable (or --disable)-strip-binaries for finer control.  One can,
105       for example, compile binaries for debug and strip them anyway.
106       Alternatively, one can compile without debug and force the binaries
107       to not be stripped.  Note that these combinations are not
108       necessarily useful.
109
110       The binaries noted above, 'fileserver' and 'volserver' and their
111       'da' variants, will never be stripped, regardless of any options
112       given to configure.
113
114    There are two modes for directory path handling: "Transarc mode" and
115    "default mode":
116
117    - In Transarc mode, we retain compatibility with Transarc/IBM AFS tools
118      by putting client configuration files in /usr/vice/etc, and server
119      files in /usr/afs under the traditional directory layout.
120    - In default mode, files are located in standardized locations, usually
121      under $(prefix), which defaults to /usr/local.
122    - Client programs, libraries, and related files always go in standard
123      directories under $(prefix).  This rule covers things that would go
124      into $(bindir), $(includedir), $(libdir), $(mandir), and $(sbindir).
125    - Other files get located in the following places:
126
127     Directory     Transarc Mode              Default Mode
128     ============  =========================  ==============================
129     viceetcdir    /usr/vice/etc              $(sysconfdir)/openafs
130     afssrvdir     /usr/afs/bin (servers)     $(libexecdir)/openafs
131     afsconfdir    /usr/afs/etc               $(sysconfdir)/openafs/server
132     afslocaldir   /usr/afs/local             $(localstatedir)/openafs
133     afsdbdir      /usr/afs/db                $(localstatedir)/openafs/db
134     afslogdir     /usr/afs/logs              $(localstatedir)/openafs/logs
135     afsbosconfig  $(afslocaldir)/BosConfig   $(afsconfdir)/BosConfig
136     afsbosserver  $(afsbindir)/bosserver     $(sbindir)/bosserver
137
138    In default mode, you can change all of the variables named above that
139    do not start with "afs" by passing the flags with the same name to
140    configure.  For example, if you want to install the server binaries in
141    /usr/local/lib/openafs instead of /usr/local/libexec/openafs, pass the
142    --libexecdir=/usr/local/lib flag to configure.
143
144    For additional options, see section I below.
145
146 B  Building
147
148    1. Now, you can build OpenAFS. 
149
150       % make
151
152    2. Install your build using either "make install" to install 
153       into the current system (you will need to be root, and files
154       will be placed as appropriate for Transarc or standard paths),
155       "make install DESTDIR=/some/path" to install into an alternate 
156       directory tree, or if you configured with --enable-transarc-paths
157       make dest to create a complete binary tree in the dest directory      
158       under the directory named for the sys_name you built for,
159       e.g. sun4x_57/dest or i386_linux22/dest 
160
161    3. As appropriate you can clean up or, if you're using Linux, build for
162       another kernel version.
163
164       To clean up:
165
166       % make clean
167
168 C  Problems
169
170    If you have a problem building this source, you may want to visit
171    http://www.openafs.org/ to see if any problems have been reported 
172    or to find out how to get more help.
173
174    Mailing lists have been set up to help; More details can be found
175    on the openafs.org site.
176
177 D  Linux Notes
178
179    With current Linux versions, the /lib/modules/`uname -r`/source symlink
180    will be used to locate the kernel headers, but you will need to have
181    the headers and build system for your kernel installed in order to
182    build the kernel module.  These are usually found in a separate package
183    from the kernel, often called something like linux-headers-<version>.
184
185    For older Linux systems, you may also need to provide the path in which
186    your kernel headers for your configured kernel can be found. This
187    should be the path of the directory containing a child directory named
188    "include". So if your version file were
189    /usr/src/linux/include/linux/version.h you would run:
190
191    % ./configure --with-afs-sysname=i386_linux24 \
192        --with-linux-kernel-headers=/usr/src/linux
193
194    Currently you can build for only one Linux kernel at a time, and the
195    version is extracted from the kernel headers in the root you specify.
196
197    To build for another Linux kernel version, determine the sysname for
198    the system type as defined in step A1 for the other kernel version and
199    then run:
200
201       % ./configure --with-afs-sysname=<sysname> \
202           --with-linux-kernel-headers=/usr/src/linux-2.2.19-i686
203       % make 
204
205    Your build tree will now include an additional kernel module for your
206    additional kernel headers. Be aware that if the kernel version string
207    which UTS_RELEASE is defined to in include/linux/version.h matches the
208    last kernel you built for, the previous kernel module will be
209    overwritten.
210
211 E  HP-UX 11.0 Notes
212
213    HP-UX 11.0 requires a header called vfs_vm.h which HP has provided on
214    their web site.  Go to http://www.hp.com/dspp, choose Software
215    downloads from the side menu, and select Software: HP operating systems
216    and then Operating systems: HP-UX from the select boxes.  The last
217    select box will have an option for downloading vfs_vm.h.
218
219 F  OpenBSD Notes
220
221    If you need to run regen.sh to make the configure script, you should
222    first install autoconf-2.59, then setenv AUTOCONF_VERSION 2.59.
223
224    You need kernel source installed to build OpenAFS.  Use the
225    --with-bsd-kernel-headers= configure option if your kernel source is
226    not in /usr/src/sys.
227
228    src/packaging/OpenBSD/buildpkg.sh will make a tar file for installing
229    the client.  There is no server package, but I am told that "make
230    install" will put server binaries in /usr/afs.
231
232    Your kernel may panic when you try to shutdown after running the
233    OpenAFS client.  To prevent this, change the "dangling vnode" panic in
234    sys/kern/vfs_syscalls.c to a printf and build a new kernel.
235
236    You can't run arla and OpenAFS at the same time.
237
238 G  FreeBSD Notes
239
240    The FreeBSD client may now work; It is tested on 7.0 and on current
241    as of the commit date.
242
243    You need kernel source installed to build OpenAFS.  Use the
244    --with-bsd-kernel-headers= configure option if your kernel source is
245    not in /usr/src/sys.
246
247    You also need access to your kernel build directory for the opt_global.h
248    include file.  Use the --with-bsd-kernel-build= configure option if your
249    kernel build is not GENERIC in the standard place. If 
250    /usr/src/sys/${CPUARCH}/compile/GENERIC does not point to 
251    /usr/obj/usr/src/sys/GENERIC you may need to resolve that and retry the 
252    build.
253
254    There is no server package, but I am told that "make install" will put
255    server binaries in /usr/afs.
256
257    You can't run arla and OpenAFS at the same time.
258
259 H  AIX notes
260
261    Make sure that your default build environment is 32bit, ie.
262    the OBJECT_MODE environment variable is either unset or set to "32".
263
264    Verify this before doing configure and make. For example, assuming
265    ksh/bash:
266
267    % export OBJECT_MODE=32
268
269    To build aklog (in order to be able to get tokens from your Kerberos v5
270    ticket), you will need Kerberos libraries.  On AIX 6.1, the IBM
271    Kerberos v5 libraries are in the packages krb5.client.rte and
272    krb5.toolkit.adt on the Expansion Pack.
273
274 I  Other configure options
275
276    AFS has a ton of other optional features that must be enabled using
277    configure options.  Here is a summary:
278
279    --enable-bigendian
280    --enable-littleendian
281        These configure options are normally not required and should not be
282        given.  They're only needed if the OpenAFS build system cannot
283        determine the endianness of your system, in which case configure
284        will abort and say to use one of these options.
285
286    --enable-bitmap-later
287        Speeds the startup of the fileserver by deferring reading volume
288        bitmaps until necessary.  Demand attach is a better solution to the
289        same problem.
290
291    --enable-checking
292        Enable compiler warnings when building with GCC and turn compiler
293        warnings into errors so that new warnings will cause compilation
294        failures.  If you are developing patches to contribute to OpenAFS,
295        please build OpenAFS with this flag enabled.  Warning-free code is
296        a requirement for all new submissions to OpenAFS.
297
298    --enable-debug
299    --enable-debug-kernel
300    --enable-debug-lwp
301    --enable-debug-pam
302        Compile the userspace code (for --enable-debug) or the code named
303        by the option with debugging information.  If --enable-debug is
304        given, also do not strip binaries when installing them.
305
306    --enable-linux-syscall-probing
307        OpenAFS now uses keyrings to manage PAGs by default on Linux, which
308        does not require hooking into the system call table.  On older
309        versions of Linux without keyring support, OpenAFS uses groups to
310        manage PAGs and probes for the system call table to hook into it to
311        preserve that group information.  Normally, which method to use is
312        detected automatically, and if keyring support is present, support
313        for system call table probing is not compiled in.  Use this
314        configure option to force inclusion of the system call table
315        probing code even if the kernel appears to support keyrings.
316
317    --enable-namei-fileserver
318        Forces the namei fileserver on platforms (like Solaris 8 and 9)
319        where the inode fileserver is the default.
320
321    --enable-pthreaded-ubik
322        Enable the threaded version of Ubik and install the threaded
323        versions of Ubik servers.  See README.PTHREADED_UBIK for more
324        information.  (EXPERIMENTAL)
325
326    --enable-redhat-buildsys
327        Enable compilation of the kernel module for the Red Hat build
328        system kernel.  Use this configure flag when building kernel
329        modules for Red Hat Linux systems.
330
331    --enable-reduced-depends
332        Try to minimize the shared library dependencies encoded in the
333        binaries.  This omits from the link line all the libraries included
334        solely because the Kerberos libraries depend on them and instead
335        links the programs only against libraries whose APIs are called
336        directly.  This will only work with shared Kerberos libraries and
337        will only work on platforms where shared libraries properly encode
338        their own dependencies (such as Linux).  It is intended primarily
339        for building packages for Linux distributions to avoid encoding
340        unnecessary shared library dependencies that make shared library
341        migrations more difficult.  If none of the above made any sense to
342        you, don't bother with this flag.
343
344    --enable-supergroups
345        Enables support of nested groups in the ptserver.  WARNING: Once
346        you make use of this option by nesting one group inside another,
347        the resulting PTS database cannot be correctly and safely used by a
348        ptserver built without this option.  If some of your ptservers were
349        built with this option and some without this option, you will
350        probably corrupt your PTS database.
351
352    --enable-tivoli-tsm
353        Build with the Tivoli TSM API libraries for butc support of the
354        Tivoli backup system.
355
356    --enable-transarc-paths
357        As discussed in A2 above, build for the traditional paths used by
358        the Transarc and IBM AFS distributions instead of the more typical
359        open source /usr/local paths.  Passing this option to configure and
360        then running make dest will generate, in the dest directory, the
361        set of files and directory layout matching a Transarc or IBM AFS
362        tape distribution.
363
364    --enable-warnings
365        Enable compilation warnings when built with GCC.  This is similar
366        to --enable-checking, but new warnings will only be displayed, not
367        cause a build failure.
368
369    It's also possible to disable some standard features.  None of these
370    options are normally needed, but they may be useful in unusual
371    circumstances:
372
373    --disable-kernel-module
374        Even if kernel headers are found, do not attempt to build the
375        kernel module.  On Linux, if you provide this flag, you'll also
376        need to provide --with-afs-sysname, since OpenAFS cannot determine
377        the correct sysname automatically without the kernel headers.
378
379    --disable-optimize
380    --disable-optimize-kernel
381    --disable-optimize-lwp
382    --disable-optimize-pam
383        Disable optimization for the given portion of the OpenAFS code.
384        Usually used either for debugging to avoid code optimization making
385        it harder to use a debugger, or to work around bugs in the compiler
386        optimizers or in the OpenAFS code.
387
388    --disable-pam
389        Do not build the AFS PAM modules.  Normally building them is
390        harmless, but the PAM modules that come with OpenAFS are deprecated
391        and should not be used unless you're still using the OpenAFS
392        kaserver (which is itself deprecated and should not be used).
393
394    --disable-strip-binaries
395        Disable stripping of binaries on installation.  You probably want
396        to use --enable-debug instead of this flag to also inclusion of
397        debugging information.
398
399    --disable-unix-sockets
400        Disable use of UNIX domain sockets for fssync.  A TCP connection to
401        localhost will be used instead.
402
403    You may need to pass one or more of the following options to specify
404    paths and locations of files needed by the OpenAFS build process or
405    additional information required by the build process:
406
407    --with-afs-sysname=SYSNAME
408        Specifies the AFS sysname of the target system is SYSNAME.
409        Normally this is determined automatically from the build
410        architecture plus additional information (such as, on Linux, from
411        the kernel headers).  The SYSNAME should be one of the options
412        listed in A2.
413
414    --with-gssapi=DIR
415    --with-gssapi-include=DIR
416    --with-gssapi-lib=DIR
417    --with-krb5[=DIR]
418    --with-krb5-include=DIR
419    --with-krb5-lib=DIR
420        Normally, OpenAFS will automatically build with Kerberos support if
421        Kerberos is found during the build.  If your Kerberos libraries are
422        in an unusual location, however, you may need to pass one or more
423        of these flags.  --with-krb5 forces building with Kerberos support
424        if given and will cause configure to fail if Kerberos is not found.
425        You may optionally specify the root path to your Kerberos
426        installation as an argument to --with-krb5.
427
428        If you have a krb5-config script, it's used to find the flags to
429        build with Kerberos.  If you have no krb5-config script, you can
430        specify the location to the include files with --with-krb5-include
431        and the libraries with --with-krb5-lib.  You may need to do this if
432        Autoconf can't figure out whether to use lib, lib32, or lib64 on
433        your platform.
434
435        --with-gssapi is similar, except for the GSS-API libraries instead
436        of the Kerberos libraries.  If you have to manually set the
437        location of the Kerberos libraries, you may need to do the same
438        thing for the GSS-API libraries.
439
440    --with-libintl=DIR
441    --with-libintl-include=DIR
442    --with-libintl-lib=DIR
443        Specifies the install location of the libintl library, used for
444        internationalization, or separately specifies the location of the
445        header files and libraries.  By default, the default system library
446        paths will be searched.  This library is not required on many
447        platforms.
448
449    --with-roken=PATH
450    --with-roken=internal
451        Specifies the install location of the libroken library.  Specify
452        "internal" to use the embedded libroken library that comes with
453        OpenAFS (the default).  This option is primarily useful for
454        building against a system libroken library if you have one.
455
456    --with-linux-kernel-build=PATH
457    --with-linux-kernel-headers=PATH
458    --with-bsd-kernel-build=PATH
459    --with-bsd-kernel-headers=PATH
460        Specifies the path to the kernel headers and build system.  See the
461        information above for Linux and *BSD systems.
462
463    --with-linux-kernel-packaging
464        Tells the OpenAFS kernel module build system to use conventions
465        appropriate for building modules to include in Linux kernel module
466        packages.  Primarily, this renames the kernel module to openafs.ko
467        rather than libafs-<VERSION>.ko, which is easier to handle in Linux
468        distribution init scripts.
469
470    --with-docbook2pdf=PROGRAM
471        Specifies the program used to convert the DocBook manuals to PDF.
472        Supported choices are fop, dblatex, and docbook2pdf.  By default,
473        the user's path is searched for those programs in that order, and
474        the first one found is used.
475
476    --with-docbook-stylesheets=PATH
477        The location of the DocBook style sheets, used to convert the
478        DocBook manuals to other formats.  By default, a set of likely
479        paths are searched.
480
481    --with-html-xsl=PATH
482        Specifies the XSLT style sheet to convert DocBook manuals into
483        HTML.  The default is html/chunk.xsl.  You may wish to use
484        html/docbook.xsml instead.
485
486    --with-xslt-processor=PROGRAM
487        Specifies the XSLT processor to use to convert the DocBook manuals
488        into HTML.  Supported choices are libxslt, saxon, xalan-j, and
489        xsltproc.  By default, the user's path is searched for those
490        programs in that order, and the first one found is used.
491
492    There are also some environment variables that you can set to control
493    aspects of the build.  They can be set either on the configure command
494    line (preferred) or in the environment.
495
496    CC
497        The C compiler to use.  Be aware that this is overridden on some
498        architectures that require a specific compiler be used to build the
499        kernel module.
500
501    CFLAGS
502        Additional flags to pass to the C compiler.
503
504    CPP
505        The C preprocessor to use.  Defaults to cpp if found, otherwise
506        $CC -E.
507
508    CPPFLAGS
509        Additional flags to pass to the C preprocessor or compiler.  This
510        is where to put -I options to add paths to the include file search.
511
512    FUSE_CFLAGS
513        Compiler flags required for building applications that use FUSE.
514
515    FUSE_LIBS
516        Libraries required for linking applications that use FUSE.
517
518    KRB5_CONFIG
519        To specify a particular krb5-config script to use, either set the
520        KRB5_CONFIG environment variable or pass it to configure like:
521
522            ./configure KRB5_CONFIG=/path/to/krb5-config
523
524        To not use krb5-config and force library probing even if there is a
525        krb5-config script on your path, set KRB5_CONFIG to a nonexistent
526        path:
527
528            ./configure KRB5_CONFIG=/nonexistent
529
530    LDFLAGS
531        Additional flags to pass to the linker.  This is where to put -L
532        options to add paths to the library search.
533
534    LIBS
535        Additional libraries to link all userspace programs with.
536
537    PKG_CONFIG
538        The path to the pkg-config utility.  Currently, this is only used
539        to locate the flags for building the FUSE version of afsd.
540
541    YACC
542        The yacc implementation to use.  Defaults to bison, byacc, or yacc,
543        whichever is found first.
544
545    YFLAGS
546        Additional flags to pass to yacc.