+

Search Tips   |   Advanced Search

Set up the DataPower appliance manager using scripting

Use the application server and the wsadmin tool to set up, query, and administer your configured DataPower appliances in the DataPower appliance manager. DataPower appliances are purpose-built, easy-to-deploy network devices that simplify, help secure, and accelerate your XML and Web services deployments.

Before beginning, verify that each appliance to manage has a 3.6.0.4 or higher level of firmware. Additionally, verify that the Appliance Management Protocol (AMP) endpoint is enabled for each appliance. If the XML Management interface AMP endpoint was disabled during installation, use the DataPower WebGUI to enable the AMP endpoint.

(ZOS) The DataPower root certificate, which is located at app_server_root/profiles/profile/etc/DataPower-root-ca-cert.pem, is shipped as part of the default keystore. During profile creation, this certificate can only be added to file-based keystores. Because SAF keyrings are not file-based, the certificate must be added to the RACF keystore manually.

Use this topic to add DataPower appliances to the DataPower appliance manager, create managed sets, and assign appliances to managed sets in your environment. We can add as many or as few appliances and managed sets as we need.

The examples in this topic set up the DataPower appliance manager to administer two managed sets of DataPower appliances, update the appliance firmware, and configure domains. The first managed set represents a production environment that uses three DataPower appliances. The second managed set represents a test environment that uses one DataPower appliance. By setting up this configuration, we can use the second managed set in the test environment to modify and test the DataPower appliance settings before importing the test appliance domain to the production environment. Modify the examples to best configure the environment.

To view additional information and examples for the commands in this topic, refer to the documentation for the dpManagerCommands .


Tasks

  1. Start the wsadmin scripting tool.

  2. Add the DataPower appliances to the DataPower appliance manager configuration.

    Use the dpAddAppliance command to add appliances to the DataPower appliance manager. Each command invocation creates a task in the DataPower appliance manager and returns the task identifier as command output. The following commands add the ProductionAppliance1, ProductionAppliance2, ProductionAppliance3, and TestAppliance1 appliances in the configuration and assign the task identifier to a specific variable: 

    app1Task=AdminTask.dpAddAppliance('[-hostname ProductionAppliance1.ibm.com -hlmPort 
 5550 -name ProductionAppliance1 -userId admin -password mypassword]') 
app2Task=AdminTask.dpAddAppliance('[-hostname ProductionAppliance2.ibm.com -hlmPort 5550 -name 
 ProductionAppliance2 -userId admin -password mypassword]')
app3Task=AdminTask.dpAddAppliance('[-hostname ProductionAppliance3.ibm.com -hlmPort 
 5550 -name ProductionAppliance3 -userId admin -password mypassword]') 
testAppTask=AdminTask.dpAddAppliance('[-hostname TestAppliance1.ibm.com -hlmPort 5550 -name 
 TestAppliance1 -userId admin -password mypassword]')

    The DataPower appliance manager submits tasks to add the appliances to the configuration. If the task uses a resource another task is using, the system queues the new task until the other task is complete. Use the following example commands to monitor the status of the tasks: 

    param = '-taskId '+app1Task; print AdminTask.dpGetTask(param)

    The command returns the task information and the appliance ID of the appliance as the value of the result attribute, as shown in the following sample output: 

    [ [currentStep 0] [totalSteps 0] [taskDescription [Add appliance ProductionAppliance1 to 
 the DataPower appliance manager]] [currentStepTimestamp [Jan 18, 2008 2:32:25 PM]] 
 [creationDate [Jan 18, 2008 2:32:23 PM]] 
 [taskStatus 2] [taskId 1] [hasError false] [createdByUser defaultWIMFileBasedRealm/admin]
 [isComplete true] [result [00605  20356]] ]

    After the system adds each appliance to the configuration, the appliances are unmanaged appliances. To manage each appliance, assign each appliance to a managed set.

  3. Add the firmware version to the DataPower appliance manager.

    Use the dpAddFirmwareVersion command to add the firmware version that the ProductionAppliance2 appliance uses to the DataPower appliance manager. The ProductionAppliance2 appliance is set as the master appliance later in this topic. Therefore, each appliance in the same managed set as the ProductionAppliance2 appliance will use the same firmware version. 

    firmwareTask=AdminTask.dpAddFirmwareVersion('[-file 
   "C:\temp\dptestFW\dev-xs-143863-3_6_0_15.scrypt2" -userComment "my new firmware"]')

    Do not use the DataPower 3.6.0.28, 3.6.0.29, or 3.6.0.30 level of firmware for a managed set.

    Typically, when we create a managed set of DataPower appliances, the DataPower appliance manager completes the following process:

    • Creates a shareable appliance settings version from the shareable appliance settings on the master appliance.
    • Synchronizes the settings across the managed set. This synchronization process is repeated whenever the shareable appliance settings change on the master appliance.

    Similarly, when a domain is added to a managed set in the DataPower appliance manager, the DataPower appliance manager typically completes the following process:

    • Creates a domain version from the domain on the master appliance.
    • Synchronizes the domain version across the managed set. This synchronization process is repeated every time that the domain changes on the master appliance.

    If we use the DataPower 3.6.0.28, 3.6.0.29, or 3.6.0.30 level of firmware for a managed set, the firmware level might cause the DataPower appliance manager to unnecessarily create new shareable appliance settings versions, or domain versions, and then synchronize these new versions across the managed set.

    The command submits a task to the system to add the firmware, and assigns the task identifier to the firmwareTask variable.

  4. Add managed sets in your DataPower appliance manager configuration.

    Use the dpAddManagedSet command to add managed sets to the DataPower appliance manager. Each command invocation creates a task in the DataPower appliance manager and returns the task identifier as command output. The following commands create the testSet and productionSet managed sets in the configuration: 

    AdminTask.dpAddManagedSet('-name testSet') 
