Best Practices for creating client alias relationships for image browse and restore

Best Practices for creating client alias relationships for image browse and restore

Article: 100009879
Last Published: 2020-10-23
Ratings: 1 0
Product(s): Appliances, NetBackup


Backup images are always stored using the client name configured in the policy at the time of the backup.   If two hostnames [or variations of the same hostname] for the same host are configured as clients in policies, then the backup images are stored using the respective hostname as the client name.


Prior to NetBackup 7.5, image browse and restore had to be performed using the client name that was used to perform the backup or the operation either failed with status 227 or return images other than the ones that are expected. Creative administrators also discovered that they could manually merge the images sub-directory of the second hostname into the images sub-directory of the first hostname and replace the second sub-directory contents with either a symbolic link (UNIX/Linux) or ALTPATH file (Windows) to the first sub-directory.   This allowed backups using either hostname to be stored in the images sub-directory for the first hostname and image browse and restore using either hostname could access all of the images.


NetBackup 7.5 and later will migrate the image header files from the image sub-directories into the Sybase NBDB, but leave the image files files in the directory structure. Image searches only look at the contents of NBDB and do not automatically benefit from the manually created symbolic links or ALTPATH files.   As a result, some browse and restore requests may fail with status 227 or return images other than the ones that are expected.

Is it possible to configure NetBackup 7.5 and later to allow the same backup images to be browsed using more than one client name?  

Yes, by using the client alias feature.



The different aspects of the client alias feature are covered in the following sections.

  • Introduction and Limitations
  • Implementation in NetBackup 7.5GA
  • Enhancements in NetBackup / 7.6 GA
  • Administration using the bpclient command
  • Best practices for client aliases
  • Creating a client alias from an existing client (merging image directories)
  • Troubleshooting tips

Note: These best practices and procedures are applicable for NetBackup versions 7.7.x, 8.0, 8.1.x and 8.2.


Introduction and Limitations

During a backup, the client name from the policy will be associated with the image information within NBDB. The symbolic link or ALTPATH file [or lack thereof] will be used to determine where the image files files are stored. This behavior is the same as pre-7.5.

For image browse and restore, NetBackup 7.5 introduced the client alias feature for accessing backup images. This feature associates aliases with known client names. The feature allows the browse or restore to use either the client name or any of the aliases when searching for the backup images. This is useful when:

  • backups were taken using both the shortname and the fully qualified domain name (FQDN)
  • backups were taken using FQDNs first in one domain and then after the host was moved to a second domain
  • backups were run using hostnames for multiple sub-interfaces on the same single host
  • backups were run using the virtual hostnames for multiple nodes in an active/active cluster and the restore needs to be node independent; i.e. Oracle RAC or DB2 EEE.
  • backups were run while the wrong hostname for the client was configured in the backup policy


Note: Each client name specified within a backup policy for a hostname must still be resolvable to an IP address and network routable in order to perform a successful backup.   The same is true of the destination client name during a restore operation.   Aliases that are used purely for image browse do not need to be resolvable or routable.

Also, the NetBackup client alias feature does not detect, modify, or remove any NTFS Junctions or NTFS Symbolic Links on Windows operating systems.   ALTPATH files existed prior to these NTFS extensions and continue to be the supported method of relocating portions of the NetBackup image database as needed.


Implementation in NetBackup 7.5GA

The NetBackup 7.5 implementation has several parts.

A. As part of the upgrade, the image header migration automatically creates client aliases for any previously existing, manually created symbolic links or ALTPATH files.

The migration scans the images database

UNIX/Linux: /usr/openv/netbackup/db/images
Windows:     <install>\NetBackup\db\images

If a sub-directory has been replaced with a symbolic link (UNIX/Linux) or contains an ALTPATH files (Windows) that references another sub-directory within the images database, then a client aliases is created in the NBDB.   The alias name uses the client name represented by the link or ALTPATH.   The alias is associated to the client name that the link or ALTPATH references.

Note: Does not detect junctions to existing directories on Windows.


B. When a backup is run for a client, a similar check is made for the existence of a symbolic link or ALTPATH file.  

If one exists a client alias is attempted to be created.   If this is a new unknown name for a client, there won’t be any conflicts and the operation will be successful.

