HP-UX CMGR A.02.01 Administrator's and
Developer's Guide
HP-UX 11i Version 3
Table of contents
Preface ............................................................................................................................................... 3
Intended Audience ........................................................................................................................... 3
Document Organization .................................................................................................................... 3
Typographic Conventions.................................................................................................................. 3
Related Information .......................................................................................................................... 4
Publishing History............................................................................................................................. 4
1 Introduction ...................................................................................................................................... 5
1.1 CMGR Architecture .................................................................................................................... 5
1.2 Features and Benefits .................................................................................................................. 6
1.3 Installing CMGR ........................................................................................................................ 6
2 Building a Template .......................................................................................................................... 8
2.1 Structure Elements ...................................................................................................................... 8
2.1.1 The template Element ........................................................................................................... 8
2.1.2 The head Element ................................................................................................................ 8
2.1.3 The prologue Element .......................................................................................................... 9
2.1.4 The body Element ................................................................................................................ 9
2.2 Configuration Elements ............................................................................................................. 10
2.2.1 The admin Element ............................................................................................................ 10
2.2.2 The commands Element ...................................................................................................... 11
2.2.3 The compartment Element ................................................................................................... 12
2.2.4 The ipaddress Element ....................................................................................................... 13
2.2.5 The ipfilter Element ............................................................................................................ 15
2.2.6 The ipsec Element .............................................................................................................. 16
2.2.7 The login Element .............................................................................................................. 17
2.2.8 The prm Element................................................................................................................ 18
2.2.9 The provision Element ........................................................................................................ 19
2.2.10 Using meta-tags .............................................................................................................. 20
2.3 Processing/Operational Elements .............................................................................................. 21
2.3.1 The data Element ............................................................................................................... 21
2.3.2 The var Element................................................................................................................. 21
2.3.3 The cst_version Element ...................................................................................................... 24
2.3.4 The description Element ...................................................................................................... 24
2.3.5 The failure Element ............................................................................................................ 24
2.3.6 The group Element ............................................................................................................. 24
2.3.7 The help Element ............................................................................................................... 24
2.3.8 The repeat Element ............................................................................................................ 25
2.3.9 The success Element ........................................................................................................... 25
2.3.10 The template_version Element ........................................................................................... 25
2.3.11 The xi:include Element ..................................................................................................... 25
2.4 Common Attributes ................................................................................................................... 26
2.5 Example: Building a Template ................................................................................................... 26
3 Developing a CMGR Plug-in ............................................................................................................ 32
3.1 Developing an Element Handler ................................................................................................. 32
3.2 Developing a Variable Validation Function ................................................................................. 33
3.3 Example Plug-in ....................................................................................................................... 34
4 Invoking cmgr to Configure Services ................................................................................................. 39
2
Preface
This document describes how to create new and modify existing security templates for HP-UX 11i v3.
Intended Audience
This guide is written for the following audience:
•
•
HP-UX developers and integrators that create or modify CMGR templates. These users must
be knowledgeable in configuring the subsystems used by their templates and should be
familiar with XML.
System administrators that apply CMGR templates to HP-UX systems. These users must be
familiar with general HP-UX administration. Chapter 1 and Chapter 4 will be of particular
interest to these users.
Document Organization
This document addresses the following topics:
chapter 1
Introduction to the HP-UX Configuration Synchronization Manager (CMGR).
chapter 2
Building a template.
chapter 3
Developing a new element handler and a new variable validation function for
CMGR.
chapter 4
Invoking the cmgr command to configure services.
Typographic Conventions
This document uses the following typographical conventions:
%, $, or #
A percent sign represents the C shell system prompt. A dollar sign represents the
system prompt for the Bourne, Korn, and POSIX shells. A number sign represents
the superuser prompt.
audit(5)
A manpage. The manpage name is audit, and it is located in Section 5.
Command
Computer
output
A command name or qualified command phrase.
Text displayed by the computer.
Ctrl+x
A key sequence. A sequence such as Ctrl+x indicates that you must hold down
the key labeled Ctrl while you press another key or mouse button.
ENVIRONMENT
VARIABLE
The name of an environment variable, for example, PATH.
ERROR NAME
The name of an error, usually returned in the errno variable.
Key
The name of a keyboard key. Return and Enter both refer to the same key.
Term
User input
The defined use of an important word or phrase.
Commands and other text that you type.
Variable
The name of a placeholder in a command, function, or other syntax display that
you replace with an actual value.
[]
The contents are optional in syntax. If the contents are a list separated by |, you
must choose one of the items.
{}
The contents are required in syntax. If the contents are a list separated by |, you
must choose one of the items.
...
The preceding element can be repeated an arbitrary number of times.
3
⋮
|
Indicates the continuation of a code example.
Separates items in a list of choices.
WARNING
A warning calls attention to important information that if not understood or
followed will result in personal injury or nonrecoverable system problems.
CAUTION
A caution calls attention to important information that if not understood or
followed will result in data loss, data corruption, or damage to hardware or
software.
IMPORTANT
This alert provides essential information to explain a concept or to complete a
task
NOTE
A note contains additional information to emphasize or supplement important
points of the main text.
Related Information
For more information about the products and subsystems used with CMGR, see the following
documentation:
http://docs.hp.com
In particular, the following documents are available:
• HP-UX Security Containment and Role-Based Access Control (RBAC) documented in the HP-UX
System Administrator's Guide: Security Management: HP-UX 11i Version 3, available at:
http://docs.hp.com/en/oshpux11iv3.html#System%20Administration
• HP Process Resource Manager (PRM) documentation is available at
http://docs.hp.com/en/ha.html#PRM%20%28process%20resource%20manager%29
• HP-UX IPFilter documentation is available at http://docs.hp.com/en/internet.html#IPFilter
• HP-UX IPSec documentation is available at http://docs.hp.com/en/internet.html#IPSec
Publishing History
The document printing date and part number indicate the document’s current edition. The printing
date will change when a new edition is printed. Minor changes may be made at reprint without
changing the printing date. The document part number will change when extensive changes are
made. Document updates may be issued between editions to correct errors or document product
changes. To ensure that you receive the updated or new editions, you should subscribe to the
appropriate product support service. See your HP sales representative for details. You can find the
latest version of this document on line at:
http://www.docs.hp.com.
4
December 2009
Part Number 5992-5171
• Added the admin and login elements (see 2.2 Configuration
Elements)
• Removed the Installing CMGR chapter and added the 1.3
Installing CMGR section.
• Updated the various examples.
November 2008
Part Number 5992-5376
First Edition
1 Introduction
The HP-UX Configuration Synchronization Manager (CMGR) includes the cmgr tool and libraries.
CMGR tracks specific changes made to configuration files. It can track multiple changes applied to
one configuration file (service) or it can track individual changes to multiple files (services). CMGR
associates changes made to a file with labels and uses the labels to trace and display the changes
that it made to the configuration files.
The cmgr command is a general purpose tool that coordinates the configuration of multiple
subsystems, such as HP-UX compartments, Process Resource management (PRM), IPFilter, and IPSec.
Related configuration changes can be added, viewed, replaced, or deleted as a set.
The cmgr command line arguments are combined with XML based CMGR synchronization templates
that define the actual configuration operations to perform. A synchronization template is an XML file
that uses variables to share configuration information between utilities.
This guide describes how to use the cmgr command and how to create synchronization templates.
1.1 CMGR Architecture
Figure 1.1 depicts the CMGR architecture. Once the administrator invokes the cmgr command, the
selected templates pass the configuration instructions to cmgr. In turn, cmgr calls the appropriate
handler library to modify a configuration file or execute a system command. Each element in a
template has a corresponding handler.
5
Figure 1.1: HP-UX CMGR Architecture
1.2 Features and Benefits
CMGR
•
•
•
•
•
has the following features and benefits:
Manages and tracks specific configuration changes for a subsystem or application.
Associate configuration changes across multiple subsystems and applications.
Provides configuration life-cycle interface (add, delete, replace, list).
User defined, XML based templates for defining and associating configuration actions.
Plug-in architecture to allow you to add configuration management of additional subsystems
and applications.
1.3 Installing CMGR
The HP-UX Configuration Synchronization Manager (cmgr) is part of the HP-UX-SRP bundle. The HPUX-SRP bundle consists of two products: CMGR and SRP. The CMGR product includes the CMGR
6
runtime commands and libraries. The SRP product includes the SRP application templates and setup
scripts. You can install the HP-UX-SRP bundle with both products, or you can install the CMGR product
only.
For system and environment requirements, refer to the HP-UX SRP A.02.01 Release Notes. You can
acquire and install HP-UX Secure Resource Partitions free of charge from Software Depot:
http://www.software.hp.com
7
2 Building a Template
You can use the CMGR templates with the cmgr command to coordinate the configuration of
subsystems and services. A CMGR template is an XML document used to describe a set of
configuration actions to perform for the add, delete, replace, list, and help operations of the cmgr
command. The CMGR template syntax is enforced via the Document Type Definition (DTD) schema
file. In addition to XML elements and attributes, a CMGR template can contain variables that are
dynamically evaluated by the cmgr command during processing. While processing the template, the
cmgr command logically replaces the occurrences of variables with the user provided (or default)
values.
The cmgr command provides handler routines for each element type defined in this section. The
cmgr command can support additional element types if you provide new handler routines.
The cmgr command processes the elements in the order that they appear in the document. The child
elements are processed before the parent elements.
The section describes the following:
•
•
•
•
•
2.1
2.2
2.3
2.4
2.5
Structure Elements
Configuration Elements
Processing/Operational Elements
Common Attributes
Example: Building a Template
2.1 Structure Elements
The CMGR template structure elements are grouping elements. They define the structure of your
template and include the following elements: template, head, prologue, and body.
This section describes each structure elements and lists their possible child elements:
•
•
•
•
2.1.1
2.1.2
2.1.3
2.1.4
The
The
The
The
template Element
head Element
prologue Element
body Element
NOTE: You can not include any attributes in the structure elements.
2.1.1 The template Element
The template element is required. It is the highest level element in the CMGR template. The
template element can have the following child elements:
Child Element Description
Head
Required
prologue
Optional
Body
Required
2.1.2 The head Element
The head element is required. We recommended that you use the head element to group elements
that must be processed when cmgr is first invoked. For example, include the default values for your
8
variables in this section before the command gets executed. The head element can have the following
child elements:
Child Element
Description
All configuration elements (See2.2
Configuration Elements)
Optional.
All processing elements (See 2.3
Processing/Operational Elements)
Optional.
Title
Optional. Only available with the head element.
description
Optional. Only available with the head element.
cst_version
Optional. Only available with the head element.
If the cst_version option is specified, cmgr checks to ensure
that it supports the listed version. If cmgr does not support the
specified version, it exits with an error and does not process the
template.
template_version
Optional. Only available with the head element. The current
version number is 1.0
2.1.3 The prologue Element
The prologue element is optional. After the head element is proccessed, the command line input is
read. The prologue element is then processed. We recommended that you use the prologue
element to group elements that cause the collection and validation of user input ahead of any actual
processing that will affect the system state.
The prologue element can have the following child elements:
Child Element
Description
All configuration elements (See2.2 Configuration Elements)
Optional
All processing elements (See 2.3 Processing/Operational Elements) Optional
2.1.4 The body Element
The body element is required. We recommended that you use the body element to group elements
that perform the actual confirmation changes for the template.
The body element can have the following child elements:
Child Element
Description
All configuration elements (See2.2 Configuration Elements)
Optional
All processing elements (See 2.3 Processing/Operational Elements) Optional
9
2.2 Configuration Elements
The CMGR template configuration elements configure various configuration files. They include the
following elements: commands, compartment, ipaddress, ipfilter, ipsec, prm, and
provision.
This section describes each configuration element and lists their possible child elements and attributes:
•
•
•
•
•
•
•
•
•
2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.2.7
2.2.8
2.2.9
The
The
The
The
The
The
The
The
The
admin Element
commands Element
compartment Element
ipaddress Element
ipfilter Element
ipsec Element
login Element
prm Element
provision Element
Each configuration element uses meta-tags to mark configuration changes. See 2.2.10 Using metatags for more information on meta-tags.
The configuration elements can have the following child elements:
Child Element Description
Data
Optional
Help
Optional
Success
Optional
Failure
Optional
See 2.3 Processing/Operational Elements for more information on these child elements.
2.2.1 The admin Element
The admin element manages the RBAC compartment administrator role. Upon invocation, the admin
element handler checks the selected operation from the cmgr command and performs one of the
following tasks:
Operation Description
10
add
Creates the RBAC compartment administrator role, SRPadmin-$compartment, and
assigns users and groups to the role. Creates the hpux.SRPadmin.$compartment
authorization for the srp_rc command in the /etc/rbac/cmd_priv file, and
associates the role with the authorization.
delete
Un-assigns users and groups from the RBAC administrator role. Deletes the RBAC role,
the RBAC hpux.SRPadmin.$compartment authorization, and the associated
srp_rc entry in the /etc/rbac/cmd_priv file.
replace
Un-assigns then assigns users and groups to the RBAC administrator role by performing
Operation Description
a set of actions equivalent to a delete followed by an add operation.
list
Lists the RBAC administrator role associated with the admin user, the RBAC
authorizations for the compartment, and the command privileges.
export
Exports users and groups associated with the RBAC administrator role. Adds the users
and groups configured for the RBAC administrator role to an XML file
(exchange.xml) in the exchange file, which is an archive file. The export operation
updates the XPath /cmgr/body/admins/admin in the exchange.xml file.
import
Imports the users and groups and associates them with the RBAC administrator role.
The users and groups are extracted from the exchange.xml file in the exchange file
archive. The import operation reads the XPath /cmgr/body/admins/admin in the
exchange.xml file.
The ipaddress element can have the following attributes:
Attribute
Description
compartment Optional. Common attribute. Defaults to the value of the $compartment variable.
Id
Optional. Common attribute.
If
Optional. Common attribute.
if_op
Optional. Common attribute.
Role
The RBAC administrator role for the compartment. Default is SRPadmin$compartment.
User
A comma separated list of users and groups to associate with the RBAC
administrator role. Group names must start with the & character.
See 2.4 Common Attributes for more information on common attributes.
2.2.2 The commands Element
The commands element executes the specified HP-UX commands. Upon invocation, the commands
element handler checks the operation option from the cmgr command line and performs one of the
following tasks:
Operation
Description
add, delete, replace,
list, export, import
The contents of the concatenated data child elements are supplied as
input to /usr/bin/sh. The commands handler will return the value
returned by /usr/bin/sh.
The commands element can have the following attributes:
Attribute
Description
compartment Optional. Common attribute.
Id
Optional. Common attribute.
11
Attribute
Description
If
Optional. Common attribute.
if_op
Optional. Common attribute.
See 2.4 Common Attributes for more information on common attributes.
2.2.3 The compartment Element
The compartment element manages interaction with HP-UX Compartments configuration. Upon
invocation, the compartment element handler checks the operation option from the cmgr command
and performs one of the following tasks for the compartment identified by the compartment
attribute:
Operation Description
Add
Searches the /etc/cmpt directory for a file containing a definition for the
compartment. If the file is not found, a new /etc/cmpt/compartment.rules is
created and a compartment definition for the compartment is added. The contents of the
concatenated data child elements are then added to the top of the compartment
definition.
NOTE: You must include meta-tags around the configuration data to be added. See
2.2.10 Using meta-tags for more information on meta-tags.
Delete
Searches the /etc/cmpt directory for a file containing a definition for the
compartment. Searches the compartment definition for the first block of data with the
exact matching open and close comment meta tag as specified in the concatenated
child data elements. If a match is found, the comment meta-tags and all data between
are deleted. If the compartment definition is empty, the handler deletes the compartment
definition. If the compartment file is empty, the handler removes it.
replace
Performs the equivalent of a delete followed by an add operation, with the exception
that the new data will be placed in the same location in the compartment definition.
list
Searches the /etc/cmpt directory for files containing matching meta tags. If a match
is found, the handler displays the entire meta-tag string. If the –verbose option is
specified, the handler displays the entire content of the meta-tag data.
export
Searches the /etc/cmpt directory for files containing matching meta tags. If a
match is found, the handler adds the entire meta-tag string and all data between the
start and stop tags to the exchange.xml file in the exchange archive. The
exchange.xml file is updated for the XPath
/cmgr/body/compartments/compartment.
import
Searches the exchange.xml file from the exchange archive, under the XML XPath
/cmgr/body/compartments/compartment directory, for matching meta tags and
their associated data. If a match is found, the handler adds the meta-tag and the data
to the compartment definition file. If necessary, a new
/etc/cmpt/compartment.rules file is created.
Status
Displays the state of the compartment. Possible states are STARTED and STOPPED.
Upon successful completion of the add, delete or replace operation, cmgr validates all
compartment configuration with the following command:
12
setrules -p
If the validation succeeds, cmgr notifies the operating system to reload the compartment rules with the
following command:
setrules
NOTE: The compartment handler processes a temporary copy of the compartment configuration
file. If the compartment handler returns an error, the contents of configuration file will be unchanged
from its original state.
If the list and status operations are required on multiple compartments, the compartment
element contains a comma separated list of those compartments.
The compartment element can have the following attributes:
Attribute
Description
compartment
Optional. Common attribute.
id
Optional. Common attribute.
if
Optional. Common attribute.
if_op
Optional. Common attribute.
cmptdelete
If FALSE, do not remove empty compartment definitions on a delete operation.
Default is TRUE.
cmptactivate If FALSE, do not execute the compartments activation command. Default is TRUE.
cmptvalidate If FALSE, do not execute the compartments validation command. Default is TRUE.
See 2.4 Common Attributes for more information on common attributes.
2.2.4 The ipaddress Element
The ipaddress element manages interaction with the IP network interface configuration files and
commands. Upon invocation, the ipaddress element handler checks the operation option from the
cmgr command and performs one of the following tasks:
Operation Description
add
Adds IP address configuration information to the system configuration files
/etc/rc.config.d/netconf or /etc/rc.config.d/netconf-ipv6 and
executes the commands ifconfig and route. See ifconfig(1M) and route(1M) for
more information.
If the ipaddress attribute contains dots (for example, 192.168.1.2), it is handled as
an IPV4 type address. The interface, ipaddress, mask, and state attributes are
used to update the /etc/rc.config.d/netconf file. Otherwise, if the ipaddress
contains colons (for example, 2222::2) it is handled as an IPv6 address. The
interface, ipaddress, and state are used to update the
/etc/rc.config.d/netconf-ipv6 file. The add operation also creates a default
route with the IP address specified as both the gateway and as the source with a count
of 0, see route(1M).
13
Operation Description
NOTE: You must provide a data buffer with meta-tag values in the format
[<variable>=<value>]. For example:
<data>compartment=”$compartment” template=”$SrpName”
service=”network” id=”$id”</data>
delete
Searches the /etc/rc.config.d/netconf and /etc/rc.config.d/netconfipv6 files for the first IP Address entry matching the meta-tag as specified in the
concatenated child data elements. Deletes the IP address entry and its associated
information; including the default route created by the add operation. Deletes a primary
IPV6 interface if it has no remaining secondary interfaces, and the interface was
automatically created by the add operation.
replace
Performs the equivalent of a delete followed by an add operation.
list
Searches the /etc/rc.config.d/netconf and /etc/rc.config.d/netconfipv6 files for IP address entries containing matching meta-tags. If a match is found,
cmgr displays the entire meta-tag string. If used with -verbose option, cmgr lists the
IP address configuration information.
export
Searches the /etc/rc.config.d/netconf and /etc/rc.config.d/netconfipv6 files for IP address entries containing matching meta-tags. If a match is found,
cmgr exports the ipaddress configuration to the exchange.xml file located in the
exchange archive under the XPath /cmgr/body/ipaddresses/ipaddress.
Import
Searches the exchange.xml file located in the exchange archive under the
/cmgr/body/ipaddresses/ipaddress Xpath for matching meta tags. If a match is
found, cmgr adds the ipaddress configuration to the
/etc/rc.config.d/netconf or /etc/rc.config.d/netconf-ipv6 file.
Status
Displays the IP address of the compartment, the interface that it is associated with, and
the status of the interface.
The ipaddress element can have the following attributes:
Attribute
Description
Compartment Optional. Common attribute.
Compartment Optional. Common attribute.
14
id
Optional. Common attribute.
if
Optional. Common attribute.
if_op
Optional. Common attribute.
ipaddress
The value of the ipaddress.
Required with the add, delete, and replace operations.
Ignored with the list and help operations.
interface
Network interface name.
Required with the add operation if ipaddress has not been previously allocated.
mask
Optional
IP mask address mask. If omitted for the add or replace operations, the system
generates a default mask. Ignored for the delete, help, and list operations.
Attribute
Description
state
Optional
Sets network interface state for ipaddress in the /etc/rc.config.d/netconf
(IPv4) or /etc/rc.config.d/netconf-ipv6 (IPv6) file. Valid values are up and
down. Default is down.
See 2.4 Common Attributes for more information on common attributes.
2.2.5 The ipfilter Element
The ipfilter element manages interaction with the IPFilter configuration file specified by the
ipfilterfile or ipfilteripv6file attribute. Upon invocation, the ipfilter handler checks
the operation option from the cmgr command and performs one of the following tasks:
Operation Description
add
Adds concatenated data child elements to the beginning of the IPFilter configuration
file.
NOTE: You must include meta-tags around the configuration data to be added. See
2.2.10 Using meta-tags for more information on meta-tags.
delete
Searches the IPFilter configuration file for the first block of data with the exact matching
open and close comment meta-tag as specified in the concatenated child data
elements. If a match is found, the comment meta-tags, and all data between are
deleted.
replace
Performs the equivalent of a delete followed by an add operation, with the exception
that the new data will be placed in the same location in the IPFilter configuration file.
list
Searches the IPFilter configuration file for matching meta-tags. If a match is found,
displays the entire meta-tag string. If used with the –verbose option, cmgr displays the
entire content of the meta-tag data.
export
Searches the IPFilter configuration file for matching meta-tags. If a match is found,
exports the entire meta-tag string to the exchange.xml file located in the exchange
archive under the /cmgr/body/ipfilters/ipfilter or
/cmgr/body/ipfilters/ipfilterv6 XPath.
import
Searches the exchange.xml file located in the exchange archive under the
/cmgr/body/ipfilters/ipfilter and /cmgr/body/ipfilters/ipfilter
XPaths for matching meta tags. If a match is found, adds the meta-tag and the data to
the appropriate IPFilter configuration file.
status
Displays the number of times individual IPFilter rules were selected as reported by
ipfstat(8).
Upon successful completion of the add, delete, or replace operation, cmgr validates the IPFilter
configuration file with the following command:
ipf -n -f ipfilterfile
If the validation succeeds, cmgr notifies ipfilter to reload its configuration with the following
command:
ipf -Fa -f ipfilterfile
15
NOTE: The ipfilter handler processes a temporary copy of the IPFilter configuration file. If the
ipfilter handler returns an error, the contents of the IPFilter configuration file will be unchanged
from its original state.
Attribute
Description
Compartment
Optional. Common attribute.
id
Optional.
if
Optional.
if_op
Optional.
ipfilterfile
Required.
Specifies the IPFilter configuration file to act upon for ipv4 type addresses.
ipfilteripv6file Required.
Specifies the IPFilter configuration file to act upon for ipv6 type addresses
ipfactivate
Optional.
If FALSE, do not execute the IPFilter activation command. Default is TRUE.
ipfvalidate
Optional.
If FALSE, do not execute the IPFilter validation command. Default is TRUE.
2.2.6 The ipsec Element
The ipsec element manages interaction with HP-UX IPsec configuration. Upon invocation, the ipsec
element handler checks the operation option from the cmgr command and performs one of the
following tasks:
Operation
Description
add, delete,
replace, and
list
The contents of the concatenated data child elements are provided as input data
of the ipsec_configbatch command. See ipsec_config_batch(1M).
NOTE: You must include meta-tags around the configuration data to be added.
See 2.2.10 Using meta-tags for more information on meta-tags.
list
The contents of the concatenated data child elements are provided as input data
of the ipsec_config show command. See ipsec_config_show(1M).
export
Adds the output of the ipsec_config export command to export the IPsec
configuration to the exchange.xml file. The exchange.xml file is located in
the exchange archive under the /cmgr/body/ipsecs/ipsec XPath.
import
Searches the exchange.xml file from the exchange archive for matching IPsec
policy names. If a match is found, the data is provided as input data for the
ipsec_config batch command.
The ipsec element automatically validates configuration for the delete or replace operations.
Upon successful completion of the IPSec batch operation for the add, delete, or replace
operations, cmgr automatically reloads the new configuration if ipsec is active and running.
16
Attribute
Description
compartment
Optional. Common attribute.
id
Optional. Common attribute.
if
Optional. Common attribute.
if_op
Optional. Common attribute.
ipsecactivate Optional. If FALSE do not execute IPSec activation. If undefined, TRUE will be
used.
ipsecvalidate Optional. If FALSE do not execute IPSec validation. If undefined, TRUE will be
used.
2.2.7 The login Element
The login element manages the users that are allowed to log into the compartment. Upon
invocation, the admin element handler checks the operation option from the cmgr command and
performs one of the following tasks:
Operation Description
add
Assigns users and login groups to the specified compartment login role.
Creates the RBAC login role for the compartment and the RBAC
hpux.security.compartment.login authorization.
delete
Deletes users and groups from the RBAC compartment login role. Also deletes the
RBAC login role, the RBAC hpux.SRPadmin.$compartment authorization, and the
associated srp_rc entry in the /etc/rbac/cmd_priv file.
replace
Deletes then adds users and groups to the RBAC compartment login role.
list
Lists the RBAC login role associated with the admin user, the RBAC authorizations for
the compartment, and the command privileges.
export
Exports users and groups associated with the RBAC login role. The users and groups
configured for the login role are added to the exchange.xml file that is located under
the /cmgr/body/logins/login path. This is done by using the tag value extracted
from the admin/data element in the template. The exchange.xml file is stored in the
exchange archive.
import
Imports users and groups to be associated with the RBAC login role. Extracts the metatag from the admin/data element in the template then searches the exchange.xml
file within the exchange archive for a matching meta-tag under the
/cmgr/body/logins/login path. The specified users and groups with a matching
tag are added to the RBAC system configuration.
The ipaddress element can have the following attributes:
Attribute
Description
compartment Optional. Common attribute.
id
Optional. Common attribute.
if
Optional. Common attribute.
17
Attribute
Description
if_op
Optional. Common attribute.
Role
The RBAC login role. Default is SRPlogin-$compartment.
user
A comma separated list of users and groups. Group names must start with the &
character.
See 2.4 Common Attributes for more information on common attributes.
2.2.8 The prm Element
The prm element manages interaction with the Process Resource Management (PRM) configuration file
specified by the prmfile attribute. Upon invocation, the prm handler checks the operation option
from the cmgr command and performs one of the following tasks:
Operation Description
add
Adds concatenated data child elements to the end of the prm configuration file.
NOTE: You must include meta-tags around the configuration data to be added. See
2.2.10 Using meta-tags for more information on meta-tags.
delete
Searches for the prmfile file for the first block of data with the exact matching open
and close comment meta-tags as specified in the concatenated child data elements. If
a match is found, the comment meta-tags and all data between are deleted.
replace
Performs the equivalent of a delete followed by an add operation, with the exception
that the new data will be placed in the same location in the PRM configuration file.
list
Searches the prmfile file for matching meta-tags. If a match is found, displays the
entire meta-tag string. If used with the –verbose option, the entire content of the metatag data is displayed.
export
Searches the prmfile file for matching meta-tags. If a match is found, exports the
entire meta-tag string to the exchange.xml file in the exchange archive under the
/cmgr/body/prms/prm xpath.
import
Searches the exchange.xml file in the exchange archive under the
/cmgr/body/prms/prm xpath for matching meta tags. If a match is found, adds the
meta-tag and the data to the prmfile file.
status
Displays CPU and memory resource entitlement, the maximum CPU and memory
allowed, and the current usage statistics for the compartment.
Upon successful completion of the add, delete, or replace operation, cmgr validates the prm
configuration file with the following command:
prmconfig -s -f $prmfile
If the validation succeeds, cmgr notifies prm to reload its configuration with the following command:
prmconfig -ie -f $prmfile
NOTE: The prm handler processes a temporary copy of the $prmfile file. If the prm handler
returns an error, the contents of the $prmfile file will be unchanged from its original state.
18
Attribute
Description
compartment Optional. Common attribute.
id
Optional.
if
Optional.
if_op
Optional.
prmfile
Required.
Specifies the PRM configuration file to use.
prmactivate Optional.
If FALSE, do not execute the prm activation command. Default is TRUE.
prmvalidate Optional
If FALSE, do not execute the prm validation command. Default is TRUE.
2.2.9 The provision Element
The provision element manages user defined provision scripts specifed by the prog attribute.
Upon invocation, the provision handler checks the operation option from the cmgr command and
performs one of the following tasks:
Operation Description
add
If pass_variables is set to yes, the provision handler invokes the provision
script, specified with the prog attribute. The provision script is invoked with all the
template variables not marked as internal in the var element:
prog –add var=”value” …
If pass_variables is set to no, the handler adds the concatenated data child
elements to the beginning of the tag_file file. The provision handler then invokes
the prog provision script with the following command, using the concatenated data:
prog -add <concatenated data>
You must include meta-tags around the configuration data to be added in the file
identified by the attribute tag_file. See 2.2.10 Using meta-tags for more information on
meta-tags.
delete
If pass_variables is set to yes, the provision handler invokes the prog
provision script with the following command:
prog –delete var=”value” …
If pass_variables is set to no, the handler searches the tag_file file for the first
block of data with the matching meta tag in the concatenated child data elements. If a
match is found, the meta-tags and all data in between are deleted. The handler then
invokes the prog provision script with the following command, using the data
previously found in the tag_file file:
prog -delete <data>
replace
If pass_variables is set to yes, the provision handler invokes the prog
provision script with the following command, using the concatenated data:
prog –replace var=”value” …
If pass_variables is set to no, the handler performs a delete followed by an add
19
Operation Description
operation.
list
If pass_variables is set to yes, the provision handler invokes the prog
provision script with the following command, using the concatenated data:
prog –list var=”value” …
If pass_variables is set to no, the hanlder searches the tag_file file for matching
meta tags and if a match is found, it displays the entire meta tag string. If used with the
option verbose, the provision handler invokes the following command with the
found data:
prog -list <data>
export
If pass_variables is set to yes, the provision handler invokes the prog
provision script with the following command, using the concatenated data:
prog –export var=”value” …
If pass_variables is set to no, the handler searches the tag_file file for matching
meta tags and if a match is found, the provision handler invokes the following
command with the data found:
prog -export <data>
import
If pass_variables is set to yes, the provision handler invokes the prog
provision script with the following command, using the concatenated data:
prog –import var=”value” …
If pass_variables is set to no, the handler searches the tag_file file for matching
meta tags and if a match is found, it invokes the following command with the found
data:
prog -import <data>
The provision handler can have the following attributes:
Attribute
Description
compartment
Optional. Common attribute.
id
Optional.
if
Optional.
if_op
Optional.
tag_file
Required.
Absolute path of file containing provision tags.
prog
Required.
Name of provision script to execute.
pass_variables Yes|y|no|no. Default is yes.
Indicates whether all non-internal template variables and their values should be
passed to the provision script.
2.2.10 Using meta-tags
The configuration elements, commands, compartment, ipfilter, prm, ipsec, and provision
use meta-tags to mark the configuration changes that their respective handler has done. The element
20
handlers use meta-tags to help add, replace, list, or delete configuration data that is stored on the
system.
To open a meta-tag, use the following format:
# @tag-start [<variable>=<value>...];
To close a meta-tag, use the following format:
# @tag-end;
The meta-tags must start on a new line. For example, a meta-tag for compartments will start with the
characters // while a meta-tag for IPFilter or PRM will start with # as shown above.
2.3 Processing/Operational Elements
The CMGR template processing elements includes the following:
•
•
•
•
•
•
•
•
•
•
•
2.3.1 The data Element
2.3.2 The var Element
2.3.3 The cst_version Element
2.3.4 The description Element
2.3.5 The failure Element
2.3.6 The group Element
2.3.7 The help Element
2.3.8 The repeat Element
2.3.9 The success Element
2.3.10 The template_version Element
2.3.11 The xi:include Element
2.3.1 The data Element
The data element is used to encapsulate template data. The handler of the parent element processes
the data in the data element.
The data element has the following child element:
Child
Element
repeat
Description
Optional. Expands a subset of the data to support insertion of multi-valued
variables.
The data element has the following attributes:
Attribute Description
if
Optional. Common Attribute.
if_op
Optional. Common Attribute.
2.3.2 The var Element
The var element manages the properties of a template variable. It is used to define and change the
attributes associated with a variable.
21
You can use variable names anywhere within a template. Several variable names, such as the
operation (op), are predefined. Other variables are provided by the user in the op command, or
assigned a default value in the template itself.
The var element has the following child element:
Child Element Description
help
Optional.
prompt
Optional. Generally used to provide prompt-level help.
The var element has the following attributes:
Attribute
Description
id
Optional. Common Attribute.
if
Optional. Common Attribute.
if_op
Optional. Common Attribute.
internal
Optional. Set to yes to indicate that cmgr should never prompt for this variable.
Default is no.
name
Variable name string. The cmgr command logically replaces instances of $name in
the template with the current contents of the value attribute as they are
encountered during template processing.
prompt_level The minimum value for the prompt argument to allow cmgr to prompt for this
variable. The cmgr command always prompts if the value attribute is null when it
encounters a variable replacement. Default level is 1.
value
The value to be assigned to the variable when a replacement opportunity has been
encountered in a template. The user can also set the value from the cmgr command
line or prompt.
validate
Specifies the validation function to perform when the value attribute for this element
is initially assigned or changed. If not specified, the “default” function is used.
The cmgr command executes the validation function when the element's value attribute is initially
assigned or changed. The variable element handler returns the same value as the validation
routine. If a variable validation fails, cmgr terminates.
The following predefined validate functions are available:
22
Value
Description
“default”
Equivalent to performing a regular expression validation with
the regular expression as specified by the value of the cmgrdefault-regex template variable. If cmgr-defaultregexdoes not exist or its value is null, default checks to
ensure that value contains only the following characters:
“a-z”, “A-Z”, “0-9”,”-“,”_”, “.”, "," , " ",
":", "/", "(", ")"
Value
Description
“regexp ('regular
expression', ‘err
message’)”
Performs a Perl match operation for value against the regular
expression.
“range(x,y, ‘error msg’)”
Ensures that the following is true:
x <= value <= y
“noop”
Accept any value.
“ipVerify('ipaddress')”
Checks whether the IP address is valid.
“userExists()”
Checks whether the user is configured on the system.
“groupExists()”
Checks whether the group is configured on the system.
“cmptExists”
Ensures value is the name of an existing compartment definition
in /etc/cmpt file.
“fileTest(‘test’,’error
msg’)”
Tests file where test is a filetest operator as defined by
Perl. For instance, test can be -dd for directory test, -ee for
exists, x for executable.
“csvList(‘function’, arg1,
… argN)”
Calls function (arg1,….,argN) for each element in a comma
separated list.
Templates can contain variables anywhere within a template. When cmgr encounters a variable,
generally defined by a dollar sign $ followed by a name attribute of a var element, it logically
replaces the variable with the var element’s current value attribute. Template variable replacement
utilizes shell style variable replacement algorithm.
The following example shows the various value for a var element with a name attribute of var1 and
a value attribute of 123:
var Element
Value
abc$var1 def
“abc123 def”
abc${var1}def “abc123def”
abc\$def
“abc$def”
NOTE: For a variable replacement with multi-valued variables, use the repeat element.
CMGR reserved the following built-in variables, which are defined for all templates:
Variable Name
Description
$op
The current operation add, delete, replace, list, import,
export, or status.
$context
The context variable passed to the handler functions.
23
2.3.3 The cst_version Element
The cst_version element defines the version of the CMGR template specification used. This guide
is the specification for CMGR template version 1.0. The cst_version element may only be a child
of the head element. For example:
<head> <cst_version>1.0</cst_version></head>
NOTE: The cst_version element has no child element and no attributes.
2.3.4 The description Element
The description element is used to encapsulate description text for a template. It is supported only
as a child of the head element.
NOTE: The description element has no child element and no attributes.
2.3.5 The failure Element
The failure element is used to encapsulate element failure message that can be displayed when the
processing of the parent element returns an error.
NOTE: The failure element has no child element and no attributes.
2.3.6 The group Element
The group element is a generic grouping element. It can be used to group elements to be executed
under a common condition.
The group element can have the following child elements:
Child Element
Description
All configuration elements (2.2 Configuration Elements)
Optional
All processing elements (2.3 Processing/Operational Elements) Optional
NOTE: The group element has no attributes.
2.3.7 The help Element
The help elements are used to encapsulate help text associated with the template or elements within a
template.
NOTE: The help element has no child element.
The help element can have the following attributes:
Attribute Description
24
If
Optional. Common attribute.
if_op
Optional. Common attribute.
2.3.8 The repeat Element
The repeat element lets you replace multi-valued variables. When replacing variables, cmgr
duplicates the contents of the repeat element once per variable value. If the repeat element
contains multiple multi-valued variables, and the variables do not have an equal number of values,
cmgr returns an error value of 1.
For example, using variables x=color, y=”'1', '2', '3'”, and z=”'red',
'yellow','green'”, the following program:
<repeat vary="y, z">
The $x $y is $z.
</repeat>
would generate
The color 1
The color 2
The color 3
the following output:
is red
is yellow
is green
NOTE: The repeat element has no child element.
The repeat element can have the following attributes:
Attribute Description
if
Optional. Common attribute.
if_op
Optional. Common attribute.
vary
Required. Comma separated list of variable names to vary.
2.3.9 The success Element
The success element is used to encapsulate element success messages that can be displayed when
the processing of the parent element returns without an error.
NOTE: The success element has no child element and no attributes.
2.3.10 The template_version Element
The template_version is used to encapsulate template version text. It is supported only as a child
of the head element.
NOTE: The template_version element has no child element and no attributes.
2.3.11 The xi:include Element
The xi:include element is used to include another XML document in the current document.
NOTE: The xi:include element has no child element.
25
The xi:include element has the following attribute:
Attribute Description
href
Required.
The url of a local file identifying additional XML data to be included in the CMGR
template. For example:
<xi:include href="file:/etc/opt/example.xml"/>
2.4 Common Attributes
The CMGR template includes command attributes and handler specific attributes. You can also create
your own attributes.
The cmgr command supports the following attributes:
Attribute
Description
compartment The name of the compartment for the add, delete, and replace operation, or a
comma separated list of compartment names for the list and status operation.
id
Element identity, does not have to be unique.
if
Specifies a condition that must be true for cmgr to process the element. Can be any
valid Perl condition statement.
if_op
Limits the cmgr processing of this element to cases with a matching cmgr operation
argument. Valid values are the complete form of any cmgr operation argument.
Multiple operations may be specified when seperated with the | sign.
NOTE: The if and if_op attributes are very useful with the data element to specify operations
based processing for the Configuration Elements.
2.5 Example: Building a Template
Example 2.1 demonstrates the capabilities of CMGR by providing a simplified version of dynamic
host firewall rule management. With this example template, an administrator or application that
detects undesirable traffic on a TCP port can instruct cmgr to generate an IPFilter rule to block all
traffic from the offending source IP address for the specified port, and to log these actions with
syslog. By associating each blocking request with an identifier, individual rules can be replaced or
deleted with cmgr.
CAUTION: To avoid effecting system-wide IPFilter configuration, Example 2.1 operates on an
alternate IPFilter configuration file (/tmp/example_ipf.conf). HP recommends that you do not use
this template on a production system.
Figure 2.1 shows the sequence of actions that occur in Example 2.1. The sequence of actions are
labeled from 1 to 4 and are referred to in the example comments.
26
Figure 2.1: Using HP-UX CMGR
Example 2.1: IPFilter Template
<?xml version="1.0" ?>
<!DOCTYPE template SYSTEM "/opt/hpcmgr/etc/templates/cmgr.dtd">
<template xmlns:xi="http://www.w3.org/2001/XInclude">
<!-========================================================================
This example template demonstrates managing dynamic IPFilter rules to
block trafic from source a IP addresses to a local tcp port. Each rule
has it's own ID, so you can add, replace, or delete individual rules. As
the rules are changed, the action is logged to syslog.
To add a rule:
27
cmgr -a -t <this file> ip_address=<Address> tcp_port=<port>
rule_id=<string>
To delete a rule:
cmgr -r -t <this file> ip_address=<Address> tcp_port=<port>
rule_id=<string>
To delete a rule:
cmgr -d -t <this file> rule_id=<string>
To list the rules in effect:
cmgr -l -t <this file> -v
=========================================================================
-->
<!-========================================================
Template Head: declare variables
[2]
=========================================================
-->
<head>
<!-===================================================
Since this is an example, set internal variables to:
use example instance of IPFilter config file.
validate, but don't activate.
===================================================
-->
<var name="ipf_file" value="/tmp/example_ipf.conf" internal="yes"/>
<var name="validate" value="yes" internal="yes"/>
<var name="activate" value="no" internal="yes"/>
<!-===================================================
Declare variables and assign default values
===================================================
-->
<var name="ip_address" value="" validate="ipVerify" >
<prompt>Source IP address:</prompt>
<help if="$interactive">
The IP address to block traffic from.
</help>
</var>
<var name="tcp_port" value="" validate="regexp('\d+')" >
<prompt>TCP port:</prompt>
<help if="$interactive">
The TCP port to block for the specified IP address.
</help>
</var>
<var name="rule_id" value="" validate="regexp('[\w\-]+')" >
<prompt>IPFilter Rule ID :</prompt>
<help if="$interactive">
User supplied identifier for this IPFilter rule.
</help>
</var>
28
</head>
<!-========================================================
Template Prologue: user interaction [1]
=========================================================
-->
<prologue>
<!-========================================================
Provide output for the help option
=========================================================
-->
<help>
Variable
Usage
--------------- -------------------------------------------------------ip_address
Source IP Adresss for IPFilter Rule
Required for: -a, -r
tcp_port
TCP port to block for ip_address
Required for: -a, -r
rule_id
User defined string(no spaces) that identfies this rule
Required for: -a, -r, -d
</help>
<!-========================================================
Touch the required variables to force a prompt if they
do not have a value yet
=========================================================
-->
<data if_op="add|replace">
$ip_address
$tcp_port
$rule_id
</data>
<data if_op="delete">
$rule_id
</data>
</prologue>
<!-========================================================
Template Body: take action
========================================================
-->
<body>
<!-========================================================
Update or list the contents of IPFilter configuration [3]
========================================================
-->
<ipfilter ipfilterfile="$ipf_file" ipfilteripv6file="" >
<data if_op="add|replace|list|delete">
#@tag-start Example Dynamic IPFilter Service Rule="$rule_id";
</data>
<data if_op="add|replace">
block in quick proto tcp from $ip_address to any port = $tcp_port
29
</data>
<data if_op="add|replace|list|delete">
#@tag-end;
</data>
<success>$op ipfilter rules succeeded</success>
<failure>$op ipfilter rules failed</failure>
</ipfilter>
<!-=========================================================
Note the action is syslog for add, replace, or delete [4]
=========================================================
-->
<commands id="$rule_id">
<data if_op="add|replace">
logger "cmgr-IPFilter Example $op - Rule: $rule_id, IP Address:
$ip_address, Port: $tcp_port"
</data>
<data if_op="delete">
logger "cmgr-IPFilter Example $op - Rule: $rule_id"
</data>
</commands>
</body>
</template>
To use this template, follow these steps:
1. Logon to your system as root and copy this template to a temporary location, for example,
/tmp/example.cst.
2. (Optional) Remove earlier usage of this example IPFilter configuration file:
# rm /tmp/example_ipf.conf
3. Add Rule_1 to block from IP address 192.0.2.1 for TCP port 2343 :
# cmgr -a -t /tmp/example.cst rule_id=Rule_1 ip_address=192.0.2.1
tcp_port=2343
add ipfilter rules succeeded
Verify the output:
# cmgr -l -v -t /tmp/example.cst
IPFilter Configuration (/tmp/example_ipf.conf):
@tag-start Example Dynamic IPFilter Service Rule="Rule_1" ;
block in quick proto tcp from 192.0.2.1 to any port = 2343
@tag-end ;
Read the configuration file:
# more /tmp/example_ipf.conf
#@tag-start Example Dynamic IPFilter Service Rule="Rule_1";
block in quick proto tcp from 192.0.2.1 to any port = 2343
#@tag-end;
4. Modify Rule_1 to block from IP address 192.0.2.1 for TCP port 1257 :
# cmgr -r -t /tmp/example.cst rule_id=Rule_1 ip_address=192.0.2.1
tcp_port=1257
replace ipfilter rules succeeded
Verify the output:
# cmgr -l -v -t /tmp/example.cst
30
IPFilter Configuration (/tmp/example_ipf.conf):
@tag-start Example Dynamic IPFilter Service Rule="Rule_1" ;
block in quick proto tcp from 192.0.2.1 to any port = 1257
@tag-end ;
5. Add a second Rule for a different source, but the same port:
# cmgr -a -t /tmp/example.cst rule_id=Rule_2 ip_address=192.0.2.2
tcp_port=1257
add ipfilter rules succeeded
Verify the output:
# cmgr -l -v -t /tmp/example.cst
IPFilter Configuration (/tmp/example_ipf.conf):
@tag-start Example Dynamic IPFilter Service Rule="Rule_2" ;
block in quick proto tcp from 192.0.2.2 to any port = 1257
@tag-end ;
IPFilter Configuration (/tmp/example_ipf.conf):
@tag-start Example Dynamic IPFilter Service Rule="Rule_1" ;
block in quick proto tcp from 192.0.2.1 to any port = 1257
@tag-end ;
Read the configuration file:
# more /tmp/example_ipf.conf
#@tag-start Example Dynamic IPFilter Service Rule="Rule_2";
block in quick proto tcp from 192.0.2.2 to any port = 1257
#@tag-end;
#@tag-start Example Dynamic IPFilter Service Rule="Rule_1";
block in quick proto tcp from 192.0.2.1 to any port = 1257
#@tag-end;
6. Remove only the first rule:
# cmgr -r -t /tmp/example.cst rule_id=Rule_1
delete ipfilter rules succeeded
7. Examine the events as logged by the above template actions in the syslog file:
# tail /var/adm/syslog/syslog.log
Oct 27 08:07:48 hptem386 syslog: cmgr-IPFilter Example add - Rule:
Rule_1, IP Address: 192.0.2.1, Port:
2343
Oct 27 08:28:52 hptem386 syslog: cmgr-IPFilter Example add - Rule:
Rule_2, IP Address: 192.0.2.2, Port:
1257
Oct 27 08:44:56 hptem386 syslog: cmgr-IPFilter Example delete Rule: Rule_1
Verify the output:
# cmgr -l -v -t /tmp/example.cst
IPFilter Configuration (/tmp/example_ipf.conf):
@tag-start Example Dynamic IPFilter Service Rule="Rule_2" ;
block in quick proto tcp from 192.0.2.2 to any port = 1257
@tag-end ;
HP-UX SRP offers SRP example templates. To download HP-UX SRP, go to HP Software Depot:
http://software.hp.com
Once you have installed HP-UX SRP, the SRP template examples are located in the
/etc/opt/hpsrp/templates directory.
31
3 Developing a CMGR Plug-in
This chapter describes how to extend CMGR’s functionality by developing a new element handler and
a new variable validation function for CMGR.
This chapter discusses the following topics:
• 3.1 Developing an Element Handler
• 3.2 Developing a Variable Validation Function
• 3.3 Example Plug-in
3.1 Developing an Element Handler
CMGR uses Perl modules to process CMGR template elements. The rules for writing a handler for a
new element are:
1. Select a lower-case name for the new element. For 3.3 Example Plug-in, we chose the
element <myconf>.
2. Update CMGR’s template Document Type Definition (DTD) with the new element. The DTD file
is /etc/opt/hpcmgr/templates/cmgr.dtd.
• Create an <!ELEMENT> entry for the new element and add the allowable child
elements for the new element (such as data, help, success, and failure).
• Define the attributes (such as if and id, allowed for the new element with
<!ATTLIST>.
• Add the new element to the allowable child elements for the head, prologue, and
body elements.
3. Create or update an existing template with the new element.
4. The file, module name, and function names for the handler are based upon the XML element
name (element_name) that it implements:
• The handler must be included in a Perl module. The module name for the handler
must be “Cmgr::Element_name” where Element_name has the first letter
capitalized.
• The filename for the module is /opt/hpcmgr/lib/Cmgr/Element_name.pm
where Element_name has the first character capitalized.
• The handler function name is “process_element_name”. Note that the first
character of the element name is not capitalized.
For example, if the element is <myconf>, then the module filename is
/opt/hpcmgr/lib/Cmgr/Myconf.pm, the module name is Cmgr::Myconf and the
handler function name is process_myconf().
5. Write the handler function. The handler function must accept $context (as the first
parameter) and $node (as the second parameter). The $context parameter is a handle for
accessing template variables, and the $node parameter is a handle for reading attribute
values attached to the handler’s XML element in the template. The following functions can be
called on the $context and $node:
32
Function Name
Description
$context->get_data()
Returns the contents of the concatenated <data> child
elements of the new element, with the variable values
substituted for their names.
Function Name
Description
$context->get_op()
Returns the current operation: add, delete, replace,
help, or list.
$context>get_var(“name”)
Returns the value of the template variable “name”. Calls
Perl's die() function if the variable has an undefined
value. Wrap the function in a Perl eval{} block if you do
not wish the handler to terminate if this error occurs.
$context>set_var(“name”,
“value”)
Sets the value of variable “name” to “value”. Calls the
variables validate function, if one is defined. If validation
fails, set_var() calls Perl’s die() function.
$context->get_xmlOut>get_xp()
$context->get_xmlIn>get_xp()
Get XML::XPath object for export/import exchange.xml
file.
$node>getAttribute(“name”)
Returns the value of attribute “name”.
6. NOTE: For import and export operations, the handler may update the exchange.xml file
which is stored in the exchange file archive. The exchange file archive is currently readable
with the tar command.
7. The handler may print output to stderr or stdout and must return a NULL list. When the
handler encounters a serious error, it must call perl’s die function with an error message.
8. Test the new element handler and DTD by running the cmgr command with the validate
option:
# cmgr –t mytemplate.cst –Validate –l
3.2 Developing a Variable Validation Function
A new CMGR variable validation function may be defined for a template. The rules for writing and
using the function are as follows:
1. Create a validation function with a descriptive name. The function must accept the template
variable name and value to be validated as the first and second parameters. Additional
parameters may also used. The function must call perl’s die() when it encounters a
validation error. Otherwise the value of the second parameter is considered valid and the
function must return 0.
2. The validation function must be part of a Perl module. The module file must be located under
/opt/hpcmgr/lib/cmgr and the module filename must be the same as the module name
as per Perl convention.
3. The CMGR template referencing the validation function must include the full module name.
For example: Cmgr::Mymodule::functionname(). Parameters should be enclosed in
single quotes and may contain template variables. For example:
<var name=”variable”
validate=”Cmgr::Modulename::functionname(‘You must enter a
value!’)” />
33
3.3 Example Plug-in
The example contained in this section is for a template that updates a configuration file which
specifies a list of client computer system names. The template is used with the cmgr command to add,
delete, replace, and list entries from the configuration file.
The add operation requires the user to specify a system name (represented with the system_name
variable) and a tag identifier (represented with the tagid variable). tagid may be an arbitrary
character string. The system_name variable is checked to ensure it responds to a ping(1M) after
which the configuration file is updated. An entry in the configuration file is in the format:
client=system_name # tagid
For a delete operation, the user is prompted to enter the tagid value. All entries in the file with a
tag field that exactly matches the tagid variable specified via cmgr are deleted.
The replace operation functions like a delete operation, followed by an add operation.
The list operation will list the entire contents of the configuration file if cmgr’s verbose option is
specified. Otherwise list will only list lines from the configuration file with a matching tag value.
To create and use a template that updates a configuration file that specifies a list of client computer
system names, follow these steps:
Modify the CMGR DTD (/etc/opt/cmgr/templates/cmgr.dtd) for the myconf element:
<!ELEMENT template (head, prologue?, body)>
<!ELEMENT head
(title|description|cst_version|template_version|
xi:include|help|group|var|admin|commands|compartment|ipaddress|ipfilter|i
psec|login|prm|provision|data|myconf)*>
<!ELEMENT prologue
(xi:include|help|group|var|admin|commands|compartment|ipaddress|ipfilter|
ipsec|login|prm|provision|data|myconf)*>
<!ELEMENT body
(xi:include|help|group|var|admin|commands|compartment|ipaddress|ipfilter|
ipsec|login|prm|provision|data|myconf)*>
… lines deleted for readability …
<!ELEMENT myconf (data|help|success|failure)*>
… lines deleted for readability …
<!ATTLIST myconf
config_file
CDATA #IMPLIED
id
CDATA #IMPLIED
if_op
CDATA #IMPLIED
if
CDATA #IMPLIED
>
… lines deleted for readability …
Create a new CMGR template, custom.cst, that uses the myconf element to update a
configuration file and the check_system validation function to verify whether a remote host will
34
respond to ping(1M). Note that the configuration filename is specified with the “config_file”
attribute for the “myconf” element:
<?xml version="1.0" ?>
<!DOCTYPE template SYSTEM "/opt/hpcmgr/etc/templates/cmgr.dtd">
<template>
<head>
<var name="system_name"
validate="Cmgr::My_check_vars::check_system('You must enter a
value!')" >
<prompt>Client system name:</prompt>
<help>
The DNS Node Name for the remote client.
The client must be reachable with ping.
</help>
</var>
<var name="tagid" value="" >
<prompt>Tag identifier:</prompt>
<help>
An identifier that identifies one or more entries to the configuration
file.
On a delete or replace operation, all existing entries with the same
identifier tag will be deleted or replaced.
</help>
</var>
</head>
<prologue>
<!-- prompt for a system name and tag id-->
<data if_op="add|replace">$system_name $tagid</data>
<data if_op="delete|list" if="!$verbose">$tagid</data>
</prologue>
<body>
<myconf config_file=”/tmp/myconf”>
<data if_op="add|replace">
client=$system_name # $tagid
</data>
<data if_op="delete|list">
# $tagid
</data>
</myconf>
</body>
</template>
Create a new module, Cmgr::Print_data, located at /opt/hpcmgr/lib/Cmgr/Myconf.pm:
#!/usr/bin/perl
########
# this module is the handler for <myconf>
########
package Cmgr::Myconf;
use strict;
use warnings;
my $TAG='#';
35
########
# process the <myconf> node
########
sub process_myconf
{
my ($context, $node)=@_;
# get the current operation
my $op = $context->get_op();
my $verbose = $context->get_var('verbose');
# get the concatenated data buffers
my $data = $context->get_data();
# read the config file into $contents
my $configFile=$node->getAttribute('config_file');
$configFile='/tmp/myconf' if !$configFile;
my $contents = read_config($configFile);
# get the tag out of the data buffer (if it is there)
my $tag = ($data =~ /$TAG\s*(\w+)/) ? $1: "";
# Process operation
# delete or repalce
if ($op =~ /^(delete|replace)/) {
# remove all lines with the tag
$contents=~s/^(.*?$TAG\s*$tag.*?)$//mg;
write_config($configFile, $contents)
if $op =~ /^delete/;
}
# add or replace
if ($op =~ /^(add|replace)/) {
# append the data to the file whether it is tagged or not
$contents .= $data;
write_config($configFile, $contents);
}
# list
elsif ($op =~ /^list/) {
if ($verbose) {
# print the contents of the config file
print $contents;
}
else {
# print all tagged lines in the file that match the tag
while ( $contents=~/^(.*?$TAG\s*$tag.*?)$/mg) {
my $line = $1;
print "$line\n";
}
}
}
# export
elsif ($op =~ /^export/) {
my $xmlp = $context->get_xmlOut();
my $xpath = $xmlp->get_xp();
# example XML::XPath code to udpate the exchange file
# create a XML::XPATH data node with some text
36
my $dataNode =
XML::XPath::Node::Element->new("data");
my $textNode =
XML::XPath::Node::Text->new("hello world");
$dataNode->appendChild($textNode);
# add new XML to the exchange.xml file at $XPATH
$xmlp->addTagDataNode($XPATH, $tag, $dataNode);
}
# import
elsif ($op =~ /^import/) {
my $xmlp = $context->get_xmlIn();
my $xpath = $xmlp->get_xp();
# find all nodes that match $XPATH with $tag
my @tagList = $xmlp->readTagList($XPATH, $tag);
# for each found $XPATH Node
for my $r_tag (@tagList) {
my $node=$r_tag->{node};
# print the text under ./data
my $text=$xpath->findnodes_as_string(
'./data/text()', $node);
print $text . "\n";;
}
}
return ();
}
sub read_config
{
my ($file) = @_;
return "" if ! -e $file;
open (my $in, '<', $file)
or die "Error: Can't open $file for reading: $!\n";
return do { local $/; <$in> };
}
sub write_config
{
my ($file, $contents) = @_;
open my $out, '>', "$file"
or die "Error: couldn't open $file for writing: $!\n";
print {$out} $contents;
}
1;
Create a variable validation function,
Cmgr::My_check_vars::check_system(), that is referenced by the example
template:
#!/usr/bin/perl
package Cmgr::My_check_vars;
use strict;
use warnings;
37
sub check_system
{
my ($name, $value, $errMsg) = @_;
# detaint
$value=~/^(.*)$/; $value=$1;
# make sure a nodename was specified
$errMsg="Error: invalid hostname for $name" if !$errMsg;
die $errMsg if !$value || $value!~/^\w+$/;
# check if the node is reachable
my $out=`/usr/sbin/ping $value -n 1 2>&1`;
die "Error: $value is not reachable.\n" if $?;
}
Run the cmgr command with the custom.cst template:
% cmgr -t custom.cst -a
Enter the requested values when prompted, then press return.
Enter "?" for help at prompt. Press control-c to exit.
Client system name: xxxyyyzzz
--------------------------------------------------------------Error: xxxyyyzzz is not reachable.
Enter "?" for help at prompt. Press control-c to exit.
--------------------------------------------------------------Client system name: system4
Tag identifier: [] test tag string
The following template variables have been set to the values shown:
system_name
tagid
=
=
system4
test tag string
Press return or enter "yes" to make the selected modifications with these
values. Do you wish to continue? [yes]
%
% cmgr -t custom.cst -l -v
client=system1 # t1
client=system2 # t1
client=system3 # t2
client=system4 # test tag string
%
% cmgr -t custom.cst -d tagid=t1
% cmgr -t custom.cst -l -v
client=system3 # t2
client=system4 # test tag string
%
38
4 Invoking cmgr to Configure Services
The cmgr command coordinates the configuration of multiple subsystems. Related configuration
changes can be added, viewed, replaced, or deleted as a set. The cmgr command line arguments
are combined with the XML-based CMGR templates to define the actual configuration operations to
perform. You can execute cmgr as a command line or in batch mode. The batch mode suppresses the
guided prompt base processing of the specified template. You can use cmgr to coordinate the
configuration of HP-UX compartments, Process Resource management (PRM), IPFilter, IPSec, network
interface, and subsystems managed with a command line interface.
You can invoke the cmgr command in two different modes: batch mode (-batch) or interactive.
The cmgr command has the following syntax:
cmgr -add|-delete|-list|-replace|-import|-export|-status -t template
[-batch] [-prompt <level>] [-Validate] [-verbose]
[-x <xpath>] [-xfile <filename> -xmloutput
[<variable>=<value>...]
cmgr -h[elp] [-t <template>] [-v] [-x <xpath>] [-xmloutput]
Following is a list and brief description of the cmgr command options:
-a, -add
Adds a new set of configuration data specified by the template.
The cmgr command exits when the first error is encountered during an
add operation. HP recommends that you execute a delete operation on
the template to remove any subsystem configuration applied before the
failure occurred.
-b, -batch
Runs cmgr in batch mode. The cmgr command does not prompt for
template variable values. If cmgr encounters an unassigned variable that
does not have a default, it exits with an error.
-d, -delete
Removes a set of existing configuration data specified by the template.
-export
Exports a set of existing configuration data to the exchange file as
specified by the template.
-h, -help
Displays any help sub-elements encountered.
-import
Imports a new set of configuration data from the exchange file, as
specified by the template.
-l, -list
Displays the configuration data associated to a configuration set. If the
element supports the verbose option, cmgr displays detailed contents of
the specified configuration components.
-r, -replace
Replaces the contents of the configuration associated with the newly
supplied data.
-status
Displays dynamic information related to an SRP. The status is displayed
for the cmpt, network, and prm services. The ipfilter service is
39
displayed when the status option is used with the verbose option.
-t, -template name Identifies the template file to use for this operation name. The cmgr
command processes it as a file system path when the name ends with
.template . Otherwise, cmgr creates a path name such as
/opt/hpcmgr/etc/templates/name.template
-p, -prompt level
Specifies an integer value for the cmgr prompt level. The cmgr command
only prompts for a variable when first encountered if it does not have an
assigned value, or the prompt_level attribute for the variable in the
template is less than or equal to level. The prompt option is ignored if used
with the batch option. The default prompt level is 1.
-v, -verbose
Prints verbose messages.
-V, -Validate
Instructs cmgr to validate the template's XML schema before executing the
selected operation for the template. The cmgr command validates the
template against a Data Type Definiton (DTD) if one is referenced by the
template. Otherwise, the XML schema is considered valid.
-x, -xpath "paths" An XML xpath specification that identifies the elements to process in the
specified template. If xpath is not specified, all elements in the template are
processed.
40
-xml, -xmloutput
Instructs cmgr to print output in XML format for the list and status
operations.
-xfile filename
Pathname of exchange file used for import and the export operations.
Technology for better business outcomes
© Copyright 2009 Hewlett-Packard Development Company, L.P. The information
contained herein is subject to change without notice. The only warranties for HP
products and services are set forth in the express warranty statements
accompanying such products and services. Nothing herein should be construed as
constituting an additional warranty. HP shall not be liable for technical or editorial
errors or omissions contained herein.
5992-5173, December 2009