Quick start (old)

Deprecated
This 'Quick Start' is neither quick nor up to date. See Getting Started With Amanda instead.

Installing Amanda

Use any of the following methods to install Amanda:

• Run one of the installation packages available from Zmanda or elsewhere:
  • The Zmanda downloads site includes installation packages for many platforms. If you are using packages from Zmanda downloads page, go to the Zmanda packages 15 minute example. If you are using Windows client, refer to the Windows client page for installation instructions.
  • Many Linux and BSD distributions include Amanda packages, as does the Sun freeware site. See your distribution's package manager docuumentation for details.

• Compile Amanda from the source. Obtain the tarball from one of the sites mentioned above, or from the subversion tree. See Amanda's Requirements, Installation/Installing Amanda Source, and Development Dependencies.

Whether you are installing Amanda packages or compiling from the source, please see the installation page for detailed instructions.

Note: when installing from RPM, debian or other packages, many of the steps below are already done for you. Unfortunately we can't advise you on which steps were done for you. We suggest you follow the instructions below to learn what the package management software did. You can then do the rest manually.

The pre-built Amanda packages make some configuration assumptions regarding the location of log files, .conf files, binaries, etc. Packages from the Zmanda downloads page perform these configuration steps at the end of the installation procedure. Please see Amanda packages from Zmanda downloads page for a list of configuration steps that are performed.

Collecting configuration information

To set up Amanda backups, you will need to know the configuration parameters of the Amanda installation you are setting up. If you built Amanda from the source tree, these are in the form of configure script parameters. If you have installed binary packages from another source, use the amadmin command piped to grep to determine the Amanda parameters. These commands must be run as superuser (root). Note that due to variation in third party packages, the values you find may vary from the defaults noted here.

"CLIENT_LOGIN"

Amanda user. This user id is used by the backup process. Example: amandabackup, amanda

# /usr/sbin/amadmin xx version | grep CLIENT_LOGIN

"CONFIG_DIR"

Amanda configuration directory. All Amanda configurations in the Amanda server are stored here. Default: /etc/amanda (though in some packages you may find /usr/local/etc/amanda).

# /usr/sbin/amadmin xx version | grep CONFIG_DIR

"AMANDA_DBGDIR"

Amanda directory for debug log files. Default: /tmp/amanda

# /usr/sbin/amadmin xx version | grep AMANDA_DBGDIR

"libexecdir"

Amanda directory where executables started by amandad process are installed. Default: /var/lib/amanda

# /usr/sbin/amadmin xx version | grep libexecdir

"listed_incr_dir"

This directory in Amanda client is used by the GNU tar command. This directory only used if GNUTAR is configured as a backup program in the dumptype section of amanda.conf(5). Default: /var/lib/amanda/gnutar-lists

# /usr/sbin/amadmin xx version | grep listed_incr_dir

Configuring the backup server

Create an Amanda user on the server

Amanda runs as a normal user, but must be in the same group that has read access to the raw disk devices. Do not run Amanda as the root user. The Amanda user name is defined by the CLIENT_LOGIN parameter from the Collecting configuration information page.

It is possible to change the name of the user used during Amanda compilation. Amanda packages from different distributions use different user names and home directories for Amanda.

For example: If you install Amanda using pre-built packages from the Zmanda downloads page, a user amandabackup is created, and is added to the group disk with the home directory /var/lib/amanda.

You must assign a password to the amandabackup user in order to unlock the account. E.g. as root:

# passwd amandabackup

Alternatively, if you built Amanda using the source tree, create the user by running the useradd command. For example:

# useradd -u <uid> -g disk -d /var/lib/amanda -s /bin/bash -c ... amandabackup

If you are running Network Information Services (NIS, a.k.a. Yellow Pages or YP), you can add the Amanda user to your NIS database. Consult your NIS documentation for details.

The Amanda user's home directory must be owned by the amanda user. For example, assuming the gnu chown and that the Amanda user's name is backup:

# chown backup:backup $(grep backup /etc/passwd | cut -d: -f6)