If backups were previously run for this client and an images sub-directory already exists, the client name will remain independent without alias.

If backups were previously run but the images sub-directory has been replaced with a symbolic link or ALTPATH file, there will be a conflict.   The bpdbm Q_IMAGE_UPDATE processing will fail with status 227 because the alias already is known as a client.  


13:54:47.837 [15521] <16> ImageUpdate::executeQuery: Failed to get image key: client = myalias backupTime = 1354053286 viewID = 0 policy = mypolicy scheduleType = 0

13:54:47.837 [15521] <16> ImageUpdate::executeQuery: error updating image (227)

This issue is resolve in NetBackup   See “Creating a Client Alias from an Existing Client”.

C. The bpclient command has been enhanced to allow client aliases to be managed by the administrator.

D. Other considerations

Note: Manual intervention is required to resolve conflicts when either a new alias to be added conflicts with existing images database sub-directories, or a newly detected symbolic link or ALTPATH file conflicts with existing client name and/or client alias configuration.   See below for methods to resolve conflicts.

Note: In the default configuration, client aliases are independent of network hostname aliases.   See ‘bpclient -add_all_aliases’ for a method of creating client aliases from network hostname aliases and other sources.


Enhancements in NetBackup / 7.6GA

The NetBackup maintenance update implements several improvements to the client alias feature.


A. When bpclient is used to add a client alias, the symbolic link or ALTPATH file is automatically created if image files do not exist in the images database directory tree.

Note: Manual intervention is still needed if the alias has previously been used as a client name, and an image sub-directory already exists for the alias, and the sub-directory contains valid image files.   See "Creating a Client Alias from an Existing Client".

B. If a symbolic link or ALTPATH file is detected, a client alias will automatically be created (like before) and (this is new) any existing backup image records in the NBDB will be updated.


Administration using the bpclient command

The bpclient command allows client aliases to be managed by the NetBackup administrator.


  • To add a client alias for a client name.

    bpclient -client client_name [-M master_server]
         -add_alias alias_name

    This will associate ‘alias_name’ with ‘client_name’ within the NBDB.

    Note: Starting with NetBackup, the appropriate symbolic link or ALTPATH file will also be created. Prior to NetBackup, the symbolic link or ALTPATH file is not automatically created, they must be created manually.   Always use absolute pathnames for the target directory during manual configuration.

    $ cd /usr/openv/netbackup/db/images
    $ ln -s /usr/openv/netbackup/db/images/myclient \

    > cd <install>\NetBackup\db\images
    > mkdir myalias
    > cd myalias
    > echo <install>\NetBackup\db\images\myclient > ALTPATH

    The client must already be known or the command will fail.

    $ bpclient -client myclient-misspelled -add_alias myalias
    bpclient: no entity was found (227)

    An error will result if the alias already exists as an alias for another client, or already exists as a unique client, or already has an sub-directory in the images database, or already has a symbolic link or ALTPATH file.

    $ bpclient -client myclient -add_alias mybadalias
    bpclient: invalid command parameter (20)

    Prior to NetBackup, an error will result if an client name previously used for backups (oldclient) is attempted to be added as an alias for a different client (newclient), after replacing the images sub-directory for oldclient with a symbolic link or ALTPATH file referencing the images sub-directory for newclient.

    $ bpclient –client newclient –add_alias oldclient
    bpclient: the entity already exists (226)
  • To display the client aliases within the NetBackup configuration.

    bpclient -client client_or_alias_name [-M master_server]

    Note: The first name displayed is not always the client name   The output is the same even if ‘myclient’ is replaced with ‘myalias’.   See the Supplemental Materials.

    $ bpclient -client myclient -list_all_aliases

    The output only reflects the configuration within NBDB.   Manually review the images database sub-directories to confirm that the related symbolic links or ALTPATH files are in place.
  • To delete an existing client alias for a client name.

    First, disassociate ‘alias_name’ from ‘client name’ in the NBDB.

    bpclient -client client_name [-M master_server]
         -delete_alias alias_name

    It may take several tries to determine which name in the –list_all_aliases output is the client from which to delete the alias.   This example uses the –list_all_aliases output from above.

    $ bpclient -client -delete_alias
    bpclient: no entity was found (227)
    $ bpclient -client myalias -delete_alias
    bpclient: Cannot delete the primary alias for a client
    $ bpclient -client myclient -delete_alias

    Optionally, manually remove the symbolic link or ALTPATH file and directory. If left in place, the client alias will be automatically re-established if a new backup is taken.  

    UNIX/Linux$ rm /usr/openv/netbackup/db/images/myalias

    Windows> del <install>\NetBackup\db\images\myalias\altpath
    Windows> rmdir <install>\NetBacukp\db\images\myalias

    Optionally, remove the alias from all policies, or deactivate those policies. If left in place, the next backup using the alias name as a client name will either re-establish the client alias relationship as noted above or cause the alias name to become an actual client name.

    NetBackup does not automatically perform the two prior steps because the operational needs of each client may vary, especially with clustered applications.

    Note that deleting an alias does not cause the expiration of the backup images that were previously created by policies configured with the alias. It only prevents image browse using that alias. The images may continue to be browsed using the client name or other aliases.

    Manual image expiration can be challenging if a hostname is switched from an alias name to a client name and back to an alias name (or the reverse).   This is because the current client name may not match the backup ID at the time of the backup.   If this command fails to expire the image

    bpexpdate –recalculate –d 0 –client {myclient | myalias }

    One of these commands will be successful

    bpexpdate –d 0 –backupid myclient_<ctime_of_backup>
    bpexpdate –d 0 –backupid myalias_<ctime_of_backup>
  • To add all client aliases for many hostnames that could potentially be associated with the client name.

    bpclient -client client_name [-M master_server]

    This option constructs client aliases for ‘client_name’ from many sources:


