Novell is now a part of Micro Focus

Integrating Applications with the IP Address Management Framework

Articles and Tips: article

CH Ganapathi
Senior Software Engineer
Novell, Inc.
cganapathi@novell.com

01 Oct 2003


Thanks to Anoop Kumar P, Manjunath Balasubramaniam, and B Thavamani Rajan of Novell for their help with this AppNote.

This AppNote discusses two different interfacing mechanisms for integrating an application with the IP Address Management Framework in NetWare 6.5. It helps you decide which interface an application should use to integrate with the framework. It also explains the features provided by the framework that the application can make use of.


Topics

IP Address Management Framework, network applications, IP addresses, TCP/IP, network management

Products

NetWare 6.5

Audience

network administrators, consultants, integrators, developers

Level

intermediate

Prerequisite Skills

familiarity with TCP/IP, NetWare 6.5

Tools

none

Sample code

no

Introduction

The IP Address Management Framework is a centralized framework that stores and displays the IP address/port configuration of applications integrated with this framework. The framework helps in managing the IP address-application association when changing the server's IP address. It also helps in resolving port conflicts.

The prominent features of the framework with regards to integrating application are:

  • A Web-based user interface (NetWare Remote Manager snap-in) to access the framework

  • A centralized interface to edit applications' IP/port configurations

  • Classification of application configurations as Valid, Invalid, or Conflict

  • Capability to assign an IP address to an application with the Default IP address category

  • Enforcing of policies on all the configurations of an application or locally to a particular configuration

  • Accommodating changes to application's IP/port configuration done outside the framework

This AppNote explains the two mechanisms that are available to integrate applications with the IP Address Management Framework: implicit and explicit interfacing. It provides a description of the appconf.xml file that is used for implicit interfacing, along with a summary of the policies supported by the framework. It also lists the APIs available for explicit interfacing of applications.

For background information on the framework, see "IP Address Management Framework: Managing Application IP Address/Port Configurations in NetWare 6.5" in the September 2003 issue of Novell AppNotes , available at http://developer.novell.com/research/appnotes/2003/septembe/02/a030902.html .

Interfacing Mechanisms

There are two mechanisms available for applications to integrate with the IP Address Management Framework: implicit and explicit interfacing. Your choice of interface depends on how the application gets its IP/port configuration information. Applications may have their own configuration files/databases, or they may use system-provided APIs to get this information. The former type of applications can use implicit interfacing, while the latter can use explicit interfacing.

Figure 1 shows an architectural overview of these two interfacing mechanisms.

Figure 1: An overall depiction of the implicit and explicit interfacing mechanisms.

Implicit Interfacing

Some cross-platform applications, legacy applications, and third-party applications refer to their own configuration files/databases for configuration information. This type of application will interface with the IP Address Management Framework using an XML interface. In order to use the framework, the application should provide a tool that follows the following sequence of steps:

  • Create a directory with a unique name (say XYZ) in SYS:\SYSTEM\IPCONF.

  • Provide a PULLCFG.NCF file and a PUSHCFG.NCF file in the XYZ directory.

  • When executed, PULLCFG.NCF should create an appconf.xml file containing the configuration information stored in the application's configuration files or database.

  • When executed, PUSHCFG.NCF should update the application's configuration files or database with the contents of the appconf.xml file.

The appconf.xml file is the implicit interface between the application and the framework. When the administrator modifies an application's configuration entries using the framework, the respective appconf.xml file is updated with the changed information and triggers the PUSHCFG.NCF file for the corresponding application.

Whenever the IP Address Management page is visited or refreshed through the NetWare Remote Manager utility, the framework executes all PULLCFG.NCF files (which are stored in multiple subdirectories of the IPCONF directory) to fetch possible changes to applications' IP/port configurations that may have been made outside of the framework.

Here is a sample appconf.xml file:

<?xml version="1.0" encoding="ISO-8859-1" ?>
	<SystemIPPPortConfig>
		<ApplicationIPConfig>
			<AppInfo>
				<Name>Xyz</Name>
				<Description>example for appconf.xml</Description>
				<GlobalPolicy>ADDRESS_NOT_EDITABLE</GlobalPolicy>
			</AppInfo>
			<IPaddressinfo>
				<SubcomponentDescription>User Instance</SubcomponentDescription>
				<LocalPolicy>PORT_NOT_EDITABLE</LocalPolicy>
				<ContextInformation>10.1.1.12</ContextInformation>
				<AddressType>IPv4</AddressType>
				<AddressCategory>2</AddressCategory>
				<IPaddress>10.1.1.1</IPaddress>
				<Protocol>TCP</Protocol>
				<Portnum>5983</Portnum>
			</IPaddressInfo>
			<IPaddressinfo>
				<SubcomponentDescription>Admin Instance</SubcomponentDescription>
				<LocalPolicy>CONFLICT_RESOLUTION_EXEMPT</LocalPolicy>
				<AddressType>IPv4</AddressType>
				<AddressCategory>2</AddressCategory>
				<IPaddress>10.1.1.1</IPaddress>
				<Protocol>UDP</Protocol>
				<Portnum>5983</Portnum>
			</IPaddressInfo>
			<Handler>SYS:\SYSTEM\IPCONF\appconf.xml</Handler>
			<CfgStatus>0</CfgStatus>
		<ApplicationIPConfig>