The Amanda programs should be accessible to the Amanda user (in other words, add them to that user's PATH). For example, if the programs reside in /usr/local/sbin directory, set the PATH variable in .profile, and/or .bashrc in the Amanda user's home directory. The following script excerpt shows how to set PATH variable in a shell script:

# Prepend these directories to PATH if needed
for d in /usr/local/bin /usr/local/sbin
do
    case :$PATH: in
        *:$d:*) : ;;
        *)  PATH=$d:$PATH ;;
    esac
done

Invent a name for the configuration

You must provide a unique name for each configuration in Amanda. This named configuration acts a backup profile, allowing you to reference a set of configuration files describing the source and target for the type of backup you want executed. Each configuration specifies the source and target of the backup:

• The backup source defines the disks, partitions, or directories you intend to back up.
• The target defines the destination of the copied data, such as tapes or disk directories.

You may define multiple configurations. Some commonly used configuration names:

• daily for normal daily backups
• archive for offsite stored archive tapes having only full dumps,
• test for your test environment
• DailySet1. Some Linux distributions ship Amanda with this default configuration name.

To create a configuration, first create a directory with the chosen configuration name in the Amanda CONFIG_DIR (See the CONFIG_DIR value described in the Collecting configuration information section:

$ mkdir -p /etc/amanda/daily

This directory works as the configuration name (label) for the configuration files. So you have now created a configuration called daily.

Most Amanda commands take the configuration name as the first argument.

Modify amanda.conf

Copy the example amanda.conf into the configuration directory. Under many Linux distributions, this file is located in /etc/amanda/DailySet1. Edit the configuration file as necessary for your site, consulting the amanda.conf(5) man page if necessary.

It is recommended that you set up a quick test environment for disk based backup. See the amanda.conf parameters described in the Test environment with virtual tapes page.

Note the values you choose for the next parameters in amanda.conf:

logdir   "/etc/amanda/daily/logs"           # log directory
infofile "/etc/amanda/daily/curinfo"        # database filename
indexdir "/etc/amanda/daily/index"          # index directory
tapelist "/etc/amanda/daily/tapelist"       # list of used tapes

Then create these directories or files, making sure the directories and files are owned by the amanda user:

# chown -R amandabackup:disk /etc/amanda
# su - amandabackup
$ mkdir -p /etc/amanda/daily
$ touch /etc/amanda/daily/tapelist

The directories curinfo and index are created automatically if amandabackup has write permission in the /etc/amanda directory.

Specify holding disks in the amanda.conf file:

amanda.conf:

holdingdisk hd1 {
    directory "/space/amandahold/daily"
    ...
}

And create them:

# mkdir -p /space/amandahold/daily
# chown -R amandabackup:disk /space/amandahold

Add entries in /etc/services on the server

Add the Amanda services to /etc/services file on the server. Before you do so, examine /etc/services for existing Amanda entries. Most UNIX and Linux distributions already provide the required entries. If you can't find them, add entries such as:

amanda 10080/udp

amandaidx 10082/tcp

amidxtape 10083/tcp

You may specify a different port number if desired, but it must match the port number in the /etc/services file of the Amanda clients that connect to the Amanda server. If you are running NIS (aka YP), you must add the Amanda service to the NIS services database. Consult the NIS documentation for details.

Configuring Internet services on the Amanda server

Determine whether the Amanda server uses inetd(8), xinetd(8), or Dan Bernstein's daemontools.

• Note that the server configuration of Amanda does not require the amandad entries shown in the examples below. However, because the Amanda server is usually a client for itself (i.e. the Amanda server should be backed up), the amandad entries have been added.

Configuring xinetd and inetd on the server

Note that BSDTCP and SSH are the recommended mechanisms for new installs. See How To:Configure bsdtcp authentication or How To:Set up transport encryption with SSH. Avoid BSD and BSDUDP if at all possible.

Now skip down to Create_the_disklist_file.

Configuring daemontools on the server

If your tape server uses Dan Bernstein's daemontools (http://cr.yp.to/daemontools.html) instead of (x)inetd, you must create amandaidx and amidxtape services manually.

• NOTE*: In Amanda 2.6.x, you no longer create the amandaidx and amidxtape services separately. Instead, the amanda service is provided command line arguments of the services allowed/used.

mkdir -p $prefix/etc/amanda/supervise/amanda mkdir -p $prefix/etc/amanda/supervise/amandaidx mkdir -p $prefix/etc/amanda/supervise/amidxtape

Create service startup files and make them executable:

/etc/amanda/supervise/amandaidx/run:

#!/bin/sh
exec /usr/local/bin/setuidgid amanda \
/usr/local/bin/tcpserver -DHRl0 0 10082 \
/usr/local/libexec/amindexd >/dev/null 2>/dev/null

/etc/amanda/supervise/amidxtape/run:

#!/bin/sh
exec /usr/local/bin/setuidgid amanda \
/usr/local/bin/tcpserver -DHRl0 0 10083 \
/usr/local/libexec/amidxtaped >/dev/null 2>/dev/null

Link the service directories to the svscan directory:

# cd /service
# ln -s $prefix/etc/amanda/supervise/amandaidx .
# ln -s $prefix/etc/amanda/supervise/amidxtape .

svscan should detect and start the new services automatically.

Create the disklist file

The disklist file is located in the same directory as the amanda.conf(5) file. Start with a small number of entries while you are testing.

disklist:

client1.example.com  /some/dir   comp-user-tar
client2.example.com  /var        comp-user-tar

Note that you might want to temporarily set the option "record no" 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 still run, but it will not interfere with your current dumpdates. However, you should remove the "record no" option under normal backup operations.

Create file .amandahosts on the server

When compiled with the configure option --without-amandahosts, use the file .rhosts and/or /etc/hosts.equiv instead.

Create a file named .amandahosts in the home directory of the Amanda user. The syntax is similar to that of the .rhosts file. An .amandahosts file is required on each client containing a line to allow the server access to the client (see Backup client configuration). On the server additional entries are needed for each client in the disklist file that wants to use amrecover (amrecover needs to be run as root).

# su - amandabackup
$ cat .amandahosts
amandahost.yourdomain.com  amandabackup
amandahost.yourdomain.com  root
client1.yourdomain.com  root
client2.yourdomain.com  root

The first line in the .amandahosts file above is for the Amanda client running on the server itself. The next lines allow the root user on each client computer to access the Amanda tape and Amanda index servers on this host with the amrecover(8) command.

The .amandahosts file also requires strict permissions. It should be owned by the Amanda user, which should have exclusive read privileges to it; it should not be accessible to any other user. Also, the home directory of the Amanda user (containing the .amandahosts file) should be write-protected from modification by any other user:

# chown amandabackup ~amanda ~/.amandahosts
# chmod 755 ~amanda
# chmod 600 ~amanda/.amandahosts

Backup client configuration

Each client in the disklist file on the Amanda server must be configured as an Amanda client.

Note: Because the server itself is usually also a client, this section applies to the server as well.

Create an Amanda user on the client

The Amanda user on the client does not have to be same user name, uid or gid as the server's Amanda user. It must, however, be included in the group that has read access to the raw disk devices.

If an Amanda user does not exist on the client, create one. For example:

# useradd -u <uid> -g disk -d /var/lib/amanda -s /bin/bash -c ... amandabackup

If you are running NIS (aka YP), you can add the Amanda user to your NIS services database. Consult your NIS documentation for details.

You can use an Amanda client user name different from the Amanda server user name. If a different user is used in the client, you must configure amanda.conf appropriately. See the CLIENT_USER field in the DUMPTYPE section of amanda.conf(5).

Create the .amandahosts file on the client

Create a file named .amandahosts in the home directory of the Amanda user on the client. The syntax is similar to that of a .rhosts file. It should contain an entry with the hostname of the Amanda server and the Amanda user on the server:

amandahost.example.com  amandabackup

This entry allows the user amandabackup on host amandahost.example.com to initiate a backup on this client.

When compiled with the configure option --without-amandahosts, use the .rhosts and/or the /etc/hosts.equiv file instead.

The .rhosts file or, since version 2.5.0, the .amandahosts file also requires strict permissions. These files should be owned by the Amanda user, which should have exclusive read privileges to them; they should not be accessible to any other user. Also, the home directory of the Amanda user (containing the .amandahosts file) should be write-protected from modification by any other user:

# chown amandabackup ~amandabackup ~/.amandahosts
# chmod 755 ~amandabackup
# chmod 600 ~amandabackup/.amandahosts

Create file /var/amanda/amandates and chmod /var/amanda/dumpdates

Create an empty file /var/amanda/amandates and change its ownership to the Amanda user.

# touch /var/amanda/amandates
# chown amandabackup:disk /var/amanda/amandates

Make the file /var/amanda/dumpdates writable by the Amanda user:

# chmod 664 /var/amanda/dumpdates
# chgrp disk_user_group /var/amanda/dumpdates

where disk_user_group is the group that amanda is in (i.e., the group that has read access to the raw disk devices). Use ls -l /dev/hda1 or a similar operating system command to list the raw disk devices and who has access to them.

Add entries in /etc/services on the client

Put the Amanda service into your /etc/services file:

/etc/services: amanda 10080/udp

You may specify a different port number if desired, but the port must match that specified in the /etc/services file on the tape server host.

If you are running NIS (aka YP), you must 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 the -h argument to display help.

Configure Internet services on the client

If you are using BSDTCP authentication, determine whether the host uses inetd, xinetd, or Dan Bernstein's daemontools. Skip accordingly to Configuring inetd on the client, Configuring xinetd on the client or Configuring daemontools on the client.

If you are using SSH authentication, you need not worry about any of these configurations.

Configuring inetd on the client

See the How To:Configure bsdtcp authentication page.

Configuring xinetd on the client

See the How To:Configure bsdtcp authentication page.

Configuring daemontools on the client

If the Amanda client uses Dan Bernstein's daemontools (http://cr.yp.to/daemontools.html) instead of (x)inetd, you must manually create the Amanda service. You will also need a UDP super-server (netcat in this example).

Create the service directory:

# mkdir -p /etc/amanda/supervise/amanda

Create service startup file and make it executable:

/etc/amanda/supervise/amanda/run:

#!/bin/sh
exec /usr/local/bin/setuidgid amanda \
 /usr/bin/netcat -l -u -p 10080 -q 0 \
 -e /usr/local/libexec/amandad >/dev/null 2>/dev/null

The netcat binary used in this runfile might also be called /usr/bin/nc on your system, depending on the operating system and version. Refer to http://netcat.sourceforge.net for detail on netcat.

• NOTE* Use of netcat is no longer supported in the 2.6.x tree (possibly prior as well). Instead of making 3 separate services monitored by Daemontools, one service named amanda will be created, and provided command line parameters of the services enabled/allowed. For example, this is the amanda service from a machine that is both an amanda server and client for itself:

/etc/amanda/supervise/amanda/run:

#!/bin/sh
exec /usr/local/bin/setuidgid amandabackup \
/usr/local/bin/tcpserver -DHRl0 0 10080 \
/usr/local/libexec/amandad amindexd amidxtaped noop selfcheck sendsize sendbackup -auth=bsdtcp >/dev/null 2>/dev/null

Link service directory into your svscan directory:

# cd /service
# ln -s /etc/amanda/supervise/amanda 

svscan should detect and start the new services automatically.

Create the listed_incr_dir for gnutar

If the dumptypes for this client use GNU tar, then you must create a directory for it. Create the directory and make sure the Amanda user has write permission:

 # mkdir -p /var/lib/amanda/gnutar-lists
 # chown -R amandabackup:disk /var/lib/amanda

(Change pathnames if Amanda was compiled using other pathnames.)

Special requirements

• 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.

Using the configuration

Label tapes or vtapes

The target for the backup can either be a physical tape or a disk directory defined as a virtual tape (vtape). Before Amanda can access either type of target, the volume must be labeled using the Amanda label (amlabel(8)) command.

Backup to tapes

Mount the tape with compression turned off and the blocksize set to 0 (variable) before labelling the tape. Use Amanda's amlabel(8) command to label the tape. The mt and amlabel commands must be executed as the Amanda user (e.g., amandabackup)

$ mt -f /dev/nst0 compression 0
$ mt -f /dev/nst0 setblk 0
$ amlabel daily Daily-01

Where /dev/nst0 is your "non-rewinding" tape device name. If you have the symlink /dev/tape for your tape device, then the '-f /dev/nst0' may be omitted. If you are using an autoloader, ensure a tape is loaded (see the man page for mtx). If you don't see a non-rewinding tape device, use the tape device you do have. e.g. /dev/st0.

The tape label (Daily-01 in the example), must match the labelstr regular expression specified in the amanda.conf file, or amlabel will return an error.

Backup to disk

Amanda implements vtapes, a method of using disk media to emulate tape devices. This is implemented by the VFS device.

To use a single vtape, add the tapedev entry to amanda.conf(5):

amanda.conf:

tapedev "file:/space/amanda-vtapes/tape"

Note that this only sets up a single vtape - not a very useful arrangement! See How To:Set Up Virtual Tapes for information on setting up multiple vtapes and distributing dumps over them.

An Amanda vtape can be any directory that contains a "data" subdirectory. The following commands create a vtape:

# mkdir /space/amanda-vtapes
# chown amandabackup:disk /space/amanda-vtapes
# su - amandabackup
$ mkdir -p /space/amanda-vtapes/tape/data

You can use the amlabel(8) command to label a vtape:

$ amlabel test Test-01

The vtape mechanism is very flexible, allowing the creation of virtual tape libraries including multiple tape volumes. All of these features are described in the Test environment with virtual tapes page.

Configuration check

Run the amcheck command as the Amanda backup user (amandabackup in the the examples):

 $ amcheck daily

This example verifies the configuration of the Amanda server and its client(s).

Resolve all errors and warnings returned by the amcheck command. Messages with the prefix NOTE: are informational messages, and usually require no action. Error messages are explained in the Amcheck issues page.

Log files

When debugging the setup, the debug log files created by the different Amanda programs can be a great help. The debug directory is usually /tmp/amanda (See the Collecting configuration information page).

The Amanda client programs create a debug file in this directory. The filename starts with the program name, followed by a date-time stamp.

The Amanda server program writes a log in a file named amdump in the logdir specified in amanda.conf(5). When finished, the file is named amdump.1; the previous file is then found with name amdump.2, etc.

See the Amanda log files page for detailed information.

Some specific problems are explained in the Troubleshooting page.

Run a backup

You may have to run amcheck several times to resolve all errors returned. Continue the cycle until amcheck runs without returning any errors.

Please note that this process is unavoidable when setting up a product as flexible as Amanda. Amanda is a complex application with several dependencies: its operation requires that particular users and directories exist with correct permissions, etc. The output of amcheck provides any needed pointers to which parts are missing or misconfigured.

To start the first production backup, use amdump(8):

$ amdump daily

This command takes as long as the backup runs. Do not enter large disks in the disklist at this time.

You might also do:

$ amdump daily &

to run that process in the background and log off.

For longer runs, particularly on a headless tape server, look into the program screen.

When finished, you should receive an email message containing the backup report.

To re-use the already-labeled tape for another test run, remove the tape by using the amrmtape(8) command, and amlabel(8) it again with the same label:

$ amrmtape daily Daily-01
$ amlabel -f daily Daily-01

Testing recovery

To ensure that your valuable data is protected, you should verify that you can actually restore a file from the backup. Assuming that indexing is enabled in the dumptype, use amrecover, which operates much like an ftp client program. This example restores files into a temporary location (which is also, by the way, recommended for restoring files in a real-world situation rather than a test). amrecover must be run as root; there must also be an entry for the client in .amandahosts on the server, see "Create file .amandahosts on the server" above.

# mkdir /var/tmp/myrestoretest
# cd /var/tmp/myrestoretest

Don't forget to rewind the tape!

# ammt -t file:/space/amanda-vtapes/tape rewind
# amrecover test
...
Invalid directory - /var/tmp/myrestoretest
amrecover> 

Amanda assumes that you are located in the top directory of a entry in the disklist, and returns an error because the current directory is not a valid disklist entry. But this was intended, to demonstrate how you can set the disk from within amrecover. Its ftp-client-like commands also allow you to explore the index, and then extract the backup file(s).

amrecover> setdisk /var
200 Disk set to /var.
amrecover> ls
...
amrecover> cd log
amrecover> add messages.1
Added /log/messages.1
amrecover> extract

Extracting files using tape drive file:/space/amanda-vtapes/tape on host amandahost.
The following tapes are needed: Test-01

Restoring files into directory /var/tmp/myrestoretest
Continue [?/Y/n]? y

Extracting files using tape drive file:/space/amanda-vtapes/tape on host amandahost.
Load tape Test-01 now
Continue [?/Y/n/s/t]? y
./log/messages.1
amrecover> quit

Common configuration errors

• Directories/files created during the configuration are not writeable by the backup user (amandabackup in our example)

Running some programs as root, instead of the Amanda user, creates some files owned by root instead of the Amanda user. When later running as the Amanda user, there could be permission problems with these files. Do not test or run Amanda suite programs as root (except amrecover, which must be run as root).

• Specifying the wrong tapedevice: Amanda needs the non-rewind version of the tape device (if it exists on your system) in your amanda.conf file.

• Forgetting to set "disable = no" for amanda services in xinetd configuration files.

• Forgetting to have (x)inetd reread the config after adding the entries. Use netstat -a command to verify the ports if xinetd/inetd listening on the ports it should be listening on.

• Wrong hostname (Use fully qualified domain names) in .amandahosts file. Not specifying IP address and host names in /etc/hosts file

• Firewall between client and server. Firewall should correctly configured to allow amanda traffic between server and client. See Firewalls & NAT and configuration with iptables sections.

• Sendmail/postfix/... configuration on the mail server refusing mail from your Amanda server. Amanda sends notification emails as the Amanda (non-root) user. Sendmail or Postfix or mail server software should be configured to allow emails from non-root user. Also the SMTP-server of your ISP might block mails from [email protected] if the mailbox does not exist there.

• When upgrading a client and changing the user from 'amanda' to 'amandabackup', remember to delete all amandarelated files at /tmp. They will have wrong permission. Amanda will create new ones when needed.

For more information on resolving other issues, see the Troubleshooting section.

Add crontab entries

Once you are comfortable that everything is working correctly, use cron to automate running a quick check of amanda and your backup run. Run amcheck during the day when operators are present and can attend to any problems. Run amdump when the system is quiet, typically late at night or early in the morning.

0 16 * * 1-5 /usr/sbin/amcheck -m confname
45 0 * * 2-6 /usr/sbin/amdump confname

(Change the pathnames if the programs were installed elsewhere like e.g. /usr/local/sbin)

Note: Some operating systems have a shared crontab for all users, and may require a userid to be specified for each entry. See the cron(8) man page from the host system for details.

With crontab entries from the example above, Amanda will check that the correct tape is in the drive every weekday afternoon at 4 PM (if it isn't, all the operators will get mail). At 12:45 AM that night the dumps will be run.

Some systems have a directory, /etc/cron.d (or equivalent). Files in that directory are treated as additional crontab files. Instead of editing crontab, add a custom file with a suitable name and your Amanda crontab entries. You will probably have to specify the user ID to run as, just as you would in crontab. With this technique, your Amanda entries won't be clobbered by an upgrade. The following example runs on a Debian Linux installation:

0 12    * * 0-4 backup   /usr/sbin/amcheck -m -c -s DailySet1
23 1    * * 1-5 backup   /usr/sbin/amdump DailySet1

Start production run

• Remove the "record no" option from the dumptype, if you added this for testing purposes.

• Add more hosts and disks to the disklist

When you add them all at once, be prepared for loud complaints in the report from Amanda about not being able to get all the data on one tape. But after a few runs, Amanda should settle down.

Better, add hosts and disks a few at a time to avoid indigestion.

• Label more tapes. Labeling them one each day a new tape is needed is fine too. After "tapecycle" runs, Amanda will ask for the first, oldest tape again.

• Verify/activate the crontab entries on the server.

• Insert the next tape for tonight, and let the amcheck in crontab verify the configuration.

• Verify the backup report you receive the next day carefully.

• Study more of the Amanda programs, and tune amanda.conf to your needs.

• Subscribe to the Amanda forums and Amanda-users mailing list:

• Exercise/practice a recover using amrecover(8), amrestore(8) or even a bare metal recovery using dd and gnutar/restore before the real disasters happen.