- symbolic links or ALTPATH files that reference 'client_name'

- hostname aliases return by the name services for 'client_name'

- the shortname if 'client_name' is a FQDN

- the domain names from other settings in the bp.conf or registry if 'client_name' is a shortname, i.e. servers, client name, cluster name, required interface

- hostname aliases returned by the name services for the newly created aliases in the prior bullets


Note: Some of the created aliases may not be appropriate.   Always review the results and delete those aliases that are not appropriate.   Also manually removing any symbolic links or ALTPATH files that should not have been created.


  • To delete all aliases for a client name.

    bpclient -client <client_name> [-M master_server]

    Note: See –delete_alias above for details and additional recommended steps.
  • To automatically add all aliases when NetBackup creates a client alias.

    Change this configuration setting from 'NO' to 'YES'.


    echo AUTO_ADD_ALL_ALIASES_FOR_CLIENT=YES | bpsetconfig

    Caution: See the Note in the add_all_aliases section above.



Best Practices for Client Aliases and Similar Implementations


A. After creating or deleting client aliases, always review the NetBackup images database sub-directories to confirm that the appropriate symbolic links or ALTPATH files exist.   NetBackup detects many unusual situations and tries to react or report appropriately, but there may be rare environments with unexpected situations.   Please report them to NetBackup support for future enhancement consideration.

B. Some sites manually create symbolic links or ALTPATH files to images sub-directories where the latter (target) sub-directory name is not used as a client in any policy and therefore does not have any image records in the NBDB.   This allows backups from several clients [in a cluster] to be stored into the target sub-directory.

Because the target sub-directory name is not an actual NetBackup client, a client alias cannot be created.

Note: The target sub-directory will be deleted by image cleanup processing if it remains empty or becomes empty due to image expiration.   Subsequent backups will fail since the symbolic links or ALTPATH files reference a non-existent directory.   This can be prevented by running a small backup using the target sub-directory name as a client, with infinite retention, before creating the symbolic links or ALTPATH files.

C. See the following procedure for how to merge independent clients into a client alias relationship.


Creating a Client Alias from an Existing Client

(Merging Images Database Sub-directories)


If backups of the same host have occurred using multiple client names, then the backup images will be stored under multiple images sub-directories.   For operational convenience or necessity, it is possible to merge the backup images of two or more clients and set up client alias relationships.   The following procedure can be used to accomplish that goal safely and successfully.


All steps are performed on the master server, in this progression:

  • Compare the desired and exiting configurations
  • Perform the pre-merge requirements
  • Merge the alias into the client
  • Validate the merge and resume backups


Caution: Do not make changes until instructed in step 9!

Caution: Once complete, using ‘-client myclient’ or ‘-client myalias’ to change retention will affect all the images backed up by either myclient or myalias.