<SystemIPPortConfig>

Table 1 contains a brief description of the tags used in the appconf.xml file.

Tag Name

Tag Description

Acceptable Values/Limits

Name

Application's name - provide a unique name for each application

Should be less than 20 characters

Description

Brief description of the application

Should be less than 64 characters

GlobalPolicy

Policies applicable to all configurations of the application

Multiple policies should be separated by commas

Subcomponent- Description

Brief description of the configuration used to distinguish between multiple identical configurations (same IP address, port, and protocol)

Should be less than 64 characters

LocalPolicy

Policies for this configuration

Multiple policies should be separated by commas

ContextInformation

Any extra information related to this configuration (the framework retains this while updating appconf.xml, so the application can use this field to keep track of any extra information related to this configuration)

Should be less than 127 characters

AddressType

Type of the IP address

Can be IPv4 or DNS

AddressCategory

Category of the address used

Can be 0, 1, 2, or 3 - 0 = Default IP address 1 = Private IP address (reserved for future use) 2 = Primary IP address 3 = Secondary IP address

IPaddress

IP address or DNS name - value can be empty if the Address Category is default (0)

Should be less than 80 characters - Can be an IPv4 address or a DNS name; IP address should be in dotted notation

Protocol

Protocol used by this configuration

Should be TCP or UDP

Portnum

Port number for this configuration

Port number supported by the TCP/IP stack - value can be empty if the CONFLICT_RESOLUTION_EXEMPT policy is set for this configuration

Handler

Absolute path of appconf.xml file

Should be less than 128 characters

Guidelines for Creating the appconf.xml File

Here are some guidelines to follow when you create an appconf.xml file for an application.

  • All tags are mandatory except <GlobalPolicy>, <SubcomponentDescription>, <LocalPolicy>, and <ContextInformation>.

  • All tags should appear in the same order as given in Table 1.

  • If there are multiple configurations, each configuration should have a corresponding <IPaddressInfo> record.

Policies Supported by the Framework

The following policies are supported by the IP Address Management Framework:

  • ADDRESS_NOT_EDITABLE - The IP address field is not editable via the framework's NetWare Remote Manager snap-in.

  • PORT_NOT_EDITABLE - The Port field is not editable via the framework's NetWare Remote Manager snap-in.

  • CONFLICT_RESOLUTION_EXEMPT - The configuration will not participate in the framework's conflict resolution process.

These policies are helpful in the following instances:

  • Applications that listen on standard ports would not be interested in listening on a port other than the standard port. For such applications, you can opt for the PORT_NOT_EDITABLE policy.

  • For an application that is not actively listening on a particular port, you can set the CONFLICT_RESOLUTION_EXEMPT policy so that the application's configuration is ignored by the framework when scanning for port conflicts.

Figure 2 shows an example of the information displayed in the NetWare Remote Manager utility when the ADDRESS_NOT_EDITABLE policy and the optional <SubcomponentDescription> tag are used.

Figure 2: Illustration of ADDRESS_NOT_EDITABLE policy and optional <SubcomponentDescription>.

Figure 3 shows an example of the information displayed in the NetWare Remote Manager utility when the PORT_NOT_EDITABLE policy is used.

Figure 3: Illustration of PORT_NOT_EDITABLE policy.

Figure 4 shows an example of the information displayed in the NetWare Remote Manager utility when the CONFLICT_RESOLUTION_EXEMPT policy and an empty <Portnum> tag are used.

Figure 4: Illustration of CONFLICT_RESOLUTION_EXEMPT policy and empty <Portnum> tag.

Default IP Address and the Framework

In NetWare 6.5, you can configure one of the primary IP addresses as the default IP address for the server. This can be done through the INETCFG utility or the "Configure TCPIP" NetWare Remote Manager snap-in. If no default is configured, the TCP/IP stack assigns the first bound IP address of the server as the default IP address.

If an application has opted for the "default" (0) setting for the AddressCategory tag, the framework overwrites the application's IP address field with the default IP address of the server.

