Network Deployment (Distributed operating systems), v8.0 > Scripting the application serving environment (wsadmin) > Use properties files to manage system configuration > Apply properties files using wsadmin.sh

Apply portable properties files across multiple environments

Use wsadmin.sh to extract a properties file from one cell, modify environment-specific variables at the bottom of the extracted properties file, and then apply the modified properties file to another cell. Modifying environment-specific variables makes a properties file portable.

If the properties file to edit was created before v7.0.0.7 of the product, examine the properties file and see whether it contains an XMI id such as the following:

#
# SubSection 1.0 # Virtual Hosts
#
ResourceType=VirtualHost
ImplementingResourceType=VirtualHost
ResourceId=Cell=!{cellName}:VirtualHost=ID#VirtualHost_1
#
#Properties
#
name=default_host

EnvironmentVariablesSection
#Environment Variables
cellName=myNode04Cell

An XMI id is a unique identifier that a product previous to v7.0.0.7 generates when creating a configuration object. An XMI id can be different in another environment for the same object. In this example, a VirtualHost resource for default host in one environment has an XMI id of VirtualHost_1. In another environment, the XMI id might be a different value, such as VirtualHost_2. Properties files that have XMI identifiers are not portable. We cannot apply extracted properties that have XMI identifiers to another environment without first modifying the resource identifiers.

The same virtual host section in a properties file that has portable resource identifiers resembles the following:

#
# SubSection 1.0 # Virtual Hosts
#
ResourceType=VirtualHost
ImplementingResourceType=VirtualHost
ResourceId=Cell=!{cellName}:VirtualHost=default_host
#
#Properties
#
name=default_host

EnvironmentVariablesSection
#Environment Variables
cellName=myNode04Cell

In this example, name is used as a key attribute to identify the VirtualHost object uniquely within an environment. An object can have more than one key attribute to uniquely identify it among different instances of the same type.

We can apply properties files that have portable resource identifiers to another environment.

To extract a properties file so that it has portable resource identifiers, use the extractConfigProperties command with the PortablePropertiesFile option set to true. Properties files extracted with this option are portable. The extracted properties files do not identify each resource uniquely. A resource identifier might have one or more attribute name and value pairs; for example, a nodeName attribute identifies a node and a serverName attribute identifies a server.

By default, an extracted properties file is not portable. But a properties file extracted with the PortablePropertiesFile option set to true is portable.

After you extract a properties file with the PortablePropertiesFile option set to true, change the EnvironmentVariablesSection at the bottom of the properties file, copy the properties files to the target environment, and then run applyConfigProperties to apply the properties file to another cell.

We can also use interactive mode with these commands, as the following syntax demonstrates:

AdminTask.command_name('-interactive')

Procedure

1. Start wsadmin.sh.

   wsadmin -lang jython
   

2. Extract a properties file using the extractConfigProperties command with the PortablePropertiesFile option set to true.

   For example, to extract properties of a server named server1 to the server.props file in a portable format, run following wsadmin command:

   AdminTask.extractConfigProperties('[-propertiesFileName server.props -configData Server=server1
   -options [[PortablePropertiesFile true]] ]')
   

   If a properties file refers to a resource of type Server, Node, Application, Cluster, or AuthorizationGroup that does not exist in the target environment, consider setting the GenerateTemplates option to true:

   AdminTask.extractConfigProperties('[-propertiesFileName server.props -configData Server=
   -options [[GenerateTemplates true][PortablePropertiesFile true]] ]')
   

   When the GenerateTemplates option is used, the extracted properties file has properties sections that support creation of another object of the same type. By default this option is disabled.

3. Optional: Open an editor on the extracted properties file and examine the resource identifiers to ensure that they are portable.

   Portable identifiers do not identify each resource uniquely. The following examples show portable identifiers in various subsections of properties files.

   Example 1: Using an attribute name and a value for a resource identifier

   In this example, jndiName is a portable resource identifier that identifies a DataSource:

   #
   # SubSection 1.0.1.0 # DataSource attributes #
   Resou:rceType=DataSource
   ImplementingResourceType=JDBCProvider
   ResourceId=Cell=!{cellName}:Node=!{nodeName}:Server=!{serverName}:JDBCProvider=Derby JDBC
    Provider(XA):DataSource=jndiName#jdbc/DefaultEJBTimerDataSource
   

   Example 2: Using multiple attribute name and value pairs for a resource identifier

   In this example, the nodeName and serverName attributes together identify the coreGroupServer resource.

   #
   # SubSection 1.0.8.0 # CoreGroupServer Section
   #
   ResourceType=CoreGroupServer
   ImplementingResourceType=CoreGroup
   ResourceId=Cell=!{cellName}:CoreGroup=!{coreGroup}:CoreGroupServer=nodeName#myNode04,serverName#server1
   AttributeInfo=coreGroupServers
   
   

   Example 3: Singleton resource identifier

   In this example, there is only one Security object in the cell. Because the Security object is considered a singleton object, no attribute is required to identify this resource uniquely.

   #
   # SubSection 1.0 # Security Section
   #
   ResourceType=Security
   ImplementingResourceType=Security
   ResourceId=Cell=!{cellName}:Security=
   
   

   Some resources, such as JDBCProvider and ThreadPool, can be created with the same name multiple times. The name is the key attribute for these objects. Do not create multiple instances of these objects with the same name under a given scope.