Compare the desired and existing configurations


  1. Design the client alias relationships that are needed.   A client name can have many alias names, but an alias name can be associated with only one client name.

Which client name should be used to store the backup images?

Which alias names can be used to create or retrieve the backup images?

Which client or alias names should no longer be used after this merge?


  2. Review the current images database.

UNIX/Linux: /usr/openv/netbackup/db/images
Windows:     <install>\NetBackup\db\images

  • Is there a sub-directory for the client name?

  • Is there a sub-directory for any of the alias names?

  • Is there a symbolic link or ALTPATH file for the client name?

  • What sub-directory does it reference?

  • Is there a symbolic link or ALTPATH file for each of the alias names?

  • What sub-directory does each reference?

  • Are there symbolic links or ALTPATH files for other names that reference the client name or alias names?

Make a note of each and the sub-directory that it references.

Return to step 1 if new client or alias names are discovered.


  3. Check that there aren’t any potential conflicts between backup images, created at the same second, for the various clients to be merged.

The resulting merged image directory tree might contain multiple images with the same backup ctime.  If two images have the same backup time, some parts of NetBackup which expect the ctime to be unique, may not be able to tell the two images apart after they are relocated under the same client name.

This situation might arise two ways.  

  • When merging client images that were replicated from a second master server that took a backup at the same second.
  • When merging client images that were created by a Netbackup 8.2+ master that can initiate backups for multiple clients during the same second.

This determination requires an input file containing all of the image files files for the prospective client names that will be merged.  E.g.

$ cd /usr/openv/netbackup/db/images
$ find client1 client2 -type f -name '*.f' > image_files_file_names

> cd <install_path>\NetBackup\db\images
> dir /s /b client1 client2 > image_files_file_names

A conflict may be present if any two files files, to be merge, have the same ctime and view ID.  The ctime is the 10 digit value between the policy name and the schedule type.  There may be an optional view ID present after the schedule type.  In this example the top and bottom images will likely cause a problem, as will the second and third.


The list of files can be quickly processed on a UNIX/Linux host.  Use of the following commands and regular expressions will display any potential conflicts.

  • Removes trailing carriage return characters; in case the file was transferred from Windows.
  • Extract the ctime and view ID pairs.
  • Sorts the lines and counts the images for each unique pair.
  • Sort the counts, highest at the top of the output.
  • Anything >1 is a potential problem.

$ cat image_files_file_names | tr -d '\015' | sed -e 's,^.*_\([0-9]\{10\}\)_[A-Z][A-Z][A-Z][A-Z]\(_[0-9]\{1\,8\}\)\{0\,1\}\.f$,\1 \2,' | sort | uniq -c | sort -n -r | less

Output for the example files above shows there are two pairs of images with duplicate backup ctime and viewID; 1552938472 and 1552928591.

      2 1552938472 _48
      2 1552928591
      1 1553287318 _8412350
      1 1492698906

If any duplicates are present, please request assistance from NetBackup Technical Services.  Reference the Internal Notes for this article and E-Track 4011059.


  4. Review the current client alias configuration.

For the client name and each alias name from steps 1 and 2, run this command.

bpclient -client <client_or_alias> -list_all_aliases


Note any unexpected aliases for specific client names that will need to be removed.

Return to step 1 if any new client or alias names are displayed.


  5. Review the current policy configuration.

Note the policies that are not using a correct client name or alias name.


  6. Determine which changes to make based on steps 2 - 5.

  • Which existing client aliases need to be deleted?
  • Which images sub-directory will remain for the client name?


  • Which images sub-directory will be renamed to become the one for the client name?
  • Which images sub-directories need to be merged into the one for client name?
  • Which images sub-directories for current client names will be empty and removed after the merge
  • Which images symbolic links or ALTPATH files (and directories) need to be deleted because they do not reference the images sub-directory for the correct client name?
  • Which image symbolic links or ALTPATH files (and directories) need to be created to reference the images sub-directory for the client name?
  • Which clients in which policies need to be changed or removed?


Perform the pre-merge requirements

  7. Ensure the master server is NetBackup or higher.

Follow all recommended upgrade procedures if needed.

  8. Determine when to perform the merge.

