The onpsm utility for storage management

Use the onpsm utility to manage the Informix® Primary Storage Manager catalogs, devices, locks, and objects.

Pre-requisite: To run the onpsm utility, you must be user root or informix.

Syntax


1  onpsm
1 
2.1  %Catalog options
2.1  %Device options
2.1  %Object options
2.1  %Pool
options
1? 
2.1  -h 
1 
2.1  -V 
2.1   -version
2.1   -version
all
Catalog options

1   -C 
2.1  check
2.2.1  -l 
2.2.1  -n 
2.1 ?  detail 
2.1 ?  export 
2.2.1  import 
2.2.1  -y 
2.1 
2.2.1  init 
2.2.1  init -d 
2.2.1  -y 
2.2.1  unlock
Device options

1   -D 
2.1   add path   -p  priority   -g  pool_name   -t  type?   -s  size
2.1  del path
2.2.1   -g  pool_name
2.2.2.1  -y 
2.2.1   -d 
2.2.2.1  -y 
2.1  list
2.2.1  -u 
2.2.1   -l  dev_def_file.txt
2.1  purge path
2.1  scan path
2.1  update path?   -p  priority?   -s  size
Object options

1   -O  
2.1  del  -o  object_id
2.2.1  -y 
2.1  detail  -o  object_id
2.1  dump  -o  object_id
2.1  list
Pool options

1   P 
2.1  add pool_name
2.1  del pool_name
2.2.1  -y 
2.1  list
Table 1. onpsm utility catalog options
Element Purpose Key Considerations
-C check Checks storage manager catalog tables, which store metadata about the pools and devices that the storage manager manages This command identifies files that have problems.
-C check -l Displays index keys while checking the catalog tables
-C check -n Indicates that the storage manager does not fix errors that are found
-C detail Shows details about the storage manager catalog tables
-C export Exports the Informix® Primary Storage Manager catalog tables to a directory called psm_catalog.exp
-C import Replaces the current Informix® Primary Storage Manager catalog with a catalog that is recreated from files that are in the psm_catalog.exp directory Only import the catalog if you have a system problem, lost your current catalog, and need to revert to the exported catalog. If you need to import a catalog, run the onpsm -C init command before you run the onpsm -C import command.
-C init Deletes storage manager catalog tables
-C init -d Deletes storage manager catalog table and the backup objects in file devices
-C unlock Unlocks the storage manager catalog If the storage manager exits abnormally from a backup or restore session because a failure occurred, storage manager catalog tables might remain locked. If catalog tables are locked, you can release the locks.
-y Specifies to not to ask for confirmation before deleting catalog tables
Table 2. onpsm utility device options
Element Purpose Key Considerations
-D add Adds a device to the pool specified with the -g option Before adding devices, gather information about the device. See Collecting information about file directories and devices.
-D del Removes a device:
  • If you use the -g option, removes a device from the pool specified with the -g option, while retaining the device objects in the Informix® Primary Storage Manager catalog.
  • If you use the -d option, removes the device from all pools and removes all backup objects from the file system in that device
If you delete the device using -g option, you can restore the objects if necessary.

If you remove a device, the storage manager cannot add new objects to the device.
-D list Displays a list of all devices in the system
-D purge Removes missing storage manager objects from the Informix® Primary Storage Manager catalog
-D scan Scans objects in the device to verify that the objects exist in the Informix® Primary Storage Manager catalog so the objects can be restored if necessary

If an object is not in the catalog, this command adds the object to the catalog.

 If the command cannot add an object to the catalog, the command ignores the missing file.
Before a missing object can be added to a catalog, the following conditions must occur:
  • The object ID must not be assigned to any other object in the storage manager.
  • Files must not be renamed or relocated to different directories inside the device
  • The object version must not be assigned to any other object in the storage manager.
-D update Modifies information about a device If you want to modify information about more than one device, run a separate command for each device.
path Full name and path to the device (for TAPE devices) or to a directory (for FILE devices) The path must be in the format appropriate to the operating system to which the device is attached .

The name of the device must be unique within a pool.

You can include the same device in multiple pools.

If you are deleting, listing, purging, scanning, or updating information, the path must be to an existing device.

-d Deletes the pool from all pools and deletes backup objects
-g pool_name The pool in which to add the device, either DBSPOOL, LOG POOL, or EXTPOOL Information about pools is stored in the Informix® Primary Storage Manager catalog.