4. Modify the extracted properties file as needed.

   • If the extracted portable properties file refers to a resource of type Server, Node, Application, Cluster, or AuthorizationGroup that does not exist in the other environment and the extractConfigProperties command was run with the GenerateTemplates option set to true, edit the properties file to enable creation of the resource.

     The GenerateTemplates option enables you to create another server that is similar to an existing server. For example, when server properties are extracted using this option, the extracted properties file has a template at the top of the file to create another server. The template section is skipped by default. If you set SKIP=false and then set the required properties to create a new object, the product creates a new object when applyConfigProperties is run and supplies the edited properties file. Because the following sections contain configuration properties of an existing server and those sections are processed when applyConfigProperties is run, the newly created server has the same configuration as the old server from which the properties file was extracted.

     We must modify the environment section to reflect the new server that is created by changing the nodeName, cellName and serverName variables.

     This option generates a template properties section in front of each of server, cluster, application, and authorization group section. The sections are disabled by default.

     For each object that does not exist in target environment, edit the section corresponding to that object. Insert proper properties values and remove SKIP=true. Set environment specific variables at the end of the properties file that reflect the new target environment.

   • Do not modify or delete properties that are used as keys to identify an object.

     If you modify or delete a key attribute in an object, then subsequent sections of the properties file must not reference the object again. The resource specified in the subsequent sections will not be found.

     For example, examine the virtual host properties in the following sections:

     ResourceType=VirtualHost
     ImplementingResourceType=VirtualHost
     ResourceId=Cell=!{cellName}:VirtualHost=admin_host
     #
     #Properties
     #
     name=admin_host #required
     #
     # SubSection 1.0.1 # MimeTypes section
     #
     ResourceType=VirtualHost
     ImplementingResourceType=VirtualHost
     ResourceId=Cell=!{cellName}:VirtualHost=admin_host
     AttributeInfo=mimeTypes(type,extensions)
     

     If name=admin_host is changed to name=my_host, the Mime Types section that has ResourceId==!{cellName}:VirtualHost=admin_host will not be able to find the resource specified by ResourceId because the name is changed in the previous section. Similarly, if name=admin_host is deleted, the Mime Types section will not be able to find the resource specified by ResourceId.

5. Validate the properties file.

   Run the validateConfigProperties command. See the topic on validating properties files.

6. Copy the extracted portable properties file to another environment.

7. If the extracted portable properties file refers to a resource of type Server, Node, Application, Cluster, or AuthorizationGroup that does not exist in the other environment and the extractConfigProperties command was not run with the GenerateTemplates option set to true, create the resource in the other environment.

   Because the properties file originally applied to a different environment, a resource identifier in the properties file might refer to a resource that does not exist in the target environment. If a resource of type Server, Node, Application, Cluster, or AuthorizationGroup does not exist in the target environment and the properties files does not enable creation of the resource, create the resource in the target environment before applying the properties for that resource. Also, an attribute might reference another resource. Ensure that all the referenced resources exist and, if necessary, create resources of type Server, Node, Application, Cluster, or AuthorizationGroup that are missing.

8. Apply the extracted portable properties file in the other environment using applyConfigProperties.

   For example, to apply the properties file server.props and generate a report named rep.txt, run following wsadmin command:

   AdminTask.applyConfigProperties('[-propertiesFileName server.props -reportFileName rep.txt]')
   

   If a resource specified in the properties file exists in the target environment and the property value specified in the properties file is the same as what is already set in the target environment, that property is skipped or not set in target environment. The product only applies the properties that are different from what is specified in the properties file.

   If a resource specified in the properties file does not exist in the target environment, the product creates a new resource and sets all the properties for the newly created resource from the values for the resource in the properties file. The product does not create resources of type Server, Node, Application, Cluster, or AuthorizationGroup unless the extractConfigProperties command was run with the GenerateTemplates option set to true and the properties file specifies one or more new resources of those types.

Results

The target environment is updated by the applied properties file.

What to do next

Save the changes to the configuration.
Extract properties files using wsadmin.sh
Validate properties files using wsadmin.sh
Apply properties files using wsadmin.sh
Use properties files to manage system configuration

Related

PropertiesBasedConfiguration command group using wsadmin.sh
Properties file syntax

+

Search Tips   |   Advanced Search