Installing the HFS backup software for Linux

With effect from version 8.1 onwards, the IBM TSM (Tivoli Storage Manager) backup / archive product has been rebranded as IBM Spectrum Protect. This is a rebranding exercise by IBM and, unless indicated specifically, there is no difference in the operation of the two brands. Version 7 of the (old) TSM client is still available for installation on older operating systems and you will see references to both IBM Spectrum Protect and TSM throughout these pages.

1. Platform Support

The latest IBM Spectrum protect client for Linux runs on Intel x86_64 platforms. IBM no longer support the 32-bit Intel x86 platform. Currently supported versions require Java 7 or higher (for running the GUI). For older distributions that only have Java 6 and for 32-bit versions you can continue to use the older versions but be aware that this is unsupported. The HFS packages make sure you have the appropriate version for your system installed. 

These versions of the client include native support for the following filesystem types: EXT2, EXT3, EXT4, JFS, XFS, NSS, ReiserFS, VxFS, and GPFS.

IBM officially supports (to varying degrees) the TSM Linux client on recent versions of Red Hat Enterprise Linux, SUSE Linux Enterprise Server, SUSE Linux Enterprise Desktop, Ubuntu, CentOS, Debian,  Fedora, OpenSUSE, and Scientific Linux. However in practice just about any recent Linux distribution should be able to run the Spectrum Protect/TSM backup/archive client software and we have successfully tested on a number of others. In certain cases it may not be possible to run the Java GUI client but even then the command line client can usually be installed and run.

2. Prerequisites

The preferred method of installation is using the HFS software repositories. When doing this software prerequisites should be automatically installed. These include:

Item Version Notes
libstdc++ 6  
X Window System   required for the GUI
Java runtime JRE 7 or higher  required for the GUI
IBM GSKit libraries   supplied with the TSM client software

It is possible to run the command line application without having to have a Java runtime or X Window System installed.