If you do not provide a pool name, the command fails.

Specify:

  • DBSPOOL for backups of dbspaces, blobspaces, and sbspaces
  • LOGPOOL for backups of logical logs
  • EXTPOOL that serves as a staging area from which you can move specific backups or backup generations to permanent storage or onto a different computer.
-l dev_def_file.txt Loads information about the device from a device-definition file
-p priority Priority of the device, either HIGHEST, HIGH, LOW, or READ-ONLY The storage manager fills high-priority devices in a pool before placing data into low-priority devices in that pool. If the high-priority devices are busy at the moment when the storage manager is ready to fill a pool, the storage manager uses low priority devices.

Only one device in a pool can have the priority of HIGHEST.

If multiple devices have the same priority in the same pool, the storage manager determines which device to use first.

When a device becomes full, the storage manager changes the priority to READ-ONLY. You can change the priority after you add more space to the device.

-s size For tape devices only, the maximum storage capacity of the device in kilobytes The size is optional for tape devices. If a size is not specified, or if you specify 0, the storage manager interprets the size as unlimited. When the size is unlimited, the device is not considered full until it returns an error that specifies that the device is full.

To specify the size enter the numeric value of the size followed by the suffix B, K, M, G, T, or P (for bytes, kilobytes, megabytes, gigabytes, terabytes, or petabytes). The suffix can be upper or lowercase.
- t type Type of device, either FILE or TAPE Information about devices is stored in the Informix® Primary Storage Manager catalog,
-u Unloads information about the device to a device-definition file The device definition file is a text file with a specific format. The storage manager uses the file to recreate the information when you run an onpsm command with the load option.
-y Specifies not to ask for confirmation to complete the requested action
Table 3. onpsm object options
Element Purpose Key Considerations
-O del Deletes physical objects from a pool
-O detail Displays details about the specified object. Details include the location of the object.
-O dump Extracts the object data to a file in the current directory
- o object_id Identifies the particular object You can delete or dump one or more objects with a single command, as shown in Usage.
-O list Displays all objects in a pool For each object, the list includes the date and time the object was created, the size of the object, and the path name of the object.
-y Specifies not to ask for confirmation to complete the requested action.
Table 4. onpsm pool options
Element Purpose Key Considerations
-P add pool_name Adds a new pool
-P del pool_name Deletes the specified pool
-P list Lists all pools in the system
-y Specifies not to ask for confirmation to complete the requested action.
Table 5. onpsm utility general options
Element Purpose Key Considerations
-h Displays help information
-V Displays the software version number and the serial number For more details about the standard -V and -version options, see Obtaining utility version information.
-version Displays the software version number, serial number, and additional information such as the host, operating system, build date, and the Global Language Support (GLS) version For more details about the standard -V and -version options, see Obtaining utility version information.
-version all Displays onpsm version information and information about the PSM shared library

Usage

When you run an onpsm command to define a device, the storage manager automatically creates storage manager catalogs if they do not exist.

The default device for the storage manager is $INFORMIXDIR/backups. The device, which is low priority, is automatically created when the catalog is created. You can remove the default device.

When you create a device, the storage manager automatically creates the directory for the device if the directory does not exist. The storage manager uses the directory path that you specify in the onpsm -D add command.

You can delete one or more objects with a single command, for example, by running a command that has this format:
onpsm _O del -o obj_1 -o obj_2
You can also dump one or more objects with a single command, for example, by running a command that has this format:
onpsm _O dump -o obj_1 -o obj_2

If the data is not needed, run the onsmsync utility to delete backup objects from the Informix® Primary Storage Manager.

Some third-party storage managers do not allow the onsmsync utility to delete backup objects from the storage manager. If you have a third-party storage manager, you might need to manually delete backup objects that you no longer need.

Examples

The following command adds a file device with the path name $INFORMIXDIR/backups in the DBSPOOL pool: 
onpsm -D add $INFORMIXDIR/backups -g DBSPOOL -t FILE  -p HIGH

The following command checks Informix® Primary Storage Manager catalog tables and indicates that the storage manager does not fix any errors found during the check:

onpsm -C check -n

The following command lists objects in pools, including the date and time the object was created, the size of the object, and the path name of the object.

onpsm -O list