AdminTask.dpAddManagedSet('-name productionSet')

    The command submits the task to the DataPower appliance manager.

  5. Verify the system added each appliance and managed set to the configuration.

    The dpAddAppliance and dpAddManagedSet commands might not complete immediately. Before adding the appliances to the managed sets, verify the system completed the tasks from the previous commands. If we did not set the command output to variables in the previous steps, use the following command to display each task identifier from the DataPower appliance manager: 

    AdminTask.dpGetAllTaskIds()
    Otherwise, use the dpGetTask command to determine whether the system has completed the tasks. Run the command for each task, as the following commands demonstrate: 
    AdminTask.dpGetTask('-taskId '+app1Task) 
AdminTask.dpGetTask('-taskId '+app2Task) 
AdminTask.dpGetTask('-taskId '+app3Task) 
AdminTask.dpGetTask('-taskId '+testAppTask) 
AdminTask.dpGetTask('-taskId '+prodSetTask) 
AdminTask.dpGetTask('-taskId '+firmwareTask) 
AdminTask.dpGetTask('-taskId '+prodSetTask)

    The commands return information about the asynchronous task of interest. The isComplete attribute displays a value of true if the task is complete. If it is not complete, note the value for the taskStatus attribute. If the returned value is 0, then the task is in a queue and the system has not started the task. If the returned value is 1, then the task is in progress. If the returned value is 2, then the task completed successfully. If the returned value is 3, then the task experienced an exception.

    For descriptions of the additional attributes that the command returns, see the documentation for the dpManagerCommands command group for the AdminTask object.

  6. Assign the production appliances to the production managed set.

    To assign appliances to the managed set, we must know the appliance IDs of the appliances of interest. Use the dpGetAllApplianceIds command to display the appliance IDs of each appliance in the configuration, as the following example demonstrates: 

    AdminTask.dpGetAllApplianceIds()

    Use the dpGetAppliance command to display additional information for a specific appliance ID: 

    AdminTask.dpGetAppliance('[-applianceId "00605 20356"]')

    Use the dpManageAppliance command to add each appliance to the managed set, specifying the appliance ID of each appliance to add to the managed set.

    To assign multiple appliances to a managed set, each appliance must be the same appliance type, such as XI50 or XS40, and model type. Additionally, the appliances must have the same required features installed. By verifying that each appliance is exactly the same, you ensure that the DataPower appliance manager can synchronize the same firmware, domains, and settings for each appliance in the managed set.

    The following command examples add the ProductionAppliance1, ProductionAppliance2, and ProductionAppliance3 appliances to the productionSet managed set, and specify the ProductionAppliance2 appliance as the master appliance. If we do not specify an appliance as the master appliance, the system automatically assigns the first appliance in the managed set as the master appliance. 

    manageTask1=AdminTask.dpManageAppliance('[-managedSetId productionSet -applianceId "00605 20351"]') 
manageTask2=AdminTask.dpManageAppliance('[-managedSetId productionSet -applianceId "00605 20352" -asMaster]') 
manageTask3=AdminTask.dpManageAppliance('[-managedSetId productionSet -applianceId "00605 20353"]')

    The command submits a task to the system and sets the corresponding task identifiers to the manageTask1, manageTask2, and manageTask3 variables.

  7. Assign the test appliance to the test managed set.

    The following command uses the dpManageAppliance command to add the TestAppliance1 appliance to the testSet managed set, specifying the appliance ID of the TestAppliance1 appliance: 

    manageTask4=AdminTask.dpManageAppliance('[-managedSetId testSet -applianceId "00605 20354"]')

    The command submits a task to the system and sets the corresponding task identifier to the manageTask4 variable.

  8. Verify the system added the appliances to the managed sets.

    Use the dpGetTask command to determine the status of the manageTask1, manageTask2, manageTask3, and manageTask4 tasks before continuing to configure the DataPower appliance manager.

A test environment managed set and a production environment managed set exist in the DataPower appliance manager configuration in this example. The test environment managed set manages the TestAppliance1 appliance. The production environment managed set manages the ProductionAppliance1, ProductionAppliance2, and ProductionAppliance3 appliances. Each appliance in both managed sets uses the default domain.


What to do next

Use the DataPower WebGUI to set up domains for the testAppliance1 appliance in the test environment if the domains do not already exist. After configuring and testing the domains, we can use the wsadmin tool to copy the test environment appliance configuration to the production environment managed set.

You can also use the wsadmin tool to manage appliances, firmware, domains, managed sets, and appliance-specific settings. Additionally, the system creates versions of domains, firmware, and appliance-specific settings. Use the wsadmin tool to modify the current version, or to revert to previous versions of domains, firmware, and appliance-specific settings.


Related:

  • WebSphere DataPower appliance manager overview
  • Secure Socket Layer communication with DataPower
  • Copying DataPower appliance domains between managed sets using scripting
  • Update firmware versions for DataPower appliances using scripting
  • Administer managed domains, firmware, and settings versions using scripting
  • Use the DataPower appliance manager
  • Add DataPower appliances to the DataPower appliance manager
  • Administer DataPower appliance domains
  • dpManagerCommands