The backup images for the client and alias names must not be modified, by other NetBackup processing, during the merge.   Plan a time when backup and SLP operations for those clients and images can be deactivated.   Image cleanup will also need to be disabled.   Plan accordingly.

  9. Run a full Catalog Backup on the master server before proceeding.

  10. Deactivate any policies and SLP operations from operating on images for the client and alias names.

11. Check if this touch file exists.

UNIX:     /usr/openv/netbackup/bin/NOexpire

Windows: <install>\NetBackup\bin\NOexpire

If not, temporarily create it as an empty file to prevent image cleanup from running while the modifications are made.   Be sure that Windows does not add a '.txt' or other suffix to the file name.

It is not necessary to stop and restart NetBackup, bpdbm will detect the file in real time.

07:35:39.196 [20394] <4> ImageDelete::ImageDelete: Cleanup running in background, pid=20394
07:35:39.197 [20394] <8> ImageDelete::ImageDelete: NOT EXPIR ING/COMPRESSING/PRUNING IMAGES: /usr/openv/netbackup/bin/NOexpire exists!


12. Confirm all backup and SLP operations for these clients and aliases have completed, or cancel the jobs.


13. Confirm all image cleanup operations have completed, or cancel the jobs.

14. Capture a list of the backup images for the client name and also the prospective alias name.

bpimagelist -client myclient –idonly > bpimagelist-myclient-before
bpimagelist –client myalias –idonly > bpimagelist-myalias-before

Merge the alias into the client

15. Use the bpclient command to delete any client aliases that either should not exist or that do not have a correct symbolic link or ALTPATH file.

Note: An alias that was previously used as a client for backups and has an images sub-directory will fail to delete.   This is expected.


16. Delete any symbolic links or ALTPATH files (and parent directory) that do not match the results from step 14.

17. Optionally, rename any images sub-directory that is to become the correct client name sub-directory.

18. Move any image files from sub-directories that are to become alias names, into the sub-directory for the client name.

Preserve the sub-directory structure when moving the files and/or sub-directories.

Move the STREAMS* files.   Each file is unique to a client and policy so there should not be any collisions unless a single policy previously contained two client names for the same host.   If needed, correct the client list in the policy and move (and thus preserve) only the most recent STREAMS* file.

Move the files in each <ctime000000> sub-directories, including those in the catstore and tmp sub-directories.   Be sure that the files are placed into the same <ctime000000> sub-directory under the target client name as the alias name from which they originated.


19. Delete the images sub-directories once the files have been moved out so that they can be replaced with an alias.

Note: ‘bpclient –client myclient –add_alias myalias’ will fail if the images sub-directory exists.   It is the lack of a sub-directory that allows NetBackup to delete ‘myalias’ as a client from NBDB and change ‘myalias’ to reference ‘myclient’.


20. Use the bpclient command to add any missing client aliases.

bpclient -client myclient -add_alias myalias

21. Use the bpclient command to confirm that all the correct client aliases exist.

bpclient -client <each_client> -list_all_aliases

22. Review the images directory and confirm that all of the correct symbolic links or ALTPATH files have been created.   If not, create them manually per the –add_alias section above.

Validate the merge and resume backups

23. Confirm that the existing backup images from step 14 are accessible using each client and alias name.

bpimagelist -client <each_client_or_alias> -idonly

Note: The output shows the time of each backup and the backup ID. The latter identifies the policy client that was used for the backup.   The output should be the same for each client and its client aliases.


24. Re-activate any policies and SLPs that were disabled in step 10.

25. If the NOexpire touch file was created in step 11, remove it now.   If it was previously in place for other reasons, leave it in place until those reasons are no longer valid.


Troubleshooting Tips

It is always useful to collect the nbdb_unload when debugging client aliases.   Review the DBM_Client and DBM_ClientAlias table contents.

Once upgraded to NetBackup, it is not necessary to request custom SQL to resolve client alias problems.   Simply create the necessary symbolic links or ALTPATH files to match the DBM_Client and DBM_ClientAlias tables.

Then configure the name resolution to match, where the client is the primary hostname and the aliases are secondary hostnames to the primary.   Thereafter the bpclient command options to –add_alias and –delete_alias will work.



Etrack : 3023360 Etrack : 2380117 Etrack : 3293920

Was this content helpful?