12 Using Configuration Files

Learn about the Oracle Communications Billing and Revenue Management (BRM) configuration and properties files, including where to find them and how to edit them.

Topics in this document:

• About Configuration Files

• Syntax for Configuration Entries

• Syntax for Facilities Module Entries

• Guidelines for Editing Java Properties Files

• Configuring BRM by Using the pin_bus_params Utility

• Configuring a Shared pin.conf File

• Preparing for Platform Migration by Using Variables in pin.conf Files

• About Oracle Wallet

• Viewing Configuration Entries in the Client Wallet

• Storing Configuration Entries for Java PCM Applications in Client Wallet

• Retrieving Configuration Entries from Client Wallet for Java PCM Applications

• Storing Configuration Entries for BRM PCM Applications in Client Wallet

• Retrieving Configuration Entries from Client Wallet for BRM PCM Applications

About Configuration Files

The primary purpose of configuration files is to enable the different components of BRM to communicate with each other (see "Connecting BRM Components"). The configuration files can also include other entries that let you increase performance and implement business policies.

• Most BRM components and utilities use configuration files (pin.conf).

• BRM Java programs use properties files (usually Infranet.properties).

  Any configuration entry that includes an application name, such as Infranet.pricing_tool.log.file, is specific to that application. Any other entry is a shared entry, applying to all applications. Any application-specific entry overrides a shared entry.

• BRM programs based on Perl scripts read configuration information from a file named pin.conf.pl.

Note:

By default, the BRM Installer stores configuration entries, including the sensitive information (such as database and account passwords), in the Oracle wallet and the BRM applications retrieve the data from the Oracle wallet. For more information, see "About Oracle Wallet".

You can use any text editor to edit configuration files.

Note:

Before you edit a configuration file, save a backup copy.

Some configuration files are write-protected. Before editing the file, remove that restriction. After you edit the file, restore the restriction.

Each configuration file includes specific, detailed information about how to edit each configuration entry in that file. To edit an entry, follow the guidelines provided for that entry.