If the server's default IP address changes, the framework automatically updates the IP address of all configurations having the default AddressCategory setting with the changed default IP address. For each application that is using the implicit interfacing mechanism, the framework updates the appconf.xml file and triggers the PUSHCFG.NCF file. For applications integrated using the explicit interfacing mechanism, the framework generates the OS event called EVENT_IPSERVICES_CONFIG_CHANGE.

NetWare 6.5 Applications Integrated Using Implicit Interfacing

The following applications that come with NetWare 6.5 are already integrated with the IP Address Management Framework using the implicit interfacing mechanism.

  • Admin Tomcat (Tomcat Admin Instance)

  • Apache 2.0 Web Server

  • ApacheAdmin (Apache Administration Web Server)

  • iManager 2.0 Framework

  • MySQL Database Server

  • Native File Access for UNIX (NFAU)

  • NetWare FTP Server

  • NetWare Web Search Server 3.0.0

  • Novell exteNd Application Server

  • Novell Small HTTP Interface (HTTPSTK)

  • SSH Server

  • Tomcat 4 (Tomcat User Instance)

Explicit Interfacing

The explicit interfacing mechanism is a programmatic approach. The framework exports C APIs, and also generates the OS event EVENT_IPSERVICES_CONFIG_CHANGE if there is a change in the server's IP address or an application's configuration. The application programmatically imports and uses the framework's APIs to interface with it.

The steps in this approach are:

  • The application successfully registers with the framework

  • The application listens for the framework-generated OS event EVENT_IPSERVICES_CONFIG_CHANGE.

  • Upon receipt of this event notification, the application uses the framework's API to determine whether the administrator has changed its configuration, or if the IP address of one of its configurations is no longer available.

  • Depending on the information obtained from the framework, the application may continue to listen on the new configuration, or it may shut down gracefully.

  • Optionally, the application can change its IP/port configuration using the framework's API without the administrator's intervention.

  • When the application unloads, it de-registers with the framework.

Applications using the explicit interfacing mechanism should get the ipconfig.h header file from the Novell NDK, available at http://developer.novell.com/ndk .

APIs To Be Used

Here are the framework APIs that the application should use to carry out the steps outlined above.

IpMgmtRegisterApp(ServiceConfigEntry *)

Use this API to register applications with the framework. The following fields of the ServiceConfigEntry structure should be filled in by the application when registering:

  • versionInfo - This is the version of ipconfig.h that the application is using. This should be the same as IPMGMT_VERSION in the ipconfig.h header.

  • serviceName - This is the unique name of the application (should be less than 20 characters).

  • serviceDescription - This is a brief description of the application (should be less than 64 characters).

  • numIpAddrInfo - This specifies the number of configurations (IP address, port, protocol) that the application is using.

  • ipCfgInfo - This is a pointer to an array of IpAddressInfo structure. The array size should be numIpAddrInfo .

  • globalPolicy - Bit-wise ORing of the policies that are applicable to all configurations of the application. If no common policy is applied to all the configurations, the value should be zero. Policies supported are SKIPCR, IP_NOEDIT, and PORT_NOEDIT. For explanations of these policies, see CONFLICT_RESOLUTION_EXEMPT, ADDRESS_NOT_EDITABLE, and PORT_NOT_EDITABLE respectively under "Implicit Interfacing."

  • res_configEntry - This field should be NULL (it is reserved for future use).

  • cfgStatus - The framework fills this field once you register the application.

While registering, the application should also fill in the following fields of the IpAddressInfo structure:

  • ipAddrType - This is one of the enum values of IpAddressType. Support for DNS is restricted to the names present in the local server's etc/hosts file.

  • ipAddrCategory - The supported categories are:

    • IPDEFAULT - Default IP address of the server

    • IPPRIMARY - Primary IP address of the server

    • IPSECONDARY - Secondary IP address of the server

    • IPPRIVATE - Reserved for future use

  • protocol - This is one of the enum values of TransportType .

  • ipAddress.dnsname - This is the DNS name or IPv4 address in dotted notation. If the ipAddrCategory is IPDEFAULT, this field can be left empty; the framework will overwrite this field with server's default IP address.

  • portNum - This is a valid port number. It can be zero if the SKIPCR policy is set for this configuration.

  • cfgStatus - This should be zero.

  • localPolicy - This is a bit-wise ORing of policies for this configuration. If no policy is applied for this configuration, the value should be zero.

  • addressPortDescription - This is a brief description of this configuration; it can be empty also. If an application has multiple identical configurations (same IP address, port, and protocol), this description is required to distinguish between them.

  • ContextInformation - This field can be left empty, as the framework ignores it. An application can make use of this field to keep track of its previous configuration or any other information specific to this configuration.

  • res_ipEntry - This field is reserved for future use.

