Veritas NetBackup™ Commands Reference Guide
- Introduction
- Appendix A. NetBackup Commands
Name
bpimmedia — display information about NetBackup images on media
SYNOPSIS
[-disk_stu storage_unit_label | [-dt disk_type | -stype server_type [-dp disk_pool_name [-dv disk_volume]] [-legacy]]] [-l | -L] [-disk | -tape] [-policy policy_name] [-client client_name] [-d date time] [-e date time] [-mediaid media_id | path_name] [-mtype image_type] [-option option_name] [-rl retlevel] [-sl sched_label] [-t sched_type] [-M master_server...] [-verbose]
-spanpools [-cn copy_number] [-mediaid media_id] [-U]
On UNIX systems, the directory path to this command is /usr/openv/netbackup/bin/admincmd/
On Windows systems, the directory path to this command is <install_path>\NetBackup\bin\admincmd\
DESCRIPTION
bpimmedia queries the NetBackup image catalog and produces the following two types of reports on the images:
An Images-on-Media report
A Spanpools report
The first form of bpimmedia in the SYNOPSIS displays a set of NetBackup images in the Images-on-Media report. This report lists the contents of media as recorded in the NetBackup image catalog.
You can generate this report for any medium including disk. Filter the report contents according to client, media ID, path, and so on.
for more about the fields in the Images-on-Media report, see NetBackup Reports in the NetBackup Administrator's Guide, Volume II.
The report does not show information for the media that is used in backups of the NetBackup catalogs.
Several options (-dt, -dp, -dv, -stype) report images present on SAN disk storage only, not on any other disk-resident images. Other options and output format continue to function as before.
The second SYNOPSIS form of bpimmedia uses -spanpools to list the disk ID pools that are related because images span from one volume to another. The output lists, for each media server in the cluster, the media IDs that have spanned images. The -spanpools form of bpimmedia must be run on the NetBackup master server that administers the volumes.
For more about spanned images, see "Spanning Media" in the NetBackup Administrator's Guide, Volume II.
Only removable media types are processed.
bpimmedia sends its error messages to stderr
. bpimmedia sends a log of its activity to the NetBackup admin log file for the current day.
Authorized users can run this command.
For more about NetBackup authorization, see the NetBackup Security and Encryption Guide.
OPTIONS
- client client_name
Client name. This name must be as it appears in the NetBackup catalog. By default, bpimmedia searches for all clients.
- -cn copy_number
Copy number (1 or 2) of a backup ID. The default is copy 1. This option is used only in combination with -spanpools.
- -d date time, -e date time
Specifies the start date and end date range for the listing.
-d specifies a start date and time for the listing. The output list shows only images in backups or the archives that occurred at or after the specified date and time.
-e specifies an end date and time for the listing. The output list shows only files from backups or the archives that occurred at or before the specified date and time. Use the same format as for the start date. The default is the current date and time.
The valid range of dates is from 01/01/1970 00:00:00 to 01/19/2038 03:14:07. The default is the previous midnight.
The required date and time values format in NetBackup commands varies according to your locale. The
/usr/openv/msg/.conf
file (UNIX) and theinstall_path\VERITAS\msg\LC.CONF
file (Windows) contain information such as the date-time formats for each supported locale. The files contain specific instructions on how to add or modify the list of supported locales and formats.For more about the locale of your system, see "About specifying the locale of the NetBackup installation" in the NetBackup Administrator's Guide, Volume II.
- -dp disk_pool_name
Displays the images on the specified disk pool only.
- -dt disk_type
Specifies the type of disk storage. The following are valid options:
1 - BasicDisk
3 - SnapVault
This option does not apply to the OpenStorage disk type.
- -dv disk_volume
Displays the images that reside on the specified disk volume only. The input value is the path for BasicDisk.
- -L
The list type is long.
See the DISPLAY FORMATS section that follows.
- -l
The list type is short. This setting is the default if the command line has no list-type option (for example, if you enter bpimmedia and a carriage return).
See the DISPLAY FORMATS section that follows.
- -legacy
Formats the new data in legacy format.
- -M master_server,...
A list of alternative master servers. This list is a comma-separated list of hostnames. If this option is present, the command is run on each of the master servers in this list. The master servers must allow access by the system that issues the command. If an error occurs for any master server, the process stops at that point in the list. The default is the master server for the system where the command is entered.
- -mediaid media_id | pathname
This ID is either a VSN or an absolute pathname. If the media ID is a VSN, it is a one- to six-character string. If the media ID is a pathname, it is the absolute pathname of the file system for a disk storage unit.
When -mediaid is specified, the Images-on-Media report displays only the images that are stored on this VSN or pathname. By default, the report displays the images that are stored on all media IDs and pathnames.
For the Spanpools report (-spanpools), only a VSN can follow -mediaid. If -mediaid is omitted when -spanpools is present, bpimmedia displays all media in all spanning pools.
- -mtype image_type
Image type. The defined values and their interpretations are as follows:
0 = Regular backup (scheduled or user-directed backup)
1 = Pre-imported backup (phase 1 completed)
2 = Imported backup
- -option option_name
Specifies a criterion for finding images to list. option_name is one of the following character strings, in either uppercase or lowercase:
INCLUDE_PRE_IMPORT - Include images that completed phase 1 of an import.
ONLY_PRE_IMPORT - Include only the images that completed phase 1 of an import.
The default is INCLUDE_PRE_IMPORT.
- -policy policy_name
Searches for images with the specified policy name. By default, bpimmedia searches for images for all policies.
- -rl retlevel
Specifies the retention_level. The retention_level is an integer between 0 and 100. By default, bpimmedia searches for all retention levels.
Note:
If you run this command on a pre-NetBackup 8.0 media server, you can only specify a retention level between 0 and 24.
- -sl sched_label
Searches for images with the specified schedule label. By default, bpimmedia searches for images for all schedule labels.
- -spanpools
Specifies that bpimmedia should create a Spanpools report. The default (-spanpools not present on the command line) is to create an Images-on-Media report.
- -stype server_type
Specifies a string that identifies the storage server type. The server_type value can originate from one of the following sources:
Veritas provided storage. Possible values are AdvancedDisk and PureDisk.
Third-party disk appliances. The vendor supplies the server_type string.
Cloud storage. Possible values are
amazon
,att
, azure, andrackspace
. The cloud stype values reflect the cloud storage provider. Cloud storage stype values can also incorporate a suffix (for example,amazon_crypt
). Possible suffixes are:_raw: The NetBackup backup image is sent to the cloud in raw format. Use this option if you do not want to compress or encrypt data before sending to cloud storage.
_rawc: Compresses the data before it is written to the cloud storage.
_crypt
: Encrypt the data using AES-256 encryption before writing the data to cloud storage. You must have KMS configured in NetBackup to use this option._cryptc: Compress and encrypt the data before writing to cloud storage.
The storage server type is case sensitive.
- -t sched_type
Specifies a schedule type for the image selection. The default is any schedule type. Valid values, in either uppercase or lowercase, are as follows:
FULL (full backup)
INCR (differential-incremental backup)
CINC (cumulative-incremental backup)
UBAK (user backup)
UARC (user archive)
- -tape
Displays in the Images-on-Media report only the images that have at least one fragment that resides on removable or tape-based media. Disk-based fragments in these images are ignored. If an image has fragments on both tape and disk, this option displays only the tape-based fragments.
- -U
The list type is user. This option is used only in combination with -spanpools.
See the DISPLAY FORMATS section that follows.
- -verbose
Select verbose mode for logging. This option is only meaningful when it runs with debug logging on; that is, when the following directory is defined:
UNIX systems: /usr/openv/netbackup/logs/admin
Windows systems: install_path\NetBackup\logs\admin
DISPLAY FORMATS
IMAGES-ON-MEDIA REPORT
The Images-on-Media report consists of two formats, short (-l or default) and long (-L).
To process and use the output of bpimmedia, use the -l option. The output of bpimmedia that uses the -L or -U options may be truncated for the Backup-ID, Policy, and Host columns. The -L or -U options are useful when you want to obtain a quick, more readable view of the NetBackup images on media.
The following shows the long display format (-L) and the short display format (-l) of the Images-on-Media report:
Long Display Format (-L)
If the command line contains -L, the display format is long. It contains a multi-line entry for each backup image. The number of lines for an entry is n+1, where n is the number of fragments for the image. The fields for an entry are listed later. The first line of the entry contains the fields Backup_ID...Expires. Each fragment in the image has a line that contains the fields Copy_Media ID. The report has a two-line header. The first header line lists the field names for line 1 of each entry. The second header line lists the field names for the lines that contain fragment information.
See the bpduplicate command page for more information on the copy number and primary copy.
Fields and meanings for the -L format are as follows:
Line 1
Backup-ID - Unique identifier for the backup that produced this image
Policy - Policy name (may be truncated if long)
Type - Schedule type (FULL, etc.)
RL - Retention level (0.100)
Note:
If you run this command on a pre-NetBackup 8.0 media server, the output only displays the retention levels between 0 and 24.
Files - Number of files in the backup
C - Compression (Y or N)
E - Encryption (Y or N)
T - Image type
R - Regular (scheduled or user-directed backup)
P - Pre-imported backup (phase 1 completed)
I - Imported backup
PC - Primary copy, 1 or 2. Designates which copy of the backup NetBackup chooses when it restores.
Expires - The expiration date of the first copy to expire, which appears in the Expires field of the fragment, which is described later.
Line 2_n+1
Copy - Copy number of this fragment
Frag - Fragment number or IDX for a true-image-restore (TIR) fragment
KB - Size of the fragment, in kilobytes. This value does not include the size of tape headers between backups. A fragment size of 0 is possible for a multiplexed backup.
Type - Media type (Rmed - removable media; Disk otherwise)Density - Density of the removable media that produced the backupFnum - File number; the n-th backup on this removable media Host - Server whose catalog contains this imageDWO - Device Written On; device where the backup was written. The DWO matches the drive index as configured in Media Manager (applies only to removable media).
MPX - Flag that indicates whether this copy is multiplexed: Y or N (applies only when fragment number is 1)
Expires - The expiration date of this copy (applies only when fragment number is 1)
MediaID - Media ID or absolute path where the image is stored
Example of Long display format:
bpimmedia -L -policy regr1_gava -t FULL Backup-ID Policy Type RL Files C E T PC Expires Copy Frag KB Type Density FNum Host DWO MPX Expires MediaID ---------------------------------------------------------------- gava_0949949902 r1_guav FULL 3 25 N N R 1 12:58 03/09/2012 1 1 256 RMed dlt 13 0 plim 0 Y 12:58 03/09/2012 A00002
Short Display Format (-l)
If the bpconfig command line contains -l or contains no list-format option, the display format is short, which produces a terse listing. This option can be useful for scripts or the programs that rework the listing into a customized report format. The -l display format contains a multi-line entry for each backup image. The number of lines per entry is n+1, where n is the number of fragments for the image. The layout of an entry is a first line that contains information about the image. A second line follows that contains information about each fragment of the image. The attributes appear in the following order (separated by blanks).
Fields for the -l format are as follows:
Field 1 = Client. The name of the image's client.
Field 2 = Version. The NetBackup version of the client.
Field 3 = Image keyword. The keyword for the backup image.
Field 4 = Policy name. The name of the policy that created the image.
Field 5 = Policy type. 0=Standard, 4=Oracle, 8=Sybase, 9=MS-SharePoint
Field 6 = Schedule - Schedule name that is run to create the backup.
Field 7 = Schedule type. 0=Full, 1=Differential incremental, 2=User-directed backup, 3=User-directed archive, 4=Cumulative incremental
Field 8 = Retention level (0-100).
Note:
If you run this command on a pre-NetBackup 8.0 media server, the output only displays the retention levels between 0 and 24.
0 = 1 week, 4mm cartridge media
1 = 2 weeks, 8mm cartridge media
2 = 3 weeks, 8mm2 cartridge media
3 = 1 month, 8mm3 cartridge media
4 = 2 months, dlt cartridge media
5 = 3 months, dlt2 cartridge media
6 = 6 months, dlt3 cartridge media
7 = 9 months, dtf cartridge media
8 = 1 year, half-inch cartridge media
9-100 = infinite (except 25 which is expire immediately), half-inch cartridge 2 media
Field 9 = Number of files in the image.
Field 10 = Expiration time of the image in seconds since January 1, 1970. A value of zero (0) denotes an image in progress or failed.
Field 11 = Compression. 0=Use compression, 1=Do not use compression
Field 12 = Encryption.
Field 13 = Hold. 0=Image is not on hold, 1=Image is on hold
Fragments
Field 1 = Copy number
Field 2 = Fragment number
Field 3 = Fragment size in KBytes
Field 7 = File number
Field 8 = Media. The media where the image is stored.
Field 9 = The media server for the image.
Field 10 = Block size in KBytes
Field 11 = Offset
Field 12 = The time (in seconds since January 1, 1970) when the fragment was created
Field 13 = The device number where the image was written
Field 16 = Expiration time of the image in seconds since January 1, 1970. A value of zero (0) denotes an image in progress or failed.
Field 17 = Multiplexing. 0=multiplexing not used, 1=multiplexing used
Field 18 = Retention level.
0 = 1 week, 4mm cartridge media
1 = 2 weeks, 8mm cartridge media
2 = 3 weeks, 8mm2 cartridge media
3 = 1 month, 8mm3 cartridge media
4 = 2 months, dlt cartridge media
5 = 3 months, dlt2 cartridge media
6 = 6 months, dlt3 cartridge media
7 = 9 months, dtf cartridge media
8 = 1 year, half-inch cartridge media
9-100 = infinite (except 25 which is expire immediately), half-inch cartridge 2 media
Field 20 = Hold. 0=Fragment not on hold, 1=Fragment on hold
Example of the short display format:
# bpimmedia -l -policy regr1_gava -t FULL IMAGE gava 3 gava_0949949902 regr1_gava 0 full 0 3 25 952628302 0 0 FRAG 1 1 10256 512 2 13 13 A00002 plim 65536 0 949616279 0 0 *NULL* 952628302 1
SPANPOOLS REPORT
The Spanpools report has two formats: user (-U option) and short (the default). Both formats list the server name and the pool data for each server. It lists the media IDs for each pool of media that share spanned backup images. When -mediaid appears on the command line, only the server pool and the disk pool that are related to that media ID appear.
If you want to process and use the output of bpimmedia, we recommend that you use the -l option. The output of bpimmedia that uses the -U or -L options may be truncated for the Backup-ID, Policy, and Host columns. The -U or -L options are useful when you want to obtain a quick, more readable view of the NetBackup images on media.
The user (-U) display format looks like the following:
# bpimmedia -spanpools -U Related media pools containing spanned backup images, server plim: Pool: A00002 A00003 Pool: 400032
The short display format looks like the following
# bpimmedia -spanpools SERVER plim POOL A00002 A00003 POOL 400032
EXAMPLES
Example 1 - List the images for policy c_NDMP. This request runs on a NetBackup media server. The report is based on the image catalog on the media server's master server, almond.
# bpimmedia -L -policy c_NDMP Backup-ID Policy Type RL Files C E T PC Expires Copy Frag KB Type Density FNum Off Host DWO MPX Expires MediaID ------------------------------------------------------------------------------------ t_0929653085 c_NDMP FULL 3 5909 N N R 1 15:58 07/18/2012 1 IDX 844 RMed dlt 2 0 almond 3 CB7514 1 1 9136 RMed dlt 1 0 almond 3 N 15:58 07/18/2012 CB7514
Example 2 - Display the tapes that are required to restore a particular file. If the bpimmedia command line provides the criteria to identify an individual backup, the output shows the media that was used for the backup.
In this case, the command line provides the client, the date of the backup and the schedule type. The output shows that tape A00002 on the server plim
contains the backup.
# bpimmedia -L -client gava -d 2/7/2012 -t UBAK Backup-ID Policy Type RL Files C E T PC Expires Copy Frag KB Type Density FNum Off Host DWO MPX Expires MediaID ------------------------------------------------------------------------------------- gava_0949949686 regr1_guav UBAK 3 25 N N R 1 12:54 03/09/2011 1 1 10256 RMed dlt 11 0 plim 0 Y 12:54 03/09/2011 A00002
Example 3 - List in long format all the backups in the image catalog on master server gava
.
# bpimmedia -L -M gava Backup-ID Policy Type RL Files C E T PC Expires Copy Frag KB Type Density FNum Off Host DWO MPX Expires MediaID ------------------------------------------------------------------------------------- gava_0949599942 test-policy FULL 1 15 N N R 1 11:45 02/17/2011 1 1 224 Disk - - - gava - N 11:45 02/17/2011 /var/qatest/storage_unit//gava_0949599942_C1_F1
Example 4 - List in long format the backups on media ID CB7514.
# bpimmedia -L -mediaid CB7514 Backup-ID Policy Type RL Files C E T PC Expires Copy Frag KB Type Density FNum Off Host DWO MPX Expires MediaID -------------------------------------------------------------------------------------- toaster1_0929679294 tort_policy FULL 3 5898 N N R 1 23:14 07/18/2012 1 IDX 839 RMed dlt 4 0 almond 6 CB7514 1 1 27154 RMed dlt 3 0 almond 6 23:14 07/18/2012 CB7514 toaster1_0929653085 NDMP_policy FULL 3 5909 N N R 1 15:58 07/18/2012 1 IDX 844 RMed dlt 2 0 almond 3 CB7514 1 1 9136 RMed dlt 1 0 almond 3 15:58 07/18/2012 CB7514
RETURN VALUES
An exit status of zero (0) means that the command ran successfully.
Any exit status other than zero (0) means that an error occurred.
If the administrative log function is enabled, the exit status is logged in the administrative daily log under the log directory:
UNIX systems: /usr/openv/netbackup/logs/admin
Windows systems: install_path\NetBackup\logs\admin
It has the following form:
bpimmedia: EXIT status = exit status
If an error occurred, a diagnostic precedes this message.
FILES
UNIX systems:
/usr/openv/netbackup/logs/admin/* /usr/openv/netbackup/db/images
Windows systems:
install_path\NetBackup\logs\admin\* install_path\NetBackup\db\images