To insert a comment, type a crosshatch (#) followed by the comment. BRM ignores all text on that line.

Configuration File Locations

The default location for a configuration file is the directory where the system process or program runs. Typical locations are:

• Directories inside the BRM_home/sys directory (for example, BRM_home/sys/cm/pin.conf).

• Directories inside the BRM_home/apps directory (for example, BRM_home/apps/pin_billd/pin.conf).

• In the application folder (for example, BRM_home/Application_home/Infranet.properties).

Syntax for Configuration Entries

Entries in a configuration file use the following syntax:

host_name     program     keyword     values

where:

• host_name is the name or IP address of the computer. To refer to the current computer, use a single hyphen (-). If several computers share the same configuration file, use the name of the current computer. In this case, BRM components, such as the Connection Manager (CM) or the Data Manager (DM), use only the entries that contain the host name on which they are started.

• program is the name of the program to which this entry applies. The program can be:

  • The name of the application (or custom application) or Facilities Module (FM), such as cm, pin_billd, or fm_bill. Use a specific name when the entry applies only to a single program.

  • nap (Network Application Program). Use nap when the entry applies to general BRM applications, which use the PCM_CONNECT and PCM_CONNECT_OPEN functions.

  • Blank or a single hyphen (-). The entry applies to any BRM function, such as pin_virtual_time.

• keyword is the name of the configuration entry.

• values is one or more parameters specific to the configuration entry. Values are separated by spaces.

A single configuration entry resembles the following example:

- cm   userid   0.0.0.1   /service   1

This entry applies to the Connection Manager (cm) on the local computer (-). The entry is called userid, and the three values associated with that entry are 0.0.0.1, /service, and 1.

Note:

Some configuration files have entries with userid and a database number, as shown here. BRM ignores the database number in these entries:

- cm   userid   0.0.0.1   /service   1

Syntax for Facilities Module Entries

The CM configuration file includes entries for Facilities Module (FM) that are linked to the CM at startup. Some of these entries are for the base set of FMs that are part of the standard release; other entries are for optional BRM components. You can also add entries for custom FMs.

Configuration entries for FMs use the following syntax:

- cm fm_module file_name initialization_table initialization_function tag

where:

• file_name is the path to the shared library file containing the functions that make up the FM. The file name has the .so extension on Oracle Linux and Oracle Solaris.

  Do not change this parameter unless you change the location of the file.

• initialization_table is the name of the configuration structure that maps each opcode to a function. Do not change this text for standard FMs.

• initialization_function is either a hyphen (-), meaning that no function is run when the CM is started, or the name of the function to be run at startup. Some FMs call optional initialization functions that you can use to configure the FM.

• tag identifies the FM to the CM. Each CM has an equivalent tag as part of the cm_ports configuration entry. Each FM with a matching tag is linked to that CM at startup. The default tag for the base set of FMs is pin. You can use other tags to define separate sets of FMs for multiple CMs on the same computer.

Note:

Some FMs depend on others. Never change the order of the base set of FMs in the CM configuration file.

Guidelines for Editing Java Properties Files

Java applications get configuration information from Java properties files instead of the pin.conf files that are used for C applications.

The BRM installation program uses information supplied by the installer to write configuration information to the properties files.

Each properties file includes specific, detailed information about how to edit each configuration entry in that file. To edit an entry, follow the guidelines provided with that entry.

You can add comments to properties files to help others understand the purpose of your entries. To insert a comment, type a crosshatch (#) followed by the comment. BRM ignores all text on the same line after the crosshatch.

Connection entries, failover entries, and other entries each have their own syntax considerations.

Connection Entry

The connection entry consists of a full URL to the BRM services. It takes one of two forms, depending on the type of login setting:

• For the Type 1 login setting, which requires a password, use the following format:

  pcp://user_name:password@host_name:port/service_object

  where:

  • user_name is the login name to use for connecting to BRM.

  • password is the password for the specified user name.

  • host_name is the name or IP address of the computer running the CM or Connection Manager Master Process (CMMP).

  • port is the TCP port number of the CM or CMMP on the host computer. The port number must match the corresponding cm_ports entry in the CM or CMMP configuration file.

  • service_object is the service type. The trailing number, “1," is the Portal object ID (POID) of the service.

  For example:

  infranet.connection=pcp://root.0.0.0.1:password@hostname:11960/service/admin_client

• For the Type 0 login setting, which does not require a password, use the following format:

  pcp://host_name:port/database_number/service_object

  where:

  • host_name is the name or IP address of the computer running the CM or Connection Manager Master Process (CMMP).

  • port is the TCP port number of the CM or CMMP on the host computer. The port number must match the corresponding cm_ports entry in the CM or CMMP configuration file.

  • database_number is the database number assigned to your BRM database when the DM was installed. For example, 0.0.0.1.

  • service_object is the service type. The trailing number, “1," is the Portal object ID (POID) of the service.

  For example:

  infranet.connection=pcp://hostname:11960/0.0.0.1/service/admin_client

Failover Entry

A failover entry refers to an alternate CM host that an application can use to connect to BRM if the main host, specified in the connection entry, is unavailable.

Use the following format:

infranet.failover.1=pcp://host_name:port

where:

• host_name is the name or IP address of the computer running the CM or CMMP.

• port is the TCP port number of the CM or CMMP on the host computer. The port number must match the corresponding cm_ports entry in the CM or CMMP configuration file.

  Note:

  user_name, password, and service_object for the alternative hosts are the same as for the main host and are not specified in failover entries.

Other Properties Entries

The flags used in the connection entry of the main Infranet.properties file are used by all the other properties entries, unless they are overridden.

Other entries that override these values for all your Java applications use the following format:

infranet.entry.specific_entries

The Infranet.properties file also contains entries specific to particular Java applications, in the following format:

infranet.application.specific_entries

Configuring BRM by Using the pin_bus_params Utility

As part of the BRM installation, a standard group of /config/business_params objects is added to the BRM database. These objects contain all the business parameters normally used by BRM. In their default state, these parameters typically disable optional features and direct BRM to use behaviors optimal for most users. However, your business might require optional features or alternative BRM behaviors. Or you might want to add business parameters or parameter classes that are not part of BRM.

If so, use the pin_bus_params utility to perform those tasks. This utility has the following capabilities:

• Retrieving: Use the utility to retrieve the contents of an existing /config/business_params object in your BRM installation and translate it into an XML file that you can edit.

• Loading: Use the utility to load the contents of an XML file that contains business parameters into an existing /config/business_params object or to create entirely new objects.

You can use the XML file created during retrieval to add new parameters for existing classes or to create an entirely new class of parameters. When you use the utility to load the XML file into the /config/business_params object, BRM adds the new parameters to your parameter configuration, and these parameters can be called from custom code. For information on adding new parameters and classes, see BRM Developer's Guide.

Retrieving /config/business_params Objects

To retrieve a /config/business_params object, run the following command:

pin_bus_params -r ParameterClassTag bus_params_ParameterClassName.xml

This command retrieves the /config/business_params object for the specified class into the specified XML file. Consider the following when retrieving business parameters:

• To retrieve a specific parameter, you must know which parameter class it belongs to. The resulting XML file for each class is short so you can quickly locate specific parameters within the class.

• Because you retrieve one parameter class at a time, you can edit parameters for a single parameter class without affecting any other parameter classes. BRM overwrites only the /config/business_params object whose parameter class appears in the resulting XML file, so the overall BRM business parameter configuration remains stable.

• To update more than one parameter class, you must perform multiple retrievals and loads, one for each class.

• You can create a library of class-based business parameter files and individually reload modified versions of these files only when needed.

Loading /config/business_params Objects

To load parameters into /config/business_params objects, use the following command:

pin_bus_params bus_params_ParameterClassName.xml

This command finds the /config/business_params object for the parameter class in the XML file and overwrites the object with the new parameters.

Configuring a Shared pin.conf File

If you run several BRM applications and processes on one computer, they can share a single configuration file. To set up a shared configuration file:

1. Combine configuration entries for each BRM component into a single pin.conf file.

2. Save that file to the BRM_home directory.

3. For each BRM component that uses the shared configuration file, move its specific configuration file to a backup location or rename the file.

When BRM starts any BRM application, component, or process, it searches for the appropriate pin.conf file in the following directories in the order shown:

1. The current directory.

2. The system /etc directory.

   Note:

   The /etc directory is included in the search path for backward compatibility.

3. If the PIN_HOME environment variable is defined, the BRM_home/config directory.

   Note:

   If the PIN_HOME environment variable is not defined, BRM skips this part of the search.

Preparing for Platform Migration by Using Variables in pin.conf Files

You can reference certain system environment variables in pin.conf configuration files. These references can facilitate future migration of the pin.conf files to BRM implementations on other platforms.

For information about environment variables, see BRM Installation Guide.

Table 12-1 shows the environment variables that can be referenced in BRM configuration files (pin.conf).

Table 12-1 BRM Configuration File Environment Variables

Environment Variable	Reference in pin.conf Files
PIN_HOME	${PIN_HOME}
PIN_LOG_DIR	${PIN_LOG_DIR}
LIBRARYEXTENSION	${LIBRARYEXTENSION}
LIBRARYPREFIX	${LIBRARYPREFIX}

Sample pin.conf file with environment variable references:

- - pin_virtual_time ${PIN_HOME}/lib/pin_virtual_time_file
- fm_rate tax_supplier_map ${PIN_HOME}/sys/cm/tax_supplier.map
- cm fm_module ${PIN_HOME}/lib/fm_utils/${LIBRARYEXTENSION} fm_utils_config fm_utils_init pin
- cm fm_module ${PIN_HOME}/lib/fm_delivery/${LIBRARYEXTENSION} fm_delivery_config - pin

About Oracle Wallet

By default, the BRM Installer stores configuration entries, including sensitive information (such as database and account passwords), in Oracle wallet and BRM applications retrieve the data from Oracle wallet. However, if the configuration entries are also stored in the Infranet.properties and pin.conf configuration files, the BRM applications retrieve the data from the configuration files. BRM applications automatically decrypt the encrypted passwords when retrieving them from the configuration files.

To view the list of configuration entries in the Oracle wallet, see "Viewing Configuration Entries in the Client Wallet".

You can store and retrieve configuration entries from the Oracle wallet by using the pin_crypt_app and pin_config_editor utilities. You can use these utilities to update the configuration entries in the Oracle wallet; for example, to change connection details, log level, or a password.

Note:

If you change the database password in the Oracle wallet, ensure that you change the database password in all the other configuration entries in the Oracle wallet.

For more information, see:

• Storing Configuration Entries for Java PCM Applications in Client Wallet

• Retrieving Configuration Entries from Client Wallet for Java PCM Applications

• Storing Configuration Entries for BRM PCM Applications in Client Wallet

• Retrieving Configuration Entries from Client Wallet for BRM PCM Applications

Viewing Configuration Entries in the Client Wallet

To view entries in the client wallet:

1. Go to the BRM_home/bin directory.

2. Run the following command:

   orapki wallet display -wallet client

A list of configuration entries that are stored in the client wallet is displayed.

Storing Configuration Entries for Java PCM Applications in Client Wallet

To store a configuration entry for the Java PCM applications in the client wallet:

1. Go to the BRM_home/bin directory.

2. Do one of the following:

   On Unix:

   • To store a value, run the following command:

     pin_config_editor -setconf -wallet clientWalletLocation –parameter configEntry -value value

     where:

     • clientWalletLocation is the path to the client wallet.

     • configEntry is the configuration entry in the client wallet.

     • value is the appropriate value for the respective entry in the client wallet.

     For example, running the following command stores the BRM log level as 1 in the client wallet:

     pin_config_editor -setconf -wallet opt/brm_wallet –parameter infranet.log.level -value 1

   • To store a password, run the following command:

     pin_config_editor -setconf -wallet clientWalletLocation –parameter configEntry [-pwd]

     For example, running the following command stores the password in the client wallet:

     pin_config_editor -setconf -wallet opt/brm_wallet –parameter infranet.cmt.passwd -pwd

   On Windows:

   • To store a value, run the following command:

     java -cp ".;oraclepkijarLocation;cetjarLocation com.portal.cet.ConfigEditor  -setconf -wallet clientWalletLocation –parameter configEntry -value value

     For example, running the following command stores the BRM log level as 1 in the client wallet:

     java -cp ".;BC\lib\oraclepki.jar;BC\lib\cet.jar" com.portal.cet.configEditor -setconf -wallet opt/brm_wallet -parameter infranet.log.level -value 1

   • To store a password, run the following command:

     java -cp ".;oraclepkijarLocation;cetjarLocation com.portal.cet.ConfigEditor  -setconf -wallet clientWalletLocation –parameter configEntry [-pwd]

     For example, running the following command stores the BRM password in the client wallet:

     java -cp ".;BC\lib\oraclepki.jar;BC\lib\cet.jar" com.portal.cet.configEditor -setconf -wallet opt/brm_wallet -parameter infranet.cmt.passwd -pwd

   Enter the password for the wallet prompt appears.

3. Enter the client wallet password.

   When you run the utility with the –pwd parameter, the Enter the password prompt appears.

4. Enter the password to be stored.

   Note:

   If you want to store the encrypted password, enter the encrypted password at the prompt.

The password is stored in the client wallet.

Retrieving Configuration Entries from Client Wallet for Java PCM Applications

To retrieve a configuration entry from the client wallet for Java PCM applications:

1. Go to the BRM_home/bin directory.

2. Do one of the following:

   On Unix:

   • To retrieve a value, run the following command:

     pin_config_editor -getconf -wallet clientWalletLocation –parameter configEntry

     For example, running the following command retrieves the value stored for the infranet.connection entry:

     pin_config_editor -getconf -wallet -wallet opt/brm_wallet -parameter infranet.connection 

   On Windows:

   • To retrieve a value, run the following command:

     java -cp ".;oraclepkijarLocation;cetjarLocation com.portal.cet.ConfigEditor -getconf -wallet clientWalletLocation -parameter configEntry

     For example, running the following command retrieves value stored for the infranet.connection entry:

     java -cp ".;BC\lib\oraclepki.jar;BC\lib\cet.jar" com.portal.cet.ConfigEditor -getconf -wallet  opt/brm_wallet -parameter infranet.connection

   The value of the configuration entry is displayed.

Storing Configuration Entries for BRM PCM Applications in Client Wallet

For BRM PCM applications, you typically store the database user ID, database password, and encryption algorithm in the client wallet by using the pin_crypt_app utility. For information about the utility's syntax and parameters, see "pin_crypt_app" in BRM Developer's Guide.

To store a configuration entry and value for BRM PCM applications in your client wallet, go to the BRM_home/bin directory and do the following:

1. On Unix, run the following command:

   pin_crypt_app -setconf -wallet clientWalletLocation -program program -parameter configEntry -value value

   where:

   • clientWalletLocation is the full path to the client wallet.

   • program is the BRM component to which the configuration entry belongs. For example, enter dm if the configuration entry is in the DM pin.conf file, enter cm if the configuration entry is in the CM pin.conf file, and so on.

   • configEntry is the name of configuration entry to store in the client wallet, such as sm_id or crypt for the DM pin.conf file.

   • value is the value for configEntry.

   For example, to store the DM pin.conf file entry "- dm sm_id pin01" in the client wallet:

   pin_crypt_app -setconf -wallet $PIN_HOME/opt/brm_wallet -program dm –parameter sm_id -value pin01

2. On Windows, run the following command:

   java -cp ".;oraclepkijarLocation;cetjarLocation com.portal.cet.PinCrypt -setconf -wallet clientWalletLocation -program program -parameter configEntry -value value

   For example, to store the pin_billd pin.conf file entry "- nap login_name myName" in the client wallet:

   java -cp ".;BC\lib\oraclepki.jar;BC\lib\cet.jar" com.portal.cet.PinCrypt -setconf -wallet c:\pin\wallet\client -program pin_billd -parameter login_name -value myName

3. At the Enter the wallet password prompt, enter your client wallet password.

The utility parameter creates a new entry in your client wallet if one does not exist. If an entry already exists, it overwrites the value.

To store a password for BRM PCM applications in your client wallet, go to the BRM_home/bin directory and do the following:

1. On Unix, run the following command:

   pin_crypt_app -setconf -wallet clientWalletLocation -program program -parameter configEntry -pwd

   For example, to store the DM pin.conf file entry "- dm sm_pw password" in the client wallet:

   pin_crypt_app -setconf -wallet $PIN_HOME/opt/brm_wallet -program dm –parameter sm_pw -pwd

2. On Windows, run the following command:

   java -cp ".;oraclepkijarLocation;cetjarLocation com.portal.cet.PinCrypt -setconf -wallet clientWalletLocation -program program -parameter configEntry -pwd

   For example, to store the pin_billd pin.conf file entry "- nap login_pw myName" in the client wallet:

   java -cp ".;oraclepkijarLocation;cetjarLocation com.portal.cet.PinCrypt -setconf -wallet c:\pin\wallet\client -program pin_billd –parameter login_pw -pwd

3. At the Enter the wallet password prompt, enter your client wallet password.

4. At the Enter value to be stored in the wallet prompt, enter the password to store in the wallet.

   Note:

   If you want to store an encrypted password, enter the encrypted password at the prompt.

The password is stored in the client wallet.

Retrieving Configuration Entries from Client Wallet for BRM PCM Applications

To retrieve a configuration entry from the client wallet for BRM PCM applications:

1. Go to the BRM_home/bin directory.

2. On Unix, run this command:

   pin_crypt_app -getconf -wallet clientWalletLocation -program program -parameter configEntry

   where:

   • clientWalletLocation is the full path to the client wallet.

   • program is the BRM component to which the configuration entry belongs. For example, enter dm if the configuration entry is in the DM pin.conf file, enter cm if the configuration entry is in the CM pin.conf file, and so on.

   • configEntry is the name of the configuration entry to retrieve from the client wallet, such as sm_id or crypt for the DM pin.conf file.

   For example, to retrieve the sm_id value for the DM pin.conf file:

   pin_crypt_app -getconf -wallet $PIN_HOME/opt/brm_wallet -program dm -parameter sm_id

3. On Windows, run the following command:

   java -cp ".;oraclepkijarLocation;cetjarLocation" com.portal.cet.PinCrypt -getconf -wallet clientWalletLocation -program program -parameter configEntry

   For example, to retrieve the sm_pw value for the DM pin.conf file:

   java -cp ".;BC\lib\oraclepki.jar;BC\lib\cet.jar" com.portal.cet.PinCrypt -getconf -wallet c:\pin\wallet\client -program dm -parameter sm_pw

4. At the Enter the wallet password prompt, enter your client wallet password.

The value of the configuration entry is displayed.