The TSM software installs in /opt/tivoli and /usr/local/ibm. It must be possible to create these directories (if they don't exist) and write into them.

You need to be connected to the university network directly or via VPN to download or upgrade the client software; an eduroam connection without VPN is not sufficient.  Once it is downloaded, you can install and use the client software over eduroam as well as with a wired connection or VPN.

3. Installation - General Outline

The installation or upgrade procedure depends on the distribution and version of Linux you are using. For most Linux distributions you can install the Spectrum Protect client from the IT Services HFS repository. You first download and install a package that configures your system to use the HFS repository. You then install the client from that repository which means all dependencies will be automatically installed and also you will automatically get client updates alongside all your other software updates.

The Linux repositories are signed. If you wish to confirm the signing key refer to Checking the repository signing key.

For Linux distributions that don't have repository support you can download and install from rpm files, or for distributions that don't support rpm (e.g. Gentoo) we provide a tar file that can be used to install the client.

When installing the HFS packaged client for the first time on Debian based systems the installer will ask for your nodename, password, and whether you want to run scheduled backups, and will then automatically configure the software correctly to connect to the HFS service. On other systems you will have to manually run the setup utility after installation.

Provided it finds an existing valid configuration the installer will upgrade that configuration without any further input on your part. If you were previously running scheduled backups the installer will stop the old scheduler before upgrading the software then restart it afterwards. It will upgrade your dsm.opt and dsm.sys configuration files.

If something does go wrong with the upgrade process your old configuration files will have been saved with the suffix .SAVE, for example as /opt/tivoli/tsm/client/ba/bin/dsm.opt.SAVE.

If it can work out how to do it, the installer will create a desktop menu item for Spectrum Protect. When you select this you will usually be prompted for a password to enable you to run this with administrative privileges.

The client installs into /opt/tivoli/tsm/client/ with some additional files placed in /usr/bin. The GSKit packages installed as a dependency install into /usr/local/ibm.

The relevant executables are:

dsmj The Java GUI client
dsmc The command line client
dsmtca The 'trusted client agent', which allows non-root users to connect to the HFS

A file /etc/TIVGUID is created the first time a client is run. This file holds the Global Unique Identifier that associates a client with a Spectrum Protect server and should not be edited or removed.

The password for the HFS account will be stored in an encrypted form, readable only by root, in /etc/adsm/TSM.PWD.

If you have installed from the HFS repository you will get client updates along with all your other system updates.

If you have specific installation problems then email hfs@ox.ac.uk attaching /opt/tivoli/tsm/client/ba/bin/tsm-install.log. This describes what the post installation scripts have attempted to do, and highlights any problems. It may also be required to email the following files: dsm.sys, dsm.opt.

4. The HFS repository

4.1. Supported distributions

The following table lists distributions and versions that are known to install correctly from the HFS repository. If a distribution/version is not in the table it doesn't mean you can't install from the repository - it just means we haven't tried it. Most distributions based on Debian or RedHat will install from the HFS repository.

Distribution Version Notes
Centos 6, 7  
Debian 7, 8, 9 see note 2
Fedora 22, 23, 24, 25, 26 see notes 1 and 2
Mageia 4, 5  
OpenSUSE 12.1. 12.2, 12.3, 13.1. 13.2  
Red Hat Enterprise Linux 6, 7  
Scientific Linux 6, 7  
Ubuntu 14.04 LTS, 16.04 LTS, 17.04, 17.10 see notes 1 and 2

Note 1: There is a known problem with versions of the TSM client prior to 6.4.1.7 on Linux systems with glibc 2.16 or higher (notably Fedora 18, Ubuntu 13.04, RHEL/Centos 7, and later). If you are upgrading you operating system please make sure you upgrade your TSM client to the latest level first.

Note 2: The TSM/IBM Spectrum Protect GUI cannot be run directly when logged in as a normal user on Ubuntu 17.10, Fedora 25 and higher, and Debian 9 (using GNOME and Wayland) and other distributions using the Wayland display manager. See knowledge base article KBNIX0009 for more information and a workaround.

4.2. Unsupported distributions

Distributions that do not use Debian or Redhat style software packaging cannot use the HFS repository. These include Arch, Gentoo and Slackware. If you cannot use the repository it doesn't mean you cannot use TSM - you may be able to successfully install the client from rpm or tar files as described below.

5. Setting up the repository

5.1. Downloading the repository package file

Download the ox-hfs-repo package.

For Debian based systems (including Debian, Ubuntu, Kubuntu, Lubuntu, Xubuntu, Linux Mint, Zorin) download the ox-hfs-repo Debian package.

For RedHat based systems (including RedHat Enterprise Linux, Fedora, Centos, Scientific Linux, Mandriva, Mageia, OpenSUSE, SUSE Enterprise Linux) download the ox-hfs-repo RPM package.

Note that access to this file is restricted to the University network. If you are outside the University you can still obtain the file and install the Spectrum Protect/TSM client provided you have a VPN connection to the University network while you do the installation.

If you download this package file using a browser you may be prompted to install it. You may be able to do this (the details will vary from one distribution to another) but it is known that there are cases where this doesn't work so we recommend that you save the file to disk and use the commands described below to install the package.

5.2. Installing the repository package

Open a command shell, change to the directory where you saved the file, and as root run the following command (depending on your Linux distribution):

For Debian based systems (including Debian, Ubuntu, Kubuntu, Lubuntu, Xubuntu, Linux Mint, Zorin) run

dpkg -i ox-hfs-repo_1.4.0-1_all.deb

For RedHat based systems that use the yum package manager (including RedHat Enterprise Linux, Fedora, Centos, Scientific Linux) run

yum install ox-hfs-repo-1.4.0-1.noarch.rpm

For RedHat based systems that use the dnf package manager (Fedora 22 and later) run

dnf install ox-hfs-repo-1.4.0-1.noarch.rpm
For other RedHat based systems (including Mandriva, Mageia, OpenSUSE, SUSE Enterprise Linux), or if yum install (or dnf install) doesn't work on your system, run
rpm -i ox-hfs-repo-1.4.0-1.noarch.rpm

6. Client installation

Make sure you have installed the repository package as described in the previous section, then follow the instructions in the appropriate section below depending on your distribution

Alternatively, if the repository doesn't support your distribution follow the instructions for manual rpm installation, if your system supports rpm packages, or tar file installation

6.1. Debian based distributions (e.g. Debian, Ubuntu)

6.1.1. Installing the client

  1. Make sure the universe repository is enabled in /etc/apt/sources.list
  2. Update your list of packages with apt-get update
  3. To install the full client including GUI support do apt-get install ox-hfs-sp-client
  4. Alternatively to install the command line only client do apt-get install ox-hfs-sp-client-nogui
  5. The selected package as well as some packages it depends on (including gskcrypt64 and gskssl64) will be installed. For new installs you will be prompted for your HFS nodename and password and will be asked whether you want to run scheduled backups.

There are some older systems (those that don't usually have Java 7 available) which will not install the latest client. If you get a message like 'Unable to locate package ox-hfs-sp-client' try installing the older client with apt-get install tsm-client.

It is also possible to install the client with GUI tools. However the details vary between distributions so are not covered here.

6.1.2. Upgrading the TSM client

If you are upgrading from TSM 6.1, 5.5 or 5.4 first install the ox-hfs-repo package as described above.

Usually the client will be updated alongside all your other software updates. If you want to upgrade just the Spectrum Protect/TSM client run the following two commands (as root, or prefixed with sudo):

apt-get update
apt-get install ox-hfs-sp-client 

or

apt-get update
apt-get install ox-hfs-sp-client-nogui 

if you have only the tsm-client-base package installed.

If your upgraded configuration is not working and you would like to start with a fresh configuration then run:

dpkg-reconfigure ox-hfs-sp-client-nogui

This will ignore your old configuration files and prompt you for your Nodename and Password, and whether you want to run scheduled backups.

If the update was successful, you can continue to use the backup/archive client as previously. Your scheduled backups should also continue to function as previously.

6.2. Red Hat based distributions (e.g. Red Hat Enterprise Linux, Fedora, CentOS, Scientific Linux)

6.2.1. Installing the client

You can install the client using yum (or dnf for Fedora 22 and later):

  1. Make sure you are logged in as root.
  2. To install the full client including GUI support do yum install ox-hfs-sp-client
  3. Alternatively to install the command line only client do yum install ox-hfs-sp-client-nogui
  4. The selected package as well as some packages it depends on (including gskcrypt64 and gskssl64) will be installed.
  5. Run /opt/tivoli/tsm/client/ba/bin/HFSsetup.sh. This will prompt for a Nodename, Password, and whether to start the scheduler.

There are some older systems (those that don't usually have Java 7 available) which will not install the latest client. If you get a message like 'Unable to locate package ox-hfs-sp-client' try installing the older client with yum install tsm-client.

It is also possible to install the client with GUI tools. However you will still need to run /opt/tivoli/tsm/client/ba/bin/HFSsetup.sh as root after installation.

6.2.2. Upgrading the client

If you are upgrading from TSM 6.1, 5.5 or 5.4 first install the ox-hfs-repo package as described above.

Usually the client will be updated alongside all your other software updates. If you want to upgrade just the Spectrum Protect/TSM client run the following commands as root (replace yum with dnf for Fedora 22 and later):

yum update tsm-client ox-hfs-sp-client 

or

yum update tsm-client-base ox-hfs-sp-client-nogui

if you have only the tsm-client-base or ox-hfs-sp-client-nogui package installed.

If your upgraded configuration is not working and you would like to start with a fresh configuration then run:

/opt/tivoli/tsm/client/ba/bin/HFSsetup.sh reconfigure

This will ignore your old configuration files and prompt you for your Nodename and Password, and whether you want to run scheduled backups.

If the update was successful, you can continue to use the client as previously. Your scheduled backups should also continue to function as previously.

6.3. SUSE distributions

6.3.1. Installing the client

You can install the client using zypper:

  1. Make sure you are logged in as root
  2. To install the full client including GUI support do zypper install ox-hfs-sp-client
  3. Alternatively to install the command line only client do zypper install ox-hfs-sp-client-base
  4. The selected package as well as some packages it depends on (including gskcrypt64 and gskssl64) will be installed.
  5. Run /opt/tivoli/tsm/client/ba/bin/HFSsetup.sh. This will prompt for a Nodename, Password, and whether to start the scheduler.

It is also possible to install the client with GUI tools. However the details vary between distributions so are not covered here. You will still need to run /opt/tivoli/tsm/client/ba/bin/HFSsetup.sh as root after installation.

6.3.2. Upgrading the client

If you are upgrading from TSM 7.1.x.x or earlier you will need to uninstall the older TSM client and then reinstall the new Spectrum Protect client.

Once you have this installed it will usually be updated alongside all your other software updates. If you want to just update the Spectrum Protect client and not other packages, run the following commands as root:

zypper update ox-hfs-sp-client ox-hfs-sp-client-nogui

or

zypper update ox-hfs-sp-client-nogui

if you have only the ox-hfs-sp-client-nogui package installed.

If your upgraded configuration is not working and you would like to start with a fresh configuration then run:

/opt/tivoli/tsm/client/ba/bin/HFSsetup.sh reconfigure

This will ignore your old configuration files and prompt you for your Nodename and Password, and whether you want to run scheduled backups.

If the update was successful, you can continue to use the client as previously. Your scheduled backups should also continue to function as previously.

6.4. Mageia/Mandriva distributions

6.4.1. Installing the client

You can install the client using urpmi:

  1. Make sure you are logged in as root
  2. To install the full client including GUI support do urpmi ox-hfs-sp-client
  3. Alternatively to install the command line only client do urpmi ox-hfs-sp-client-nogui
  4. The selected package as well as some packages it depends on (including gskcrypt64 and gskssl64 for TSM) will be installed.
  5. Run /opt/tivoli/tsm/client/ba/bin/HFSsetup.sh. This will prompt for a Nodename, Password, and whether to start the scheduler.

It is also possible to install the client with GUI tools. However the details vary between distributions so are not covered here. You will still need to run /opt/tivoli/tsm/client/ba/bin/HFSsetup.sh as root after installation.

6.4.2. Upgrading the client

If you are upgrading from TSM 6.1, 5.5 or 5.4 first install the ox-hfs-repo package as described above.

Usually the client will be updated alongside all your other software updates. However, because versions up to 6.2 were 32-bit while later versions are 64-bit software you will not be past 6.2. If you are running TSM 6.2 or earlier on a 64-bit system you must first uninstall the old version by doing:

urpme tsm-client tsm-client-base gskcrypt64 gskssl64

if your current version is TSM 6.2, or

urpme tsm-client 

if your current version is 6.1 or earlier. Then install the latest Spectrum Protect client as described above.

If you want to just upgrade the Spectrum Protect client and not other packages, run the following commands as root:

urpmi ox-hfs-sp-client 

or

urpmi ox-hfs-sp-client-nogui 

if you have the GUI components installed.

If your upgraded configuration is not working and you would like to start with a fresh configuration then run:

/opt/tivoli/tsm/client/ba/bin/HFSsetup.sh reconfigure

This will ignore your old configuration files and prompt you for your Nodename and Password, and whether you want to run scheduled backups.

If the update was successful, you can continue to use the client as previously. Your scheduled backups should also continue to function as previously.

6.5. Manual RPM Install

6.5.1. Installing

Install the HFS rpm signing key

rpm --import http://downloads.hfs.ox.ac.uk/repo/GPG-KEY

Download all the RPM files from http://downloads.hfs.ox.ac.uk/repo/rpm/streams/current/ (or http://downloads.hfs.ox.ac.uk/repo/rpm/streams/java6/ if you need the version 6 client for use with Java 6)

For 64-bit Linux distributions with Java 7 or higher install the required downloaded packages with

rpm -i ox-hfs-repo-1.4.0-1.noarch.rpm ox-hfs-sp-client-8.1.0.2-1.x86_64.rpm ox-hfs-sp-client-nogui-8.1.0.2-1.x86_64.rpm gskcrypt64-8.0-50.66.x86_64.rpm gskssl64-8.0-50.66.x86_64.rpm

or if you only want the command line client

rpm -i ox-hfs-repo-1.4.0-1.noarch.rpm ox-hfs-sp-client-nogui-8.1.0.2-1.x86_64.rpm gskcrypt64-8.0-50.66.x86_64.rpm gskssl64-8.0-50.66.x86_64.rpm

For 64-bit Linux distributions with Java 6 only install the required downloaded packages with

rpm -i ox-hfs-repo-1.4.0-1.noarch.rpm otsm-client-6.4.3.0-1.x86_64.rpm tsm-client-base-6.4.3.0-1.x86_64.rpm gskcrypt64-8.0-50.40.x86_64.rpm gskssl64-8.0-50.40.x86_64.rpm

For 32-bit Linux you can try installing the older 32-bit client packages (but be aware that this is no longer supported) with

rpm -i ox-hfs-repo-1.4.0-1.noarch.rpm tsm-client-6.2.5.3-3.i386.rpm tsm-client-base-6.2.5.3-3.i386.rpm gskcrypt32-8.0-14.6.i386.rpm gskssl32-8.0-14.6.i386.rpm

or if you only want the command line client

rpm -i ox-hfs-repo-1.4.0-1.noarch.rpm tsm-client-base-6.2.5.3-3.i386.rpm gskcrypt32-8.0-14.6.i386.rpm gskssl32-8.0-14.6.i386.rpm

If this complains about missing dependencies (for example compat-libstdc++-33) you will need to find and install those packages for your distribution. If the dependent libraries are actually installed you can try using the --nodeps switch to install ignoring dependencies. If you can't meet dependencies for the tsm-client package try omitting that - you may still be able to install the command line only package. (Note that the ox-hfs-repo package is installed even though you can't use a repository as as it is a dependency of the tsm-client-base package).

To automatically configure the client run: /opt/tivoli/tsm/client/ba/bin/HFSsetup.sh. This will prompt for a Nodename, Password, and whether to start the scheduler.

6.5.2. Upgrading

Follow the instructions above for installation only use rpm -U option in place of rpm -i, e.g. for 64-bit Linux distributions with Java 7 or higher

rpm -U ox-hfs-repo-1.4.0-1.noarch.rpm ox-hfs-sp-client-8.1.0.2-1.x86_64.rpm ox-hfs-sp-client-nogui-8.1.0.2-1.x86_64.rpm gskcrypt64-8.0-50.66.x86_64.rpm gskssl64-8.0-50.66.x86_64.rpm

If the update was successful, you can continue to use the client as previously. Your scheduled backups should also continue to function as previously.

However, if your configuration is not working after the upgrade and you would like to start with a fresh configuration then run:

/opt/tivoli/tsm/client/ba/bin/HFSsetup.sh reconfigure

Then follow the installation instructions. This will ignore your old configuration files and prompt you for your Nodename and Password, and whether you want to run scheduled backups.

6.6. Installing using the tar file (e.g. Gentoo)

6.6.1. Installing the client

Download the gzipped tar file from http://downloads.hfs.ox.ac.uk/clients/linux/8.1.0.2/ox-hfs-sp-client-8.1.0.2-2.tgz (or if you have Java 6 available but not Java 7 or higher, download the version 6 client from http://downloads.hfs.ox.ac.uk/clients/linux/6.4.3.0/tsm-client-6.4.3.0-1.tgz)

Install the software by untarring the file from the root directory.

After the software has been unpacked, to automatically configure the client run: /opt/tivoli/tsm/client/ba/bin/HFSsetup.sh. This will prompt for a Nodename and Password, and whether you want to run scheduled backups. (If you are using a system with a startup script system significantly different to that used on Debian and Redhat systems, e.g. Gentoo, you may have to manually configure the scheduler to start).

For example:

cd /tmp
wget http://downloads.hfs.ox.ac.uk/clients/linux/8.1.0.2/ox-hfs-sp-client-8.1.0.2-2.tgz
cd /
su -
tar -xhzf /tmp/ox-hfs-sp-client-8.1.0.2-2.tgz
/opt/tivoli/tsm/client/ba/bin/HFSsetup.sh 

6.6.2. Upgrading the TSM client.

Save the files dsm.opt, dsm.sys, incl.excl and dsmsched.rc (if they exist) to a safe area.

Remove the /opt/tivoli directory tree.

Download the tar file and untar as for a fresh installation.

Copy back the files you saved earlier (dsm.opt, dsm.sys, etc) back to /opt/tivoli/tsm/client/ba/bin/

Run the /opt/tivoli/tsm/client/ba/bin/HFSsetup.sh script, which will upgrade the existing configuration.

If the update was successful, you can continue to use the client as previously. Your scheduled backups should also continue to function as previously.

7. Allowing or preventing non-root use of the client

By default non-root users are able to use the Spectrum Protect/TSM software to back up and restore their own files. Should you wish to disable this functionality, do as follows:

  • Change the permissions on /opt/tivoli/tsm/client/ba/bin/dsmtca by running the following command as the root user:
    chmod 4700 /opt/tivoli/tsm/client/ba/bin/dsmtca 

If you wish to allow access to only a group of users, do the following:

  • Create a trustedusers Unix group (the actual name is up to you).
  • Add each user who needs access to the trustedusers group.  The root user does not need to be a member of this group.
  • Change the group owner of /opt/tivoli/tsm/client/ba/bin/dsmtca to the trustedusers group by running the following command as the root user:
    chgrp trustedusers /opt/tivoli/tsm/client/ba/bin/dsmtca 
  • Change the permissions on /opt/tivoli/tsm/client/ba/bin/dsmtca by running the following command as the root user:
    chmod 4750 /opt/tivoli/tsm/client/ba/bin/dsmtca 
  • Ensure that there is access to dsmerror.log. You can do this by changing the value of errorlogname in dsm.sys from the default (/var/log/dsmerror.log) to a location where the user concerned has access, e.g. their home directory. An alternative is to change permissions on /var/log/dsmerror.log, to enable write-access.

This will enable a non-root user to back up and restore only their own files. To back up and restore all files, you must run Spectrum Protect/TSM as the root user.

8. Running an Initial Backup of your System

It is important to ensure that you run an initial manual backup of your machine for the following reasons:

  1. To verify connectivity between your client and the HFS server
  2. To verify that the software is working correctly
  3. To ensure that we receive your data correctly
  4. To ensure that any issues can be addressed as soon as possible.

Now please follow these instructions to run through the initial backup.

9. Frequently Asked Questions

Downloading/installing the Spectrum Protect/TSM Client - FAQ (See all FAQs)

Written by IT Services. Latest revision 17 November 2017