Imported Upstream version 2.4.4p3

[debian/amanda] / docs / INSTALL

Amanda INSTALLATION NOTES

This document covers the compilation, installation, and runtime setup
of Amanda 2.4.2 and higher.

0. BEFORE DOING ANYTHING

    A.  Read this document all the way through.

    B.  Consult the docs/SYSTEM.NOTES file for installation notes
        specific to particular operating systems.  There is often
        important information there, so don't forget this step.

    C.  Read docs/UPGRADE if you are upgrading from a previous Amanda
        version.  There are some issues that you will need to be aware
        of.

    D.  If you are using KERBEROS authentication, read docs/KERBEROS
        for details on installing and running the kerberized version of
        Amanda.

    E.  Check the Amanda Patches Page, www.amanda.org/patches.html.

1. COMPILING THE AMANDA SOURCES

If you have multiple architectures, you only need to install the whole
Amanda package on the tape server host (the one with tape drive).  On
the backup client hosts (the ones you are going to dump), you only need
to compile some of the Amanda programs (see section 1.2.H below).

1.1. SOURCE CONFIGURATION:

    A.  Amanda can optionally make use of the following packages to
        back up different types of clients or clients with different
        filesystem dumping programs.  If you wish to use GNU tar to
        back up filesystems, we can install version 1.12 or 1.13.25.
        gnutar 1.12 can be found at:

                ftp://ftp.gnu.org/pub/gnu/tar/tar-1.12.tar.gz
 
        Apply the patch from patches/tar-1.12.patch.  The first hunk
        may be enough, unless it's a SunOS4 host.  Read more about the
        patches in the patch file itself.

        gnutar 1.13.25 can be found at:

                ftp://alpha.gnu.org/pub/gnu/tar/tar-1.13.25.tar.gz

        Samba allows Unix systems to talk to PC clients.  Amanda can
        back up Microsoft Windows clients using Samba:

                http://www.samba.org

        Read docs/SAMBA for configuration tips and known limitations.

        Look at http://www.amanda.org/patches.html for up to date
        information on patches.

    B.  If you wish to make use of some of the scripts that come with
        Amanda, you will need to install Perl.  You can get Perl from
        any CPAN site.  
            ftp://ftp.cpan.org/pub/CPAN/src/perl-5.6.1.tar.gz


    C.  One of the programs included in this package is amplot,
        which reads a data file that Amanda generates for each dump
        and translates that information in it into a nice picture that
        can be used to determine how your installation is doing and if
        any parameters need to be changed.  To use amplot, you need a
        version of awk that understands command line variable
        substitutions, such as nawk or gawk, which is available from

            ftp://ftp.gnu.org/pub/gnu/gawk/gawk-3.1.1.tar.gz

        Amplot also required that gnuplot be installed on your system.
        Gnuplot is available at

            http://www.gnuplot.org/
            ftp://ftp.gnuplot.org/pub/gnuplot

    D.  The process of building Amanda requires that some other
        packages be installed on your system.  The following packages
        are used:

            ftp://ftp.gnu.org/pub/gnu/readline/readline-4.2.tar.gz
                amrecover optionally uses the readline library for its
                command-line edition mechanisms.  This library itself
                requires either termcap, curses or ncurses.  termcap
                is preferred, and it may be obtained from:
            ftp://ftp.gnu.org/pub/gnu/termcap/termcap-1.3.tar.gz

        If you wish to edit and enhance Amanda, you may need to install
        the following tools.  Autoconf and automake are required if you
        are going to rebuild the Makefiles and auto configuration scripts.
        Bison is only needed if you are going to work on the index server
        and client code.

            ftp://ftp.gnu.org/pub/gnu/autoconf/autoconf-2.53.tar.gz
            ftp://ftp.gnu.org/pub/gnu/automake/automake-1.6.3.tar.gz
            ftp://ftp.gnu.org/pub/gnu/bison/bison-1.27.tar.gz
            ftp://ftp.gnu.org/pub/gnu/flex/flex-2.5.4a.tar.gz

    E.  Read about the different configuration options available for
        building and running Amanda.  To see the options, do both:

            a.  Run `./configure --help' to see the available options
                that configure takes.
            b.  Read the example/config.site file which gives longer
                descriptions to the same options as in step a).

    F.  Choose which user and group you will run the dumps under.
        Common choices for user are `bin' or another user specifically
        created for Amanda, such as `amanda'; common choices for group
        are `operator' or `disk'.  If you do not specify
        --with-user=<username> and --with-group=<groupname>, configure
        will abort.  Also choose the default name for your
        configuration, such as `csd' or `DailySet1').  This name is
        used by the Amanda commands to choose one of multiple possible
        configurations.  You may specify it using the
        --with-config=<confgname>.

    G.  Decide where Amanda will live.  You need to choose a root
        directory for Amanda.  Let this root directory be called
        $prefix.  Unless you change the default behavior with the
        appropriate command line options, Amanda will install itself
        as.  Listed below each directory is the appropriate
        configure option to change the location of this part of
        Amanda.

            $prefix/sbin                Amanda server side programs
                                        --sbindir=
            $prefix/libexec             Amanda backup client programs
                                        --libexecdir=
            $prefix/lib                 Amanda dynamic libraries
                                        --libdir=
            $prefix/etc/amanda          Runtime configuration files
                                        --with-configdir=
            $prefix/var/amanda/gnutar-lists
                                        Directory for GNUtar lists (client)
                                        --with-gnutar-listdir=
            $prefix/man                 Directory for manual pages
                                        --mandir=

        Note that the GNU tar listdir should be a local filesystem on
        each client that is going to be backed up with GNU tar.  If it 
        really must be NFS-mounted, make sure the filesystem is
        exported so that the client has root access to it.

    H.  Decide if you are compiling Amanda on a server only or a
        client only platform.  If you have a particular operating system
        that will only be a Amanda client and will never run as the
        master tape host, then add the --without-server option to
        configure.  In the unlikely case that you have a particular
        operating system that will serve as the tape host and you do
        not wish to back up any machines that run this operating system,
        add the --without-client option to the configure options.
        There are many other configuration switches for amanda.  You
        may learn more about them by running `configure --help' and by
        reading examples/config.site.

    I.  Now configure Amanda.  There are two ways of doing this.  If
        you are running Amanda on a single OS, then probably the first
        method works better for you.  If you need to support multiple
        platforms, then the second method will work better.

            a.  Run `configure' with the appropriate command line
                options.  You will probably want to remember the
                command line options for future builds of Amanda.

            b.  Edit example/config.site and install it in the directory
                $prefix/etc or $prefix/share.  When `configure' runs
                the next time it will look for this file and use it to
                configure Amanda.

1.2. BUILDING AND INSTALLING THE BINARIES

    A.  Back at the top-level source directory, build the sources:
                1. make
                2. su root; make install
        If you want to change the compiler flags, you can do so like
        this:
                make CFLAGS="-O3 -Wall"

    B.  If you have built with USE_VERSION_SUFFIXES, you will want to
        create symlinks to the version you wish to use, eg:
                ln -s amdump-x.y.z amdump
        This is not done automatically by the install process, so that
        you can have multiple Amanda versions co-existing, and choose
        yourself which to make the default version.  The script
        contrib/set_prod_link.pl may save you some keystrokes.

2. SETTING UP YOUR AMANDA CONFIGURATION

2.1. SETTING UP THE TAPE SERVER HOST

    B.  Create the config directory (eg /usr/local/etc/amanda/confname)
        and copy the example/ files into that directory.  Edit these
        files to be correct for your site, consulting the amanda(8) man
        page if necessary.  You can also send mail to
        amanda-users@amanda.org if you are having trouble deciding how
        to set things up.  You will also need to create the directory
        for the log and database files for the configuration to use (eg
        /usr/local/var/amanda/confname), and the work directory on the
        holding disk.  These directories need to agree with the
        parameters in amanda.conf.  Don't forget to make all these
        directories writable by the dump user!

        Make sure that you specify the *no-rewind* version of the tape
        device in your amanda.conf file.  This is a frequently
        encountered problem for new sites.

        Note that you might want to temporarily set the "no-record"
        option in all your dumptypes when first installing amanda if
        you'd like to run tests of Amanda in parallel with your
        existing dump scheme.  Amanda will then run but will not
        interfere with your current dumpdates.  However, you don't want
        to run with "no-record" under normal operations.

    C.  Put amanda into your crontab.  Here's a sample:
                0 16 * * 1-5 /usr/local/bin/amcheck -m confname
                45 0 * * 2-6 /usr/local/bin/amdump confname
        This is for SunOS 4.x, which has a per-user crontab; most other
        systems also require a userid on each cron line.  See your
        cron(8) for details.  With these cron lines, Amanda will check
        that the correct tape is in the drive every weekday afternoon
        at 4pm (if it isn't, all the operators will get mail).  At
        12:45am that night the dumps will be run.

    D.  Put the Amanda services into your /etc/services file.  Add
        entries like:
                amanda          10080/udp
                amandaidx       10082/tcp
                amidxtape       10083/tcp
        You may choose a different port number if you like, but it must
        match that in the services file on the client hosts too.

        If you are running NIS (aka YP), you have to enter the amanda
        service into your NIS services database.  Consult your NIS
        documentation for details.

        You may use the `patch-system' script, from client-src, in
        order to modify this file.  Run it with a `-h' argument for
        usage.

    E.  If you are going to use the indexing capabilities of Amanda,
        and your server uses inetd, then add these to your inetd.conf
        on the tape server host:

            amandaidx stream tcp nowait USER AMINDEXD_PATH amindexd
            amidxtape stream tcp nowait USER AMIDXTAPED_PATH amidxtaped

        where AMINDEXD_PATH and AMIDXTAPED_PATH are the complete paths
        to where the amindexd and amidxtaped executables (usually
        libexec_dir/amindexd and libexec_dir/amidxtaped), and USER is
        the Amanda user.

        You may use the `patch-system' script, from client-src, in
        order to modify this file.  Run it with a `-h' argument for
        usage.

        If your tape server uses xinetd instead of inetd, then you have
        to add the following two files to your xinetd-configuration
        (usually /etc/xinetd.d):

        #/etc/xinetd.d/amandaidx

        service amandaidx
        {
                socket_type             = stream
                protocol                = tcp
                wait                    = no
                user                    = USER
                group                   = GROUP
                groups                  = yes
                server                  = AMINDEXD_PATH/amindexd 
        }

        #/etc/xinetd.d/amidxtaped

        service amidxtape
        {
                socket_type             = stream
                protocol                = tcp
                wait                    = no
                user                    = USER
                group                   = GROUP
                groups                  = yes
                server                  = AMIDXTAPED_PATH/amidxtaped
        }

    F.  If the tape server host is itself going to be backed up (as is
        usually the case), you must also follow the client-side install
        instructions below on the server host, INCLUDING setting up the
        .amandahosts file so that the server host lets itself in.
        This is a frequently encountered problem for new sites.


2.2. SET UP THE BACKUP CLIENT HOSTS

    A.  When using BSD-style security (enabled by default), set up
        your ~dumpuser/.amandahosts (or ~dumpuser/.rhosts and/or
        /etc/hosts.equiv, if you have configured
        --without-amandahosts) so that the dumpuser is allowed in from
        the server host.  Only canonical host names will be accepted
        in .amandahosts, and usernames must be present in every line,
        because this is safer.

    B.  Set up your raw disk devices so that the dumpuser can read
        them, and /etc/dumpdates so that the dumpuser can write to it.
        Normally this is done by making the disk devices readable by
        (and dumpdates read/writable by) group `operator', and putting
        the dumpuser into that group.

    C.  Put the Amanda service into your /etc/services file.  Add
        entry like:
                amanda          10080/udp
                amandaidx       10082/tcp
                amidxtape       10083/tcp
        You may choose a different port number if you like, but it must
        match that in the services file on the client hosts too.

        If you are running NIS (aka YP), you have to enter the amanda
        service into your NIS services database.  Consult your NIS
        documentation for details.

        You may use the `patch-system' script, from client-src, in
        order to modify this file.  Run it with a `-h' argument for
        usage.

    D.  If your Amanda client uses inetd, put the Amanda client service 
        into inetd's config file.  
        This file is usually found in /etc/inetd.conf, but on older systems
        it is /etc/servers.  The format is different on different OSes,
        so you must consult the inetd man page for your site.  Here is
        an example from our site, again from SunOS 4.x:

            amanda dgram udp wait USER AMANDAD_PATH amandad

        You may use the `patch-system' script, from client-src, in
        order to modify this file.  Run it with a `-h' argument for
        usage.

        If your Amanda client uses xinetd, you have to add the following
        file to your xinetd-configuration
        (usually /etc/xinetd.d):

        #/etc/xinetd.d/amanda

        service amanda
        {
                socket_type             = dgram
                protocol                = udp
                wait                    = yes
                user                    = USER
                group                   = GROUP
                groups                  = yes
                server                  = AMANDAD_PATH/amandad 
        }

    E.  Kick inetd/xinetd to make it read its config file.  On most systems
        you can just kill -HUP inetd (or xinetd). On older systems you may have to
        kill it completely and restart it.  Note that
        killing/restarting (x)inetd is not safe to do unless you are sure
        that no (x)inetd services (like rlogin) are currently in use,
        otherwise (x)inetd will not be able to bind that port and that
        service will be unavailable.

    F.  If you intend to back up xfs filesystems on hosts running IRIX,
        you must create the directory /var/xfsdump/inventory, otherwise
        xfsdump will not work.

THAT'S IT!  YOU ARE READY TO RUN, UNLESS WE FORGOT SOMETHING.  PLEASE
send mail to amanda-users@amanda.org if you have any comments or
questions.  We're not afraid of negative reviews, so let us have it!

Before writing questions, you may prefer to take a look at the FAQ (in
docs/FAQ) and at the Amanda home page, at http://www.amanda.org.
Browsable archives of amanda mailing-lists are available there.

By James da Silva <jds@cs.umd.edu> and others.