Backup
IBM Spectrum Protect (also referred to as TSM for Tivoli Storage Manager) is a storage service on disk (for the primary copy) and on magnetic tape (for the secondary copy) that provides regular data backup. The HOME and THRONG directories accessible from the CC-IN2P3 interactive servers and compute nodes are automatically backed up every day.
Users and experiments also have the option to request a backup on specific storage areas by contacting the user support.
The software for the backup service provided by CC-IN2P3 is IBM Spectrum Protect.
For practical issues, please refer to the dedicated FAQ page.
Terms of use
The terms of use of the backup service are described in this document (French only).
Installation
Unix machines
The automation of the backup task must be done on the client side via cron for example.
Please refer to the dedicated page on setting up a cron job.
The TSM client is configured mainly through two files:
/opt/tivoli/tsm/client/ba/bin/dsm.opt
/opt/tivoli/tsm/client/ba/bin/dsm.sys
To prevent a client update from affecting the configuration you have made, we recommend that you unpack the entire TSM configuration in a separate tree. We usually use /var/spool/tsm.
Create the tree
Create the TSM client configuration directory:
% mkdir -p /var/spool/tsm/{etc,log,lock,bin}
Copy the IBM template config files or those form the tsm-ccin2p3 package:
% cp /opt/tivoli/tsm/client/ba/bin/dsm.{opt,sys} /var/spool/tsm/etc/
or:
% cp /usr/share/doc/tsm-ccin2p3/etc/* /var/spool/tsm/etc/
Edit the config files
Backup server address
After contacting the TSM admins, they may have assigned you an alias such as tsm${LAB_NAME}.in2p3.fr
(example: tsmlpnhe.in2p3.fr).
Attention
This alias must be used. In some cases, this alias does not exist or cannot be used, for example if you have backup nodes on different TSM servers. In the rest of the documentation ${SERVER_NAME} will have to be replaced by the server name you are assigned to.
Backup credentials
After contacting the TSM admins, you will be provided a node name (backup identifier) associated with a password.
Attention
In the rest of the documentation ${NODE_NAME} will have to be replaced by the node name you are assigned to.
File dsm.opt
This file specifies the server that the TSM client will try to contact when launching a backup:
% cat /var/spool/tsm/etc/dsm.opt
************************************************************************
* IBM Tivoli Storage Manager *
* *
* Sample Client User Options file for UNIX (dsm.opt.smp) *
************************************************************************
* This file contains an option you can use to specify the TSM
* server to contact if more than one is defined in your client
* system options file (dsm.sys). Copy dsm.opt.smp to dsm.opt.
* If you enter a server name for the option below, remove the
* leading asterisk (*).
************************************************************************
* SErvername A server name defined in the dsm.sys file
SErvername ccin2p3
File dsm.sys
This file defines the known TSM backup profiles:
% cat /var/spool/tsm/etc/dsm.sys
************************************************************************
* IBM Tivoli Storage Manager *
* *
* Sample Client System Options file for UNIX (dsm.sys.smp) *
************************************************************************
* This file contains the minimum options required to get started
* using TSM. Copy dsm.sys.smp to dsm.sys. In the dsm.sys file,
* enter the appropriate values for each option listed below and
* remove the leading asterisk (*) for each one.
* If your client node communicates with multiple TSM servers, be
* sure to add a stanza, beginning with the SERVERNAME option, for
* each additional server.
************************************************************************
SErvername ccin2p3
COMMMethod TCPip
TCPPort 1500
NodeName ${NODE_NAME}
PasswordAccess generate
TCPServeraddress ${SERVER_NAME}
errorlogname "/var/spool/tsm/log/dsmerror.log"
Attention
Pay attention to specify the values of the options NodeName and TCPServeraddress.
Link backup profile to IBM directories :
% ln -s /var/spool/tsm/etc/dsm.{sys,opt} /opt/tivoli/tsm/client/ba/bin/
Initial entry of the TSM password
The option PasswordAccess Generate from the config file dsm.sys allows the TSM client to remember
the TSM password used to authenticate to the CC-IN2P3 backup servers.
However, during the first configuration, you must enter this password at least once:
% /usr/bin/dsmc
IBM Spectrum Protect
Command Line Backup-Archive Client Interface
Client Version 8, Release 1, Level 13.0
Client date/time: 01/19/2023 19:38:47
(c) Copyright by IBM Corporation and other(s) 1990, 2021. All Rights Reserved.
Node Name: DEMO
Please enter your user id <DEMO>: (1)
Please enter password for user id "DEMO": (2)
Session established with server CCTSM9: Linux/x86_64
Server Version 8, Release 1, Level 13.000
Server date/time: 01/19/2023 19:38:49 Last access: 01/19/2023 11:56:15
Protect>
Just press Enter ou type the TSM node that you need to use.
Enter the initial password you received from the TSM administrators.
If the
dsm.sysordsm.optfiles are not found whendsmcstarts, you will need to specify the path to these files in theDSM_DIRenvironment variable.
Red-Hat like machines
For systems using the RPM, YUM pair, CC-IN3P3 provides a repository to maintain your TSM package in a version known to be compatible with the one used on the CC-IN2P3 TSM servers. You can also get the TSM packages directly from the official IBM repository to get the latest version available (see link above in the Installation section).
Importing the package signing key
The repository available at CC-IN2P3 to distribute the backup service packages is based on the digital signature of the repository packages and metadata to ensure the integrity of the packages that will be installed on your machinery.
Note
For the procedure to retrieve the signature key, please refer to here.
Package repository
Set up the repository:
% cat > /etc/yum.repos.d/tsm_ccin2p3.repo
[tsm-ccin2p3]
name=tsm-ccin2p3
baseurl=https://ccrepository.in2p3.fr/pulp/repos/el/all/x86_64/tsm
gpgcheck=1
gpgkey=https://ccrepository.in2p3.fr/pulp/static/tsm.gpg
Install the Spectrum Protect client and sample files :
% yum install tsm-ccin2p3
[...]
Dependencies Resolved
============================================================================================================================================================================================================
Package Arch Version Repository Size
============================================================================================================================================================================================================
Installing:
tsm-ccin2p3 noarch 2.0-0 tsm 4.9 k
Installing for dependencies:
TIVsm-API64 x86_64 7.1.2-0 tsm 29 M
TIVsm-BA x86_64 7.1.2-0 tsm 62 M
gskcrypt64 x86_64 8.0-50.40 tsm 1.2 M
gskssl64 x86_64 8.0-50.40 tsm 6.0 M
Transaction Summary
============================================================================================================================================================================================================
Install 1 Package (+4 Dependent packages)
[...]
Note
The installation RPMs will install the TSM client and its libraries under the tree /opt/tivoli/tsm/client.
Use the Spectrum Protect client
Note
To install the Spectrum Protect client on non-Red-Hat like Unix systems, please contact your IT administrators.
To run the Spectrum Protect client in interactive mode, simply use the command dsmc (ou dsmc.exe).
The prompt Protect> indicates that you are in the TSM interactive shell.
Change your password:
Protect> set password
Please enter password for user id "DEMO": (1)
Please enter a new password: (2)
Enter new password for verification: (3)
Password updated.
Session established with server CCTSM9: Linux/x86_64
Server Version 8, Release 1, Level 13.000
Server date/time: 01/19/2023 19:43:14 Last access: 01/19/2023 11:56:15
Here you must:
Enter the initial password you received from the CC-IN2P3 TSM admins;
enter your new password;
enter your new password once again.
Check the management classes available for my backup:
Protect> query mgmt -detail
Check the options enabled for my backup:
Protect> query options
[...]
ACTIVATEKEY: YES
AFSBACKUPMNTPNT: YES
ALLOWWILDCARDCH: NO
ARCHMC:
ARCHSYMLINKASFILE: YES
ASNODENAME:
ASRFILESPATH:
ASRMODE: NO
AUTOFSRENAME: PROMPT
AUDITLOGGING: OFF
AUDITLOGNAME: /tmp/dsmaudit.log
AUTOMOUNT:
AUTODEPLOY: YES
BACKMC:
BACKUPREGISTRY: YES
CANDIDATESINTERVAL: 1
CASESENSITIVEAWARE: NO
CHANGINGRETRIES: 4
CHECKFORORPHANS: NO
CHECKTHRESHOLDS: 5
CLIENTVIEW: STANDARD
CLUSTERDISKSONLY: NO
CLUSTERNODE: NO
COMMMETHOD: TCP/IP
COLLOCATEBYFILESPEC: NO
COMMRESTARTDURATION: 60
[...]
DOMAIN:
/home
/etc
[...]
VIRTUALMOUNTPOINT:
/home
/etc
Note
For more information on the directives VirtualMountPoint or Domain, please refer to the FAQ.
Check the list of the filters used by my backup client:
Protect> query inclexcl
[...]
*** FILE INCLUDE/EXCLUDE ***
Mode Function Pattern (match from top down) Source File
---- --------- ------------------------------ -----------------
No exclude filespace statements defined.
Excl Directory /.../*no_backup* Server
Excl Directory /.../*NO_BACKUP* Server
Excl Directory /.../.beagle Server
Excl Directory /.../.[Cc]ache Server
Excl Directory /.../[Cc]ache.Trash Server
Excl Directory /.../Cache Server
Excl Directory /usr/lib64 Server
Excl Directory /usr/lib32 Server
Excl Directory /usr/lib Server
Excl Directory /usr/bin Server
Excl Directory /var/lock Server
Excl Directory /var/run Server
Excl Directory /var/tmp Server
Excl Directory /boot Server
Excl Directory /lib64 Server
Excl Directory /lib32 Server
Excl Directory /lib Server
Excl Directory /sbin Server
Excl Directory /bin Server
[...]
For example, the following line means that everything under /bin will not be saved:
Excl Directory /bin Server
The information Server indicates that this filter originates from the backup server (and is therefore not modifiable without intervention from the CC-IN2P3 TSM administrators).
Check the FileSpaces assigned to my backup node:
Protect> query files
Backup a directory:
% dsmc incremental /PATH/TO/DIR/ -subdir=yes
Backup a file:
% dsmc incremental /PATH/TO/FILE
Preview a directory contents as backuped by the TSM client:
% dsmc preview backup /PATH/TO/DIR/ -subdir=yes
[...]
Preview function invoked.
Depending on the number of objects to query, this operation could take a while to complete.
Are you sure you want to continue? (Yes (Y)/No (N)) Y
Preview output has been successfully written to file '/var/spool/tsm/log/dsmprev.txt'.
This command generates a list of files and directories in $PWD/dsmprev.txt, and mentions whether Spectrum Protect will save them or not.
The preview file dsmprev.txt may in some cases be requested by CC-IN2P3 administrators to help you solve your backup problems.
Check the backuped files and their state in Spectrum Protect:
In Spectrum Protect a file may assume two states:
A pour Active when the file is still available on the machine that performs the backup;
I pour Inactive when the file is not longer available on the machine that performs the backup or is no longer the latest version of the file:
% dsmc query backup /var/spool/tsm/etc/dsm.sys -inactive
[...]
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
2 206 B 20/09/2011 17:10:36 PCMGM A /var/spool/tsm/etc/dsm.sys
1 929 B 01/06/2011 17:06:08 PCMGM I /var/spool/tsm/etc/dsm.sys
2 010 B 18/07/2011 17:52:02 PCMGM I /var/spool/tsm/etc/dsm.sys
2 178 B 19/07/2011 17:13:58 PCMGM I /var/spool/tsm/etc/dsm.sys
Restore the last version of a file:
% dsmc restore /var/spool/tsm/etc/dsm.sys /tmp/dsm.sys.restored
[...]
Restore function invoked.
** Interrupted **
Restoring 2 206 /var/spool/tsm/etc/dsm.sys --> /tmp/dsm.sys.restored [Done]
Restore processing finished.
Total number of objects restored: 1
Total number of objects failed: 0
Total number of bytes transferred: 2,17 KB
Data transfer time: 0,00 sec
Network data transfer rate: 90 779,62 KB/sec
Aggregate data transfer rate: 0,02 KB/sec
Elapsed processing time: 00:01:37
This command restores the last version of the file /var/spool/tsm/etc/dsm.sys to the location /tmp/dsm.sys.restored.
If a new location would have not been specified, the file would have been restored directly in /var/spool/tsm/etc/dsm.sys and would have overwritten our file in case it already existed.
Restore the last version of a directory and its contents:
% dsmc restore /var/spool/tsm/ -verbose -subdir=yes
As for files, you may specify a new location for the restore:
% dsmc restore /var/spool/tsm/ /tmp/tsm.restored/ -subdir=yes
Restore an older file version using a date:
% dsmc query backup /var/spool/tsm/etc/dsm.sys -inactive -pitd=09/01/2011
[...]
Size Backup Date Mgmt Class A/I File
---- ----------- ---------- --- ----
2,178 B 07/19/2011 17:13:58 PCMGM I /var/spool/tsm/etc/dsm.sys
The option -pitd means Point In Time Date and allows to specify a precise date for the restoration.
In the command shown as an example we asked which version of file /var/spool/tsm/etc/dsm.sys was in Spectrum Protect as of September 1st 2011.
The date format as specified in the option -pitd is MM/DD/YYYY (default format if LANG=C).
We can see that the file /var/spool/tsm/etc/dsm.sys from September 1st 2011 is an inactive version of the file backed up
on July 19th 2011 and never modified since then.
To restore it, just use the -pitd option in conjunction with the dsmc restore function:
% dsmc restore /var/spool/tsm/etc/dsm.sys -inactive -pitd=09/01/2011
Restore data between two dates:
% dsmc restore /path/to/restore/ -fromdate=06/01/2014 -todate=06/11/2014 -subdir=yes
Restore a list of files:
Given a file to_restore.txt with the following content:
/tmp/file1.txt
/tmp/file2.txt
[...]
/var/tmp/files/fileN.txt
To restore all the files listed in to_restore.txt, use the -filelist option of the Spectrum Protect client:
% dsmc restore -filelist=to_restore.txt
[...]
Get a report on the TSM client installation and configuration:
% dsmc query systeminfo
[...]
QUERY SYSTEMINFO output has been written to file /var/spool/tsm/etc/CCAFS/dsminfo.txt.
The file dsminfo.txt generated by this command may in some cases be requested by CC-IN2P3 administrators to help you solve your backup problems.
Backup statistics
Detailed statistics per laboratory can be obtained by querying the API at https://tsmlabapi.in2p3.fr. For any access request to the API please contact the user support.
Description
Information delivered by the API is:
the date of the last update for the data given in the Unix timestamp format;
statistics for the entire laboratory;
statistics for a given node in the laboratory;
statistics for a given filespace in a specific node in the laboratory.
Information delivered at laboratory level is:
the lab name;
the total number of backup nodes assigned to this lab;
the total number of lab files available in the backup system (primary copy + secondary copy);
the total used space in bytes for the lab backup in the backup system (primary copy + secondary copy);
the list of the backup nodes assigned to this lab.
Information delivered at the backup node level is:
the node name;
the total number of files in this node available in the backup system (primary copy + secondary copy);
the total used space in Bytes for the node backup in the backup system (primary copy + secondary copy);
the list of users registered as official contact for this node (users that will be contacted if necessary by CC-IN2P3 backup administrators);
the last access date to this node, given in timestamp Unix format;
the number of days since the node last access to the backup system (<1 meaning that access has been made in the last 24 hours);
the list of the filespaces assigned to this node.
Information delivered at the filespace level is:
the filespace name;
the total number of files belonging to this filespace available in the backup system (primary copy + secondary copy);
the the total used space in bytes for this filespace backup in the backup system (primary copy + secondary copy).
API querying
Access to this API requires identifiers that must be communicated to you by the CC-IN2P3 backup service administrators. The API provided by CC-IN2P3 is in Web Service REST form. The supported output formats (or serializer) are:
application/xml (utilisé par défaut) (Wikipedia description)
application/json (Wikipédia description)
text/html (currently not supported)
text/x-yaml (Wikipédia description)
Examples of use
With a Web browser
Access the URL https://tsmlabapi.in2p3.fr with your browser and check the SSL certificate presented by the website before entering your credentials.
Enter the identifiers that you received from CC-IN2P3 backup service administrators.
The Web interface that is currently displayed is only the result of a basic rendering made by your Web browser of the XML document returned by the API.
With a command line interface
The tool that will be used as an example is cURL. The options that will be used in the following examples are:
-H "Accept: application/json"that allows to add the HTTP header Accept: application/json to the request;-u "username:password"that allows to authenticate to the Web server with the login “username” and the password “password”;-Lthat tells cURL to follow the HTTP redirections.
Example of data retrieval in JSON format:
% curl -L -H 'Accept: application/json' -u 'username:password' https://tsmlabapi.in2p3.fr
{
"details": {
"generated_in": "0.66ms",
"last_cache_update": 1406551433
},
"results": [
{
"laboratory": "CCIN2P3",
"nodes": [
{
"contacts": [
"no-reply@cc.in2p3.fr"
],
"days_since_last_access": "<1",
"filespaces": [
{
"filespace_name": "/backup/volume1",
"num_files": 6,
"physical_b": 21
},
{
"filespace_name": "/backup/volume2",
"num_files": 6,
"physical_b": 21
}
],
"last_access": 1406524790,
"node_name": "DEMO_NODE",
"total": {
"num_files": 12,
"physical_b": 42
}
}
],
"total": {
"nodes": 1,
"num_files": 12,
"physical_b": 42
}
}
]
}
Note
The output of this command was formatted with curl … | python -mjson.tool.
Digital signatures
The documents made available by TSM administrators are digitally signed using OpenGPG.
Details on the key used for signatures
The public key used for all digital signatures can be found here.
here.
Key details:
pub 2048R/18877579 2012-12-05
Key fingerprint = 1868 E312 47B4 610A CC8A CD67 14A7 1D76 1887 7579
uid CC-IN2P3 TsmMaster <tsmmaster@cc.in2p3.fr>
Import the public key into your keyring to verify digital signatures
Given ${PUBLICKEY_PATH} your public key path. It can be for instance
C:\Documents and settings\Administrator\CC-IN2P3_public_key.gpg or /tmp/CC-IN2P3_public_key.gpg.
Verify the public key fingerprint:
% gpg --with-fingerprint ${PUBLICKEY_PATH} pub 2048R/18877579 2012-12-05 CC-IN2P3 TsmMaster <tsmmaster@cc.in2p3.fr> Key fingerprint = 1868 E312 47B4 610A CC8A CD67 14A7 1D76 1887 7579
Import the public key into your keyring:
% gpg --verbose --import ${PUBLICKEY_PATH} gpg: armor header: Version: GnuPG v2.0.14 (GNU/Linux) gpg: pub 2048R/18877579 2012-12-05 CC-IN2P3 TsmMaster <tsmmaster@cc.in2p3.fr> gpg: using PGP trust model gpg: key 18877579: public key "CC-IN2P3 TsmMaster <tsmmaster@cc.in2p3.fr>" imported gpg: Total number processed: 1 gpg: imported: 1 (RSA: 1)
Modify the confidence attributed to the CC-IN2P3 backup service key:
% gpg --edit "CC-IN2P3 TsmMaster" gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. pub 2048R/18877579 created: 2012-12-05 expires: never usage: SC trust: unknown validity: unknown [ unknown] (1). CC-IN2P3 TsmMaster <tsmmaster@cc.in2p3.fr> gpg> trust pub 2048R/18877579 created: 2012-12-05 expires: never usage: SC trust: unknown validity: unknown [ unknown] (1). CC-IN2P3 TsmMaster <tsmmaster@cc.in2p3.fr> Please decide how far you trust this user to correctly verify other users' keys (by looking at passports, checking fingerprints from different sources, etc.) 1 = I don't know or won't say 2 = I do NOT trust 3 = I trust marginally 4 = I trust fully 5 = I trust ultimately m = back to the main menu Your decision? 5 Do you really want to set this key to ultimate trust? (y/N) y pub 2048R/18877579 created: 2012-12-05 expires: never usage: SC trust: ultimate validity: unknown [ unknown] (1). CC-IN2P3 TsmMaster <tsmmaster@cc.in2p3.fr> Please note that the shown key validity is not necessarily correct unless you restart the program. gpg> quit
% gpg --verbose --list-key "CC-IN2P3 TsmMaster" gpg: using PGP trust model pub 2048R/18877579 2012-12-05 uid CC-IN2P3 TsmMaster <tsmmaster@cc.in2p3.fr>
Verify a digital signature
Given:
MY_FILE.pdfthe file which signature we want to verify.MY_FILE.ascthe signature file:
% gpg --verbose --verify MY_FILE.asc
gpg: armor header: Version: GnuPG v2.0.14 (GNU/Linux)
gpg: assuming signed data in `MY_FILE.pdf'
gpg: Signature made Tue 26 Feb 2013 02:28:03 PM CET using RSA key ID 18877579
gpg: using PGP trust model
gpg: Good signature from "CC-IN2P3 TsmMaster <tsmmaster@cc.in2p3.fr>"
gpg: binary signature, digest algorithm SHA1
Version compatibilities
The client/server compatibility matrix of IBM supported versions is described in the official documentation.
Tools
Data generator for new tree structures backup
This generator allows to set up an exchange format when the addition to the backup of a new tree structure is requested.
Direct link: http://mirror.in2p3.fr/TSM/html/tsm-mg-generator.html;
Documentation : see here.