Automating Host Group Management > General Utilities
  
Version 10.2.01P10
General Utilities
The utilities contained in this section apply to all host groups and hosts.
• Categorize Host Operating Systems by Platform and Version
• Identifying a Host Group ID
• Move or Copy Clients
• Organize Clients by Attribute
• Move Host Group
• Delete Host Group
• Move Hosts and Remove Host Groups
• Organize Clients into Groups by Backup Server
• Merge Duplicate Backup Clients
Categorize Host Operating Systems by Platform and Version
Host data can be collected from various APTARE IT Analytics products, such as Capacity Manager, Backup Manager, and Virtualization Manager. Data Collectors persist values as they are collected from the subsystems. For a host’s operating system, subsystems supply values (operating system names) in a variety of formats that do not lend themselves to grouping hosts by OS for reports. For example, Red Hat Linux may be represented as RedHat Linux, rhel, or Red Hat Linux. In order to report on hosts in reasonable groupings, database processing references a set of default regular expressions to parse OS names to categorize the collected host OS data by platform and version.
The following sections provide the details for maintaining and customizing the default Host OS categorization:
• Use Regular Expressions to Override or Modify Default Host OS Categorization
• Host OS Categorization Default Settings
• Utility to Update Host OS Categorizations
• Categorize Host Operating Systems On Demand
Use Regular Expressions to Override or Modify Default Host OS Categorization
APTARE IT Analytics supplies a set of regular expressions (Regex) that define the processing used to process the collected Host OS data to glean the platform and version from the text strings.
• The Host OS Categorization Default Settings can be modified using the Utility to Update Host OS Categorizations.
• Data collection automatically processes the Host OS regular expressions and updates the database with the normalized values. If you want to make immediate changes and not wait for the next collection cycle, you can Categorize Host Operating Systems On Demand.
• Regex processing is case-insensitive.
• To learn more about Regular Expressions, reference Oracle’s documentation: Using Regular Expressions.
Host OS Categorization Default Settings
Each row in this table represents a regular expression used to determine a common OS platform and version.
OS Platform Regex
OS Platform
Version Regex
Ignore
Priority
Domain ID
Creation Date
ID
FreeBSD
FreeBSD
\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
1
Solaris
Solaris
\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
2
AIX
AIX
\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
3
Ubuntu
Ubuntu
6.06LTS|8.04LTS|10.04LTS|12.04LTS|14.04LTS|16.04LTS|\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
4
Data ONTAP
Data ONTAP
\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
5
MAC
MAC
Rhapsody Developer Release|Server 1.0|Developer Preview|Public Beta|\d+\.?\d?+
Linux|(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
6
HP-UX|HPUX
HP-UX|
\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
7
CentOS
CentOS
\d+?(/?)\d+?(/?)\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
8
openSUSE|SUSE|SLES
openSUSE
Leap 42.1|\d+\.?\d?+
(64-bit)|(32-bit)|(x86_64)
1
 
15-DEC-15 12.03.33
9
Windows|win
Windows
(\d+?|SERVER|NT|XP|Vista)\s?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
10
Linux
Linux
 
(64-bit)|(32-bit)
0
 
15-DEC-15 12.03.33
11
Red Hat|RedHat|rhel
Red Hat
\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
12
vmnix
vmnix
 
-x86|x86
1
 
15-DEC-15 12.03.33
13
SunOS
SunOS
\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
14
Data Domain
Data Domain
 
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
15
Fedora
Fedora
\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
16
Debian
Debian
\d+\.?\d?+
(64-bit)|(32-bit)
1
 
15-DEC-15 12.03.33
17
Utility to Update Host OS Categorizations
Use this utility to insert new regular expression rules into the database table or to modify existing rules.
Usage
To insert a regular expression row into the database table, use this command:
execute server_group_package.insertCustomerOsNormData(null, 'os_platform_regex', 'os_platform', 'os_version_regex', 'ignore_string', priority, domain_id);
To update values in a regular expression row into the database table, use this command:
execute server_group_package.insertCustomerOsNormData(os_normalization_id, 'os_platform_regex', 'os_platform', 'os_version_regex', 'ignore_string', priority, domain_id);
Where:
os_normalization_id: This value is unique for each Regex row (see Host OS Categorization Default Settings). IDs less than 100000 are system defaults and cannot be removed, but their values can be modified. When inserting a regular expression into the database table, this value must be null because the process assigns this number.
os_platform_regex: These strings are used to match a substring in the collected text to identify the platform. This field cannot be null.
os_platform: This is the value that is saved to the database when the regular expression is encountered in the collected Host OS. This platform value can never be null, however, the version derived from the version regex may be null.
os_version_regex: This is the regular expression used to match a substring in the collected text to identify the version.
ignore_string: These strings are ignored and are treated as irrelevant details when determining the platform or version.
priority: This value indicates precedence: the higher the value, the higher the priority. For example, Red Hat has a higher priority than Linux, which means that a Host OS that contains a Red Hat substring and a Linux substring will result in a Host OS of Red Hat. User-defined regular expressions must have a priority higher than 1 to override system defaults. This field cannot be null.
domain_id: The Domain ID is shipped with a null default value. In multi-tenancy environments, such as Managed Services Providers, the Domain ID can be updated to change the processing for a specific domain/customer.
Note that a Creation Date also is saved in the database table. This is the date and time that the Regex record was created in the database.
Categorize Host Operating Systems On Demand
Use this utility to process hosts to categorize their operating systems without waiting until the next data collection cycle. This utility uses the regular expressions as described in Categorize Host Operating Systems by Platform and Version.
Usage
execute server_group_package.updateExisting HostOsinfo(hostGroupId);
Where:
host_group_id: This is the numeric identifier of a host group. See Identifying a Host Group ID.
 
 
Identifying a Host Group ID
Whenever you want to apply a change to a table in the Reporting Database, you must specify the host group’s ID in your SQL utility. For example, you need to identify host group IDs if you intend to delete a host group through the reporting database or if you want to use PL/SQL utilities. The host group ID that you specify in your SQL statement is very important and determines how the change is applied:
• If you are not an Managed Services Provider (MSP) and you want to apply a change to a specific host group, determine the group ID for that host group. If you want to apply a change to all host groups, choose the host group ID of the top level folder, the root folder. The group ID for the root folder is always 300000.
• If you are an MSP and you want to apply a change to a specific customer, choose the host group ID of that customer’s domain. If you want to apply a change to all customers, choose the group ID of the top-level root folder (ID = 300000).
Find the Host Group ID
To identify the unique identifier associated with a host group, take the following steps in the Portal.
1. Navigate to the Inventory.
2. Click the Host Groups icon to switch the Inventory view.
3. Verify the Host Group column is displayed on the grid, and optionally, use Advanced Filtering to locate the Host Group.
Note: The Host Group column, displayed in the Inventory for the Host Group management view, has sorting disabled to improve portal performance.
4. Hover your mouse over the Host Group folder in which your hosts reside. The Group ID will display in a tooltip.
 
Move or Copy Clients
Description
This utility enables you to move or link large quantities of clients to different host groups. This tool accepts wildcards for the client_name_mask attribute. This utility will first validate the existence or the two group names passed as the first two parameters (see below). If the groups do not exist, the utility return an error.
Usage
execute server_mgmt_pkg.moveOrCopyClients('<source_host_group>', '<destination_host_group>', '<client_name_mask>', <move_or_copy_flag>);
Where:
source_host_group is the full pathname to the source host group, for example /Aptare/Masters/GroupA
destination_host_group is the full pathname to the destination host group.
client_name_mask is a string that can contain wildcards (*). For example, abc* indicates all clients that have an internal_name that starts with abc. To process all clients use the value NULL (which should not be within quotes).
move_or_copy_flag is 0=copy and 1=move.
Organize Clients by Attribute
Description
This groupClientsbyAttributes utility enables you to organize clients within a host group, based on client attributes. This utility will create host groups named for each attribute value, underneath a parent host group, as shown in the following example.
Example of Organizing Clients by Geographical Location:
Create a host group named Geography. This will be the destination group that will be used to organize the clients by location.
Then, create an attribute named Geography.
For a subset of a host group’s clients, set their Geography attribute value to London and for another subset of clients, set their Geography attribute to New York.
Use the following groupClientsbyAttributes utility to organize the clients that have a Geography attribute configured.
execute server_mgmt_pkg.groupClientsbyAttributes(300000, 302398, 1, StringObjectListType(stringObjectType('Geography')));
Where 300000 is the group ID of the root group, Global; 302398 is the ID of the Geography group you just created.
So, for this example, the clients in the Global (source) group are organized into the following host group hierarchy:
 
Additional References:
Usage
execute server_mgmt_pkg.groupClientsbyAttributes(<source_Group_ID>, <destination_group_ID>, <cascade_Source_Group>, StringObjectListType(<attribute_List>));
Where:
source_Group_ID is the numeric identifier of the host group for which you want to group the clients. See Identifying a Host Group ID for the steps for finding a group ID.
destination_group_ID is the numeric identifier of the group under which you want to group the clients.
cascade_Source_Group is a numeric flag that indicates if you want this utility to process the source host group’s sub-groups and organize those clients in the destination group.
attribute_List is a comma-separated list of attribute names, each enclosed in straight single quotes. These names are used to create the sub-groups that organize the clients underneath the source group.
Move Host Group
Description
This utility enables you to move a host group and all of its hierarchical contents to another host group.
Usage
execute server_mgmt_pkg.moveServerGroup('<source_host_group>', '<destination_host_group>');
Where:
source_host_group is the full pathname to the source host group, for example /Aptare/Masters/GroupA. Be sure to use the host group name, not the host group ID.
destination_host_group is the full pathname to the destination host group. Be sure to use the host group name, not the host group ID.
Delete Host Group
Description
There are some occasions where you may wish to remove the entire contents of a host group, including any sub-groups within this group and any clients under the hierarchy. This utility allows administrators to perform this type of delete operation.
 
CAUTION: IF YOU USE THIS COMMAND TO REMOVE A HOST GROUP, AND IF CLIENTS UNDER THE HOST GROUP HIERARCHY DO NOT EXIST IN ANY OTHER GROUP, THE CLIENTS AND ALL OF THEIR ASSOCIATED CONFIGURATIONS WILL BE PERMANENTLY REMOVED FROM THE DATABASE.
Usage
execute server_group_package.deleteEntireGroupContents(100, <parent_group_id>, <group_to_remove_id>);
Where:
parent_group_id is the group id of the parent group which contains the group to be deleted.
group_to_remove_id is the group id of the group to be deleted.
Move Hosts and Remove Host Groups
This process, often referred to as Server Group Cleanup, enables removal of backup server groups that had been created automatically in prior APTARE IT Analytics versions. In addition to cleaning up server groups, this process can also be used on other host groups.
 
Description
Prior versions of IT Analytics automatically created several server/host groups during backup data collection. In certain environments, these auto-generated groups may not be needed, as other host groups are more relevant. This utility can be used to clean up a Portal’s host groups by moving servers/hosts and child host groups from a host group and then deleting the source host group. While this utility, by default, is intended for system-created host groups, it can be used for any host group that you want to delete, but retain its contents.
Note: Once this process completes, log out of the Portal and log back in before accessing host groups and hosts in the Inventory.
Best Practice: In multi-tenancy environments, run this command on a domain-by-domain basis, starting from the bottom of the domain hierarchy to the top IT Analytics domain. This ensures that each domain has been explicitly processed with log messages that confirm the actions taken.
CAUTION: THIS COMMAND MOVES CLIENTS TO THE DOMAIN’S HOME HOST GROUP AND THEN PERMANENTLY REMOVES THE SPECIFIED HOST GROUPS FROM THE DATABASE. RUN THIS COMMAND IN VALIDATE MODE FIRST TO VERIFY THAT THE ACTIONS REPRESENT THE INTENDED RESULTS.
Usage
server_mgmt_pkg.serverGroupCleanup(<processingMode>, '<domain_name>', (<server_group_names_list>), '<log_file_path_name>', '<log_file_name>');
Where:
processing_mode is either 1 = Validate or 2 = Execute. Run this command in Validate mode first to understand what hosts will be moved and what host groups will be deleted.
domain_name, enclosed in single straight quotes, is the case-insensitive name of the IT Analytics domain for the group to be deleted. See the Best Practice listed above.
server_group_names_list is a comma-separated list of host group names to remove, in single straight quotes. This list must be enclosed in parentheses and prefaced with stringListType. If NULL is specified, the utility will process these system-created host groups: NetBackup Policy Types, NetBackup Policies, Inactive Policy Clients, and Policy Domains.
log_file_path_name, enclosed in single straight quotes, is the location of the log file for this process.
log_file_name, enclosed in single straight quotes, is the name of the log file.
 
Example of Validate Mode:
execute server_mgmt_pkg.serverGroupCleanup(1, 'EMEAfinance', stringListType('NetBackup Policy Types','NetBackup Policies','Inactive Policy Clients', 'Policy Domains'), '/tmp', 'serverGrpCleanup.log');
 
Example of Execute Mode:
execute server_mgmt_pkg.serverGroupCleanup(2, 'EMEAfinance', stringListType('NetBackup Policy Types','NetBackup Policies','Inactive Policy Clients', 'Policy Domains'), '/tmp', 'serverGrpCleanup.log');
 
Example of Validate without a list of Host Group Names:
exec server_mgmt_pkg.serverGroupCleanup(1, 'EMEAfinance', NULL, '/tmp', 'serverGrpCleanup.log');
Organize Clients into Groups by Backup Server
This utility can be used for any backup product, such as IBM Spectrum Protect (TSM), Veritas Backup Exec, or HP Data Protector.
Description
This utility enables you to create a hierarchy of servers and links all clients that are members of a server into the respective host group.
For example, in an IBM Spectrum Protect (TSM) environment if you have two IBM Spectrum Protect (TSM) servers called TSM1, TSM2, this utility creates two host groups, TSM1 and TSM2, and links the IBM Spectrum Protect (TSM) server’s clients into the corresponding IBM Spectrum Protect (TSM) host group.
Usage
execute common_package.moveClientsIntoServerGroups( <source_group_id>,<destination_group_id>, <move_or_copy_flag>, <latest_server_only>);
 
Example:
exec common_package.moveClientsIntoServerGroups(300000, 300010, 1, 1), ;
Where:
source_group_id is the internal group ID of the group hierarchy to traverse.
destination_group_id is the group ID in which host groups by management server will be created. APTARE recommends that you create a host group under source_group_id called <vendor_name> Servers and use the group ID of this new host group for the second parameter.
 
When you organize by server, if a host group exists anywhere under the source group hierarchy with the name of that server, the routine associates the clients with that folder and does not create a new folder under the destination folder. This association occurs whether you explicitly specify the destination folder or if the destination is NULL. However, if you pass a source folder that is at a lower level, the routine only checks for a folder under that hierarchy. If you specify NULL as the destination folder, the routine creates a host group under the source_group_id called Master Servers.
move_or_copy_flag can be set to 0=Link (copy) clients or 1=Move clients. If set to 0, the utility links the clients to their respective host groups and keeps the clients in their original group location. If set to 1, the utility moves all clients from the source host group and to their respective host groups.
The utility processes and organizes all clients of the source group hierarchy into the target server grouping. However, if the move_or_copy flag is set to 1, the utility removes only clients in the top level source_group_id group—and does not remove those already organized in lower-level sub-groups.
latest_server_only, when set to 1, indicates the last server to back up the client; otherwise, set this flag to 0.
Merge Duplicate Backup Clients
ADVANCED USE ONLY - Due to the nature of this utility’s processing, if executed incorrectly, backup clients could be incorrectly moved. This process is particularly risky in a multi-tenancy environment, where multiple IT Analytics domains could have hosts/servers with the same name.
This merge utility can be used for clients that have been collected from the following backup products: Veritas NetBackup, EMC NetWorker, and Commvault Simpana.
Description
Under certain circumstances, backup clients may have duplicate entries in the IT Analytics database. This utility enables you to merge the data of clients that appear more than once in the database.
In most cases, it is not necessary to shut down the data receiver while the client records are being merged. Although not required, it is recommended that you shut down the data receiver before executing this utility so that data will not continue to be collected for the hosts that are being merged.
Merging of NetBackup master servers is not supported.
Usage
execute duplicate_package.mergeDuplicateServers(<'host_grp'>,<host_name_type>);
 
Example:
exec duplicate_package.mergeDuplicateServers('/Corp',1);
 
Where:
host_grp is the explicit host group path and name.
host_name_type indicates whether to use only the host’s base name while finding duplicates, or use the fully qualified name. 0 = fully qualified host name, 1 = host base name.
 
Example of a host base name: QAhost1
Example of a fully qualified host name: QAhost1.yourcompany.com