The value returned by IpMgmtRegisterApp() can be one of the following:

  • REGISTER_SUCCESS - The application has registered successfully.

  • REGISTERED_ALREADY - An application with the serviceName has already registered with the framework.

  • REGISTER_FAILURE - The application failed to register with the framework.

If the registration is successful, the cfgStatus field of the ServiceConfigEntry is set to one of the following values:

  • noError - The application's configurations are valid and none of them conflicts with another application's configuration.

  • portConflict - One of the configurations conflicts with another application's configuration.

If the registration fails, cfgStatus will have one of the following values:

  • invalidVersion - The version specified is not supported

  • invalidAppName - serviceName contains no characters, has more character than what is allowed, or contains only blank spaces.

  • invalidIpInfo - The type or category of the IP address in one of the configurations is invalid, or the IP address itself is invalid.

  • invalidPortInfo - The port value of one of the configurations is invalid.

  • otherErrors - serviceDescription contains more characters than what is allowed, or a wrong protocol is specified in one of the configurations.

IpMgmtGetCfgInfo(ServiceConfigEntry *)

Use this API to get the configuration information. To use this API, the application must have registered successfully with the framework; otherwise, the cfgStatus field will be set to invalidAppName . On event notification, the application should use this API to get its configuration information from the framework. This is done to see if the administrator has changed its configuration or if the IP address of one of its configurations is not available with the system anymore. In the later case, cfgStatus will be set to invalidIpInfo .

The application must fill in the following fields of ServiceConfigEntry :

  • versionInfo - This should be same as the one used for registration.

  • serviceName - This is the name for the application that was registered with the framework.

  • numIpAddrInfo - This specifies the number of configurations the application has registered with the framework.

  • ipCfgInfo - This is a pointer to an array of IpAddressInfo structure. The array size should be numIpAddrInfo .

IpMgmtChangeIPAddress(char *AppName, u_short Protocol, char * OldIp, u_short OldPort, char *NewIp, u_short NewPort)

Use this API to dynamically change a registered configuration. An application can use this API to change the configurations that it has registered with the framework without the administrator's intervention.

A newer version of this API is available as IpMgmtChangeIPAddress_V1dot3 (char *AppName, u_short Protocol, char * OldIp, u_short OldPort, char *NewIp, u_short NewPort, u_int policy, char *description) .

The parameters are:

  • AppName - This is the name of the application.

  • Protocol - This is the protocol used for the configuration.

  • OldIp - This is the old IP address of the configuration to be changed (in dotted notation).

  • OldPort - This is the old port number of the configuration to be changed.

  • NewIp - This is the new IP address for the configuration.

  • NewPort - This is the new port for the configuration

  • policy - This indicates any local policy registered for this configuration.

  • description - This is the addressPortDescription, if any, of this configuration.

    • Note: Only IP address and Port numbers can be changed using these APIs. If an application changes only one of these (say Port), the old and new values of the other should be same (OldIp and NewIp). An application can use the first API if it there is no addressPortDescription for the OldIp-OldPort configuration.

IpMgmtDeregister(char * AppName)

Use this API to de-register an application from the framework. The application needs to supply only the name ( serviceName ) that it registered with the framework.

The framework exports two more APIs which applications can make use of.

IpMgmtGetValidIPAddress(char *IPArray[], int IPCat[])

Use this API to get a list of the configured IP addresses on the server that the application can use. The arrays IPArray and IPCat should be of identical size (preferably 256). The return value of this API tells how many addresses are configured on the server. IPCat[] will have the address category of the corresponding IP address in IPArray[] .

IpMgmtGetDefaultIp(char *IpAddr)

Use this API for an application to get the default IP address of the server. The default IP address will be returned in the parameter IpAddr as an array of at least 20 characters.

NetWare 6.5 Applications Integrated Using Explicit Interfacing

The following applications included in NetWare 6.5 are already integrated with the IP Address Management Framework using the explicit interfacing mechanism.

  • DNS Server (eDirectory-integrated DNS Server)

  • NDPS Broker (host for brokered services SRS, ENS, and RMS)

  • Novell Licensing Service (NLS) usage metering

  • RSync NRM Management Utility (RSyncNRM)

  • SMS Storage Data Register (SMDR)

The framework-integrated applications listed in this AppNote are available starting with the October 2003 release of the NDK. The header files are available in the Server Protocol Libraries for C.

Conclusion

When a server's IP address changes, this change must be reflected in numerous configuration files and in several other places to ensure that applications continue to work. The IP Address Management Framework in NetWare 6.5 greatly simplifies this task for network administrators. With the framework, the administrator can make IP address changes from one centralized place. The administrator doesn't have to know where the application-specific configuration files reside. Moreover, the administrator no longer has to worry about incomplete IP address changes. For applications integrated with the framework, the administrator can better manage IP address/port configurations and easily resolve port conflicts.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates