Command-line PureApplication

+

Search Tips   |   Advanced Search

1. Command-line interface overview
2. Download the CLI
3. Invoke the CLI
4. Get help on the CLI
   1. Resolve CLI errors when using multi-byte character sets
   2. Exception encountered when starting CLI
5. Use the command line interface for the system console
   1. Help information
   2. List all IP groups
   3. List IP groups by filters
   4. Create an IP group
   5. Add addresses to an IP group
   6. List addresses by filters
   7. Remove an address from the IP group
   8. Delete an IP group
   9. Update multiple fields of an IP group
   10. Set cloud group
   11. List all cloud groups
   12. List cloud groups by filter
   13. Create a cloud group
   14. List virtual machine configurations in the cloud group
   15. Create a virtual machine configuration in the cloud group
   16. Delete a volume configuration
   17. Create a volume configuration in the cloud group
   18. Delete a virtual machine
   19. Delete a virtual machine configuration
   20. List volume configurations in the cloud group
   21. Delete a cloud group
   22. Add a compute node
   23. Remove a compute node
   24. List virtual appliances
   25. Create a virtual appliance
   26. Retrieve a virtual appliance
   27. Delete a virtual appliance
   28. Export a virtual appliance
   29. List storage volumes
   30. Create a storage volume
   31. Retrieve a storage volume
   32. Delete a storage volume
   33. List virtual machines
   34. Start virtual machine
   35. Stop virtual machine
   36. Restart virtual machine
   37. Capture virtual machine as virtual appliance
   38. Add an IP address to a virtual machine
   39. Delete an IP address from virtual machine
   40. Mount volumes to a virtual machine
   41. Unmount volumes from virtual machine
   42. Create a virtual machine
   43. List compute nodes
   44. Start compute node
   45. Power on compute node
   46. Power off compute node
   47. Quiesce compute node
   48. Maintain compute node
   49. List network devices
   50. List groups
   51. Create a group
   52. Update a group
   53. Retrieve a group
   54. Delete a group
   55. Add the user to a group
   56. Remove the user from a group
   57. List the roles of the group
   58. Add new roles to the group
   59. Remove a role from the group
   60. List Users
   61. Create a user
   62. Update a user
   63. Retrieve a user
   64. Delete a user
   65. Remove a user from the group
   66. List the roles of a user
   67. Add a new role to the user
   68. Remove roles from the user
   69. List all jobs
   70. Delete a job
   71. List all events
   72. Delete an event
   73. List LED status
   74. List LED status of a specific status type
   75. Obtain a particular LED by its name
   76. Obtain a particular vendor information with its serial number
   77. List vendor information
   78. List vendor information of a specific vendor
   79. List all system logs
   80. Obtain a single system log info
   81. Download a single system log by its ID
   82. Create a new system log
   83. List all trace settings
   84. Create a new trace setting
   85. Delete an existing trace setting
   86. Change the trace level of an existing trace setting
   87. List all auditing records
   88. Retrieve specific auditing record information
   89. Download a specific auditing record package
   90. Retrieve auditing utilization
   91. Create a new record package
   92. Get current external storage server configuration
   93. Retrieve system public key for auditing
   94. List all DNS servers
   95. Add DNS servers
   96. Remove a DNS server
   97. List all NTP servers
   98. Add NTP servers
   99. Remove an NTP server
   100. List SNMP information
   101. Set system information
   102. Create trap destination
   103. Delete a trap destination
   104. List the ACL of a resource
   105. Get the ACL of a given user or group
   106. Assign ACL to a given user or group
   107. Delete ACL of a given user of group
   108. List current LDAP setting
   109. Change LDAP setting
   110. Accept LDAP certificate
6. Use the CLI for databases
7. Use the command line interface for the workload console
   1. Audit logging CLI reference
   2. AddOn CLI reference
   3. Use the CLI for applications
      • Pattern type CLI
      • Virtual application pattern CLI reference
      • Virtual application instance CLI reference
      • Shared service instance CLI reference
   4. Emergency fix CLI reference
   5. Environment profile cloud IP groups on the CLI
   6. Environment profile clouds on the CLI
   7. Environment profiles CLI reference
   8. Ethernet interface management CLI reference
   9. Firmware management CLI reference
   10. IP CLI reference
   11. License management CLI reference
   12. Maintenance CLI reference
   13. Pattern CLI reference
       • Export virtual system patterns
       • Import virtual system patterns
       • Patterns on the CLI
       • Pattern parts on the CLI
       • Pattern scripts on the CLI
       • Parts on the CLI
   14. Plug-in CLI reference
   15. Power CLI reference
   16. Use the CLI for problem determination
   17. Script package CLI reference
   18. Virtual images CLI reference
   19. Virtual machines on the CLI
   20. Virtual system instances CLI reference
8. Use the CLI for problem determination
9. Snap shots on the CLI
10. Resources, resource collections, and methods
    1. Resources on the command line
    2. Resource collections on the command line
    3. Resource methods on the CLI
    4. Resource collections methods on the CLI
    5. Wizard objects on the CLI
    6. ACL object
11. Additional CLI utilities

Use the command-line interface

To perform administrative functions in PureApplication System, you can download the command-line interface from the system onto a local machine. You can then run the CLI from the local machine.

In the CLI examples, >>> denotes the Python command prompt, meaning the three greater than symbols together in these examples, >>>, precede code that you enter.

Command-line interface overview

The command-line interface runs Python scripts or individual Python commands.

If you are migrating to IBM PureApplication System W1500 from a different model, you must download the CLI code from the Welcome page of PureApplication System.

The IBM PureApplication System W1500 CLI provides a scripting environment based on Jython. Jython is the Java-based implementation of Python. In addition to commands specific to PureApplication System, you can also issue Python commands at the command prompt. To manage PureApplication System with the CLI, you can download the CLI to any machine and then point to where PureApplication System is running. You can use the CLI on Windows and Linux operating systems.

Using the PureApplication System CLI, you can manage a IBM PureApplication System remotely. The CLI communicates with the IBM PureApplication System over a hypertext transfer protocol secure (HTTPS) session. The CLI does not cache updates and has only minimal caching for reads. If the machine on which the CLI is running loses connectivity to port 443 of the system, you can perform only rudimentary operations.

The Jython interpreter included with the PureApplication System CLI implements some of the Python 2.5.1 language. The CLI uses the Jython interpreter to help you manage the IBM PureApplication System. In addition to the standard Jython libraries, the CLI provides functions and classes to help you manage the IBM PureApplication System.

The CLI can run in both interactive and batch modes.

Each of these methods of passing commands to the CLI supports the same Jython scripting language.

For more information about how to invoke the CLI, specify the --help parameter to the deployer or deployer.bat command.

Download the command-line interface

Download and use the command-line interface on a local machine to complete administrative functions for the product.

Install JRE v6 on the machine on which you run the CLI. The CLI is currently supported on Windows and Linux systems.

1. Download the CLI from the user interface. From the Welcome page, click...
   Download tools | Download command-line tool

2. Save the ZIP file to your local hard disk drive.

3. Extract the contents of the ZIP file to a directory on your hard disk. When extracted, a single directory called pure.cli is created.

4. Ensure that either the JAVA_HOME or the PATH environment variable is set to the location of your JRE.

5. For Windows Server 2003 or 2008, create file...

   pure.cli/lib/<version>/registry

   ...with the following line...

   python.os=nt

   This causes Jython to bypass the normal OS detection logic and treat the system as a Windows machine.

   The <version> directory matches the firmware level of the product from which the CLI was downloaded. If you use this CLI installation to communicate with different firmware levels, then there is one subdirectory under the /lib directory for each of these firmware levels. You must copy the registry file into each of these subdirectories, for example...

   pure.cli/lib/3.0.0.0-12345/registry

Now that you have installed the CLI, you can verify the installation by running the shell script (pure.bat on Windows and pure on Linux) from the pure.cli/bin directory.

Invoke the command-line interface

To perform administrative functions for system, you can invoke the command-line interface in either interactive mode or batch mode from a local machine running either Windows or Linux operating systems.

Download and extract the CLI. If you recently upgraded the system, download the new version of the CLI. Downloading a new version of the CLI ensures new functionality works as expected and you also get the latest samples.

The PureApplication System CLI is invoked on your local machine. You can run the CLI in interactive mode or in batch mode.

A CLI session uses the timeout value specified on the system. When a user session expires, they are prompted to re-enter their ID and password. If the DEPLOYER_REAUTHENTICATE environment variable is set, a new session is automatically started for the user when an existing session expires. If the userid and password entered to start a session are not correct, then you are re-prompted for new values.

To invoke the CLI in interactive mode.

-u <userID>

User ID used to authenticate to the system. Use the same user ID and password that you use to log on to the system GUI.

-p <password>

Password used to authenticate to the system. Use the same user ID and password that you use to log on to the system GUI. You are not required to specify a password to access the help for the CLI.

-h <hostName>

Host name or the IP address of the system. If you specify this option, do not use the URL to access the Web interface. If this parameter is not specified, the CLI uses the value of the host_name environment variable to determine the host name.

-a

Automatically accepts the certificates from the system. You can also format the parameter as --acceptcert.

Usage example

pure -h <hostName> \
     -u <userID> \
     -p <password> \
     --acceptcert

Invoke the CLI in batch mode. Use in addition to parameters used to start CLI in interactive mode:

-c <command>

Passes a command to the command line to be run. You can specify this option multiple times to run multiple commands. If the command is a Jython expression, it is evaluated and the CLI displays the result. If the command is a Jython statement, it is run but no output is generated unless the statement itself causes output to be generated.

Do not specify this parameter to run the CLI in interactive mode.

-f <script_file> <arg>*

Results in the command line running the specified Jython script file with the specified arguments. Any arguments following the script file name are passed to the Jython script. Only one -f parameter can be specified on the command line.

Usage example

pure -h <hostName> \
     -u <userID> \
     -p <password> \
     --acceptcert \
     -c deployer.patterns

pure -h <hostName> \
     -u <userID> \
     -p <password> \
     --acceptcert \
     -f /SOAPolicyLoader/pureCLI/pure.cli/samples/exportPattern.py \
     --downloadAll \
     -t /SOAPolicyLoader/export

On Linux, you can make the shell automatically use the PureApplication System command to execute your Jython scripts. If the PureApplication System command is on your PATH, insert the following line at the top of your script to have the shell execute it using the CLI:

#!/usr/bin/env pure

The same Jython scripting language is supported when you pass commands to the command line by using any of these methods, the -c parameter, or a script file specified using the -f parameter. To pass the CLI password in a file, run the savePassword utility. By default, this utility resides in the CLI /bin directory. Run the command as shown in the following example:

savePassword <fileName> <password>

Do not include any path or directory information in the command. The password file is saved to the folder that corresponds to %APPDATA% on computers running Windows operating systems, or to the directory that corresponds to $HOME on computers running Linux or Unix operating systems.

Use the --passfile argument when you are invoking the CLI and want to use a password file instead of explicitly specifying a password in the invocation command. The following example provides such an invocation:

pure.bat -h 172.16.98.225 \
         -u admin \
         --passfile <filename> \
         -a

Get help on the command-line interface

As you perform administrative functions for the system using the command-line interface, you can get help for all resources.

Download and initialize the CLI.

You can get help for any system resources, attributes, and methods on the CLI. This task provides basic information about options for invoking the CLI help function.

Use the help command to get help for command syntax, available commands, and using interactive mode. To get help, start the CLI in interactive mode by initializing with the required -u -p and -h parameters, but do not include the -c or -f parameters. Then enter help, as shown in the following example:

$ deployer -h mydeployer.mycompany.com \
           -u joeadmin \
           -p password >>> help 

The help command shown in the previous example is a Jython function. When it is used as shown in the previous example, it provides a high-level overview of the command line environment and instructions for accessing help on more specific topics.

• Invoke general help.

  When used with no parentheses and no parameters, the help command provides general help for using the PureApplication System CLI.

  In interactive mode, you can invoke admin.help without the package prefix, as shown in the following example:

  >>> help 

• Invoke help for the package.

  >>> help(admin)
  

  When invoked with a parameter, the help function provides detailed information about the specified package, module, function, or property. Information about invoking help for each resource is available in the reference information for that resource.

• Invoke detailed help about a specific topic.

  Pass a single parameter to the help function to get more detailed help about a specific topic. For example, to see detailed help for how to work with hypervisors in the CLI, enter the following command:

  >>> help(admin.clouds)
  
  

  The clouds prefix is used to group all the PureApplication System-specific Jython functions into a single package to reduce the chances of name collisions with functions and variables in your own scripts.

Detailed or general help is displayed.

Resolve CLI errors when using multi-byte character sets

If you are working with codecs commonly used for languages with multi-byte characters, you could see errors. These Jython 2.5.1 errors most commonly occur while using the CLI in interactive mode. Errors usually occur as LookupErrors indicating that your encoding is unknown.

If you are using Jython 2.5.1 in a multi-byte character set, you can see a LookupError error as shown in the following example:

LookupError: unknown encoding 'gb2312'

If you encounter these errors while using the CLI, use the following steps to correct the problem.

1. Identify the lib directory that corresponds to the firmware version of the IBM PureApplication System. The deployer.cli/lib directory contains one subdirectory for each PureApplication System firmware version with which the CLI has communicated. You can determine the firmware version of a particular system with the following command:

   $ pure -h <system_hostname> \
          -u <username> \
          -p <password> \
          -c deployer.version
   

   The following example shows this command:

   $ pure -h mysystem.foo.com \
          -u cbadmin \
          -p pw \
          -c deployer.version
      System at mysystem.foo.com firmware version 3.0.0.0-30839
   

   In this example, the lib directory is pure.cli/lib/3.0.0.0-30839.

2. Update the registry file in the following ways:

   • Uncomment the following two lines:

     # python.console.encoding=iso-8859-1
     # deployer.console.encoding=gb2312
     

   • Update deployer.console.encoding to specify the correct codec for your environment. As examples, the following list includes specific codecs for certain locales:
     • Simplified Chinese: deployer.console.encoding=gb2312
     • Traditional Chinese: deployer.console.encoding=big5
     • Japanese: deployer.console.encoding=shift_jis
     • Korean: deployer.console.encoding=ks_c_5601-1987
     • Western European: deployer.console.encoding=ibm850

3. Ensure that you add a back slash (\) as an escape sequence to the following characters, which are also known as string literals in this case, when specifying directories or file paths:

   .\a, \b, \f,\n,\r, \t,\x,\v
   

   
   Example

   c:\\foo.tgz
   

4. Restart the CLI.

Exception encountered when starting command-line interface

An exception occurs when starting the command-line interface

If an unsupported JRE is used on the computer on which you have installed the CLI an exception similar to the one in the following example can occur.

 "java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.
websphere.ssl.protocol.SSLSocketFactory"

If this exception occurs, replace the JDK/JRE with the standard IBM Java Runtime Environment.

Use the command line interface for the system console

To perform administrative functions like you do with the system console, you can download the CLI from the system onto a local machine. You can then run the CLI on the local machine.

A user without the Cloud group administration (Full permission) role and Security Administration (Full permission) role cannot set or modify the Access granted to: field of cloud group resources, IP group resources, virtual appliance resources, and virtual machine resources by way of the command line or the system console. Another user with such permissions should modify the Access granted to: field instead.

Help information

help(<almost every class/object, function AND attribute>)

Sample:

help(admin .ipgroups)

List all IP groups

admin.ipgroups

Output:

>>> admin.ipgroups
[
{ "cloud": (nested object),
 "createdtime": "Tue, 17 Jan 2012 02:57:29
GMT",
 "dns": "172.16.248.2",
 "gateway": "172.16.64.1",
 "id":
"/deployment/resources/subnets/68a0a8ca-c011-42f1-b4b4-7d1dcfd4d92e",
"ips": (nested object),
"ipversion": "ipv4",
"mask": "255.255.240.0",
"name": "172",
"secondarydns": None, "subnet": "172.16.64.0",
"updatedtime": "Tue, 17 Jan 2012 02:57:29 GMT"
}
]

List IP groups by filters

admin.ipgroups.list(<query_dict>)

Example:

admin.ipgroups.list({"name":"test"})

Create an IP group

Create an IP group:

Use help(admin.ipgroups.create) to show what parameters to input.

Example:

admin.ipgroups << {
"subnet": "172.16.64.0",
"mask": "255.255.240.0",
"gateway": "172.16.64.1",
"dns": "172.16.248.2",
"vlan_id": "667"}

Add addresses to an IP group

Add addresses to an IP group

Add a single IP address

<ipgroup object>.ips.create(<an ipaddress>)

Example:

admin.ipgroups[0].ips.create('172.16.66.50')

Output:

[{
"createdtime": "Tue, 17 Jan 2012 17:20:52 GMT",
"currentstatus": "available",
"hostname": None, "id":"/deployment/resources/addresses/b0676045-5395-4d2f-826d-54d50784ee65",
"ip": "172.16.66.50",
"ipgroup": (nested object),
"updatedtime": "Tue, 17 Jan 2012 17:20:52 GMT"
}]

Add a range of IP addresses

<ipgroup object>.ips.create(<start ip address>, <end ipaddress>)

Example:

 admin.ipgroups[0].ips.create('172.16.66.2','172.16.66.3')

Output:

 [{ 
 "createdtime":
"Tue, 17 Jan 2012 17:27:13 GMT", 
 
"currentstatus": "available", 
 
"hostname": None, "id":
"/deployment/resources/addresses/19e9b78d-0825-46fb-bf1e-ab5bdcf4483b",
"ip": "172.16.66.2",
.ipgroup": (nested object), 
 
"updatedtime": "Tue, 17 Jan 2012 17:27:13 GMT" 
}, { 
 "createdtime":
"Tue, 17 Jan 2012 17:27:14 GMT", 
 
"currentstatus": "available", 
 
"hostname": None, 
 
"id":
"/deployment/resources/addresses/245d81cd-2a3b-4d1d-877d-7de659ab58f9",
 
"ip": "172.16.66.3",
"ipgroup": (nested object),
"updatedtime": "Tue, 17 Jan 2012 17:27:14 GMT" }] 

Add a list of hostnames

<ipgroup object>.ips.create(<a list of hostnames>)

Example:

admin.ipgroups[0].ips.create(['a.com',.b.com.])

Output:

[{ 
 "createdtime":
"Tue, 17 Jan 2012 17:34:45 GMT", 
 
"currentstatus": "available", 
 "hostname":
"a.com", 
 "id":
"/deployment/resources/addresses/1ae4be3d-c861-40bc-9aa6-8d2347a856d1",
 
 "ip": None, 
 "ipgroup":
(nested object), 
 "updatedtime":
"Tue, 17 Jan 2012 17:34:45 GMT" 
}, { 
 "createdtime":
"Tue, 17 Jan 2012 17:34:47 GMT", 
 "currentstatus":
"available", 
 "hostname":
"b.com", 
 "id":
"/deployment/resources/addresses/f77468d0-022b-464f-9e38-e3bb99970231",
 
 "ip": None, 
 "ipgroup":
(nested object), 
 "updatedtime":
"Tue, 17 Jan 2012 17:34:47 GMT" 
}]

List addresses by filters

List addresses by filters

<ipgroup object>.ips[<ipaddress>]

For other filters, the format is:

<ipgroup object>.ips.list(<query dict>)

Example:

admin.ipgroups[0].ips.list({'hostname':'a.b.com'})

Remove an address from the IP group

Remove an address from the IP group

<ip object>.delete()

Example:

admin.ipgroups[0].ips[0].delete()

Delete an IP group

Delete an IP group

<ipgroup object>.delete()

Example:

admin.ipgroups[0].delete()

Update multiple fields of an IP group

Update multiple fields of an IP group

<ipgroup object>.update((dict object))

Example:

admin.ipgroups[0].update({.subnet.: .172.16.64.0., .mask.: .255.255.240.0., .gateway.:.172.16.64.1., .cloud.: admin.cloud[0]})

Set cloud group

Set cloud group

<ipgroup object>.cloud=<cloud object>

Example:

admin.ipgroups[0].cloud=admin.clouds[1]

List all cloud groups

List all cloud group

admin.clouds

Output:

[ {
"colocationpolicy": "Availability",
"computenodes": (nested object), "description":
"Default PureScale Dedicated Cloud Group"
"id":"/deployment/resources/vdcs/cdd1bb17-118c-4ddb-98bb-0d7b06b6bba6",
 
"ipgroups": (nested object), "name":
"Dedicated", "state": "online",
"type": "Dedicated", "vmconfigurations": (nested
object), "volumeconfigurations": (nested
object) }]

List cloud groups by filter

List cloud groups by filter

admin.clouds.list(<query dict>)

Example:

admin.clouds.list({.type.:.Dedicated.})

Create a cloud group

Create a cloud group.

Use help(admin.clouds.create) to check what parameters to input.

Example:

admin.clouds<<{'name':'cli_test','type':'Dedicated', 'mgmt_vlan_id': '2'}

Output:

{
  "acl": (nested object),
  "colocation_policy": "Availability",
  "computenodes": (nested object),
  "created_time": "Nov 15, 2012 12:43:00 PM",
  "description": None,   "id": "f5fb04c7-ea50-439b-8146-199066449bab",
  "ipgroups": (nested object),
  "mgmt_vlan_id": (nested object),
  "name": "cli_test",
  "state": "pending",
  "type": "Dedicated",
  "updated_time": "Nov 15, 2012 12:43:00 PM",
  "url": "/admin/resources/vdcs/f5fb04c7-ea50-439b-8146-199066449bab",
"vmconfigurations": (nested object),
  "volumeconfigurations": (nested object)}

List virtual machine configurations in the cloud group

List virtual machine configurations in the cloud group

<cloud object>.vmconfigurations or <cloud object>.vmconfigurations.list(<query
object>

Example:

admin.clouds[0]. vmconfigurations[
{ "cloud": (nested object),
"cpucount": 1, "createdtime": "Thu, 19 Jan 2012
14:31:16 GMT", "id":
"/deployment/resources/vm_configurations/4529f0fb-d8a6-4191-8111-5b08fdf75369",
"memory": 1024.0, "name":
"Small", "pcpucount": 1.0,
"updatedtime": "Thu, 19 Jan 2012 14:31:16 GMT" },
{ "cloud": (nested object),
"cpucount": 2, "createdtime": "Thu, 19 Jan 2012
14:31:16 GMT", "id":
"/deployment/resources/vm_configurations/d0654265-a913-47ca-a57d-aaddb25bbd59",
"memory": 2560.0, "name":
"Medium", "pcpucount": 2.0,
"updatedtime": "Thu, 19 Jan 2012 14:31:16 GMT" }]

Create a virtual machine configuration in the cloud group

Create a virtual machine configuration in the cloud group

Use help(admin.vmconfigurations.create) to check what parameters to input.

<cloud object>.vmconfigurations << (a dict for parameters)

Examples:

admin.clouds[1].vmconfigurations<<{'name':'cli_test_vm_config','memory':1024,'cpucount':2,'physicalcpucount':1}

Output:

{ "cloud": (nested
object), "cpucount": 2, "createdtime":
"Fri, 20 Jan 2012 15:12:15 GMT", "id":
"/deployment/resources/vm_configurations/17335ebe-b7f6-45d9-be83-5c5f3a441406",
"memory": 1024.0, "name":
"cli_test_vm_config", "physicalcpucount":
1.0, "updatedtime": "Fri, 20 Jan 2012 15:12:15
GMT"}

Delete a volume configuration

Delete a volume configuration

<volume configuration object>.delete()

Example:

admin.clouds[0].volumeconfigurations[0].delete()

Create a volume configuration in the cloud group

Create a volume configuration in the cloud group

Create a volume configuration in the cloud group

Use help(admin.volumeconfigurations.create) to check what parameters to input

<cloud
object>.volumeconfigurations << ( a dict for parameters)

Example:

admin.clouds[1].volumeconfigurations<< {'name':'cli_test_vol_config','size':10240}

Output:

{
"cloud":(nested object),
"createdtime":"Fri, 20 Jan 2012 15:21:07 GMT",
"id":"/deployment/resources/volume_configurations/97c6b64d-0283-4e70-b47a-2511b8968d20",
"name":"cli_test_vol_config",
"size":10240,
"updatedtime":"Fri, 20 Jan 2012 15:21:07 GMT"
}

Delete a virtual machine

Delete a virtual machine

<virtualmachine object>.delete()

Examples:

admin.virtualmachine[0].delete() 
admin.virtualmachine.list({'name':'test'})[0].delete()

Delete a virtual machine configuration

Delete a virtual machine configuration

<vmconfiguration
object>.delete()

Example:

admin.clouds[1].vmconfigurations[0].delete()

List volume configurations in the cloud group

List volume configurations in the cloud group

<cloud object>.volumeconfigurations or <cloud object>.volumeconfigurations.list(<query
object>)

Example:

admin.clouds[0].volumeconfigurations

Output:

[{
"cloud": (nested object),
"createdtime": "Fri,20 Jan 2012 15:21:07 GMT",
"id":"/deployment/resources/volume_configurations/97c6b64d-0283-4e70-b47a-2511b8968d20",
"name":"cli_test_vol_config",
"size":10240,
"updatedtime":"Fri,20 Jan 2012 15:21:07 GMT"
}]

Delete a cloud group

Delete a cloud group

<cloud
object>.delete()Example: admin.clouds[0].delete()

Add a compute node

Add a compute node

<cloud object>.computenodes.add((computenode object)

Example:

admin.clouds[0].computenodes.add(admin.computes[0])

Remove a compute node

Remove a compute node

<cloud object>.computenodes.remove((computenode object))

or

(computenode object).cloud = (cloud object)

Example:

admin.clouds[0].computenodes.remove(admin.clouds[0].computenodes[1])

or

admin.computenodes[0].cloud = admin .clouds[0]

List virtual appliances

List virtual appliances:

admin.virtualappliances

Sample:

>>> admin.virtualappliances
 
[
 {
 "acl": (nested object),
 "createdtime": "Thu, 12 Jan 2012 15:41:48
GMT",
 "description": None,  "id":
"/deployment/resources/images/cdab24d2-11db-4b26-a1bb-aeb3ad412232",
 "label": "Image",
 "name": "aix71b_REST",
 "owner": (nested object),
 "state": "available",
 "updatedtime": "Thu, 12 Jan 2012 15:41:48
GMT",
 "url": None  },
 {
 "acl": (nested object),
 "createdtime": "Thu, 12 Jan 2012 15:41:48
GMT",
 "description": None,  "id":
"/deployment/resources/images/54af35bc-1f1e-4fb3-94a7-9c31db7fe4b6",
 "label": "Image",
 "name": "aix71d",
 "owner": (nested object),
 "state": "available",
 "updatedtime": "Thu, 12 Jan 2012 15:41:48
GMT",
 "url": None }
]

Create a virtual appliance

Create a virtual appliance:

admin.virtualappliances.create({<propetyName>:<value>,....})

Example:

>>>admin.virtualappliances.create({'url':'http://myServer.com:9080/public/myImage.ova', 'name':'test','userid':'test','password':'test'})

Output:

{
 "acl":(nested object),
 "createdtime":"Thu, 19 Jan 2012 09:51:59 GMT",
 "description":None,
 "id":"/deployment/resources/images/9720e603-2a35-4a17-8b39-8d240ff82d05",
 "label":"Image",
 "name":"test",
 "owner":(nested object),
 "state":"pending",
 "updatedtime":"Thu, 19 Jan 2012 09:51:59 GMT",
 "url":"http://myServer.com:9080/public/myImage.ova"
}

Retrieve a virtual appliance

Retrieve a virtual appliance

admin.virtualappliances[<index>]

Example:

>>> admin.virtualappliances[0]
{
 "acl": (nested object),
 "createdtime": "Thu, 19 Jan 2012 09:51:59 GMT",
 "description": None,  "id":
"/deployment/resources/images/9720e603-2a35-4a17-8b39-8d240ff82d05",
 "label": "Image",
 "name": "test",
 "owner": (nested object),
 "state": "pending",
 "updatedtime": "Thu, 19 Jan 2012 09:51:59 GMT",
 "url": "http://myServer.com:9080/public/myImage.ova"
}

Delete a virtual appliance

Delete a virtual appliance

admin.virtualappliances[<index>].delete()

Example:

>>>admin. virtualappliances[0].delete()

Export a virtual appliance

Export a virtual appliance to the system catalog.

Export a virtual appliance

(virtualappliance object).export(local directory or a dict file)

The dict file contains the following keys:

Protocol

The protocol used for export. The following list details valid values:

SCP

When using the SCP protocol, 'host', 'path', 'username' and 'password' are required.

HTTPS

When using the HTTPS protocol, 'url', 'username' and 'password' are required.

Username

A user name with appropriate credentials to export a virtual appliance.

Password

The password to match a user name with appropriate credentials to export a virtual appliance.

Host

Address for the SCP protocol.

Path

Destination absolute path for the SCP protocol.

URL

The URL for posting the OVA file to using the HTTPS protocol.

Example:

   admin.virtualappliances[0].export("C:\\temp")
   admin.virtualappliances[0].export({"host": "172.16.65.21", "path": "/tmp", "username": "root", "password": "test"})

List storage volumes

List storage volumes:

admin.volumes

Sample:

>>> admin.volumes[0]
{
"acl": (nested object),
"cloud": (nested object),
"created_time": "Feb 27, 2013 1:50:58 PM",
"description": None, "harddiskdrive": None, "id": "c2108d9e-b982-4e7f-8eaa-2120a5a2bbc8",
"name": "vm_OS_Node_1_disk_0",
"size": 204800,
"solidstatedrive": None, "state": "available",
"units": None, "updated_time": "Jul 11, 2013 6:18:48 AM",
"url": "/admin/resources/volumes/c2108d9e-b982-4e7f-8eaa-2120a5a2bbc8",
"virtualmachines": (nested object),
"volumeconfiguration": (nested object)
}

The virtualmachines attribute is useful to determining whether or not the volume is in use.

Create a storage volume

Create a storage volume:

admin.volumes.create({<propetyName>:<value>,....})

When creating a new volume, either a volume configuration or the .size. attribute have to provided, but not both.

Example:

>>>admin.volumes.create({'name':'test',
'description': 'test_create_volume', 'size': 1000,
"cloud":admin.clouds[0]})"
{
 "createdtime": "Thu, 19 Jan 2012 11:42:16 GMT",
 "description": "test_create_volume",
 "harddiskdrive": None,  "id":
"/admin/resources/volumes/2a2ed959-1167-4d46-a7b1-3946f3c1e9a2",
 "isosvolume": "true",
 "label": None,  "name": "test",
 "size": 1000,
 "solidstatedrive": None,  "units": "MB",
 "updatedtime": "Thu, 19 Jan 2012 11:42:16 GMT",
 "volume_configuration": None }
>>> admin.volumes.create({'name':'test',
'description': 'test_create_volume', "cloud":admin.clouds[0],
'volume_configuration':admin.clouds[0].volumeconfigurations[0]})
{
 "createdtime": "Thu, 19 Jan 2012 14:19:58 GMT",
 "description": "test_create_volume",
 "harddiskdrive": None,  "id":
"/admin/resources/volumes/5470b407-a92a-426f-a573-7d1d9d03f7f4",
 "isosvolume": "true",
 "label": None,  "name": "test",
 "size": None,  "solidstatedrive": None,  "units": "MB",
 "updatedtime": "Thu, 19 Jan 2012 14:19:58 GMT",
 "volume_configuration": None }

When a storage volume is added to a virtual machine it is not usable until the volume is formatted and the creation of a valid partition is performed. To validate that the volume is attached successfully, use the following command:

fdisk -l

When this command is entered the volume is listed, but is not formatted and does not contain a valid partition. The following example displays typical results when the fdisk -l command is entered.

Disk /dev/sda: 12.9 GB, 12884901888 bytes
255 heads, 63 sectors/track, 1566 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x00005a0f
 
   Device Boot      Start         End      Blocks   Id  System /dev/sda1   *           1        1306    10484736   83  Linux
/dev/sda2            1306        1567     2097152   82  Linux swap / Solaris
Disk /dev/sda: 12.9 GB, 12884901888 bytes
 
Disk /dev/sdb: 10 MB, 10485760 bytes
1 heads, 20 sectors/track, 1024 cylinders
Units = cylinders of 20 * 512 = 10240 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x00000000
 
Disk /dev/sdb doesn't contain a valid partition table 

Retrieve a storage volume

Retrieve a storage volume

admin.volumes[<index>]

Example:

>>> admin.volumes[0]
{
 "createdtime": "Thu, 19 Jan 2012 11:42:16 GMT",
 "description": "test_create_volume",
 "harddiskdrive": None,  "id":
"/admin/resources/volumes/2a2ed959-1167-4d46-a7b1-3946f3c1e9a2",
 "isosvolume": "true",
 "label": None,  "name": "test",
 "size": 1000,
 "solidstatedrive": None,  "units": "MB",
 "updatedtime": "Thu, 19 Jan 2012 11:42:16 GMT",
 "volume_configuration": None }

Delete a storage volume

Delete a storage volume

admin.volumes[<index>].delete()

Example:

>>>admin. volumes[0].delete()

List virtual machines

List virtual machines:

admin.virtualmachines

Example:

admin.virtualmachines

Output:

>>>admin.virtualmachines
[
 {
 "cloud": (nested object),
 "computenode": (nested object),
 "cpucount": None,  "cpustats": (nested object),
 "createdtime": "Wed, 08 Feb 2012 02:20:51
GMT",
 "description": None,  "id":
"/admin/resources/instances/546c0bf5-edd7-4bdc-ad83-928c814c8dee",
 "image": (nested object),
 "ips": (nested object),
 "memory": None,  "memorystats": (nested object),
 "mountedvolumes": (nested object),
 "name": "test",
 "physicalcpucount": None,  "state": "pending",
 "updatedtime": "Wed, 08 Feb 2012 02:20:51
GMT",
 "vmconfiguration": (nested object)
 }
]

Start virtual machine

Start virtual machine:

virtualmachine.start()

Example:

admin.virtualmachines[0].start()

Stop virtual machine

Stop virtual machine:

virtualmachine.stop()

Example:

admin.virtualmachines[0].stop()

Restart virtual machine

Restart virtual machine:

virtualmachine.restart()

Example:

admin.virtualmachines[0].restart()

Capture virtual machine as virtual appliance

Capture virtual machine as virtual appliance:

instance.capture(<virtual appliance name>)

Example:

admin. virtualmachines[0].
capture(.capturedImage.)

Add an IP address to a virtual machine

Add an IP address to a virtual machine.

(virtualmachine object).ips += [(ip object)] or (ip object)

Example:

admin. virtualmachines[0]. ips += admin.ipgroups[0].ips

Delete an IP address from virtual machine

Delete an IP address from virtual machine:

(virtualmachine object).ips -= [(ip object)] or (ip object)]

Example:

admin.virtualmachines[0].ips -= admin.virtualmachines[0].ips[0]

Output:

>>> admin. virtualmachines[0].
deleteip(admin.ips[0])

Mount volumes to a virtual machine

Mount volumes to virtual machine

virtualmachine.volumes + = [<list of dict
object>] or (dict object)
dict= {.volume.: (volume object),

Example:

admin. virtualmachines[0].volumes += [
{
.volume.: admin. volumes[0],
}
]

When a storage volume is added to a virtual machine it is not usable until the volume is formatted and the creation of a valid partition is performed. To validate that the volume is attached successfully, use the following command:

fdisk -l

When this command is entered the volume is listed, but is not formatted and does not contain a valid partition. The following example displays typical results when the fdisk -l command is entered.

Disk /dev/sda: 12.9 GB, 12884901888 bytes
255 heads, 63 sectors/track, 1566 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x00005a0f
 
   Device Boot      Start         End      Blocks   Id  System /dev/sda1   *           1        1306    10484736   83  Linux
/dev/sda2            1306        1567     2097152   82  Linux swap / Solaris
Disk /dev/sda: 12.9 GB, 12884901888 bytes
 
Disk /dev/sdb: 10 MB, 10485760 bytes
1 heads, 20 sectors/track, 1024 cylinders
Units = cylinders of 20 * 512 = 10240 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x00000000
 
Disk /dev/sdb doesn't contain a valid partition table 

When the fdisk -l command is entered and the volume is not listed, you must restart the virtual machine.

Unmount volumes from virtual machine

Unmount volumes from virtual machine

virtualmachine.volumes - = [<list of dict
object>] 

or

(dict object)
 dict= {.volume.: (volume object),
.mount_point.: (str)}

Example:

admin. virtualmachines[0].volumes -= [{
.volume.: admin. volumes[0],
.mount_point.:./test_mount_point.
}]

Create a virtual machine

Create a virtual machine

admin. virtualmachines.create(<params to create a virtual machine>)

Example:

Create a virtual machine from a pre-configured VM configuration:

admin. virtualmachines.create({
>>>"name":"my_vm",
>>>"cloud":admin.clouds[0],
>>>"virtualappliance":admin.virtualappliances[0],
>>>"vmconfiguration":admin.clouds[0].vmconfigurations[0]
>>>})

Example:

Create a virtual machine by using a customized value to configure physical/virtual CPU and memory:

admin. virtualmachines.create({
>>>"name":"my_vm",
>>>"cloud":admin.clouds[0],
>>>"virtualappliance":admin.virtualappliances[0],
>>>"cpu_count":1,
>>>"pcpu_count":1,
>>>"memory":1024
>>>})

List compute nodes

List compute nodes:

admin.computenodes

Example:

admin.computenodes

Output:

>>> admin. computenodes
[ {
 "architecture": None,  "cloud": (nested object),
 "energystats": (nested object),
 "firmwarelevel": "AA730_028 - 05/06/2011 -
1116 - Different",
 "healthstats": (nested object),
 "id":
"/admin/resources/physical_compute_nodes/5a252f90-8bef-48e2-8de1-86b71
83a9da9",
 "leds": (nested object),
 "locations": (nested object),
 "machinetype": None,  "name": "SN#Y310KW13L01H",
 "numberofpowercycles": 0,  "physicalcpus": (nested object),
 "physicalioadapters": (nested object),
 "physicalmemory": (nested object),
 "powerstate": "powered_on",
 "state": "available",
 "virtualmachines": (nested object)
 }]

Start compute node

Start compute node:

computenode.start()

Example:

admin.computenodes[0].start()

Power on compute node

Power on compute node:

computenode.poweron()

Example:

admin.computenodes[0]. poweron()

Power off compute node

Power off compute node:

computenode.poweroff()

Example:

admin.computenodes[0]. poweroff()

Quiesce compute node

Quiesce compute node:

computenode.quiesce()

Example:

admin.computenodes[0]. quiesce()

Maintain compute node

Maintain compute node:

computenode.maintain()

Example:

admin.computenodes[0]. maintain ()

List network devices

List network devices:

admin.networkdevices

Sample:

>>> admin.networkdevices
 
[
 {
 "firmwareversion": "1",
 "id":
"6e00c320-7233-4a4c-8809-9cdbca7933e5",
 "label_text": "Network Switch",
 "locations": (nested object),
 "softwareversion": "1.0.1.0 (FLASH image1),
active configuration.",
 "state": "available",
 "switch_type": "chassis_network_switch",
 "switchmodel": "Ethernet SM",
 "switchports": (nested object),
 "temperature": None  },
 {
 "firmwareversion": "1",
 "id":
"1c2a5bdc-202f-4cb0-a293-238c68daf36f",
 "label_text": "Network Switch",
 "locations": (nested object),
 "softwareversion": "1.0.1.0 (FLASH image1),
active configuration.",
 "state": "available",
 "switch_type": "chassis_network_switch",
 "switchmodel": "Ethernet SM",
 "switchports": (nested object),
 "temperature": None  }
]

List groups

List groups:

admin.groups

Sample:

>>> admin.groups
[
 {
 "created_time": "Tue, 17 Jan 2012 07:32:30
GMT",
 "description": "test",
 "id":
"/admin/resources/user_groups/9c88e186-6b2e-4de7-a395-4fd5e3ca2f5d",
 "name": "test",
 "owner": .nested object.,
 "updated_time": "Tue, 17 Jan 2012 07:32:30
GMT",
 "users": .nested object.
 }
]

Create a group

Create a group:

admin.groups.create({<propetyName>:<value>,....})

Example:

>>> admin.groups.create({"name": "test1",
"description": "test1"})
{ "created_time": "Mon, 16 Jan 2012 08:32:55
GMT",
 "description": "test1",
 "name": "test1",
 "updated_time": "Mon, 16 Jan 2012 08:32:55
GMT"
}

Update a group

Update a group:

admin.groups[<index>].<propertyName>

Example:

>>>admin.groups[0].name="updatedName"

Retrieve a group

Retrieve a group:

 admin.groups[<index>]
 

Example:

>>> admin.groups[0]
 
{
 "created_time": "Tue, 17 Jan 2012 07:32:30 GMT",
 "description": "test",
 "id":
"/admin/resources/user_groups/9c88e186-6b2e-4de7-a395-4fd5e3ca2f5d",
 "name": "test",
 "owner": .nested object.,
 "updated_time": "Tue, 17 Jan 2012 07:32:30 GMT",
 "users": .nested object.
}

Delete a group

Delete a group:

admin.groups[<index>].delete()

Example:

>>>admin.groups[0].delete()

Add the user to a group

Add the user to a group

(user object).groups.add(<group object>)

Example:

admin.users[0].groups.add(admin.groups[0])

Remove the user from a group

Remove the user from a group

(user object).groups.remove(<group object>)

Sample:

admin.users[0].groups.remove(admin.groups[0])

List the roles of the group

List the roles of the group

(group object).roles

Example:

>>>admin.groups[1].roles

Add new roles to the group

Add new roles to the group

(group object).roles += <role_name>

Example:

>>>admin.groups[1].roles += admin.PATTERN_CREATOR_ROLE

For more role names that are defined in the admin object, you can check with dir(admin) for those ending with a ._ROLE. suffix.

Remove a role from the group

Remove a role from the group

(group object).roles -= <role_name>

Example:

>>>admin.groups[1].roles -= admin.PATTERN_CREATOR_ROLE

List Users

List Users

admin.users

Sample:

>>> admin.users
[
 {
 "auth_mode": "internal",
 "created_time": 1332138581000,
 "current_status": None,  "email": "test@cn.ibm.com",
 "id":
"54b2d696-1aea-4313-97f7-3daa8b0779a8",
 "name": "test1",
 
 "url":
"/admin/resources/users/54b2d696-1aea-4313-97f7-3daa8b0779a8",
 "user_id": "test1"
 }
]

Create a user

Create a user

admin.users.create({<propetyName>:<value>,....})

Example:

>>>admin.users.create({"user_id":"test1","name":"test1","email":"test@cn.ibm.com","password":"password"})
{
 "auth_mode": "internal",
 "created_time": 1332138581000,
 "current_status": None,  "email": "test@cn.ibm.com",
 "id": "54b2d696-1aea-4313-97f7-3daa8b0779a8",
 "name": "test1",
 "url":
"/admin/resources/users/54b2d696-1aea-4313-97f7-3daa8b0779a8",
 "user_id": "test1"
}

Update a user

Update a user

admin.users[<index>].<propertyName>=<value>

Example:

>>>admin.users[0].name="updatedName"

Retrieve a user

Retrieve a user:

admin.users[<index>]

Sample:

>>>
admin.users[1]
 
{
"auth_mode": "internal",
 "created_time": 1332138581000,
 "current_status": None,  "email": "test@cn.ibm.com",
 "id": "54b2d696-1aea-4313-97f7-3daa8b0779a8",
 "name": "test1",
 "url":
"/admin/resources/users/54b2d696-1aea-4313-97f7-3daa8b0779a8",
 "user_id": "test1"
}

Delete a user

Delete a user:

admin.users[<index>].delete()

Example:

>>> admin.users[1].delete()

Remove a user from the group

Remove a user from the group

(group object).users.remove(<user object>)

Example:

>>>admin.groups[0].users.remove(admin.users[0])

List the roles of a user

List the roles of a user

(user object).roles

Example:

>>>admin.users[1].roles

Add a new role to the user

Add a new role to the user

(user object).roles += <role_name>

Example:

>>>admin.users[1].roles += admin.PATTERN_CREATOR_ROLE

Remove roles from the user

Remove roles from the user

(user object).roles -= <role_name>

Example:

>>>admin.users[1].roles -= admin.PATTERN_CREATOR_ROLE

List all jobs

List all jobs

admin.jobs

Sample:

>>> admin.jobs
 [{
 "created_time": "Thu, 19 Jan 2012 02:25:45
GMT",
 "name": "watchdog",
 "state": "pending",
 "type": "watchdog",
 "updated_time": "Thu, 19 Jan 2012 02:25:45
GMT"
 
 },
 {
 "created_time": "Thu, 19 Jan 2012 02:25:45
GMT",
 "name": "static vlan create",
 "state": "pending",
 "type": "vlan",
 "updated_time": "Thu, 19 Jan 2012 02:25:45
GMT"
 }
]

Delete a job

Delete a job

admin.jobs.list({"name": "query compute amm chassis2"})[0]
job.delete()

Example:

>>> admin.jobs.list({"name": "query compute amm chassis2"})[0]
job.delete()

List all events

List all events

admin.events

Sample:

>>> admin.events
[ {
 "category": "Alert",
 "created_time": "Wed, 18 Jan 2012 08:01:56
GMT",
 "msg_text": "Connection reset
(172.16.96.19)",
 "severity": "Minor",
 "type": "switches"
 },
 
 {
 "category": "Alert",
 "created_time": "Wed, 18 Jan 2012 08:02:05
GMT",
 "msg_text": "Closed by foreign host (172.16.96.109)",
 "severity": "Minor",
 "type": "switches"
 }
]

Delete an event

Delete a event

admin.events[<index>].delete()

Example:

>>> admin.events[0].delete()

List LED status

List LED status

admin.leds

Output:

[
{
"id": "0dd8b71e-d2a0-4d95-a54b-8239c9158b1c",
"name": "enclosure-1_slot-1",
"power_state": "off",
"severity": "error",
"state": "available",
"url": "/admin/resources/leds/0dd8b71e-d2a0-4d95-a54b-8239c9158b1c"
},
{
"id": "1d0a335a-a915-45e8-91e6-346ff7e1cb3b",
"name": "enclosure-1_slot-1",
"power_state": "off",
"severity": "identity",
"state": "available",
"url": "/admin/resources/leds/1d0a335a-a915-45e8-91e6-346ff7e1cb3b"
},
...
]

List LED status of a specific status type

List LED status of a specific status type

admin.leds.list({"power_state":"off"})

Example:

admin.leds.list({.power_status.:"off"})

Output:

[
{
 "chassis_fans":
"/admin/resources/chassis_fans/8936d0dc-d346-4c52-9684-b8bb337507f4",
 "created_time": "Thu, 09 Feb 2012 10:32:52 GMT",
 "id":
"/admin/resources/leds/20d3e348-0dc0-4905-82d0-8d6ed888401f",
 "label_key": "purescale0504",
 "label_text": "Indication LED",
 "name": "SN#YK10CD133131",
 "parent_type": "chassis_fans",
 "power_state": "off",
 "power_target_result": "done",
 "power_target_state": "off",
 "severity": "error",
 "state": "available",
 "updated_time": "Fri, 10 Feb 2012 05:42:18 GMT",
 "version": "1.0.0.0"
},
...

Obtain a particular LED by its name

Obtain a particular LED by its name

admin.leds.get(<name>)

Example:

admin.led.get("SN#YK10CD133131")

Output:

{
"chassis_fans":
"/admin/resources/chassis_fans/8936d0dc-d346-4c52-9684-b8bb337507f4",
"created_time": "Thu, 09
Feb 2012 10:32:52 GMT",
"id":
"/admin/resources/leds/20d3e348-0dc0-4905-82d0-8d6ed888401f",
"label_key":
"purescale0504",
"label_text":
"Indication LED",
"name":
"SN#YK10CD133131",
"parent_type":
"chassis_fans",
"power_state": "off",
"power_target_result":
"done",
"power_target_state":
"off",
"severity": "error",
"state": "available",
"updated_time": "Fri, 10
Feb 2012 05:42:18 GMT",
"version": "1.0.0.0"
}

Obtain a particular vendor information with its serial number

Obtain a particular vendor information with its serial number

admin.vendors.getBySerial(<serial
number>)

Example:

admin.vendors
getBySerial(.12345.)

Output:

{
 
"created_time": "Thu, 09 Feb 2012 10:27:05 GMT",
 
"id":
"/admin/resources/vendor_informations/28f4d4da-c52a-4244-82c2-5aa031dcc1d9",
 
"label_key": "purescale0505",
 
"label_text": "Vendor Information",
 
"model": "8278-3F2",
 
"name": "Rack 1",
 
"parent_type": "racks",
 
"racks":
"/admin/resources/racks/9573b8a8-e992-4155-aef9-24f774f12e4b",
 
"serial": "12345",
 
"state": "available",
 
"type": "racks",
 
"updated_time": "Thu, 09 Feb 2012 10:30:37 GMT",
 
"vendor": "IBM",
 
"version": "1.0.0.0"
}

List vendor information

List vendor information

admin.vendors

Output:

[
{
 
"created_time": "Thu, 09 Feb 2012 10:27:05 GMT",
 
"id":
"/admin/resources/vendor_informations/28f4d4da-c52a-4244-82c2-5aa031dcc1d9",
 
"label_key": "purescale0505",
 
"label_text": "Vendor Information",
 
"model": "8278-3F2",
 
"name": "Rack 1",
 
"parent_type": "racks",
 
"racks":
"/admin/resources/racks/9573b8a8-e992-4155-aef9-24f774f12e4b",
 
"serial": "12345",
 
"state": "available",
 
"type": "racks",
 
"updated_time": "Thu, 09 Feb 2012 10:30:37 GMT",
 
"vendor": "IBM",
 
"version": "1.0.0.0"
}
...
]

List vendor information of a specific vendor

List vendor information of a specific vendor

admin.vendors.getByVendor(<vendor>)

Example:

admin.vendors.getByVendor(.IBM.)

Output:

[
    {
        "created_time": "Thu, 09 Feb 2012 10:27:05 GMT",
        "id": "/admin/resources/vendor_informations/28f4d4da-c52a-4244-82c2-5aa031dcc1d9",
        "label_key": "purescale0505",
        "label_text": "Vendor Information",
        "model": "8278-3F2",
        "name": "Rack 1",
        "parent_type": "racks",
        "racks": "/admin/resources/racks/9573b8a8-e992-4155-aef9-24f774f12e4b",
        "serial": "12345",
        "state": "available",
        "type": "racks",
        "updated_time": "Thu, 09 Feb 2012 10:30:37 GMT",
        "vendor": "IBM",
        "version": "1.0.0.0"
    },
    ...
]

List all system logs

List all system logs

admin.systemlogs

Example:

admin.systemlogs

Output:

[
{
 "collection_set": "all",
 "created_time": "Fri, 10 Feb 2012 06:42:36 GMT",
 "id":
"/admin/resources/systemlogs/961e7076-86ee-41d4-968b-472fc6770744",
 "jobs": [
 
"0ecb7947-b200-4203-b2d6-19a8a42ea49d"
 ],
 "packaged_log_url": null,
 "state": "pending",
 "updated_time": "Fri, 10 Feb 2012 06:42:36 GMT",
 "version": "1.0.0.0"
},
...
]

Obtain a single system log info

Obtain a single system log info

admin.systemlogs.get(<id>)

Example:

admin.systemlogs.get("961e7076-86ee-41d4-968b-472fc6770744")

Output:

{
    "collection_set": "all",
    "created_time": "Fri, 10 Feb 2012 06:42:36 GMT",
    "id": "/admin/resources/systemlogs/961e7076-86ee-41d4-968b-472fc6770744",
    "jobs": [
        "0ecb7947-b200-4203-b2d6-19a8a42ea49d"
    ],
    "packaged_log_url": null,
    "state": "pending",
    "updated_time": "Fri, 10 Feb 2012 06:42:36 GMT",
    "version": "1.0.0.0"
}

Download a single system log by its ID

Download a single system log by its ID.

<a systemlog object>.download()

Example:

admin.systemlogs.get("961e7076-86ee-41d4-968b-472fc6770744").download()

or

admin.systemlog[0].download()

Output:

Download the file.

Create a new system log

Create a new system log.

admin.systemlogs.create() 

or

admin.systemlogs.create(<setting>)

Example:

admin.systemlogs.create("complete")

Output:

 {
"collection_set": "complete",
"created_time": "Fri, 10
Feb 2012 06:42:36 GMT",
"id":
"/admin/resources/systemlogs/961e7076-86ee-41d4-968b-472fc6770744",
"jobs": [
 
"0ecb7947-b200-4203-b2d6-19a8a42ea49d"
],
"packaged_log_url": null,
"state": "pending",
"updated_time": "Fri, 10
Feb 2012 06:42:36 GMT",
"version": "1.0.0.0"
}

The following types of collection sets are available:

System

Collects logs for the rack including:

• Management collection logs
• Deploy collection logs
• System configuration (status and inventory).

Management

Collects PureApplication System management logs. This collection contains data to help resolve problems with the system console and run time.

Deploy

Collects workload console logs. This collection contains data to help resolve problems with workload management. For diagnostics on any virtual images, use the viewer within the workload console.

Complete

Collects the following:

• System collection set
• Dumps collection set
• Logs from the management nodes

Dumps

Collects JVM diagnostic information from the PureSystems. Manager. This collection set contains diagnostic information from the JVM which supports the system console functions. This information is primarily used by the IBM support team.

IPaddress

Collects diagnostic data from a specific rack component. This information can be collected with the assistance of an IBM service representative who can provide instructions to determine what IP address to specify.

List all trace settings

List all trace settings

admin.tracesettings

Example:

admin.tracesettings

Output:

[
{
"component": "instances",
"created_time": 1332943073000,
"id": "c3470b00-6a83-4e2d-bec8-c08d00d3426e",
"level": "FINEST",
"state": "successful",
"updated_time": 1332943073000,
"version": "1.0.0.0"
},
.
]

Create a new trace setting

Create a new trace setting

admin.tracesettings.create({"component": component, "level": level})
 valid level values are 'OFF', 'SEVERE', 'WARNING', 'INFO', 'FINE', 'FINER', 'FINEST', 'ALL'
 

Example:

admin.tracesettings.create({"component": ".a.new.trace", "level": "FINEST"})

Output:

{
"component": "instances",
"created_time": 1332943073000,
"id": "c3470b00-6a83-4e2d-bec8-c08d00d3426e",
"level": "FINEST",
"state": "successful",
"updated_time": 1332943073000,
"version": "1.0.0.0"
}

options of the traceLevel parameter are: ALL, FINEST, FINER, FINE, INFO, WARNING, SEVERE, and OFF.

Delete an existing trace setting

Delete an existing trace setting

<a trace setting object>.delete()

Example:

admin.tracesettings[0].delete()

Change the trace level of an existing trace setting

Change the trace level of an existing trace setting

 <a trace setting object>. level=<trace level>

Example:

admin.tracesettings[0].level = "INFO" 

Valid values for trace level are: ALL, FINEST, FINER, FINE, INFO, WARNING, SEVERE, and OFF.

List all auditing records

List all auditing records

admin.audits

Output:

[
{
"created_time": "Mon, 06 Feb 2012 18:23:52 GMT",
"filesize": 0, "id": "a7579cec-000d-4358-9acc-54cdb5675f5d",
"state": "available",
"timezone": "GMT",
"updated_time": "Mon, 06 Feb 2012 18:23:53 GMT",
"version": "1.0.0.0"
}
...
]

Retrieve specific auditing record information

Retrieve specific auditing record information:

 admin.audits.get[<id>]
 

Example:

admin.audits.get("a7579cec-000d-4358-9acc-54cdb5675f5d")

Output:

{
    "created_time": "Mon, 06 Feb 2012 18:23:52 GMT",
    "filesize": 0,     "id": "a7579cec-000d-4358-9acc-54cdb5675f5d",
    "state": "available",
    "timezone": "GMT",
    "updated_time": "Mon, 06 Feb 2012 18:23:53 GMT",
    "version": "1.0.0.0"
}

Download a specific auditing record package

Download a specific auditing record package by its id

 <an auditrecord object>.download()

Example:

admin.audits.get("a7579cec-000d-4358-9acc-54cdb5675f5d").download()

or

admin.audits[0].download()

Output:

Download the file.

Retrieve auditing utilization

Retrieve auditing utilization

admin.audits.getUtilization()

Example:

admin.audits.getUtilization()

Output: 0.04

Create a new record package

Create a new record package (with or without a specific filter)

help(admin.audits.create)

Submit a request to create a new record package. This method accepts the following parameters:

setting

A Json object that contains setting parameters of the new record package.

Possible parameters are 'start_time' (long value), 'end_time' (long value), and 'timezone' (Java supported timezones), and all of them are optional. If either 'start_time' or 'end_time' are not given, it is considered as open start or end timestamp. If 'timezone' is not given, it is set to GMT automatically.

Example:

admin.audits.create({
       'start_time': 1328421600000,
       'end_time': 1330501500000,
       'time_zone': 'GMT'
     })

Output:

{
"created_time":
"Mon, 06 Feb 2012 18:23:52 GMT",
"filesize":
0, "id":
"a7579cec-000d-4358-9acc-54cdb5675f5d",
"state":
"available",
"timezone":
"GMT",
"updated_time":
"Mon, 06 Feb 2012 18:23:53 GMT",
"version":
"1.0.0.0"
}

Get current external storage server configuration

Get current external storage server configuration

admin.audits.getConfig()

Example:

admin.audits.getConfig()

Output:

{
"external_storage_audit_url": "http://172.16.98.179",
"external_storage_audit_download_path":
"/data/download",
"external_storage_audit_port_number": "22",
"external_storage_audit_limit": "250000"
}

Retrieve system public key for auditing

Retrieve system public key for auditing:

 admin.audits.getKey()
 

Example:

admin.audits.getKey()

Output:

"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjcoJwlOBGdtgXic9GqFRqfvn1XeQmwdnKkLhaT7RiwN7Bnj7meQKR7KsRaZwRH6GhQ04PdCdD8khc0W7WVxXQAJi9l8SghNrDrMcSEX2xlAVL/oE/wU1LO10A4eDw0i9dGWMiw5TQxsX0vztju5yuN8MjvjpoXY4pBZQ8EvYa+ErjeuqM4DI5UTPu1q3B4lmHaO+M8FprlT5z3XwivbhR8YKJFMF3nJUB7d7H30NQ1PqAb+n6HtMFY10HMKiW7q6VIsgfmjE2x1IFyuYhlkKKwypGmxtM/m2NWAOB0jzhnwirBCY49pCgjOeLtoqegdhgjOLZv4JJyimdTqZY/EDmwIDAQAB"

List all DNS servers

List all DNS servers

admin.dns.servers

Add DNS servers

Add DNS servers

admin.dns.servers.append(<single ip address string>) or admin.dns.servers.extend( <a list of ip address string>)

Example:

admin.dns.servers.append('172.16.248.2') or admin.dns.servers.extend(['172.16.248.2', '172.16.248.3'])

Remove a DNS server

Remove a DNS server

admin.dns.servers.remove(<single ip address string>)

Example:

admin.dns.servers.remove(admin.dns.servers[1])

List all NTP servers

List all NTP servers

admin.dateandtime.ntpservers

Add NTP servers

Add NTP servers

admin.dateandtime.ntpservers.append(<single ip address string>) 
 
or 
 
admin.dateandtime.ntpservers.extend( <a list of ip address string>)

Example:

admin.dateandtime.ntpservers.append('172.16.248.2') 
 
or 
 
admin.dateandtime.ntpservers.extend(['172.16.248.2', '172.16.248.3'])

Remove an NTP server

Remove an NTP server

admin.dateandtime.ntpservers.remove(<single ip address string>)

Example:

admin.dateandtime.ntpservers.remove(admin.dateandtime.ntpservers[1])

5.100. List SNMP information

List SNMP information

admin.snmp

5.101. Set system information

Set system information

admin.snmp.(system field)=<value>

Example:

admin.snmp.system_name=.server.

5.102. Create trap destination

Create trap destination

admin.snmp.trapdestinations.create(<dict object>)

Example:

admin.snmp.trapdestinations.create({.ipaddress.: .1.1.1.1., .community.:.public.})

5.103. Delete a trap destination

Delete a trap destination

(trapdestination object).delete()

Example:

admin.snmp.trapdestinations[0].delete()

5.104. List the ACL of a resource

List the ACL of a resource

(resouce object).acl

Example:

>>> admin.clouds[0].acl

5.105. Get the ACL of a given user or group

Add the user to a group

(resouce object).acl[<user or group object>]

or

(resouce object).acl["thename?user|group"]

Use the "?user|group" syntax when the user does not have the right to get the user or group object

Example:

>>>admin.clouds[0].acl[admin.users[0]]

or

>>>admin.clouds[0].acl["admin?user"]

5.106. Assign ACL to a given user or group

Assign ACL to a given user or group

(resouce object).acl[<user or group object>] = <permission>

or

(resouce object).acl["thename?user|group"] = <permission>

Use the "?user|group" syntax when the user does not have the right to get the user or group object

Example:

>>> admin.clouds[0].acl[admin.users[1]] = admin.READ_PERMISSION

or

>>> admin.clouds[0].acl["admin?user"] = admin.READ_PERMISSION

Valid permissions are: admin.READ_PERMISSION, admin.UPDATE_PERMISSION, admin.CREATE_PERMISSION, admin.DELETE_PERMISSION

5.107. Delete ACL of a given user of group

Delete ACL of a given user of group

del (resouce object).acl[<user or group object>]

or

del (resouce object).acl["thename?user|group"]

Use the "?user|group" syntax when the user does not have the right to get the user or group object

Example:

>>> del admin.clouds[0].acl[admin.users[1]]

or

>>> del admin.clouds[0].acl["user?admin"]

5.108. List current LDAP setting

List current LDAP setting

admin.ldap

Example:

>>> admin.ldap

5.109. Change LDAP setting

Change LDAP setting

admin.ldap.<setting name> = <value>

Example:

admin.ldap.jndi_provider_url = "ldaps://172.16.248.9:636"

5.110. Accept LDAP certificate

Accept LDAP certificate

admin.ldap.acceptCert(<jndi provider url(optional)>)

Example:

>>> admin.ldap.acceptCert()
 
or 
 
>>> admin.ldap.acceptCert(.ldaps://172.16.248.9:636.)

If no JNDI provider URL is passed, the current setting is used.

Use the CLI for databases

You can use the PureApplication System CLI to manage your database patterns, database instances, database images, database workloads, pattern types, and system plug-ins.

The following tasks can be completed using the CLI:

Database pattern type CLI command specifications

Retrieve detail information of database pattern type

deployer.patterntypes.get(<dbaas_patterntype>, <version>)

The value of {dbaas_patterntype} could be dbaas, dbaas.std.oltp or dbaas.std.datamart

Retrieve detail information of database pattern type details.

Example	deployer.patterntypes.get("dbaas.std.oltp","1.1")
Sample output	{ "description": "IBM Transactional Database Pattern", "name": "IBM Transactional Database Pattern", "required": (nested object), "shortname": "dbaas.std.oltp", "status": "avail", "version": "1.1" }

Accept license agreement of database pattern type

deployer.patterntypes.get((<dbaas_patterntype>,<version_vrmf>).acceptLicense()

The value of {dbaas_patterntype} could be dbaas.std.oltp or dbaas.std.datamart

Accept license agreement of database pattern type details.

Example	deployer.patterntypes.get('dbaas.std.oltp', '1.1.0.0').acceptLicense()
Sample output	{'status':'accepted'}

Enable database pattern type

deployer.patterntypes.get(<dbaas_patterntype>,<dbaas_version>).enable()

The value of {dbaas_patterntype} could be dbaas, dbaas.std.oltp or dbaas.std.datamart

Enable database pattern type details.

Example	deployer.patterntypes.get('dbaas', '1.1.0.0').enable()
Sample output	{'status':'avail'}

Disable database pattern type

deployer.patterntypes.get(<dbaas_patterntype>,<dbaas_version>).disable()

The value of {dbaas_patterntype} could be dbaas, dbaas.std.oltp or dbaas.std.datamart

Disable database pattern type details.

Example	deployer.patterntypes.get('dbaas', '1.1.0.0').disable()
Sample output	{ 'status': 'deprecated'}

Database Plug-in Configuration CLI command specifications

Retrieve plug-in configuration information

deployer.plugins.getConfig(<plugin_name>) or deployer.plugins.get(<plugin_name>).getConfig()

Retrieve plug-in configuration information details.

Example	deployer.plugins.getConfig('oltp/1.1.0.0')
Sample output	{ 'metadata': [ { 'label': 'Environment', 'displayId': 'Environment', 'type': 'string', 'id': 'parms.environment', 'options':[ { 'value': None, 'name': 'None(disabled)' } { 'value': 'PROD', 'name': 'Only IBM Transactional Database Pattern' } { 'value': 'NONPROD', 'name': 'Only IBM Transactional Database Pattern for Non-Production Environment' } { 'value': 'BOTH', 'name': 'Both' } ] } ], 'config': { 'version': '1.1.0.0', 'patterntypes': { 'secondary': [ { 'dbaas': '1.1' } ], 'primary': { 'dbaas.std.oltp': '1.1' } }, 'parms': { 'environment': 'PROD' 'dbaas_standard': True }, 'packages': { 'oltp.prod': [ { 'node-parts': [ { 'node-part': 'nodeparts/license.tgz', 'parms': { 'tagfile': 'Transactional_Database_Pattern.1.1.0.swtag' } } ] } ], 'oltp.nonprod': [ { 'node-parts': [ { 'node-part': 'nodeparts/license.tgz', 'parms': { 'tagfile': 'Transactional_Database_Pattern_for_Non_Production_Environment.1.1.0.swtag' } } ] } ] }, 'name': 'oltp' } }

Database Pattern CLI command specifications

List all database patterns

deployer.applications.list({"app_type":"database"})

List all database patterns details.

Example	deployer.applications._list({"app_type":"database"})
Sample output	{ "access_rights": (nested object), "acl": (nested object), "app_id": "a-5f733bb6-4be8-4c74-852f-055f09274192", "app_name": "pattern1", "app_type": "database", "artifacts": (nested object), "content_md5": "D086CC2D8E54E7E86E159085392DD6D8", "content_type": "application/json", "create_time": "2011-09-08T03:27:46Z", "creator": "cbadmin", "last_modified": "2011-09-08T03:27:48Z", "last_modifier": "cbadmin" }

Create a database pattern

deployer.applications.create(<LOCAL_FILE_PATH>)

Create a database pattern details.

a) Apply a default database workload standard. Example	deployer.applications.create("D:\\deployer.cli\\bin\\appmodel-default.json")
Input file: appmodel-default.json	{"model":{"app_type":"database","patterntype":"dbaas","version":"1.1","name":"dbp_default","description":"","nodes":[{"attributes":{"purpose":"production","source":"defaultWorkloadStandardApproach","dbDiskSize":30,"workloadStandard":"departmental_OLTP","sqlType":"DB2","dbTerritory":"US","dbCodeset":"UTF-8","dbCollate":"SYSTEM","versionName":"V97Linux","fixpackName":"db2_hybrid_en-9.7.0.5-linuxx64-20120112.tgz"},"type":"DB2","id":"database"}]}}
b) Applying a customized database workload standard. Example	deployer.applications.create("D:\\deployer.cli\\bin\\appmodel-customized.json")
Input file: appmodel-customized.json	{"model":{"app_type":"database","patterntype":"dbaas","version":"1.1","name":"dbp_cust","description":"","nodes":[{"attributes":{"purpose":"production","source":"workloadStandardApproach","cusDbDiskSize":30,"cusWorkloadStandard":"8e64a636-7920-4e11-a471-55ffb3e7b75c","cusVersionName":"V97Linux","cusFixpackName":"db2_hybrid_en-9.7.0.5-linuxx64-20120112.tgz"},"type":"DB2","id":"database"}]}}
c) Cloning from a database image. Example	deployer.applications.create("D:\\deployer.cli\\bin\\appmodel-clone.j son")
Input file: appmodel-clone.json	{"model":{"app_type":"database","patterntype":"dbaas","version":"1.1","name":"clone_dbp","description":"","nodes":[{"attributes":{"purpose":"production","source":"cloneApproach","databaseImage":"auto_172.16.68.124_mydb6_20120511230014.json"},"type":"DB2","id":"database"}]}}
Sample output	{ "access_rights": (nested object), "acl": (nested object), "app_id": "a-aa0581a8-c0e1-47ce-8909-686f1b588edf", "app_name": "dbp_default", "app_type": "database", "artifacts": (nested object), "content_md5": "3EB002BE6EB3CE941FDE95668B283E35", "content_type": "application/json", "create_time": "2012-05-14T02:30:34Z", "creator": "cbadmin", "last_modified": "2012-05-14T02:30:34Z", "last_modifier": "cbadmin", "patterntype": "dbaas", "version": "1.1" }

Update a database pattern specified by Database Pattern ID

deployer.applications.get(<dbpatternID>).update("<local file path>")

Update a database pattern details.

Example	deployer.applications.get("a-5f733bb6-4be8-4c74-852f-055f09274192").update("/home/updateDBPattern.json")
Input file: createDBPattern.json	{"model": {"app_type":"database", "patterntype":"dbaas", "version":"1.1", "name":"db_pattern1", "description":" ","nodes": [{"attributes": {"purpose":"production", "source":"defaultWorkloadStandardApproach", "dbDiskSize":30, "workloadStandard":"departmental_OLTP" "sqlType":"DB2" "dbTerritory":"US" "dbCodeset":"UTF-8" "dbCollate":"SYSTEM" "versionName":"V97Linux" "fixpackName":"db2_hybrid_en-9.7.0.5-linuxx64-20120112.tgz"} "type":"DB2" "id":"database"}]}}
Sample output	No output. View the details of the updated pattern type to verify that the command executed successfully.

Upload a script file for database pattern specified by Database Pattern ID

deployer.applications.get(<dbpatternID>).artifacts.upload(<local_file_path>)

Upload a script file for database pattern specified by Database Pattern ID details.

Example	deployer.applications.get("a-5f733bb6-4be8-4c74-852f-055f09274192").artifacts.upload("/home/lyy/my/testdb.sql")
Sample output	{'file': 'artifacts/testdb.sql', 'file_name': 'testdb.sql', 'fileName': 'testdb.sql'}

Update database pattern access rights for specified user name or group name

deployer.applications.get(<dbpatternID>).sharegroup(<group_name>,<accessRights>)
deployer.applications.get(<dbpatternID>).shareuser(<user_name>,<accessRights>)

Update database pattern access rights for specified user name or group name details..

Example, group	deployer.applications.get("a-cdaac959-672c-4df7-a648-b333a3843422").sharegroup("Everyone","F")
Example, user	deployer.applications.get("a-cdaac959-672c-4df7-a648-b333a3843422").shareuser("liuyy","F")
Sample output	No output. View the details of the updated pattern type to verify that the command executed successfully.

Delete a database pattern specified by Database Pattern ID

deployer.applications.delete(<dbpatternID>)

Delete a database pattern specified by Database Pattern ID details.

Example	deployer.applications.delete("a-5f733bb6-4be8-4c74-852f-055f09274192")
Sample output	No output. View the list of all pattern types to verify if the pattern type has been removed.

Database Instance CLI command specifications

You must create a database pattern before deploying a database when using CLI commands.

List all databases

deployer.databases.getlist()

List all databases details.

Example	deployer.databases.getlist()
Sample output	[ { 'status': 'TERMINATED', 'creator_name': 'cbadmin', 'dbname': 'mydb', 'start_time': '2011-10-18T06: 55: 46.661Z', 'id': 'd-fc0c1425-8daf-41ba-ac6e-7413d7f4bc87', 'creator': 'cbadmin' }, ... ]

Provision a database specified by Database Pattern ID

deployer.applications.get("<dbpatternID>").deploy("<deployment_name>", <cloud_group (optional)>, <certFile>(optional), <params>)

Provision a database specified by Database Pattern ID details.

Example	deployer.applications.get("a-aa0581a8-c0e1-47ce-8909-686f1b588edf ").deploy("defdb",deployer.clouds[0],None,{"database.dbname":"defdb"})
Sample output	{ "acl": (nested object), "app_id": "a-aa0581a8-c0e1-47ce-8909-686f1b588edf", "app_type": "database", "appmodel": "https://172.16.65.62:9444/storehouse/user/deployments/d-d497f877- 4526-4578-8e4d-2662fd1125f2/appmodel.json", "deployment": "https://172.16.65.62:9444/storehouse/user/deployments/d-d497f87 7-4526-4578-8e4d-2662fd1125f2/deployment.json", "deployment_name": "defdb", "id": "d-d497f877-4526-4578-8e4d-2662fd1125f2", "maintenance_mode": False, "operations": (nested object), "role_error": False, "start_time": "2012-05-14T02:36:39.017Z", "status": "LAUNCHING", "topology": "https://172.16.65.62:9444/storehouse/user/deployments/d-d497f877- 4526-4578-8e4d-2662fd1125f2/topology.json" }

Retrieve database information specified by Database ID

deployer.databases.get(<database_ID>)

Retrieve database details specified by Database ID details.

Example	deployer.databases.get("d-201fd95b-31c4-403a-8169-7c976da57a2f")
Sample output	{ 'status': 'TERMINATED', 'description': '', 'dbname': 'mydb', 'id': 'd-fc0c1425-8daf-41ba-ac6e-7413d7f4bc87', 'creator': 'cbadmin', 'sqlType': 'DB2' }

Destroy a database specified by Database ID

deployer.virtualapplications.terminate("d-201fd95b-31c4-403a-8169-7c976da57a2f")

Destroy a database specified by Database ID details.

Example	https://localhost/resources/virtualApplications/d-7956c64e-0fac-49f2-b04e-efbc131a4cc4
Sample output	True

Delete a database specified by Database ID

deployer.virtualapplications.delete(<dbID>)

Delete a database specified by Database ID details.

Example	deployer.virtualapplications.delete("d-201fd95b-31c4-403a-8169-7c976da57a2f")
Sample output	No output. View the list of all databases to verify the database has been removed.

Database Image CLI command specifications

List all database images

deployer.dbimages.getlist()

List all database images details.

Example	deployer.dbimages.getlist()
Sample output	[{'tsmnodename': 'd-3651868c-99d7-4fd4-89fb-02a6f0b01a6d', 'timestamp': '20110518092615', 'dbname': 'mydb', 'imagename': 'bk30', 'id': 'myimage2.json', 'imagedescription': 'bk', 'host': '172.16.37.180'}]

List database images by dbaasversionge

deployer.dbimages.getlist({"dbaasversionge":< dbaas_version>})

List database images by dbaasversionge details.

Example	deployer.dbimages.getlist({"dbaasversionge":"1.1"})
Sample output	[{'tsmnodename': 'd-3651868c-99d7-4fd4-89fb-02a6f0b01a6d', 'timestamp': '20110518092615', 'dbname': 'mydb', 'imagename': 'bk30', 'id': 'myimage2.json', 'imagedescription': 'bk', 'host': '172.16.37.180'}]

Create a database image specified by Database ID

deployer.virtualapplications.get(<dbID>).operations.create (<python_dictionary_object>)

Creating a backup database image includes two parts: 1) create a database image manually 2) automatically create a database image

Create a database image specified by Database ID manually details.

Example	deployer.virtualapplications.get("d-201fd95b-31c4-403a-8169-7c976da57a2f").operations.create({"role": "database-db2.DB2","type": "backup","global": "false", "parameters": {"imageName": "testimage", "imageDescription": "My database image for testdb"},"script": "backup.py","method": "backup","roleType": "DB2"})
Sample output	{ "operation_id": "o-dc099918-e727-403e-aeb6-07ab4c8a5407", "parameters": (nested object), "result": (nested object), "role": "database-db2.DB2", "virtualapplication": (nested object) }

Create a database image specified by Database ID automatically details.

Example	deployer.virtualapplications.get("d-201fd95b-31c4-403a-8169-7c976da57a2f").operations.create({"role":"database-db2.DB2","type":"auto-backup", "parameters":{"frequency":"daily"}})
Sample output	{ "operation_id": "o-8baaa258-640f-44a6-ad58-256fa70c12dc", "parameters": (nested object), "result": (nested object), "role": "database-db2.DB2", "virtualapplication": (nested object) }

Retrieve database image information specified by Database Image ID

deployer.dbimages.get(<database_image_ID>)

Retrieve database image information specified by Database Image ID details.

Example	deployer.dbimages.get("myimage.json")
Sample output	{'tsmnodename': 'd-3651868c-99d7-4fd4-89fb-02a6f0b01a6d', 'dbaasversion': '1.1', 'backupmode': 'ONLINE', 'timestamp': '20110518092615', 'dbname': 'mydb', 'imagename': 'bk30', 'backuptype': 'NORMAL', 'imagedescription': 'bk', 'host': '172.16.37.180'}

Database Configuration CLI command specifications

Change appuser/appdba password specified by Database ID

deployer.virtualapplications.get(< dbID>).operations.create(< python_dictionary_object>)

Change appuser/appdba password specified by Database ID details.

Example	deployer.virtualapplications.get("d-201fd95b-31c4-403a-8169-7c976da57a2f").operations.create({"role": "database-db2.DB2","type": "configuration","global": false, "parameters": {"DB2.PASSWORD": "NQitXSzfpcZ6L3", "DB2.APPDBAPASSWORD": "8ga0AOQ79dkk1VwCQh"},"script": "change.py","method": "configuration","roleType": "DB2"})
Sample output	{ "role": "database-db2.DB2", "type": "configuration", "global": false, "parameters": { {"DB2.PASSWORD": "NQitXSzfpcZ6L3", "DB2.APPDBAPASSWORD": "8ga0AOQ79dkk1VwCQh"} }, "script": "change.py", "method": "configuration", "roleType": "DB2" }

Database Workload CLI command specifications

Get database workload list

deployer.dbworkloads.getlist()

Get database workload list details.

Example	deployer.dbworkloads.getlist()
Sample output	[ { "rate": "3", "workload_type": "Departmental OLTP", "workload_file": "departmental_OLTP.zip", "is_system": "true", "version": "1.1.0.1", "initial_disk_size": "1", "name": "Departmental Transactional", "id": "departmental_OLTP", "description": "For databases primarily used for online transaction processing (OLTP). The database will be optimized for transactional applications." }, { "rate": "3", "workload_type": "Dynamic Data Mart", "workload_file": "dynamic_datamart.zip", "is_system": "true", "version": "1.1.0.1", "initial_disk_size": "1", "name": "Data Mart", "id": "dynamic_datamart", "description": "For databases primarily used for data warehousing. The database will be optimized for reporting applications." }, { "rate": "3", "workload_type": "Departmental OLTP", "workload_file": " customized_oltp.zip", "is_system": "false", "version": "1.1.0.1", "initial_disk_size": "1", "name": "dwl1", "id":"121b79d0-9faf-457c-9bda-67b4864c115d", "description": "the first one" } ]

Database VM Logging CLI command specifications

Get log list from a database VM specified by Database ID and Virtual Machine ID

deployer.loggings.getLogList(deployer.virtualapplications.get(<dbID>),<v
mID>)

Get log list from a database VM specified by Database ID and Virtual Machine ID details.

Example	deployer.loggings.getLogList(deployer.virtualapplications.get("d-50dedbbc-a0f4-46ce-8788-8c09fe51f096"),"database-db2.11316173053230")
Sample output	{'DB2': ['/home/db2inst1/sqllib/log/instance.log', '/home/db2inst1/sqllib/db2dump/db2diag.log', '/home/db2inst1/sqllib/db2dump/db2inst1.nfy', '/home/db2inst1/sqllib/db2dump/stmmlog/stmm.0.log'], 'IWD Agent': ['/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.DB2/console.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.DB2/trace.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.SSH/console.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.SSH/trace.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.AGENT/console.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.AGENT/trace.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/console.log.0', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.systemupdate/console.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.systemupdate/trace.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/ffdc.log.0', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/trace.log.0', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.MONITORING/console.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/database-db2.11316173053230.MONITORING/trace.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/install/console.log', '/opt/IBM/maestro/agent/usr/servers/database-db2.11316173053230/logs/install/trace.log', '/0config/0config.log'], 'OS': ['/var/log/cron', '/var/log/acpid', '/var/log/wtmp', '/var/log/secure', '/var/log/brcm-iscsi.log', '/var/log/maillog', '/var/log/mcelog', '/var/log/messages', '/var/log/spooler', '/var/log/yum.log', '/var/log/boot.log', '/var/log/dmesg'] }

Download log content from a database VM specified by Database ID and Virtual Machine ID and Log File Path

deployer.loggings.download(<specific_file_name>, deployer.virtualapplications.get(<dbID>) , <vmID>, <log_File_Path>)

Download log content from a database VM specified by Database ID and Virtual Machine ID and Log File Path details.

Example	deployer.loggings.download("/home/mylog.log",deployer.virtualapplications.get("d-50dedbbc-a0f4-46ce-8788-8c09fe51f096"),"database-db2.11316173053230","/home/db2inst1/sqllib/db2dump/db2diag.log")
Sample output	No specific result is returned, you can check the downloaded log file from your <specific_file_name>.

Database Customized Workload Standards CLI command specifications

Create a new customized database workload standard

deployer.dbworkloads.create(<python_dictionary_object>)

Create a new customized database workload standard.

Example	deployer.dbworkloads.create({"rate":"3","workload_type":"Departmental OLTP","initial_disk_size":"1","name":"dbwl1","description":"the first one","is_system":"false","version":"1.1.0.1","workload_file":"customized_oltp.zip"})	workload_type: Value must be .Departmental OLTP. or .Dynamic Data Mart. initial_disk_size: Value must be from 0 to 500 rate: Value must be from 1 to 3 is_system: Value must be .false. workload_file: File must be a.zip file and the file name can not start with numbers or an underscore
Sample output	{ 'version': '1.1.0.1', 'initial_disk_size': '1', 'description': 'the first one', 'rate': '3', 'workload_type': 'Departmental OLTP', 'id': '121b79d0-9faf-457c-9bda-67b4864c115d', 'is_system': 'false', 'name': ' dbwl1', 'workload_file': 'customized_oltp.zip' }

Upload the .zip file

This step is required to create a customized workload standard.

deployer.dbworkloads.get(<dbworkloadID>).workloadfiles.upload("<local file path>")

Upload the .zip file.

Example	deployer.dbworkloads.get("121b79d0-9faf-457c-9bda-67b4864c115d").workloadfiles.upload("/root/deployer.cli/bin/customized_oltp.zip")
Sample output	{ 'filename': 'customized_oltp.zip', 'success': 'true' }	The file name must be the same as the value of "workload_file" in the meta json file.

List all database workload standards

deployer.dbworkloads.list()

List all database workload standards.

Example	deployer.dbworkloads.list()
Sample output	[ { "rate": "3", "workload_type": "Departmental OLTP", "workload_file": "departmental_OLTP.zip", "is_system": "true", "version": "1.1.0.1", "initial_disk_size": "1", "name": "Departmental Transactional", "id": "departmental_OLTP", "description": "For databases primarily used for online transaction processing (OLTP). The database will be optimized for transactional applications." }, { "rate": "3", "workload_type": "Dynamic Data Mart", "workload_file": "dynamic_datamart.zip", "is_system": "true", "version": "1.1.0.1", "initial_disk_size": "1", "name": "Data Mart", "id": "dynamic_datamart", "description": "For databases primarily used for data warehousing. The database will be optimized for reporting applications." }, { "rate": "3", "workload_type": "Departmental OLTP", "workload_file": " customized_oltp.zip", "is_system": "false", "version": "1.1.0.1", "initial_disk_size": "1", "name": "dwl1", "id":"121b79d0-9faf-457c-9bda-67b4864c115d", "description": "the first one" } ]

Update a customized database workload standard specified by Database Workload Standard ID

The two default database workload standards, Departmental Transactional and Data Mart, can not be updated.

deployer.dbworkloads.get(<dbworkloadID>).update(<python_dictionary_object>)

Update a customized database workload standard.

Example	deployer.dbworkloads.get("121b79d0-9faf-457c-9bda-67b4864c115d").update({"version": "1.1.0.1", "initial_disk_size": "1", "description": "the first one", "rate": "2", "workload_type": "Departmental OLTP", "id": "121b79d0-9faf-457c-9bda-67b4864c115d", "is_system": "false", "name": "dbwl1", "workload_file":"customized_oltp.zip"})	workload_type: Value must be .Departmental OLTP. or .Dynamic Data Mart. initial_disk_size: Value must be from 0 to 500 rate: Value must be from 1 to 3 is_system: Value must be .false. workload_file: File must be a.zip file and the file name can not start with numbers or an underscore
Sample output	No output.	Get the details of the updated workload standard to verify.

Download the .zip file of a customized database workload standard specified by Database Workload Standard ID and Zip File Name

deployer.dbworkloads.get("<dbworkloadID>").workloadfiles.download("<workload_file>","<local file path>") 

Download the .zip file of a customized database workload standard.

Example	deployer.dbworkloads.get("121b79d0-9faf-457c-9bda-67b4864c115d").workloadfiles.download("customized_oltp.zip","/root/deployer.cli/bin/a.zip")
Sample output	No output. Check the local file path.

Download the .zip file of a default database workload standard specified by Database Workload Standard ID and Zip File Name

deployer.dbworkloads.get("<dbworkloadID>").workloadfiles.download("<workload_file>","<local file path>") 

Download the .zip file of a default database workload standard.

Example	deployer.dbworkloads.get("departmental_OLTP").workloadfiles.download("departmental_OLTP.zip","/root/deployer.cli/bin/a.zip")
Sample output	No output. Check the local file path.

Delete a customized database workload standard

The two default database workload standards, Departmental Transactional and Data Mart, can not be deleted.

deployer.dbworkloads.get("<dbworkloadID>").delete()

Delete a customized database workload standard.

Example	deployer.dbworkloads.get("121b79d0-9faf-457c-9bda-67b4864c115d").delete()
Sample output	No output. Check the result by listing all database workload standards.

Database User Management CLI command specifications

Create a new user

deployer.virtualapplications.get(<dbID>).operations.create(<python_dictionary_object>)

Create a new user.

Example	deployer.virtualapplications.get("d-0a70a575-4bac-420e-8c7a-e663d2448e10").operations.create({"role":"database-db2.DB2","type":"createDB2User","parameters":{"sshAccess":"Deny","userName":"newuser","password":"123456","authLevel":["SYSADM","SYSCTRL","SYSMAINT","SYSMON"]},"groups":{}})
Sample output	{ "operation_id": "o-cc986b72-a38c-47a7-9940-61f0116e0e40", "parameters": (nested object), "result": (nested object), "role": "database-db2.DB2", "virtualapplication": (nested object) }

Change the password of a specified user

deployer.virtualapplications.get(<dbID>).operations.create(<python_dictionary_object>)

Change the password of a specified user.

Example	deployer.virtualapplications.get("d-0a70a575-4bac-420e-8c7a-e663d 2448e10").operations.create({"role":"database-db2.DB2","type":"resetPassword", "parameters":{"userName":"newuser","newPassword":"<xor>a2pp"},"groups":{} })
Sample output	{ "operation_id": "o-216e22e1-1085-4fae-ad67-b185883e0372", "parameters": (nested object), "result": (nested object), "role": "database-db2.DB2", "virtualapplication": (nested object) }

List all users for a specified database

deployer.virtualapplications.get(<dbID>).dbusers.getlist()

List all users for a specified database.

Example	deployer.virtualapplications.get("d-0a70a575-4bac-420e-8c7a-e663d 2448e10").dbusers.getlist()
Sample output	[{'sshAccess': 'Deny', 'userName': 'new2', 'authLevel': ''}, {'sshAccess': 'Allow', 'userName': 'user4', 'authLevel': 'SYSADM,SYSCTRL,SYSMAINT,SYSMON'}, {'sshAccess': 'Deny', 'userName': 'newuser', 'authLevel': 'SYSADM,SYSCTRL,SYSMAINT,SYSMON'}]

Delete a user

deployer.virtualapplications.get(<dbID>).operations.create(<python_dictionary_object>)

Delete a user.

Example	deployer.virtualapplications.get("d-0a70a575-4bac-420e-8c7a-e663d 2448e10").operations.create({"role":"database-db2.DB2","type":"userList","globa l":"false","role_type":"DB2","parameters":{"userName":"newuser"}})
Sample output	{ "operation_id": "o-18967b36-1776-4e66-b732-bdd099d1e794", "parameters": (nested object), "result": (nested object), "role": "database-db2.DB2", "virtualapplication": (nested object) }

Database DB2 Fix Pack CLI command specifications

The Create, Upload and Update steps are required to create a fix pack.

Create a DB2 fix pack

deployer.virtualapplications.get(<dbID>).operations.create(<python_dictionary_object>)

Create a DB2 fix pack.

Example	deployer.db2fixpacks.create(< python_dictionary_object >)
Sample output	{{'description': 'db2 v97fp6', 'id': 'f552d174-89da-4799-a130-82fe2973d8bd', 'name': 'v97fp6'}

Upload a package file by DB2 fix pack package name

deployer.db2fixpacks.upload("<local_file_path>")

Upload a package file by DB2 fix pack package name.

Example	deployer.db2fixpacks..upload("/home/alex/deployer.cli.3102/deployer.cli/bin/v9.7fp6_linuxx64_server.tgz")
Sample output	{'file': 'v9.7fp6_linuxx64_server.tgz', 'file_name': 'v9.7fp6_linuxx64_server.tgz', 'fileName': 'v9.7fp6_linuxx64_server.tgz'}

Update a package file by DB2 fix pack package name

deployer.db2fixpacks.get("<db2fixpackID>").update(<python_dictionary_object>)

List all users for a specified database.

Example	deployer.db2fixpacks.get("f552d174-89da-4799-a130-82fe2973d8bd").update({"name": "v97fp6","description": "db2 v97fp6", "id": "f552d174-89da-4799-a130-82fe2973d8bd","packageFile": "v9.7fp6_linuxx64_server.tgz "})	The uploaded file name must be the same with the value of "packageFile" in the meta json file.
Sample output	There is no output from this command, retrieve the details of the updated DB2 fix pack to verify success.

List all DB2 fix packs

deployer.db2fixpacks.list()

List all DB2 fix packs.

Example	deployer. db2fixpacks.list()
Sample output	[{ "db2fixpackfiles": (nested object), "description": "db2 v97fp7", "id": "9b59c1c5-87db-49c5-aea1-db49f9c7cd1d", "name": "db2v97fp7", "packageFile": " v9.7fp7_linuxx64_server.tgz ", "db2level": "9.7.0.7", "db2version": "9.7", "platform": "linuxx64" }, { "db2fixpackfiles": (nested object), "description": "db2 v97fp6", "id": "f552d174-89da-4799-a130-82fe2973d8bd", "name": "v97fp6", "packageFile": "v9.7fp6_linuxx64_server.tgz", "db2level": "9.7.0.6", "db2version": "9.7", "platform": "linuxx64" }]

List all fix packs valid for DB2 upgrade

deployer.db2fixpacks.getvalidfixpacks(<dbID>)

List all fix packs valid for DB2 upgrade.

Example	deployer.db2fixpacks.getvalidfixpacks("d-96652bdd-8543-4e51-aaa0-2eda7f582e7c ")
Sample output	{'label':'name','identifier':'value','items':[{'value':'v9.7fp6_linuxx64_server.tgz', 'name': 'V97fp6'}] }

List all DB2 fix packs valid for creating a database pattern or database instance

deployer. db2fixpacks. getfixpacks ()

List all DB2 fix packs valid for creating a database pattern or database instance.

Example	deployer.db2fixpacks.getfixpacks ()
Sample output	{'label': 'name', 'identifier': 'value', 'items': [{'platform': 'linuxx64', 'db2 version': '9.7', 'value': 'db2_hybrid_en-9.7.0.5-linuxx64-20120112.tgz', 'name': 'DB2 Version 9.7 Fix Pack 5 for Linux'}, {'platform': 'aix64', 'db2version': '9 .7', 'value': 'db2_hybrid_en-9.7.0.5-aix64-20120112.tgz', 'name': 'DB2 Version 9 .7 Fix Pack 5 for AIX'}, {'platform': 'linuxx64', 'db2version': '10.1', 'value': 'db2_hybrid_en-10.1.0.0-linuxx64-20120312.tgz', 'name': 'DB2 Version 10.1 for Linux'}, {'platform': 'aix64', 'db2version': '10.1', 'value': 'db2_hybrid_en-10.1 .0.0-aix64-20120312.tgz', 'name': 'DB2 Version 10.1 for AIX'}, {'platform': 'lin uxx64', 'db2version': '9.7', 'value': 'v9.7fp6_linuxx64_server.tgz', 'name': ''V97fp6''}]}

Create a database pattern that uses a DB2 fix pack

command:deployer.applications.create("<local_json_file_path>)") 

Create a database pattern that uses a DB2 fix pack.

Example	deployer.applications.create("D:\\deployer.cli\\bin\\appmodel-fixpack.json")	The content of appmodel-default.json looks like: {"model":{"nodes":[{"attributes":{"workloadStandard":"departmental_OLTP","dbDiskSize":10,"dbCodeset":"UTF-8","dbCollate":"SYSTEM","sqlType":"DB2","versionName":"V97Linux","fixpackName":"v9.7fp6_linuxx64_server.tgz","source":"defaultworkloadStandardApproach","dbTerritory":"US","purpose":"non-production"},"type":"DB2","id":"database"}],"version":"1.1","app_type":"database","patterntype":"dbaas","name":"fixPattern","description":"use the db2 fixpack named v9.7fp6_linuxx64_server"}}
Sample output	{ "access_rights": (nested object), "acl": (nested object), "app_id": "a-ab1cfdde-da0a-4cc2-aa86-9ddba1abcb29", "app_name": "fixPattern", "app_type": "database", "artifacts": (nested object), "content_md5": "DB9A55836909646ADECAB7551FEAD70F", "content_type": "application/json", "create_time": "2012-02-28T06:43:37Z", "creator": "cbadmin", "last_modified": "2012-02-28T06:43:39Z", "last_modifier": "cbadmin", "patterntype": "dbaas", "version": "1.1" }

Deploy a database with a database pattern that uses a DB2 fix pack

deployer.applications.get("<dbpatternID>").deploy("<deployment_name>", <cloud_group (optional)>, <certFile>(optional), <params>)

Deploy a database with a database pattern that uses a DB2 fix pack.

Example	deployer.applications.get("a-ab1cfdde-da0a-4cc2-aa86-9ddba1abcb29").deploy("fixdb",deployer.clouds[0],None,{"database.dbname":"fixdb"})
Sample output	{ "acl": (nested object), "app_id": "a-ab1cfdde-da0a-4cc2-aa86-9ddba1abcb29", "app_type": "database", "appmodel": "https://172.16.65.196:9444/storehouse/user/deployments/d-96652bdd -8543-4e51-aaa0-2eda7f582e7c/appmodel.json", "deployment": "https://172.16.65.196:9444/storehouse/user/deployments/d-96652b dd-8543-4e51-aaa0-2eda7f582e7c/deployment.json", "deployment_name": "fixdb", "id": "d-96652bdd-8543-4e51-aaa0-2eda7f582e7c", "maintenance_mode": False, "operations": (nested object), "role_error": False, "start_time": "2012-02-28T06:51:30.876Z", "status": "LAUNCHING", "topology": "https://172.16.65.196:9444/storehouse/user/deployments/d-96652bdd -8543-4e51-aaa0-2eda7f582e7c/topology.json" }]

Upgrade a deployed database

deployer.virtualapplications.get(<dbID>).operations.create(<python_dictionary_object>)

Upgrade a deployed database.

Example	deployer.virtualapplications.get("d-96652bdd-8543-4e51-aaa0-2eda7f582e7c").operations.create({"role":"database-db2.DB2","type":"applyFixpacks","parameters":{"fixpackName":"v9.7fp6_linuxx64_server.tgz"}})
Sample output	{ "operation_id": "o-45616cda-7594-4683-930f-81eccdaf0b44", "parameters": (nested object), "result": (nested object), "role": "database-db2.DB2", "virtualapplication": (nested object) }

Upgrade database application

deployer.virtualapplications.get(<dbID>).upgrade()

Upgrade database application.

Example	deployer.virtualapplications.get("d-96652bdd-8543-4e51-aaa0-2eda7f582e7c ").upgrade()
Sample output	True

Delete a specified DB2 fix pack

deployer.db2fixpacks.get("<db2fixpackID>").delete()

Delete a specified DB2 fix pack.

Example	deployer.db2fixpacks.get("f552d174-89da-4799-a130-82fe2973d8bd).delete()
Sample output	There is no output from this command, retrieve the list of all DB2 fix packs to verify if the fix pack has been removed.

Use the command line interface for the workload console

Anything that can be managed in IBM PureApplication System W1500 is a resource object on the CLI. The CLI manages different types of resources, for example, patterns, virtual images, and virtual system instances.

A user without the Workload resources administration (Full permission) role cannot set or modify the Access granted to: field of console resources, such as pattern resources and catalog resources by way of the command line. Instead, the user can use the workload console to modify the field, or another user with such permissions should modify the field.

Audit logging CLI reference

This topic provides a reference for collecting your audit reports using the CLI tool.

You can gather your reports by working with the following objects on the CLI:

• Audit

Audit object

An Audit object represents the audit logs stored on the system.

To get help on the CLI for the Audit object, pass the name of the object as an argument to the help() function. See the following example for details:

>>> help(deployer.audit)

Audit methods

You can use the following methods on an Audit object:

get(f, start, end, size)

This method downloads an audit log from the system in a .zip file. Use the size parameter to specify the maximum number of audit records to download. You can use other parameters to filter your record set, according to the time frame in which the records were logged.

Parameter descriptions:

• f - A file object or file name used to store the audit log. If a file name is specified, then .zip is automatically appended if the specified name does not end in .zip. If no name is specified, the file is given the default name of audit.zip.
• start - The earliest timestamp to be included in the audit data, specified as the number of seconds since midnight, January 1, 1970 UTC. Floating point values can be specified to indicate fractional seconds.
• end - The latest timestamp to be included in the audit data, specified as the number of seconds since midnight, January 1, 1970 UTC. Floating point values can be specified to indicate fractional seconds.
• tz - The time zone of the time frame that you specify with the start and end parameters. For example:

  deployer.audit.get("my.zip",start=1321391040,end=1321911000,tz="est")
  

• size - The maximum number of records to be written to the .zip file. You can request up to 20,000 records. If you specify a greater number, the product automatically resets your request to 20,000 records, and writes that number of records to the .zip file.

Returned audit data

The .zip file that you download contains four files:

• appliance-audit.csv - You receive this file if you migrated from a previous version of the product. The file contains all of the audit data that was logged by the system prior to your migration.
• license-audit.csv
• pvu-audit.csv
• audit-events.zip - This file contains four files: another .zip file of the audit event records that you just requested, as well as three other files. All four file names are:
  • audit-events.csv - This file contains the audit event records that you just specified for download.
  • audit-events-signed-events-checksum - Contains the digital signature that verifies both the integrity and authenticity of your audit data. Archive this file along with your event records.
  • audit-events-record-IDs
  • audit-events-signed-record-IDs

    The last two files contain data that you must use in a subsequent task, to delete your event records from the system and thus free storage resources.

The most important files for analysis and maintaining an audit trail are appliance-audit.csv, audit-events.csv, and audit-events-signed-events-checksum.

Next step: Because PureApplication System does not automatically delete audit data after you download it, you must run a script to delete the data from the system.

AddOn CLI reference

You can administer additions in the catalog using the IBM PureApplication System W1500 CLI.

AddOns object

An AddOns object represents the collection of add-ons defined to the PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for add-ons on the PureApplication System. To get help for the AddOns object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.addons)

AddOn object

An AddOn object represents a particular add-on defined on the PureApplication System. Use the AddOn object to query and manipulate the add-on definition on the PureApplication System. Attributes of the add-on and relationships between the add-on and other resources on the PureApplication System are represented as Python attributes on the AddOn object. Manipulate these Python attributes using standard Python mechanisms to make changes to the corresponding data on the PureApplication System. To get help for the AddOn object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.addon)

AddOn attributes

The AddOn object has the following attributes:

acl

The access control list for this add-on. For additional help on using this object, enter the following command:

>>> help(deployer.acl)

This field is read-only.

archive

An archive object represents the archive file associated with a particular add-on on the PureApplication System. This object provides mechanisms to query and manipulate the add-on archive on the PureApplication System. This field is read-only.

command

The command to be run for this add-on.

commandargs

The arguments that are passed to the command.

created

The creation time of the add-on, as the number of seconds since midnight January 1, 1970 UTC. When the add-on is displayed, this value is shown as the date and time in the local timezone. This field is read-only.

currentstatus

The current status of the add-on.

currentstatus_text

The textual representation of the currentstatus. This field is read-only.

description

The description of the add-on.

environment

The environment property holds the add-on keys and default values for the add-on. It is used much like a Python dict object, as shown in the following example:

 {
 "addonkey1": "value for addonkey1",
 "addonkey2": "value for addonkey2"
 }
 >>> myaddon.environment['addonkey1']
 'value for addonkey1'
 >>> myaddon.environment['foo'] = 'bar'
 >>> myaddon.environment
 {
 "foo": "bar",
 "addonkey1": "value for addonkey1",
 "addonkey2": "value for addonkey2"
 }
 >>> del myaddon.environment['foo']
 >>> myaddon.environment
 {
 "addonkey1": "value for addonkey1",
 "addonkey2": "value for addonkey2"
 }

This field is read-only.

id

The ID of the add-on. This field is read-only.

label

The label for the add-on. This field is read-only.

location

The directory, on the virtual machine, into which files for this add-on package are to be placed.

log

The directory, on the virtual machine, that is to contain the log files generated by this add-on.

name

The name associated with this add-on. Each add-on must have a unique name.

timeout

The maximum amount of time to wait for this add-on to finish running on a virtual machine. Specify the timeout as the number of milliseconds to wait, or 0 to wait indefinitely for the add-on to complete.

type

The type of add-on. This attribute must have a string value equal to one of the following constants:

• deployer.DISK_ADDON
• deployer.NIC_ADDON
• deployer.USER_ADDON

updated

Thd time the add-on was last updated, as number of seconds since midnight, January 1, 1970 UTC. When the add-on is displayed, this value is shown as the date and time in the local timezone. This field is read-only.

Archive methods

The Archive object has the following attributes:

get

This method retrieves the archive currently associated with the add-on. This method has one required parameter that indicates where the add-on archive should be saved. It can be either of the following values:

• A string containing the name of a file in which to save the archive. The .zip file type is automatically appended to the filename if the filename does not end in .zip.
• A Python file object. You must ensure that the file object can correctly handle binary data.

The add-on archive is returned in a zip file format, as shown in the following example

>>> myaddon.archive.get('/path/to/foo.zip')

__lshift__

This method is invoked implicitly when the Archive object is used as the left argument of a left shift operator (<<). It calls set() with the right argument of the operator, as shown in the following example:

>>> myaddon.archive << '/path/to/file'

__rshift__

This method is invoked implicitly when the Archive object is used as the left argument of a right shift operator (<<). It calls get() with the right argument of the operator, as shown in the following example:

 >>> myaddon.archive >> '/path/to/file.zip'

set

This method sets the archive associated with the add-on. It has one required parameter that indicates the source of the add-on archive to be uploaded. It maycan be either of the following values:

• A string containing the name of a file from which to get the archive.
• A Python file object.

You must ensure that the file object can correctly handle binary data, as shown in the following example:

>>> myaddon.archive.set('/path/to/foo')

Environment methods

The Environment object has the following attributes:

isDraft

Indicates if this add-on is in draft mode.

isReadOnly

Indicates if this add-on is read-only.

makeReadOnly

Makes this add-on read-only. When the add-on is read-only, it cannot be modified.

clone

Creates a copy of this add-on with all of the same files, fields, and settings. The new add-on has the name provided and an empty ACL.

Use the CLI for applications

You can use the CLI to manage the virtual application patterns, pattern types, virtual application instances and plug-ins.

7.3.1. Pattern type CLI

You can administer pattern types using the IBM PureApplication System W1500 CLI.

For information about working with the CLI, see the topic, Using CLI.

PatternType object

A PatternType object represents a particular pattern type defined on PureApplication System. Use the PatternType object to query and manipulate the pattern type definition. Attributes of the pattern type and relationships between the pattern type and other resources on PureApplication System are represented as Jython attributes on the PatternType object. Manipulate these Jython attributes using standard\nJython mechanisms to make changes to the corresponding data on PureApplication System. To get help for the PatternType object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.patterntype)

PatternTypes object

A PatternTypes object represents the collection of pattern types defined to PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for pattern types on PureApplication System. To get help for the PatternTypes object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.patterntypes)

PatternType attributes

The PatternType object has the following attributes:

• shortname

  The short name of the pattern type.

• name

  The name of the pattern type.

• version

  The version of the pattern type.

• description

  The description of the pattern type.

• status

  The status of the pattern type.

• required

  The prerequisites of the pattern type.

PatternTypes methods

The PatternTypes and PatternType object have the following methods:

acceptLicense

Accept the license of a given pattern type

deployer.patterntypes.get(<shortname>, <version>).acceptLicense()

Here the version should be in "vrmf" format, for example, "2.0.0.1".

For example, >>> deployer.patterntypes.get('webapp','2.0.0.1').acceptLicense()

list

List all pattern types deployer.patterntypes or deployer.patterntypes.list

For example, >>>deployer.patterntypes

By default, it will return pattern type with "vr" format, for example., "webapp 2.0". You can use deployer.patterntypes.list({"version":"vrmf"}) to list "vrmf" format, for example, "webapp 2.0.0.1".

For example,

>>>deployer.patterntypes.list({"version":"vrmf"}) 

get

get a pattern type with shortname and version

deployer.patterntypes.get(<shortname>, <version> )

For example,

>>> deployer.patterntypes.get('webapp','2.0.0.1')

create

Create a pattern type from a tgz file

deployer.patterntypes.create(<tgz_file_path>).

For example,

>>> deployer.patterntypes.create('E:\\dbaas-2.0.0.1.tgz') 

delete

Delete a pattern type

deployer.patterntypes.delete(<shortname>, <version>)

Here the version should be in "vrmf" format.

For example,

>>> deployer.patterntypes.delete('dbaas','2.0.0.1') 

enable

Enable a pattern type

deployer.patterntypes.get(<shortname>, <version>).enable()

Here, the version should in in "vrmf" format, for example, "2.0.0.1"

For example,

>>> deployer.patterntypes.get('dbaas','2.0.0.1').enable()

disable

Disable a pattern type

deployer.patterntypes.get(<shortname>, <version>).disable()

Here, the version should in in "vrmf" format, for example, "2.0.0.1"

For example,

>>> deployer.patterntypes.get('dbaas','2.0.0.1').disable()

7.3.2. Virtual application pattern CLI reference

You can administer virtual application pattern using the IBM PureApplication System W1500 CLI.

ApplicationPattern object

For information about working with the CLI, see the Using the CLI topic.

An ApplicationPattern object represents a particular virtual application pattern defined in PureApplication System. Use the ApplicationPattern object to query and manipulate the virtual application pattern definition. Attributes of the virtual application pattern and relationships between the virtual application pattern and other resources in PureApplication System are represented as Jython attributes on the ApplicationPattern object. Manipulate these Jython attributes using standard Jython mechanisms to make changes to the corresponding data on PureApplication System. To get help for the ApplicationPattern object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.application)

ApplicationPatterns object

An ApplicationPatterns object represents the collection of virtual application patterns defined in PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for virtual application patterns in PureApplication System. To get help for the ApplicationPatterns object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.applications)

ApplicationPattern attributes

The ApplicationPattern object has the following attributes:

acl

The access control list for this application pattern.

app_id

The id of the application pattern. The application pattern ID has to be unique. This value is automatically generated and cannot be changed.

app_name

The name of the application pattern. The name of the application pattern does not have to be unique.

app_type

Type of the application pattern.

artifacts

Artifacts of the application pattern.

create_time

The creation time of the application pattern.

creator

Creator of the application pattern.

description

The description of the application pattern.

last_modified

Time the application pattern was updated.

last_modifier

The last user who updated the application pattern.

ApplicationPattern methods

The ApplicationPattern and ApplicationPatterns object have the following methods:

List all applications patterns

deployer.applications

For example,

>>> deployer.applications 

Get a single application pattern by index:

deployer.applications[<index>]

For example,

>>> deployer.applications[0] 

Search for a single application with app_id

deployer.applications[<app_id>][0]

Example: deployer.applications["a-f4979c44-5a4f-42c0-bbbe-26a91a5a13cc"][0]

Sample output:

>>> deployer.applications.list({'name':'try1'})[0] 
{
"access_rights": (nested object),
"app_id": "a-f4979c44-5a4f-42c0-bbbe-26a91a5a13cc",
"app_name": "try1",
"app_type": "application",
"artifacts": (nested object),
"content_md5": "D3DAE053B982C86DEC80A4FFEA492812",
"content_type": "application/json",
"create_time": "2011-03-17T07:45:30Z",
"creator": "vivien",
"last_modified": "2011-03-17T07:45:32Z",
"last_modifier": "vivien"
}

Search for applications with a filter(dict format)

deployer.applications.list(<filter in dict format>)

Example: deployer.applications.list({'app_name':'testapp'})

Sample output:

>>> deployer.applications.list({'app_name':'application'}) 
[{
"access_rights": (nested object),
"app_id": "a-9121a3b3-bc9f-46c1-a1b4-53ce52fe087a",
"app_name": "Secured JEE web application",
"app_type": "application",
"artifacts": (nested object),
"content_md5": "9990B7128E0CC488081B092647DF1FEE",
"content_type": "application/json",
"create_time": "2011-03-11T18:50:39Z",
"creator": "cbadmin",
"last_modified": "2011-03-11T18:50:40Z",
"last_modifier": "cbadmin"
}, 
...
, {
"access_rights": (nested object),
"app_id": "a-f0049cf6-8f58-4da0-a4d9-f00000a08490",
"app_name": "Sample JEE web application",
"app_type": "application",
"artifacts": (nested object),
"content_md5": "024DFB5FC8679B2EDF0F21A5CB20A3F4",
"content_type": "application/json",
"create_time": "2011-03-11T18:50:36Z",
"creator": "cbadmin",
"last_modified": "2011-03-11T18:50:37Z",
"last_modifier": "cbadmin"
}]

Share an application with another user

deployer.applications.get(<app_id>).shareuser(<user name>,<access rights>)

Example: deployer.applications.get("a-f4979c44-5a4f-42c0-bbbe-26a91a5a13cc").shareuser("tester","F")

Share an application with another group

deployer.applications.get(<app_id>).sharegroup(<group name>,<access rights>)

Example: deployer.applications.get("a-f4979c44-5a4f-42c0-bbbe-26a91a5a13cc").sharegroup("users","F")

Create a virtual application pattern

deployer.applications.create(<specific attributes>)

Create an empty application pattern

deployer.applications.create("<local file path>")

Create an application pattern with JSON file or zip file, the file type is decided by the file extension

For example,

(1) Use specific attributes

>>> deployer.applications.create({'name':'demoApp'})  

(2). Use zip package or JSON file

>>> deployer.applications.create("C:\\sample.json") 

Delete an application pattern

deployer.applications.delete(<app_ID>)

For example,

>>> deployer.applications.delete("a-6aa5bf17-0c1e-457c-b135-7c8d19401109") 

Update an application pattern

deployer.application.get(<app_ID>).update(<local file path>")

For example,

>>> deployer.applications.get("a-514a4175-a771-4b3f-8761-0227663d9181").update("C:\\sample.zip") 

Clone an application pattern from an existing application pattern

deployer.application.get(<app_ID>).clone(<app_name>, <app_type>)

app_type is an optional parameter, the default is "application"

For example,

>>> deployer.applications.get("a-7dd50b00-c74c-4c63-ab70-abd7dff7fcdf").clone("clonedTest") 

Deploy an application pattern

deployer.applcations.get(<app_ID>).deploy(<depl_name>, <cloud object or env dict>, <certFile>(optional), <params>(optional))

For the second parameter, you can use a cloud object or a dictionary to describe the environment profile. The environment profile dictonary format is:

{
'environment_profile': <env_profile_obj> or <env_profile_id>
           'cloud_group': <cloud_group_obj> or   <cloud_group_id>
           'ip_group': <ip_group_obj> or <ip_group_id>
'ip_version': 'IPv4' or 'IPv6' 
    }

You can use ssh-keygen (http://www.laubenheimer.net/ssh-keys.shtml ) to generate SSH keys and save the public key in a file.

The format for <params> is:

{ "node_link_id.attributeId": attributeValue,                                                   
"groups":{"node_link_id.groupId": True/False} (optional) }. 

Need to specify "groups" if there is group definition in the plug-in metadata.

Example:

deployer.applcations.get(<app_id>).deploy(<depl_name>, <cloud object or env dict>, <certFile>(optional), <params>(optional))  

Example:

sample= deployer.applications.get('a-b62aeddb-6b43-4421-a0b6-df41b44c5407')                      
env=deployer.environmentprofiles[0]                     
cloud = env.clouds.keys()[0]                     
ipgroup=env.clouds[cloud].ipgroups.keys()[0]                     
deployOptions = {"environment_profile" : env,                            
"cloud_group": cloud,                            
'ip_group': ipgroup,                           
'ip_version': 'IPv4'                          
}               
vapp = sample.deploy('env_test', deployOptions)

Export the virtual application pattern as a single ZIP file in the local directory

The file contains the application model and archive files such as EAR or WAR files for the Web Application component and SQL files for the DB2 component.

deployer.applications[0].download("<local directory>"

List all attributes and groups

deployer.applications.listConfig()

Sample output:

{
  "Additional archive file.external_archive": "artifacts/page.zip",
  "Additional archive file.extract_path": "/webapp",
  "Log Policy.ErrLogMaxNum": None,   "Log Policy.ErrLogMaxSize": None,   "Log Policy.ErrLogName": None,   "Log Policy.OutLogMaxNum": None,   "Log Policy.OutLogMaxSize": None,   "Log Policy.OutLogName": None,   "Log Policy.extraLogDirectories": "/var/log/clientlogs/",
  "Log Policy.logLevel": "*=info",
  "WASFILE_1.sharedLibraryName": None,   "Web Application.archive": "artifacts/webappSampleWeb.war",
  "Web Application.ctx_root": "webapp",
  "Web Application.ifixes": None,   "Web Application.ignoreFailedIfix": True,
  "Web Application.maxSessionCount": None,   "groups": {
    "WASFILE_1.ShareLibrary": False
  }
}

List all artifacts

deployer.applications.get(<app_id>).artifacts

Example: deployer.applications["a-1881c73e-cac4-4af4-ba16-639ae47befff"][0].artifacts.list()

Sample output:

>>> deployer.applications.get("a-1881c73e-cac4-4af4-ba16-639ae47befff").artifacts
[
{
"content_type": "application/octet-stream",
"last_modifier": "tester",
"create_time": 1074528964,
"last_modified": 1074528964,
"access_rights": {
"tester": "F"
},
"content_md5": "64C79B6A807A13B028E5E43E950E09BD",
"name": "CounterDB.sql",
"creator": "tester"
},
... 
]

Get a single artifact by index

deployer.applications.get(<app_id>).artifacts[<index>]

Example: deployer.applications.get("a-4f581e31-b1d1-416d-8395-1d0692515eed").artifacts[0]

Sample output:

>>>deployer.applications.get("a-4f581e31-b1d1-416d-8395-1d0692515eed").artifacts[0]
{
"content_type": "application/octet-stream",
"last_modifier": "tester",
"create_time": 1074528964,
"last_modified": 1074528964,
"access_rights": {
"tester": "F"
}

Upload an artifact file for an application

deployer.applications.get(<app_id>).artifacts.upload(<local file path>)

Example: deployer.applications.get("a-4f581e31-b1d1-416d-8395-1d0692515eed").artifacts.upload("C:\\artifacts\\hello.war")

Sample output:

>>> deployer.applications.get("a-4f581e31-b1d1-416d-8395-1d0692515eed").artifacts.upload("C:\\artifacts\\hello.war") 
>>> 

Download an artifact file of an application

deployer.applications[<app_id>][0].artifacts.download(<artifact file name>, <local file path>)

Example: deployer.applications["a-4f581e31-b1d1-416d-8395-1d0692515eed"][0].artifacts.download("hello.war","D:\\hello.war")

Sample output:

>>> deployer.applications["a-4f581e31-b1d1-416d-8395-1d0692515eed"][0].artifacts.download("hello.war","D:\\hello.war") 
>>> 

7.3.3. Virtual application instance CLI reference

You can administer virtual application instances using the IBM PureApplication System W1500 CLI.

VirtualApplication object

A VirtualApplication object represents a particular virtual application instance defined on PureApplication System. Use the VirtualApplication object to query and manipulate the virtual application instance definition. Attributes of the virtual application instance and relationships between the virtual application instance and other resources on PureApplication System are represented as Jython attributes on the VirtualApplication object. Manipulate these Jython attributes using standard Jython mechanisms to make changes to the corresponding data on PureApplication System. To get help for the VirtualApplication object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.virtualapplication)

VirtualApplications object

A VirtualApplications object represents the collection of virtual application instances defined to PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for virtual application instances on PureApplication System. To get help for the VirtualApplications object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.virtualapplications)

VirtualApplication methods

The VirtualApplication and VirtualApplications object have the following methods:

List all virtual applications

deployer.virtualapplications or deployer.virtualapplications.list

Sample output:

>>> deployer.virtualapplications
[
{
"app_id": "a-f0049cf6-8f58-4da0-a4d9-f00000a08490",
"app_type": "application",
"appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-1529
3b0d-66bb-4d87-8d4d-3664e985fb6d/deployment.json",
"deployment_name": "Sample JEE web application 1",
"id": "d-15293b0d-66bb-4d87-8d4d-3664e985fb6d",
"monitorings": (nested object),
"operations": (nested object),
"role_error": False,
"start_time": "2011-03-11T19:08:39.489Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/topology.json"
},
{
"app_id": None, "app_type": None, "appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-4c59d3
31-de27-4b13-9ce1-5c7ec0d19913/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-4c59
d331-de27-4b13-9ce1-5c7ec0d19913/deployment.json",
"deployment_name": None, "id": "d-4c59d331-de27-4b13-9ce1-5c7ec0d19913",
"monitorings": (nested object),
"operations": (nested object),
"role_error": True,
"start_time": "2011-03-11T18:59:48.779Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-4c59d3
31-de27-4b13-9ce1-5c7ec0d19913/topology.json"
}
]

Search for virtual application instances with a filter(dict format):

deployer.virtualapplications.list(<filter in dict format>)

Example: >>> deployer.virtualapplications.list({'app_type':'application'})

Sample output:

>>> deployer.virtualapplications.list({'app_type':'application'}) 
[{
"app_id": "a-f0049cf6-8f58-4da0-a4d9-f00000a08490",
"app_type": "application",
"appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b0d
-66bb-4d87-8d4d-3664e985fb6d/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/deployment.json",
"deployment_name": "Sample JEE web application 1",
"id": "d-15293b0d-66bb-4d87-8d4d-3664e985fb6d",
"monitorings": (nested object),
"operations": (nested object),
"role_error": False,
"start_time": "2011-03-11T19:08:39.489Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b0d
-66bb-4d87-8d4d-3664e985fb6d/topology.json"
}]

Get a single virtual application instance by index:

deployer.virtualapplications[<index>]

Example: >>>deployer.virtualapplications[0]

Sample output:

>>>deployer.virtualapplications[0]
{
"app_id": "a-f0049cf6-8f58-4da0-a4d9-f00000a08490",
"app_type": "application",
"appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-1529
3b0d-66bb-4d87-8d4d-3664e985fb6d/deployment.json",
"deployment_name": "Sample JEE web application 1",
"id": "d-15293b0d-66bb-4d87-8d4d-3664e985fb6d",
"monitorings": (nested object),
"operations": (nested object),
"role_error": False,
"start_time": "2011-03-11T19:08:39.489Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/topology.json"
}

Get a single virtual application with a deployment ID (depl_id)

deployer.virtualapplications.get(<depl_id>)

Example: >>> deployer.virtualapplications.get("d-15368912-20db-4d65-958b-36f54fa1e462")

Sample output:

>>> deployer.virtualapplications.get("d-15368912-20db-4d65-958b-36f54fa1e462") 
{
"app_id": "a-f0049cf6-8f58-4da0-a4d9-f00000a08490",
"app_type": "application",
"appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b0d
-66bb-4d87-8d4d-3664e985fb6d/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/deployment.json",
"deployment_name": "Sample JEE web application 1",
"id": "d-15293b0d-66bb-4d87-8d4d-3664e985fb6d",
"monitorings": (nested object),
"operations": (nested object),
"role_error": False,
"start_time": "2011-03-11T19:08:39.489Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b0d
-66bb-4d87-8d4d-3664e985fb6d/topology.json"
}

Show vm instance details of a deployed application

(virtualapplication).vminstances()

Example: >>> deployer.virtualapplications.get("d-2e0c8abb-373f-46fc-a05f-a255af3d3120").vminstances()

Sample output:

>>> deployer.virtualapplications[0].vminstances()
 
{
"app_id": "d-2e0c8abb-373f-46fc-a05f-a255af3d3120",
"app_type": "application",
"creator": "u-0",
"creator_name": "cbadmin",
"deployment_name": "Sample JEE web application",
"instances": (nested object),
"role_error": False,
"start_time": "2011-08-17T21:16:59.266Z",
"status": "RUNNING",
"virtual_system": (nested object)
}

Start a virtual application instance

deployer.virtualapplications.start(<depl_id>)

Example:

>>> deployer.virtualapplications.start("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c")

Stop a virtual application instance

deployer.virtualapplications.stop(<depl_id>).

Example:

>>> deployer.virtualapplications.stop("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c")

Terminate a deployed application

deployer.virtualapplications.terminate(<depl_id>)

Example: >>> deployer.virtualapplications.terminate("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c")

Sample output:

>>> deployer.virtualapplications.terminate("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c") 
>>> 

Delete a deployed application

or deployer.virtualapplications.get(<depl_id>.delete()

Examples: deployer.virtualapplications.delete("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c") or deployer.virtualapplications.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").delete()

Sample output:

>>> deployer.virtualapplications.delete("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c") 
>>>

You can specify that you do not want to delete deployment history by calling deployer.virtualapplications.get(<depl_id>).delete(False).

Share a virtual application with another user

deployer.virtualapplications.get(<depl_id>).shareuser(<username>,<access rights>)

Example:

deployer.virtualapplications.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").shareuser("tester","F")

Share a virtual application with another group

deployer.virtualapplications.get(<depl_id>).sharegroup(<username>,<access rights>)

Example:

 >>>deployer.virtualapplications.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").sharegroup("users","F")

Start a virtual machine

deployer.virtualapplications.get(<depl_id>)startvm(<node_id>)

Example:

 >>>deployer.virtualapplications.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').startvm('database-db2.11304523030092')

Stop a virtual machine

deployer.virtualapplications.get(<depl_id>)startvm(<node_id>)

Example:

>>>deployer.virtualapplications.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').stop('database-db2.11304523030092')

Refresh the cached attribute values

Call this method before getting status of the instance.

deployer.virtualapplications.get(<depl_id>).refresh()

Example:

>>>deployer.virtualapplications.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873'). refresh()

Put a virtual application instance in maintenance mode

deployer.virtualapplications.get(<depl_id>).maintain()

Example:

>>>deployer.virtualapplications.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873'). maintain()

Resume a virtual application instance from maintenance mode

deployer.virtualapplications.get(<depl_id>).resume()

Example:

>>>deployer.virtualapplications.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873'). resume()

Upgrade the pattern type of a virtual application instance to the latest

deployer.virtualapplications.get(<depl_id>).upgrade().

Example:

>>>deployer.virtualapplications.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').upgrade()

Stop a deployed application

deployer.virtualapplications.get(<depl_id>).stop()

Example:

deployer.virtualapplications.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c") .stop()

Start a deployed application

(virtual application).start()

Example:

deployer.virtualapplications.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c") .start()

Commit the upgrade of an instance

deployer.virtualapplications.get(<depl_id>).commit()

Example:

>>>deployer.virtualapplications.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').commit()

Revert the upgrade of an instance

deployer.virtualapplications.get(<depl_id>).revert().

Example:

>>>deployer.virtualapplications.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').revert()

7.3.4. Shared service instance CLI reference

You can administer shared service instances using the IBM PureApplication System W1500 CLI.

SharedService object

A SharedService object represents a particular shared service instance defined on PureApplication System. Use the SharedService object to query and manipulate the shared service instance definition. Attributes of the shared service instance and relationships between the shared service instance and other resources on PureApplication System are represented as Jython attributes on the SharedService object. Manipulate these Jython attributes using standard Jython mechanisms to make changes to the corresponding data on PureApplication System. To get help for the SharedService object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.sharedservice)

SharedServices object

A SharedServices object represents the collection of shared services instances defined to PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for shared service instances on PureApplication System. To get help for the SharedServices object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.sharedsservices)

SharedService attributes

The SharedService and SharedServices objects have the following attributes:

access_rights

The access object of this shared service.

acl

Access control list for the shared service.

app_id

The ID of the shared service. The shared service ID must be unique.

app_name

The name of the shared service.

app_type

The type of shared service. The type of all shared services is service.

artifacts

A resource collection that contains the artifacts of this shared service.

content_md5

The content-MD5 of the shared service.

content_type

The content-type of the shared service.

create_time

The time the shared service was created.

creator

The creator of the shared service.

last_modified

The time the shared service was updated.

last_modifier

The last user who updated the shared service.

patterntype

The version of the pattern type.

service_name

The unique name of each type of shared service. This value is not translated.

service_type

The type of shared service. The value is either External or left blank.

version

The name of the pattern type.

SharedService methods

The SharedService and SharedServices objects have the following methods:

List all shared services

deployer.sharedservices

Sample output:

>>> deployer.sharedservices
[
{
   "access_rights": (nested object),
   "acl": (nested object),
   "app_id": "a-2a27189e-03bc-4f49-9526-6e31fdbeb8f7",
   "app_name": "ELB Proxy Service",
   "app_type": "service",
   "artifacts": (nested object),
   "content_md5": "248F36669E4CA533588AB8E599600195",
   "content_type": "application/json",
   "create_time": "2012-04-11T09:51:42Z",
   "creator": "cbadmin",
   "last_modified": "2012-04-11T09:51:42Z",
   "last_modifier": "cbadmin",
   "patterntype": "foundation",
   "service_name": "proxy",
   "service_type": "",
   "version": "2.0"
 },
.
]

Get a single shared service by index

deployer.sharedservices[<index>]

Example: deployer.sharedservices[0]

Sample output:

{
   "access_rights": (nested object),
   "acl": (nested object),
   "app_id": "a-2a27189e-03bc-4f49-9526-6e31fdbeb8f7",
   "app_name": "ELB Proxy Service",
   "app_type": "service",
   "artifacts": (nested object),
   "content_md5": "248F36669E4CA533588AB8E599600195",
   "content_type": "application/json",
   "create_time": "2012-04-11T09:51:42Z",
   "creator": "cbadmin",
   "last_modified": "2012-04-11T09:51:42Z",
   "last_modifier": "cbadmin",
   "patterntype": "foundation",
   "service_name": "proxy",
   "service_type": "",
   "version": "2.0"
}

Get a single shared service with app_id

deployer.sharedservices.get(<app_id>)

Example: deployer.sharedservices.get("a-f753298c-5c7d-4e75-86f8-8cbb2d3c6f6a")

Sample output:

{
   "access_rights": (nested object),
   "acl": (nested object),
   "app_id": " a-f753298c-5c7d-4e75-86f8-8cbb2d3c6f6a ",
   "app_name": "ELB Proxy Service",
   "app_type": "service",
   "artifacts": (nested object),
   "content_md5": "248F36669E4CA533588AB8E599600195",
   "content_type": "application/json",
   "create_time": "2012-04-11T09:51:42Z",
   "creator": "cbadmin",
   "last_modified": "2012-04-11T09:51:42Z",
   "last_modifier": "cbadmin",
   "patterntype": "foundation",
   "service_name": "proxy",
   "service_type": "",
   "version": "2.0"
}

Search for shared services with a filter(dict format):

deployer.sharedservices.list(<filter in dict format>)

Example: deployer.sharedservices.list({'service_name':.proxy.})

Sample output:

>>> deployer.sharedservices.list({'service_name':.proxy.})
[{
   "access_rights": (nested object),
   "acl": (nested object),
   "app_id": "a-2a27189e-03bc-4f49-9526-6e31fdbeb8f7",
   "app_name": "ELB Proxy Service",
   "app_type": "service",
   "artifacts": (nested object),
   "content_md5": "248F36669E4CA533588AB8E599600195",
   "content_type": "application/json",
   "create_time": "2012-04-11T09:51:42Z",
   "creator": "cbadmin",
   "last_modified": "2012-04-11T09:51:42Z",
   "last_modifier": "cbadmin",
   "patterntype": "foundation",
   "service_name": "proxy",
   "service_type": "",
   "version": "2.0"
 }]

Deploy a shared service to a specific cloud group and with customized parameters

deployer.sharedservices.get(<app_id>).start(<cloud object >, <depl_parameters(optional)>, <public_key_file_path>(optional))

The format for depl_parameters is { .node_link_id.attributeId.: attributeValue, .groups.:{.node_link_id.groupId.: True/False} (optional) }. Specify .groups. if there is a group definition in the plug-in metadata. You can use the "listConfig" method to view all depl_parameters. For more information, see List all configurable parameters of a shared service below.

Example: deployer.sharedservices.get("a-f753298c-5c7d-4e75-86f8-8cbb2d3c6f6a").start( deployer.clouds[0], {"sharedservice.cachingVMs": 2}, "E:\\id_rsa")

Sample output:

>>> deployer.sharedservices.get("a-f753298c-5c7d-4e75-86f8-8cbb2d3c6f6a").start(deployer.clouds[0], {"sharedservice.cachingVMs": 2}, "E:\\id_rsa") 
{
  "acl": (nested object),
  "app_id": "a-b461bf2f-3dcf-478c-966d-918c77c93480",
  "app_type": "service",
  "appmodel": "https://172.16.65.91:9444/storehouse/user/deployments/d-a10b00e5-
cdaa-4d66-9771-f1bfcf5f2ae8/appmodel.json",
  "deployment": "https://172.16.65.91:9444/storehouse/user/deployments/d-a10b00e
5-cdaa-4d66-9771-f1bfcf5f2ae8/deployment.json",
  "deployment_name": "Caching Service",
  "id": "d-a10b00e5-cdaa-4d66-9771-f1bfcf5f2ae8",
  "maintenance_mode": False,
  "operations": (nested object),
  "role_error": False,
  "start_time": "2012-04-15T16:48:22.307Z",
  "status": "LAUNCHING",
  "topology": "https://172.16.65.91:9444/storehouse/user/deployments/d-a10b00e5-
cdaa-4d66-9771-f1bfcf5f2ae8/topology.json"
}

Deploy a shared service with an environment profile

deployer.sharedservices.get(<app_id>).start(<env_dict >, <depl_parameters(optional)>, <public_key_file_path>(optional))

The format for the <env_dict> parameter is:

{
        'environment_profile': <env_profile_obj> or <env_profile_id>
        'cloud_group': <cloud_group_obj> or   <cloud_group_id>    
        'ip_group': <ip_group_obj> or <ip_group_id>
        'ip_version': 'IPv4' or 'IPv6' 
}

The format for depl_parameters is { .node_link_id.attributeId.: attributeValue, .groups.:{.node_link_id.groupId.: True/False} (optional) }. Specify .groups. if there is a group definition in the plug-in metadata. You can use the "listConfig" method to view all depl_parameters. For more information, see List all configurable parameters of a shared service below.

Example:

caching = deployer.sharedservices.list({'servicename':'caching'})[0]
cachingParams ={
        "sharedservice.cachingVMsMax": 6,
        "sharedservice.cachingVMSize": "8",
        "sharedservice.cachingVMs": 4,
        "groups":{
"sharedservice.cachingScaleOff": True, 
"sharedservice.cachingAutoscalingEnable": False
}
}
rsaPath = "E:\\id_rsa"
env=deployer.environmentprofiles[0]
cloud = env.clouds.keys()[0]
ipgroup=env.clouds[cloud].ipgroups.keys()[0]
 
deployOptions = {"environment_profile" : env, 
                 "cloud_group": cloud, 
                 'ip_group': ipgroup,
                 'ip_version': 'IPv4'
                 }
cachingVApp = caching.start(deployOptions,cachingParams, rsaPath)

Show deployment of the shared service

deployer.virtualapplications.list({ "app_id": <shared serivice's app_id>})

Example: deployer.virtualapplications.list({ "app_id": "a-285485e7-1da2-465d-a060-79b7cc9b77b9"})

Sample output:

>>> deployer.virtualapplications.list({ "app_id": "a-285485e7-1da2-465d-a060-79b7cc9b77b9"})
[{
"acl": (nested object),
"app_id": "a-285485e7-1da2-465d-a060-79b7cc9b77b9",
"app_type": "service",
"appmodel": "https://172.16.33.53:9444/storehouse/user/deployments/d-cd4710efcdf8-4e95-9b10-7844b3b2ca76/appmodel.json",
"deployment": "https://172.16.33.53:9444/storehouse/user/deployments/d-cd4710f-cdf8-4e95-9b10-7844b3b2ca76/deployment.json",
"deployment_name": "cstest",
"id": "d-cd4710ef-cdf8-4e95-9b10-7844b3b2ca76",
"operations": (nested object),
"role_error": False,
"start_time": "2011-06-13T08:40:34.252Z",
"status": "RUNNING",
"topology": "https://172.16.33.53:9444/storehouse/user/deployments/d-cd4710ef
cdf8-4e95-9b10-7844b3b2ca76/topology.json"
}]

Show vm instance details of a deployed service

deployer.virtualapplications.vminstances(<depl_id>) or deployer.virtualapplications.get(<depl_id>).vminstances() or deployer.virtualapplications[<index>].vminstances()

Example: deployer.virtualapplications[0].vminstances()

Sample output:

>>> deployer.virtualapplications[0].vminstances()
 
{
"app_id": "d-2e0c8abb-373f-46fc-a05f-a255af3d3120",
"app_type": "application",
"creator": "u-0",
"creator_name": "cbadmin",
"deployment_name": "Sample JEE web application",
"instances": (nested object),
"role_error": False,
"start_time": "2011-08-17T21:16:59.266Z",
"status": "RUNNING",
"virtual_system": (nested object)
}

List all configurable parameters of a shared service

List all configurable attributes and groups parameters that are contained in the shared service model so that users can pass in these attributes while deploying.

sharedservice.listConfig()

Example: deployer.sharedservices[1].listConfig()

Sample output:

>>>  deployer.sharedservices[1].listConfig()
{
  "groups": {
    "sharedservice.CPU": True,
    "sharedservice.ELBInstancesScaleOff": False
  },
  "sharedservice.CPU_Used": [ 20, 100 ],
  "sharedservice.ELBInstancesCPUTriggerTime": 900,
  "sharedservice.enableAutowiring": True,
  "sharedservice.numberOfELBInstances": [ 2, 7 ],
  "sharedservice.virtualHost": "defaultHost"
}

List all attributes and groups

deployer.sharedservice.listConfig()

Sample output:

{
  "groups": {
    "sharedservice.cachingAutoscalingEnable": True,
    "sharedservice.cachingScaleOff": False,
    "sharedservice.cachingdevelopment": False,
    "sharedservice.cachingproduction": True
  },
  "sharedservice.cachingAutoscalingRange": [ 20, 80 ],
  "sharedservice.cachingScalingTriggerTime": 900,
  "sharedservice.cachingVMSize": "8",
  "sharedservice.cachingVMSizedev": None,   "sharedservice.cachingVMs": 4,
  "sharedservice.cachingVMsMax": 7,
  "sharedservice.cachingVMsMaxdev": None,   "sharedservice.cachingVMsdev": None }

Emergency fix CLI reference

You can administer emergency fixes in the catalog using the IBM PureApplication System W1500 CLI.

Fixes object

The Fixes object is a resource collection of fixes for PureApplication System. You can work with a collection of fixes on the command line and help is available. To get help for the Fixes object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.fixes)

Fix object

A fix that can be applied to a virtual image.

You can work with a fix on the command line and help is available. To get help for the Fix object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.fix)

Fix attributes

The Fix object has the following attributes:

acl

The access control list for this emergency fix. This attribute is read-only.

archive

A Fix.Archive object that provides mechanisms to query and manipulate the fix archive on PureApplication System. This attribute is read-only.

description

A detailed description of the fix (optional).

id

The identifier of the Fix object. This attribute is read-only.

name

A unique name you give the fix. This attribute is a string. The maximum length of this attribute is 1024 characters.

prereqoptions

All the virtual images that you currently have access to and are not already associated with this fix. Images from this list can be added to the prereqs list in order to make the fix applicable to them. For example, you might add WebSphere Application Server 7.0 to the prereqs field to indicate that the fix is applicable to WebSphere Application Server 7.0 virtual machines. This attribute is read-only.

prereqpluginoptions

All the plug-ins that you currently have access to and are not already associated with this fix. Plug-ins from this list can be added to the prereqs list to make the fix applicable to them. This attribute is read-only.

prereqs

A list of the virtual images to which this fix can be applied. This list must be a subset of the list provided in the 'prereqoptions' field. Adding an image name to this list means that the fix is applicable to virtual machines based on that image. For example, you might add WebSphere Application Server 7.0 to the prereqs field to indicate that the fix is applicable to WebSphere Application Server 7.0 virtual machines.

You can add images to this list using the append() method:

>>> image = fix.prereqoptions[0]  
>>> fix.prereqs.append(image)

You can associate plug-in with the fix using the append() method:

>>> plugin = fix.prereqpluginoptions[0]
>>> fix.prereqs.append(plugin)

To delete a prerequisite from the prereqs list, call the del function:

del fix.prereqs[index]

For example, del fix.prereqs[0] removes the first prerequisite in the list.

severity

The severity of this fix. This attribute is a string attribute with a maximum length of 128 characters.

target

Automatically set to "APPLICATION" for a Fix object. This attribute is read-only.

type

Automatically set to ifix for a Fix object. This attribute is read-only.

Fix.Archive object

To get help for the Fix.Archive object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.fix.archive)

The Fix.Archive object has the following methods:

get(f)

This method retrieves the archive currently associated with the fix. This method has one required parameter that indicates where the fix archive is saved. It can be either of the following values:

• A string containing the name of a file in which to save the archive. If the file name does not end in .zip, then .zip is automatically appended to the filename
• A Jython file object. You must ensure that the file object correctly handles binary data. The fix archive is returned in a .zip file format. For example:

  >>> fix.archive.get('/path/to/foo.zip')
  

,

__lshift__(other)

This method is started implicitly when the Fix.Archive object is used as the left argument of a left shift operator ('<<'). It calls set() with the right argument of the operator. For example:

 >>> fix.archive << '/path/to/file'

__rshift__(other)

This method is started implicitly when the Fix.Archive object is used as the left argument of a right shift operator ('>>'). It calls get() with the right argument of the operator. For example:

>>> fix.archive >> '/path/to/file.zip'

set(f)

This method sets the archive associated with the fix. It has one required parameter that indicates the source of the fix archive to be uploaded. It can be either of the following values:

• A string containing the name of a file from which to get the archive.
• A Jython file object. You must ensure that the file object correctly handles binary data. For example:

  >>> fix.archive.set('/path/to/foo')
  

Environment profile cloud IP groups on the CLI

You can work with the environment profile cloud IP group objects on the IBM PureApplication System W1500 CLI.

EnvironmentProfileCloudIPGroups object

An EnvironmentProfileCloudIPGroups object manipulates the IP groups associated with a cloud in an environment profile. This object behaves much like a dict object with IPGroup objects as keys. References to these objects can be obtained with the ipgroups attributes of EnvironmentProfileCloud objects.

EnvironmentProfileCloudIPGroups methods

The EnvironmentProfileCloudIPGroups object has the following methods:

addIPGroup

Adds an IP group to the list of IP groups for a cloud in an environment profile. This method accepts the following parameters:

• An IPGroup object that represents the IP group to be added
• An optional alias for the IP group in this environment profile. If no alias is provided, the name of the IP group is used.

clear

Dissociates all IP groups from this cloud group in the environment profile.

__contains__

Indicates if the specified IP group is associated with this cloud group in the environment profile. This method is called automatically when you use the Python in operator.

__delitem__

Dissociates an IP group from a cloud group in this environment profile. This method is called automatically when you use the Python del statement.

get

Returns an EnvironmentProfileCloudIPGroup object that describes how an IP group is used in this environment profile. This method accepts the same parameters as the dict method of the same name:

• An IPGroup object representing the IP group about which information is to be returned
• An optional default value that is returned if the IP group is not used by this cloud in the environment profile.

__getitem__

Returns an EnvironmentProfileCloudIPGroup object that describes how an IP group is used in this environment profile. This method accepts a single parameter that must be an IPGroup object representing the IP group about which information is to be returned. This method is started automatically when you access an item using the Python [] syntax.

has_key

Indicates if the specified IP group is associated with this cloud in the environment profile. This method accepts a single parameter that must be an IPGroup object representing the IP group about which information is to be returned.

items

Returns a list of (IPGroup, EnvironmentProfileCloudIPGroup) tuples that describe the IP groups associated with this cloud group in the environment profile.

__iter__

Returns an iteration over IPGroup objects representing the IP groups associated with this cloud group in the environment profile.

iteritems

Returns an iteration over (IPGroup, EnvironmentProfileCloudIPGroup) tuples representing IP groups associated with this cloud group in the environment profile.

iterkeys

Returns an iteration over IPGroup objects representing the IP groups associated with this cloud group in the environment profile.

itervalues

Returns an iteration over the EnvironmentProfileCloudIPGroup objects associated with the environment profile cloud group.

keys

Returns a list of IPGroup objects representing the IP groups in the environment profile cloud group. The objects contain only necessary attributes, for example, ID and name.

__len__

Returns the number of IP groups associated with the environment profile cloud group.

__repr__

Returns a string representation of the IP groups associated with the environment profile cloud group.

__setitem__

Associates an IP group with the environment profile cloud group and assigns an alias to it. This method is called automatically when you assign a value to an item in an EnvironmentProfileCloudIPGroups object. The key for the item must be an IPGroup object and the assigned value must be a string, as shown in the following example:

    >>> myep = deployer.environmentprofiles['My profile'][0]
    >>> mycloud = deployer.clouds['My cloud'][0]
    >>> myipg = deployer.ipgroups['My ip group'][0]
    >>> myep.clouds[mycloud].ipgroups[myipg] = 'alias for my ip group'

__str__

Returns a string representation of the IP groups associated with the environment profile cloud group.

__unicode__

Returns a string representation of the IP groups associated with the environment profile cloud group.

values

Returns a list of the EnvironmentProfileCloudIPGroup objects associated with the environment profile cloud group.

EnvironmentProfileCloudIPGroup object

An EnvironmentProfileCloudIPGroup object is used to access and modify information about a particular IP group associated with a cloud group in an environment profile.

EnvironmentProfileCloudIPGroup methods

The EnvironmentProfileCloudIPGroup object has the following methods:

__eq__

This method is used automatically by Python to determine if two EnvironmentProfileCloudIPGroup objects are equal. That is, if they represent the same IP group in the same cloud in the same environment profile.

__nonzero__

This method is used by Python whenever an EnvironmentProfileCloudIPGroup object is used in a boolean context. It always returns True.

__repr__

This method returns a string representation of the EnvironmentProfileCloudIPGroup object.

__str__

This method returns a string representation of the EnvironmentProfileCloudIPGroup object.

__unicode__

This method returns a string representation of the EnvironmentProfileCloudIPGroup object.

EnvironmentProfileCloudIPGroup attributes

The EnvironmentProfileCloudIPGroup object has the following attributes:

alias

The alias attribute can be used to examine and modify the alias assigned to the IP group in a cloud group for an environment profile. The value for this attribute must be a string.

Environment profile clouds on the CLI

You can work with environment profile clouds on the IBM PureApplication System W1500 CLI.

EnvironmentProfileClouds object

The EnvironmentProfileClouds object manipulates the clouds and IP groups associated with an environment profile. This object behaves much like a dict object with Cloud objects as keys.

EnvironmentProfileClouds methods

The EnvironmentProfileClouds object has the following methods:

addCloud

Adds a cloud group to the list of cloud groups for an environment profile. This method accepts the following parameters:

• A Cloud object that represents the cloud group to be added.
• An optional alias for the cloud in this environment profile. If no alias is provided, the name of the cloud group is used.

clear

Dissociates all cloud groups from this environment profile.

__contains__

Indicates if the specified cloud group is associated with this environment profile. This method is called automatically when you use the Python in operator.

__delitem__

Dissociates a cloud group from this environment profile. This method is called automatically when you use the Python del statement.

get

Returns an EnvironmentProfileCloud object that describes how a cloud group is used in this environment profile. This method accepts the same parameters as thedict object method of the same name:

• A Cloud object representing the cloud group about which information is to be returned
• An optional default value that is returned if the cloud group is not used by the environment profile

__getitem__

Returns an EnvironmentProfileCloud object that describes how a cloud group is used in this environment profile. This method accepts a single parameter that must be a Cloud object representing the cloud group about which information is to be returned. This method is started automatically when you access an item using the Python [] syntax.

has_key

Indicates if the specified cloud group is associated with this environment profile. This method accepts a single parameter that must be a Cloud object representing the cloud group about which information is to be returned.

items

Returns a list of (Cloud, EnvironmentProfileCloud) tuples that describe the cloud groups associated with the environment profile.

__iter__

Returns an iteration over Cloud objects representing the cloud groups in the environment profile.

iteritems

Returns an iteration over (Cloud, EnvironmentProfileCloud) tuples representing the cloud groups associated with the environment profile.

iterkeys

Returns an iteration over Cloud objects representing the cloud groups in the environment profile.

itervalues

Returns an iteration over the EnvironmentProfileCloud objects associated with the environment profile.

keys

Returns a list of Cloud objects representing the cloud groups in the environment profile. The objects contain only necessary attributes, for example, ID and name.

__len__

Returns the number of cloud groups associated with the environment profile.

__repr__

Returns a string representation of the cloud groups and IP groups associated with the environment profile.

__setitem__

Associates a cloud group with the environment profile and assigns an alias to it. This method is called automatically when you assign a value to an item in an EnvironmentProfileClouds object. The key for the item must be a Cloud object and the assigned value must be a string, as shown in the following example:

    >>> myep = deployer.environmentprofiles['My profile'][0]
    >>> mycloud = deployer.clouds['My cloud'][0]
    >>> myep.clouds[mycloud] = 'alias for my cloud'

__str__

Returns a string representation of the cloud groups and IP groups associated with the environment profile.

__unicode__

Returns a string representation of the cloud groups and IP groups associated with the environment profile.

values

Returns a list of the EnvironmentProfileCloud objects associated with the environment profile.

EnvironmentProfileCloud object

An EnvironmentProfileCloud object is used to access and modify information about a particular cloud group in an environment profile.

EnvironmentProfileCloud methods

The EnvironmentProfileCloud object has the following methods:

__eq__

This method is used automatically by Python to determine if two EnvironmentProfileCloud objects are equal. That is, if they represent the same cloud in the same environment profile.

__nonzero__

This method is used by Python whenever an EnvironmentProfileCloud object is used in a boolean context. It always returns True.

__repr__

This method returns a string representation of the EnvironmentProfileCloud object and the IP groups it contains.

__str__

This method returns a string representation of the EnvironmentProfileCloud object and the IP groups it contains.

__unicode__

This method returns a string representation of the EnvironmentProfileCloud object and the IP groups it contains.

EnvironmentProfileCloud attributes

The EnvironmentProfileCloud object has the following attributes:

alias

The alias attribute can be used to examine and modify the alias assigned to a cloud group in an environment profile. Its value must be a string.

ipgroups

The ipgroups attribute references an EnvironmentProfileClouds object that contains additional information about how the IP groups within the cloud group are used by the environment profile. For additional help on using this object, enter the following command:

     >>> help(deployer.environmentprofilecloudipgroups)

Environment profiles CLI reference

You can work with environment profiles on the IBM PureApplication System W1500 CLI.

You can use the following resources to work with environment profiles:

EnvironmentProfiles

Represents the collection of environment profiles defined to PureApplication System.

EnvironmentProfileClouds

Use the EnvironmentProfileClouds object to manipulate the clouds and IP groups associated with an environment profile.

EnvironmentProfileCloudIPGroups

Use the EnvironmentProfileCloudIPGroups object to manipulate the IP groups associated with a cloud in an environment profile.

User

A user can own environment profiles.

Ethernet interface management CLI reference

You can administer the Ethernet interfaces of the IBM PureApplication System using the CLI.

Interface object

Help is available on the CLI for the Interface object. To get help, pass the Interface object as an argument to the help() function, as shown in the following example:

>>> help(deployer.ethernet.interface)

Interface Attributes

Interface object has the following attributes:

defaultipv6gateway

The default gateway associated with this interface. The string value must be an IPv6 address expressed in dotted decimal notation, as shown in the following example:

"192.168.1.1"."

defaultgateway

The default gateway associated with this interface. The string value must be an IP address expressed in dotted decimal notation, as shown in the following example:

"192.168.1.1"."

enabled

A boolean flag that indicates whether the interface is enabled. This attribute can be set to enable or disable the interface.

id

The identifier assigned to the interface. The CLI has the following Ethernet interfaces with identifiers:

• eth0
• eth1
• eth2
• eth3
• eth4
• eth5
• eth6
• eth7
• eth8
• eth9
• mgt0
• mgt1

The identifiers are assigned by the PureApplication System and cannot be changed.

ipv6address

A string value that specifies the IPv6 address and subnet mask assigned to the interface. The string must be of the form "<dotted_decimal_address>/<subnet_mask_length>", as shown in the following example:

"192.168.1.0/24"."

ipaddress

A string value that specifies the IP address and subnet mask assigned to the interface. The string must be of the form "<dotted_decimal_address>/<subnet_mask_length>", as shown in the following example:

"192.168.1.0/24"."

mode

The Ethernet mode used by the interface. This attribute must have one of the following string values:

• Auto
• 10baseT-HD
• 10baseT-FD
• 100baseTx-HD
• 100baseTx-FD
• 1000baseTx-FD

mtu

The maximum transmission unit to be used with the interface, expressed as a string.

Interfaces object

The list of Ethernet interfaces on the IBM PureApplication System.

Help is available on the CLI for the Interfaces object. To get help, pass the Interfaces object as an argument to the help() function, as shown in the following example:

>>> help(deployer.ethernet.interfaces)

Firmware management CLI reference

You can administer the firmware level of your system using the CLI.

Firmware object

The Firmware object has the following methods:

__lshift__

This method is an alias for the upgrade() method.

upgrade

Upgrades the firmware on the system with the contents of the specified file. This function accepts a single parameter that specifies a local file containing a firmware image to be uploaded and installed on the system. The parameter must be either the file name of the firmware image or a Python file object from which the firmware image can be read. This function uploads the firmware image and initiates the upgrade process before returning. Because firmware images are large, this upload process might take a considerable amount of time, especially if the network connection to the system is slow. This function raises exceptions to indicate problems reading the local firmware image or transferring the image to the PureApplication System.

IP CLI reference

You can work with IP addresses, using the IPs and IP objects on the IBM PureApplication System W1500 CLI.

IPs object

An IPs object represents the collection of IP addresses defined within a particular IP group. Objects of this type are accessed using the ips attribute of the IP group in which they are contained, as shown in the following example:

>>> myipgroup = deployer.ipgroups['my ip group name'][0]
>>> myipgroup.ips

Objects of this type are used to create, delete, iterate over, list and search for IP addresses on the IBM PureApplication System. Unlike other types of resource collections, IP addresses have no name attribute. When searching for IP addresses within this collection, matching is done against the ipaddress attribute.

When you are creating IPs objects, pass the IP address as a string in dotted decimal notation to the create() method. To create multiple IPs objects, pass a list of these strings, as shown in the following example:

>>> myipgroup.ips.create("1.2.3.4")
>>> myipgroup.ips.create(["1.2.3.5", "1.2.3.6"])

Because IPs objects do not have a name property, the search string supplied in any search operations is matched against the IP address.

You can work with IP addresses on the command line and help is available. To get help for the IPs object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.ips)

IP object

An IP object represents a particular IP address defined on the IBM PureApplication System. Use the IP object to query and manipulate the IP address definition on the PureApplication System. Attributes of the IP address and relationships between the IP address and other resources on IBM PureApplication System are represented as Jython attributes on the IP object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding data on IBM PureApplication System.

IP objects are contained in the IPGroup object.

You can work with IP addresses on the command line and help is available. To get help for the IP object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.ip)

IP attributes

Unlike other types of resource collections, IP addresses have no name attribute. When searching for IP addresses within this collection, matching is done against the IPaddress attribute. The IP object has the following attributes:

created

The creation time of the IP, as number of seconds since midnight, January 1, 1970 UTC. When the IP is displayed, this value is shown as the date and time in the local time zone. This field is read-only.

currentmessage

The message associated with the status of the IP. This field is read-only.

currentmessage_text

The message text describing the current message of the IP address. This field is read-only.

currentstatus

The status of the IP. This field is read-only.

currentstatus_text

The message text describing the status of the IP address. This field is read-only.

id

The ID of the IP. This field is read-only.

ipaddress

The IP address associated with this IP. The IP address must be unique and must belong to the IP group under which this IP is defined. This field is read-only.

ipgroup

A reference to the IPgroup object that contains this IP address. For more information about the properties and methods supported by IPgroup objects, enter the following command:

>>> help(deployer.ipgroup)

updated

The time the IP was last updated, as number of seconds since midnight, January 1, 1970 UTC. When the IP is displayed, this value is shown as the date and time in the local time zone. This field is read-only.

Userhostname

The hostname that was entered that is associated with this IP.

IP method

The IP object has the following method associated with it:

reset

Changes the IP status from Active to Inactive as shown in the following example:

myip.reset()

CAUTION:

Use this method only when an IP object gets into an error state. Use this method if an IP status is active in PureApplication System, but the IP is not active because a virtual machine has been deleted.

IPs object methods

The IPs object has the following methods:

create

The create method for the IPs object is unique because it accepts different parameters. The create(other) method defines a new IP address within an IP group to the IBM PureApplication System. The single parameter to this method can be any of the following values:

• A string containing the IP address in dotted decimal notation, 192.168.1.2 for example.

  The IP address must be within the subnet defined for the IP group.

• As the name of a file containing a Jython expression that evaluates to one of the values in this list.
• The deployer.wizard value or a wizard instance created by calling deployer.wizard(). If either of these values is supplied, the CLI prompts interactively for the values to create the resource. IP objects must be created within the context of an IPGroup object.

  >>> myipgroup.ips.create(deployer.wizard)
  

• A list of any of these values.

This method returns either an IPs object or a list of IPs objects, depending on the parameter passed.

delete

Deletes a resource in this collection. All information about this resource is deleted from the IBM PureApplication System. The resource to be deleted can be specified in any of the following ways:

• As an int or long that specifies the ID of the resource to be deleted, as shown in the following example:

       >>> deployer.patterns.delete(17)
  

• As the resource object representing the resource to be deleted, as shown in the following example:

  >>> mypattern = deployer.patterns[4]
      >>> deployer.patterns.delete(mypattern)
  

• As a list of any of these to delete multiple resources.

This method raises exceptions to indicate problems deleting resources. There is no return value.

License management CLI reference

You can administer the IBM License Metric Tool settings of your system using the CLI.

LicenseManagement object

The IBM License Metric Tool agent is included with IBM PureApplication System W1500. IBM License Metric Tool can be used to measure the licenses that are available and consumed by the virtual machines deployed by the system. By default, licenses are not tracked. However, if you are an IBM subcapacity licensing customer and use IBM License Metric Tool reporting, then you can enable your system utilization to be included in the IBM License Metric Tool reports.

LicenseManagement Attributes

The LicenseManagement object has the following attributes:

enabled

Track the number of licenses with IBM License Metric Tool. This boolean attribute is write only.

hostname

Host name or IP address of the computer that you have designated as your administrative server for IBM License Metric Tool.

scangroup

Scan group that is assigned to the IBM License Metric Tool agent embedded on your system. The value for the scan group is case-sensitive and must match the value defined on the IBM License Metric Tool server.

LicenseAwareness object

The LicenseAwareness object is the namespace for license awareness.

LicenseAwareness Attributes

The LicenseAwareness object has the following attributes:

HighwaterMarkLicense

Returns an object representing the high water mark license data.

get

Downloads the high water mark license data as a .csv file. This method takes the following parameters:

• A file name or file object to which the high water mark license data should be saved. If a file name is specified, .csv is automatically appended as the file type if the name does not already end in .csv.
• An optional product ID for high water mark license entries.
• An optional start date for high water mark license entries. The value must be expressed in YYYYMMDD format.
• An optional end date for high water mark license entries. The value must be expressed in YYYYMMDD format.
• An optional license type for high water mark license entries. The value must be PVU or server.

IbmSoftwareCatalog

Returns an object representing the IBM Software Catalog.

import

Imports the IBM Software Catalog as an XML or ZIP file. This method takes the IBM Software Catalog file name, that should be imported to the system, as a parameter.

Product

An array of product objects representing the products you have in the catalog.

Products

The list of license-aware products that are being used in this system.

PvuTable

Returns an object representing the Processor Value Unit (PVU) table.

import

Imports the Processor Value Unit (PVU) table as an XML or ZIP file. This method takes the Processor Value Unit (PVU) table file name, that is to be imported to the system, as a parameter.

thresholdalert

This boolean attribute determines if an email is sent to all users assigned the Create new catalog content permission when the license use exceeds the warning threshold.

Product attributes

The Product object has the following attributes:

created

Shows the creation time of the license-aware product, as number of seconds since midnight, January 1, 1970 UTC. When the license-aware product is displayed, this value is shown as the date and time in the local timezone. This field is read only.

currentallocation

The current licenses Used for this product. This field is read only.

enforcement

This attribute specifies the action to be taken when the number of PVUs or server licenses reserved exceeds the number owned. The following values are valid:

I

Ignore

W

Warn

E

Enforce

id

The ID of the license-aware product. This field is read only.

name

The name of the licensed product. This field is read only.

productID

The product ID. This field is read only. This does not have to be an IBM Software Catalog identifier.

reservedallocation

The licenses for this product that are reserved. This field is read only.

totalallocation

This field specifies the total number of licenses (PVUs or server licenses) you possess.

licenseType

The license type.

updated

Time the license-aware product was last updated, as number of seconds since midnight, January 1, 1970 UTC. This field is read only.

warningthreshold

This attribute specifies the percentage used to trigger a notification to all users assigned the Create new catalog content role. The percentage specified is the PVU or sever licenses Used to those owned.

LicenseAwareness methods

The LicenseAwareness object has the following methods:

admin.licenseawareness.ibmsoftwarecatalog.import('/tmp/IBMSoftwareCatalog.xml')

This method is used to import a new IBM Software Catalog to your system.

admin.licenseawareness.highwatermarklicense.get(filename,productid,startdate,enddate,licensetype)

This method is used to retrieve the high water usage report for the product. The startdate and enddate must be in YYYYMMDD format. The licensetype must be PVU or Server.

admin.licenseawareness.products.create(name, productID, licenseType)

Creates license awareness information for a new product.

admin.licenseawareness.product.delete()

Deletes the license awareness information for this product.

Products methods

The Products object has the following methods:

contains

A function that accepts a single argument and returns a boolean value indicating if the specified resource is contained within this collection.

getattr

This method is invoked automatically by Jython when you use the dot operator on a resource collection, as shown in the following example:

     >>> deployer.hypervisors.myhypervisorname

This method searches the resource collection for any resources that match the supplied string. By default, the match is done against the name attribute of the resource. If a particular resource collection searches on a different attribute, that fact is noted in the help for the resource collection.

This is a partial match search rather than an exact match. For example, a search for foo matches foo, food, and do not get fooled. A list of matching resources, possibly empty, is returned. A common idiom is to use [0] to select the first element in the returned list if you are certain it is the one you want, as shown in the following example:

>>> myhypervisor = deployer.hypervisors.definitelymyhypevisor[0]

If the search string contains spaces or other characters that are not allowed in Jython identifiers, use the __getitem__ method instead.

getitem

This method is invoked automatically when you index a resource collection using [], as shown in the following example:

>>> deployer.parts[10]

The following types of values are recognized within the square brackets:

• An int or long value. The value is used as a 0-based index into the collection and the method returns a single resource. To return the second IP address defined in an IP group, use the following example:

  >>> myipgroup.ips[1]
  

• A string value, in which case this method searches for resources matching the specified string. This search is described in the help for the __getattr__ method and returns a list of matching resources. This type of search can be useful if the string you are searching for contains a space or another character that is not permitted in a Python identifier, as shown in the following example:

  >>> deployer.patterns['Pattern name with a space']
  

iter

This method is invoked implicitly when you reference a resource collection in a context that requires iterating over all members in the collection. It is also invoked when you explicitly pass the resource collection to the Jython iter() function, as shown in the following example:

 >>> for vm in myvirtualsystem.vms:    ...     print vm.ip.ipaddress

len

Returns the number of resources in this collection. This method is invoked implicitly when you pass a resource collection to the Jython len() function.

repr

This method is invoked implicitly by Jython when an expression entered in interactive mode returns a resource collection. It is also invoked when a resource collection is passed to the Jython repr() function. It returns a string representation of the resource collection, as shown in the following example:

 >>> deployer.networks

str

Returns a string representation of all resources in this collection. This method is invoked implicitly by Jython when a resource collection is used as a value in a string formatting operation. This method is also invoked when it is passed as a parameter to the Jython str() function, as shown in the following example:

>>> print 'Here are the defined networks: %s' % deployer.networks
    >>> str(deployer.parts)

unicode

Returns a string representation of all resources in this collection. This method is invoked implicitly by Jython when a resource collection is used as a value in a string formatting operation. This method is also invoked when it is passed as a parameter to the Jython str() function, as shown in the following example:

>>> print 'Here are the defined networks: %s' % deployer.networks
    >>> str(deployer.parts)

Maintenance CLI reference

You can administer maintenance in the catalog using the IBM PureApplication System W1500 CLI.

Maintenances object

A Maintenances object represents the collection of maintenance defined to PureApplication System that is applicable to a virtual system instance. Objects of this type are used to create, delete, iterate over, list and search for Maintenances resources on the IBM PureApplication System.

You can work with the Maintenances object on the CLI and help is available. To get help for the Maintenances object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.maintenance)

Maintenance object

A Maintenance object represents a particular maintenance defined to PureApplication System. Use the Maintenance object to query and manipulate the maintenance definition on the PureApplication System. Attributes of the Maintenance resource are represented as Jython attributes on the Maintenance object. Relationships between the Maintenance resource and other resources in PureApplication System are also represented as Jython attributes on the Maintenance object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding data on the IBM PureApplication System.

You can work with the Maintenance object on the CLI and help is available. To get help for the Maintenance object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.maintenance)

Maintenance attributes

The Maintenance object has the following attributes:

currentstatus

The current status of the Maintenance object. This field contains an eight character string value that is generated by the PureApplication System. This attribute is read-only.

currentstatus_text

This field is a string representation of currentstatus in the preferred language of the requester. This string is automatically generated by the PureApplication System. This attribute is read-only.

fixes

A list of the fixes to be applied as part of the maintenance request.

id

The ID of the Maintenance object. This attribute is an integer value. This attribute is read-only.

Pattern CLI reference

You can work with the pattern and patterns objects on the IBM PureApplication System W1500 CLI.

You can use the following resource objects to work with virtual system patterns:

ACL

You can control the access control list for virtual system patterns with the ACL object.

Advancedoptions

You can use the Advancedoptions object to view and set the advanced options for the virtual system pattern. Different advanced options are available, depending on the topology described by the virtual system pattern.

Parts

Represents the parts and collection of parts defined to PureApplication System.

Pattern_parts

Represents the virtual system pattern parts and collection of virtual system pattern parts defined within a particular virtual system pattern on PureApplication System.

Pattern_scripts

Represents the scripts and collections of scripts defined within a particular virtual system pattern part on PureApplication System.

Patterns

Represents the virtual system patterns and collection of virtual system patterns defined to PureApplication System.

User

A user can own virtual system patterns.

7.13.1. Export virtual system patterns

Virtual system patterns are topology definitions for repeatable deployment that can be shared. You can export a command line script that reconstructs a virtual system pattern on a different system than the one on which it was created.

Use the artifacts that are generated by the exportPattern.py script, you can export virtual system patterns from one system and import them to another system. This CLI (CLI) script reconstructs the original virtual system pattern on another system by using the importPatterns.py script. The reconstructed virtual system pattern contains the same properties as the original script:

• Parts
• Property values and metadata
• Scripts
• Script environment variables
• Advanced options
• Add-ons
• Add-on parameter values
• Ordering
• Status (read-only)

Note that the script environment variables include the set of key/value pairs that are defined to the run time environment of the script, as specified in the Environment section of the Script Packages pane.

All script package configuration parameters, including executable commands and arguments (as specified in the Executable and Arguments sections, respectively, of the Script Packages pane), are included in the export and subsequent import of the virtual system pattern when using the command line interface. If script parameters are also included in a cbscript.json object file as part of the script package, the values exported from the user interface do not overwrite the values in the cbscript.json file.

Export a virtual system pattern

Use the samples/exportPattern.py script to export the virtual system pattern. Use the standard CLI parameters to specify the host name, user ID, and password to access the virtual system pattern, and the location of the exportPattern.py script. In addition, use the -a parameter, which you can also format as --acceptcert, so that SSL certificates from the system are automatically accepted. Specify both the file name and virtual system pattern, as shown in the following example:

pure -h <hostname.com> \
     -u <user> \
     -p <password> \
     --acceptcert \
     -f ../samples/exportPattern.py \
     -p <pattern_name> \
     -t <target_directory>

Options

Use the following options with the exportPattern.py script:

-p <pattern_name> or .-pattern <pattern_name>

Name of the virtual system pattern to be exported. The name you specify must uniquely identify a virtual system pattern. If you do not specify the virtual system pattern, a list of virtual system patterns that are defined is displayed and you are prompted to select one.

.t <target_directory> or .-target <target_directory>

Indicates that the exported artifacts will be written to the specified target folder or file name for the .tgz/.tar.gz file.

--passwords

Includes BASE64 encoded passwords in the pattern definition file. By default, password properties are not exported.

By default, only the archive files of script packages of the pattern are exported. To export the associated virtual images, script packages, and add-ons, you can specify the following options:

--downloadAll

Indicates that all associated artifacts are exported with the pattern, including the virtual images, script packages, and add-ons.

.d|--download <filter_file>

Indicates that only the artifacts that are listed in the filter file are downloaded. The filter is one JSON file formatted similar to the following example:

{
    "add_ons":[
        {"name":"ADD_ON_NAME"},
        ...
    ],
    "script_packages":[
        {"name":"SCRIPT_PACKAGE_NAME"},
        ...
    ],
    "virtual_images":[
        {"name":"IMAGE_NAME","version":"IMAGE_VERSION","build":"REFID"},
        ...
    ]
}

The file directory structure for the exported virtual system pattern is similar to the following example:

    /
        patterns.json    //The JSON serialization format for the exported pattern         /images
            test_image.ova
        /script_packages
            test_script1.zip
            test_script1.zip
        /add_ons
            test_add_on.zip

The JSON serialization format for the virtual system pattern is similar to the following example:

[
   {
      "references":{
         "virtual_images":[
            {"name":"IMAGE_NAME","version":"IMAGE_VERSION","build":"REFID"},
            {"name":"IMAGE_NAME","version":"IMAGE_VERSION","build":"REFID","file":"OVA_FILE_FOR_IMPORT"},
                //"file" is the relative path for the OVA file when exporting the virtual image             ...
         ],
         "add_ons":[
            {"name":"ADD_ON_NAME","type":"ADD_ON_TYPE"},       //"type" is optional.
            {"name":"ADD_ON_NAME","type":"ADD_ON_TYPE","file":"ADD_ON_FILE"},
                //"file" is the relative file path when exporting the add-on.
            ...
         ],
         "script_packages":[
            {"name":"SCRIPT_PACKAGE_NAME"},
            {"name":"SCRIPT_PACKAGE_NAME","file":"SCRIPT_PACKAGE_FILE"},
               //"file" is the relative file path when exporting the script package.
            ...
         ],
   },
      "name":"PATTERN_NAME",
      "description":"PATTERN_DESCRIPTION",      //The existing description, if applicable.
      "parts":[
         {
            "virtual_image_ref":"IMAGE_INDEX,
                  //The index for the images in the reference section, beginning with 0.
            "part":PART_NAME",
            "count": COUNT,                     //The count for the image part. The default is 1.
            "properties":[
               {
                  "class":"PROPERTY_CLASS",
                  "key":"PROPERTY_KEY",
                  "value":"PROPERTY_VALUE",
                  "locked":true | false         //Optional. The default is false.
               },
               ...
            ],
            "script_packages":[
               {
                  "script_package_ref":"SCRIPT_PACKAGE_INDEX",
                        //The index for the script packages in the reference section.
                  "parameters":[
                     {
                        "key":"PARAM_KEY",
                        "value":"PARAM_VALUE",
                        "locked":true | false   //Optional. The default is false.
                     },
                     ...
                  ]
                  starts_after:[ {"part_ref":PART_INDEX_1,"script_ref":PART_SCRIPT_INDEX_1}, ...]
                        //Optional. Specifies the order in which the script parts are started.
               }
            ],
            "add-ons":[
               {
                  "add_on_ref":ADD_ON_INDEX,
                        //The index for the script packages in the reference section.
                  "parameters":[
                     {
                        "key":"PARAM_KEY",
                        "value":"PARAM_VALUE",
                        "locked":true | false   //Optional. The default is false.
                     }
                     ...
                  ],
               }
            ],
            "configurations":[         //Optional. For script packages that are shipped with the virtual image.
               {,
                  "name":"CONFIGURATION_NAME",
                  "parameters":[
                     {
                        "key":"PARAM_KEY",
                        "value":"PARAM_VALUE",
                        "locked":true | false   //Optional. The default is false.
                     },
                     ...
                  ],
               }
            ],
            starts_after:[PART_INDEX_1,PART_INDEX_2, ... ]
                 //Optional. Specifies the order in which the parts are started.
         }
      ],
      "advanced_options":[
         ...
      ]
      "read_only":true | false     //Optional. The default is false.
   },
   ...
}

Helpful tips

Export the virtual images can take an extended amount of time depending on the size of the images. You can reduce the download time and the amount of space required by not downloading virtual images that are already included in the target environment, for example WebSphere Application Server Hypervisor Edition virtual images.

You can export the virtual system pattern without first specifying the -d or --downloadAll options. You can then extract the reference part from the exported pattern definition to create your filter file.

References to images in the JSON file refer to exact image numbers. You might need to update these references when importing to another system if it has different versions of those images.

7.13.2. Import virtual system patterns

Virtual system patterns are topology definitions for repeatable deployment that can be shared. You can export a command line script that reconstructs a virtual system pattern on a different system than the one on which it was created.

Use the artifacts that are generated by the exportPattern.py script, you can export virtual system patterns from one system and import them to another system. This CLI (CLI) script reconstructs the original virtual system pattern on another system by using the importPatterns.py script. The reconstructed virtual system pattern contains the same properties as the original script:

• Parts
• Property values and metadata
• Scripts
• Script parameter values
• Advanced options
• Add-ons
• Add-on parameter values
• Ordering
• Status (read-only)

Import a virtual system pattern

Use the samples/importPatterns.py script to import the virtual system pattern. Use the standard CLI parameters to specify the host name, user ID, and password to access the virtual system pattern, and the location of the importPatterns.py script. In addition, use the -a parameter, which you can also format as --acceptcert, so that SSL certificates from the system are automatically accepted. Specify both the file name and virtual system pattern, as shown in the following example:

pure -h <hostname.com> 
     -u <user> 
     -p <password> 
     --acceptcert 
     -f ../samples/importPatterns.py 
     -s <target_source_directory>

Options

Use the following options with the importPatterns.py script:

-s <target_source_directory> or .-source <target_source_directory>

Indicates that the patterns and the associated artifacts are uploaded from the specified source folder or file name for the .tgz/.tar.gz file.

The process to import the pattern uses the same JSON serialization format used in the pattern export process. Likewise, the associated artifacts are uploaded with the same file layout as shown in the preceding section.

Update the referenced virtual image

The script uses the values specified in the references definition of the JSON file to match the virtual image in the target environment.

        "references": {
            "virtual_images": [
                {"name": "IMAGE NAME", "version": "IMAGE_VERSION", "build": "REFID"},  .
            ] ,

In some cases, you might need to update the references definition for an exported pattern to match the target environment in which the pattern is imported.

CAUTION:

Ensure that the updated virtual image accepts the same set of configuration properties. Otherwise, an exception will occur during the import process.

In the following example, the virtual image of the exported pattern is at the WebSphere Application Server Hypervisor Edition Version 8.0.0.1 level.

• The original references definition:

              "virtual_images": [
                  {"name": "IBM WebSphere Application Server Hypervisor Edition 8.0.0.1", "version": "8.0.0.1", "build": "34964.449"},  .
              ] ,
  

To match the target environment, the virtual image of the imported pattern is then updated to the Version 8.0.0.2 level.

• The updated references definition:

              "virtual_images": [
                  {"name": "WebSphere Application Server 8.0.0.2", "version": "8.0.0.2", "build": "112022.490"},  .
              ] ,
  

Providing native language support

To provide native language support for the virtual system pattern name and description, you can add the messages.properties file of each locale in the locales directory. In the following example, the locales directory contains message files in English, French, and Simplified Chinese. The format of the messages.properties file follows Java internationalization specifications.

    /
        patterns.json
        .
        /locales 
            messages.properties
            messages_en.properties
            messages_fr.properties
            messages_zh_CN.properties 

Use a web server to host the virtual images referenced by the virtual system pattern

Because the size of the virtual image can be larger than several gigabytes, you can host the virtual image on a web server to import it in several different environments. Update the virtual image values in the references definition as shown in the following example:

"references": {
            "virtual_images": [
                {"name": "IMAGE NAME", "version": "IMAGE_VERSION",""build": "REFID", "url", "OVA_URL_FOR_IMPORT", "user": "USER", "password": "PASSWORD"}, .
            ] ,

The "url" value is the HTTP or HTTPS URL for the virtual images. The optional "user" and "password" values are used for basic authorization.

7.13.3. Patterns on the CLI

You can work with virtual system patterns by working with Pattern and Patterns objects on the IBM PureApplication System W1500 CLI.

Patterns object

The Patterns object represents the collection of virtual system patterns defined to PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for virtual system patterns in PureApplication System.

The Patterns object requires you to define the name attribute to create a virtual system pattern. You can also specify a description using the description attribute.

To get help for the Patterns object on the CLI, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.patterns)

Pattern object

A Pattern object represents a particular PureApplication System virtual system pattern. Use the Pattern object to query and manipulate the virtual system pattern definition. Attributes of the virtual system pattern and relationships between the virtual system pattern and other PureApplication System resources are represented as Jython attributes on the Pattern object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding PureApplication System data.

To get help for the Pattern object on the CLI, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.pattern)

Pattern attributes

acl

An object for manipulating the access control list for this virtual system pattern. For more information about the properties and methods supported by acl objects, enter the following command:

help(deployer.acl)

advancedoptions

Use the advancedoptions object to view and set the advanced options for the virtual system pattern. Different advanced options are available depending on the topology described by the virtual system pattern.

created

The creation time of the virtual system pattern, as the number of seconds since midnight, January 1, 1970 UTC. When the virtual system pattern is displayed, this value is shown as the date and time in the local time zone. This field is read-only.

currentmessage

The message associated with the status of the virtual system pattern. This field is read-only.

currentmessage_text

Provides a textual description of the current message. This field is read-only.

currentstatus

The status of the virtual system pattern.

currentstatus_text

Provides a textual description of the status. This field is read-only.

description

The description of the virtual system pattern.

id

The ID of the virtual system pattern. This field is read-only.

name

The name associated with this virtual system pattern. Each virtual system pattern must have a unique name.

owner

A User object that references the owner of this virtual system pattern. For more information about the properties and methods supported by user objects, enter the following command:

>>> help(deployer.user)

parts

A resource collection containing the parts contained within this virtual system pattern. For more information about the properties and methods supported by virtual system pattern parts objects, enter the following command:

>>> help(deployer.pattern_parts)

updated

The time the virtual system pattern was last updated, as number of seconds since midnight, January 1, 1970 UTC. When the virtual system pattern is displayed, this value is shown as the date and time in the local time zone. This field is read-only.

validations

The validation status and messages associated with the virtual system pattern. The value of this attribute is a list containing the results of validation tests run on the IBM PureApplication System. Each entry in the list is a dict object containing the following keys and values:

status

This key provides the validation status associated with this entry.

status_text

This key provides a textual representation of the status.

message

This key provides the message that is associated with the status.

message_text

This key provides the textual representation of the message.

This value is automatically generated and cannot be changed. To get help for the validations attribute, enter the following command:

help(deployer.pattern.validations)

validationmessage

The message associated with the validation status of the virtual system pattern. This field is read-only.

validationmessage_text

Provides a textual description of the validation message. This attribute provides a shortcut to access the first entry of the validations attribute. This field is read-only.

validationstatus

The status associated with validation of the virtual system pattern. This field is read-only.

validationstatus_text

Provides a textual description of the validation status. This attribute provides a shortcut to access the first entry of the validations attribute. This field is read-only.

virtualimage

The virtual image used to realize this virtual system pattern when the virtual system pattern is deployed.

virtualsystems

The virtual system instances currently running this virtual system pattern. For more information about the properties and methods supported by virtualsystems objects, enter the following command:

help(deployer.virtualsystems)

Pattern methods

The pattern object has the following methods:

clone()

Clones this pattern object and returns a pattern object for the new virtual system pattern, as shown in the following example:

clone(**options)

This method recognizes the following optional parameters:

description

The description for the new virtual system pattern. If not specified, the description of the virtual system pattern being cloned is used.

name

The name assigned to the new virtual system pattern. If not specified, the new virtual system pattern name is based on the name of the virtual system pattern being cloned.

virtualimage

This deprecated parameter attempts to change all parts in the new virtual system pattern to the specified virtual image, regardless of the number of virtual images referenced in the original virtual system pattern. To change the virtual image associated with parts in the new virtual system pattern, set the virtualimage attribute on those parts after the virtual system pattern has been cloned. If not specified, parts in the new virtual system pattern use the same virtual images as the corresponding parts in this virtual system pattern. If specified, an attempt is made to switch all parts in the new virtual system pattern to the indicated virtual image, as shown in the following example:

>>> newpattern = mypattern.clone(name='foo', virtualimage=myvi)

The following example shows the clone method:

>>> newpattern = mypattern.clone(name='foo', description='cloned pattern')

isDraft()

Indicates if this virtual system pattern is in draft mode.

isReadOnly()

Indicates if this virtual system pattern is read-only.

listConfig(data={})

Returns a dictionary (dict object) of the configurable part properties and script parameters contained in this virtual system pattern. The keys for thisdict object are as described in the create information in the online help for deployer.virtualsystems.create. The values reflect the default values defined in the virtual system pattern.

This method accepts a single optional parameter that can be used to supply a dict object containing overrides to the default values. Specify the overrides as described in the create method information in Virtual system instances CLI reference. Specifying overrides is useful to see what values are to be used during a virtual system pattern deployment without tying up the resources to perform an actual deployment.

makeReadOnly()

Makes this virtual system pattern read-only. When the virtual system pattern is read-only, the virtual system pattern can be deployed but not modified.

runInCloud(cloud,options)

Allocates cloud resources and starts a copy of this virtual system pattern in the cloud. This method requires the following parameters:

cloudorep

This is either a cloud object representing the cloud group in which the virtual system pattern is to be run, or an EnvironmentProfile object representing the environment profile to be used for the deployment.

options

A Jython dict object containing:

• A name key/value that specifies a name for the virtual system instance to be created.
• The part property and script parameter values to be used for the deployment.
• The environment profile configuration information.

The following example shows the runInCloud method:

>>> myvirtsys = mypattern.runInCloud(myCloud, { 'name': 'example',
...   '*.*.password': 'thepassword' })

toPython(f, **options)

This method generates a Python script on the local system that, when run, reconstructs a virtual system pattern from the IBM PureApplication System. To use the generated script, the system on which the virtual system pattern is reconstructed must already contains the virtual image and scripts used by the virtual system pattern.

This method takes, as a parameter, a file name or file object to which the generated CLI script is saved. This method has no return value. Exceptions are thrown if any errors are encountered while generating the Python script.

Additional options can be passed to this method by including name=value pairs in the method invocation, as shown in the following example:

mypattern.toPython('filename.py', includePasswords=True)

This method recognizes the following options:

includePasswords

A boolean value that indicates if passwords are included in the generated script. By default, the values for any part properties or script parameters that are passwords are omitted from the generated script.

Advancedoptions object

Use the Advancedoptions object to view and set the advanced options for the virtual system pattern. Different advanced options are available, depending on the topology described by the virtual system pattern. For some topologies, there are no advanced options available.

Advancedoptions methods

The Advancedoptions property supports the following methods to view and set the advanced options:

add(key)

Accepts a single parameter that must be either a string specifying an advanced option or a list of these strings. The specified advanced options are added to the existing advanced options for this virtual system pattern. If any of the new advanced options conflict with advanced options that were previously added, the new advanced options take precedence. If any of the new advanced options depend on other advanced options that have not already been set, the needed advanced options are automatically set. The following example shows advanced options being set:

>>> mypattern.advancedoptions.add('messaging-enabled')
>>> mypattern.advancedoptions.add(['sessionpersistence-db',
...   'security-enabled'])

clear()

Clears all advanced options from the virtual system pattern. There are no parameters to this method, as shown in the following example:

>>> mypattern.advancedoptions.clear()

__contains__(item)

Called implicitly by the Jython in operator, this method accepts a single string parameter. The parameter names an advanced option and returns a boolean value. The boolean value indicates if the specified advanced option is set in the virtual system pattern, as shown in the following example:

>>> if 'security-enabled' in mypattern.advancedoptions:
...     print 'security is enabled'

getAvailableOptions()

Returns a list of strings that name all the advanced options available for this virtual system pattern. This method has no parameters, as shown in the following example.

>>> mypattern.getAvailableOptions()

This list of strings returned includes all available advanced options, regardless of whether they are currently set. To see just the options that are currently set, pass the advancedoptions property to the Jython list() function.

__iadd__(other)

Started implicitly when you use the Jython += operator with the advancedoptions property, as shown in the following example:

>>> mypattern.advancedoptions += 'messaging-engine-ha'

The __iadd__ method has the same behavior as the add method.

__isub__(other)

This method is started implicitly when you use the Jython -= operator with the advancedoptions property, as shown in the following example:

>>> mypattern.advancedoptions -= ['messaging-mq-link',
...     'messaging-enabled']

The __isub__ method has the same behavior as the remove method.

__iter__()

Returns an iterator over all the advanced options (as strings) that are currently set for this virtual system pattern, as shown in the following example:

>>> for ao in mypattern.advancedoptions:       
...     print 'advanced option %s is set' % ao

The __iter__ method is implicitly started when the advancedoptions property is used in an iterative context

__len__()

Returns the number of advanced options currently set for the virtual system pattern. This method is started implicitly by the Jython len function, as shown in the following example:

>>> len(mypattern.advancedoptions)

remove(other)

This method accepts a single parameter that must be either a string specifying an advanced option or a list of these strings, as shown in the following example:

>>> mypattern.advancedoptions.remove('messaging-enabled')
>>> mypattern.advancedoptions.remove(['sessionpersistence-db',
...   'security-enabled'])

The specified advanced options are removed from the existing advanced options for this virtual system pattern.

• Some advanced options are grouped into sets that require at least one of the advanced options to be set. If removing one advanced option would cause this constraint to be violated, the default advanced option from the set is automatically selected.
• Removing an advanced option does not automatically remove any parent advanced options.

__repr__()

Returns a string representation of the advanced options. The string representation includes short textual descriptions of each advanced option and shows the hierarchy of the advanced options.

__str__()

Returns a string representation of the advanced options. The string representation includes short textual descriptions of each advanced option and shows the hierarchy of the advanced options.

__unicode__()

Returns a string representation of the advanced options. The string representation includes short textual descriptions of each advanced option and shows the hierarchy of the advanced options.

In addition to these methods, you can also assign a string or list of strings to the advancedoptions property. The result is the same as if you had issued the clear() and then the add() methods of the same advanced options.

7.13.4. Pattern parts on the CLI

You can work with virtual system patterns by working with virtual system pattern parts on the IBM PureApplication System W1500 CLI.

Pparts object

A pattern_parts object represents the collection of parts defined within a particular virtual system pattern on the IBM PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for parts within a virtual system pattern on the IBM PureApplication System. When creating a Ppart object, an ID (of the part to be added to the virtual system pattern) is required. A Pparts object has all the methods of a resourcecollection object. The create() method is described because it has specific behavior unique to the Pparts object. The create method creates a virtual system pattern part or parts within a virtual system pattern. The parts to be added can be specified in any of the following ways:

• As a Part object for the part that is to be added to this virtual system pattern, as shown in the following example:

  >>> mypattern.parts.create(thepart)
  

• As a dictionary (dict) object with the required keys, as shown in the following example:

  >>> mypattern.parts.create({'id': thepart.id })
  

• As a long or int value that specifies the ID of the Part object to be used to create a virtual system pattern part, as shown in the following example:

  >>> mypattern.parts.create(thepart.id)
  

• As the name of a file containing a Jython expression that evaluates to one of the values in this list.
• As the value deployer.wizard or a wizard instance created by calling deployer.wizard(). If either of these values is supplied, the CLI prompts interactively for the values to create the resource.
• As a list of any of the previous items in the list, in which case multiple parts are created within the virtual system pattern. This usage is shown in the following example:

  >>> mypattern.parts.create([part1, part2])
  

The create method returns a resource object for the new virtual system pattern part, or a list of these objects if multiple virtual system pattern parts were created.

To get help for the pattern_parts object on the CLI, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.pattern_parts)

Ppart object

A Ppart object represents a part that has been added to a virtual system pattern on the system. Use the pattern_part object to query and manipulate the part definition on the system. Attributes of the part and relationships between the part and other resources on the PureApplication System system are represented as Jython attributes on the pattern_part object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding data on the system.

Help is available for the virtual system pattern part object on the CLI. To get help, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.pattern_part)

Ppart Attributes

The Ppart object has the following attributes:

count

The number of instances of this part that are to be created when the virtual system pattern is deployed.

This property is only defined for types of parts that can be replicated at deployment time. For those types of parts, the count is initially set to 1 and can be changed to any positive integer value. For other types of parts, the count is None and cannot be changed.

countLocked

This attribute provides a boolean value that indicates if virtual machines, based on this part, can be dynamically added to or removed from the virtual system instance after the virtual system pattern has been deployed. For parts that cannot be dynamically added or removed, the countLocked attribute returns the None value and cannot be changed. For more information, enter the following command:

help(deployer.pattern_part.countLocked)

description

The description of the part. This field is a string value with a maximum of 1024 characters.

id

The ID of the part. This numeric value is automatically generated by the system.

partCaption

The label used for this part. This field is a string value with a maximum of 1024 characters.

pattern

The virtual system pattern that contains this part. For more information about the properties and methods supported by pattern objects, enter the following command:

>>> help(deployer.pattern)

properties

The list of properties defined for this part. Each property is a dict object with the following properties:

key

The key of the property.

locked

Indicates whether the value of the userConfigurable property can be changed.

pclass

The pclass value of the property.

value

The default value assigned to the property.

UserConfigurable

Indicates whether the value of the property can be changed at deployment time.

This property is read-only. Changes to the dict object have no effect on the part. To change a property of the part, use the setProperty() method of the part.

scripts

A resource collection containing the scripts contained within this virtual system pattern part. For more information about the properties and methods supported by pattern_scripts objects, enter the following command:

>>> help(deployer.pattern_scripts)

startsafter

The set of parts in the virtual system pattern that must start before this part. For additional information on manipulating part startup order, enter the following command:

>>> help(deployer.pattern_part.StartsAfter)

startuporder

The startup order of this part relative to other parts in the same virtual system pattern. Virtual system pattern parts with smaller values start before virtual system pattern parts with larger values. This attribute is an integer.

validations

This attribute provides the validation status and messages associated with the virtual system pattern part. The value of this attribute is an array containing the results of validation tests run on the IBM PureApplication System. Each entry in the array is a dict object containing the following keys and values:

message

This key provides the message that is associated with the status.

message_text

This key provides the textual representation of the message.

status

This key provides the validation status associated with this entry.

status_text

This key provides a textual representation of the status.

This value is automatically generated and cannot be changed. To get help for the validations attribute, enter the following command:

help(deployer.pattern_part.validations)

virtualimage

The virtual image to be used to realize this part when the virtual system pattern including the part is deployed. For more information about the properties and methods supported by virtualimage objects, enter the following command:

help(deployer.virtualimage)

Ppart Methods

The Ppart object has the following methods:

getProperty

Returns information about a particular property of a part. This method accepts the following parameters:

key

The key of the property to be retrieved. This parameter is required.

pclass

The pclass of the property to be retrieved. This parameter is required.

wantMetadata

An optional boolean value indicating one of the following method returns:

• Metadata about the property (True)
• Just the value of the property (False)

The following example shows the wantMetadata parameter:

>>> mypattern.parts[0].getProperty('ConfigPWD_ROOT', 'password', True)

setProperty

Sets the value and (optionally) metadata for a part property. This method accepts the following parameters:

key

The key of the property to be retrieved. This parameter is required.

metadata

An optional dict object that can contain the userConfigurable key. The userConfigurable key is a boolean value that indicates if users can change the value of this property at deployment time.

pclass

The pclass of the property to be retrieved. This parameter is required.

value

An optional value to be set for the property. If not specified, the current value of the property is unchanged.

The following examples show the setProperty method:

• >>> mypattern.parts[0].setProperty('ConfigPWD_ROOT', 'password',
  ...   'mypassword', **{ 'userConfigurable': False })
  

• >>> mypattern.parts[0].setProperty('ConfigPWD_ROOT', 'password',
     ...   'mypassword', userConfigurable=False)
  

StartsAfter object

A list-like object that represents the parts in the pattern that must start before this part.

StartsAfter methods

The StartsAfter object has the following methods:

__contains__

This method is invoked implicitly by Jython when you use the in operator on a StartsAfter object. Its single parameter must be a virtual system pattern part from the same virtual system pattern. The method returns True or False to indicate if the specified virtual system pattern part is in the set of virtual system pattern parts that must start before the virtual system pattern part to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

    >>> firstPart = mypattern.parts[0]
    >>> secondPart = mypattern.parts[1]
    >>> if firstPart in secondPart.startsafter:
    >>>    # firstPart starts before secondPart

__delitem__

This method is invoked implicitly by Jython when you use the del operator on a StartsAfter object. Its single parameter must be the index of the virtual system pattern part to be removed from the set of virtual system pattern parts that must start before the virtual system pattern part to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

     >>> del mypattern.parts[0].startsafter[0]

__getitem__

This method is invoked implicitly by Jython when you use the [] operator on a StartsAfter object. Its single parameter must be the non-negative index of the virtual system pattern part to be returned from the set of virtual system pattern parts that must start before the virtual system pattern part to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

     >>> mypattern.parts[0].startsafter[0]

__iadd__

This method is invoked implicitly by Jython when you use the += operator on the StartsAfter attribute of a virtual system pattern part. It accepts a single parameter that can be either a virtual system pattern part or list of virtual system pattern parts. All virtual system pattern arts must belong to the same virtual system pattern. All parts passed as arguments are added to the set ofvirtual system pattern parts that must start before the virtual system pattern part to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

    >>> firstPart = mypattern.parts[0]
    >>> secondPart = mypattern.parts[1]
    >>> secondPart.startsafter += firstPart

This method returns StartsAfter to allow chained operations.

isDeletable

Indicates if the specified virtual system pattern part can be removed from the list of parts that start after this part.

__isub__

This method is invoked implicitly by Jython when you use the -= operator on the StartsAfter attribute of a virtual system pattern part. It accepts a single parameter that can be either a virtual system pattern part or list of virtual system pattern parts. All virtual system pattern parts must belong to the same virtual system pattern. All parts passed as arguments are removed from the set of virtual system pattern parts that must start before the virtual system pattern part to which the StartsAfter attribute belongs. Invocation of this method is shown in the following example:

    >>> firstPart = mypattern.parts[0]
    >>> secondPart = mypattern.parts[1]
    >>> secondPart.startsafter -= firstPart

This method returns the StartsAfter attribute to allow chained operations.

__iter__

This method is invoked implicitly by Jython when a StartsAfter object is used in a context that requires iterating over its elements. It returns an iterator over the virtual system pattern parts required to start before the original virtual system pattern part.

__len__

Returns the number of virtual system pattern parts that are explicitly required to start before the virtual system pattern part to which the StartsAfter object belongs. This method is invoked implicitly by Jython when you use the len() function, as shown in the following example:

     >>> len(mypattern.parts[0].startsafter)

__lshift__

This method is invoked implicitly by Jython when you use the left shift operator ('<<') on a StartsAfter object. Its single parameter can be either a virtual system pattern part or a list of virtual system pattern parts. All virtual system pattern parts must belong to the same virtual system pattern. All parts passed as arguments are added to the set of virtual system pattern parts that must start before the virtual system pattern part to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

    >>> firstPart = mypattern.parts[0]
    >>> secondPart = mypattern.parts[1]
    >>> secondPart.startsafter << firstPart

This method returns the StartsAfter to allow chained operations.

__repr__

Returns a string representation of the virtual system pattern parts that must start before a particular virtual system pattern part.

__rshift__

This method is invoked implicitly by Jython when you use the right shift operator ('>>') on a StartsAfter object. Its single parameter can be either a virtual system pattern part or a list of virtual system pattern parts. All virtual system pattern parts must belong to the same virtual system pattern. All parts passed as arguments are removed from the set of virtual system pattern parts that must start before the virtual system pattern part to which the StartsAfter belongs. Invocation of this method is shown in the following example:

    >>> firstPart = mypattern.parts[0]
    >>> secondPart = mypattern.parts[1]
    >>> secondPart.startsafter >> firstPart

This method returns the StartsAfter object to allow chained operations.

__str__

Returns a string representation of the virtual system pattern parts that must start before a particular virtual system pattern part.

__unicode__

Returns a string representation of the virtual system pattern parts that must start before a particular virtual system pattern part.

7.13.5. Pattern scripts on the CLI

You can work with pattern_script and pattern_scripts objects on the IBM PureApplication System W1500 CLI.

Pscripts object

A pattern_scripts object represents the collection of scripts defined within a particular virtual system pattern part on the IBM PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for scripts within a pattern part on the IBM PureApplication System.

When creating virtual system pattern scripts, the ID (of the script to be added to the pattern part) is required. The pattern_scripts object has all the normal methods of a resourcecollection object. The create() method, however, has behavior that is unique to the Pscripts object.

Help is available for the pattern_scripts object on the CLI. To get help, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.pattern_scripts)

The Pscripts object has the following method:

create

Creates a pattern script or scripts within a pattern part. The scripts to be added can be specified in the following ways:

• As a script object for the part that is to be added to this pattern part, as shown in the following example:

  >>> mypart.scripts.create(thescript)
  

• As a dictionary (dict) object with the required keys, as shown in the following example:

  >>> mypart.scripts.create({'id': thescript.id })
  

• As a long or int value that specifies the ID of the script object to be used to create a virtual system pattern script. This value is shown in the following example:

  >>> mypart.scripts.create(thescript.id)
  

• As the name of a file containing a Jython expression that evaluates to one of the values in this list.
• As the value deployer.wizard or a wizard instance created by calling deployer.wizard(). If either of these values is supplied, the CLI prompts, interactively, for the values to create the resource.
• As a list of any of the previous parts specified, in which case multiple scripts are created within the virtual system pattern part. This list of parts is shown in the following example:

  >>> mypart.scripts.create([script1, script2])
  

This method returns a virtual system pattern script object for the new virtual system pattern script, or a list of these objects if multiple virtual system pattern scripts were created.

Pscript object

A virtual system pattern script object represents a script that has been added to a part in a virtual system pattern on the IBM PureApplication System. Use the virtual system pattern script object to query and manipulate the script definition on the system. Attributes of the script and relationships between the script and other resources in PureApplication System are represented as Jython attributes on the virtual system pattern script object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding data in PureApplication System.

To get help for the pattern_script object, on the CLI, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.pattern_script)

Pscript Attributes

The pattern_script object has the following attributes:

description

The description of the script.

executionOrder

Indicates the order in which this script is to run, relative to other scripts in the same part. Virtual system pattern scripts with larger values for the executionOrder attribute are run before scripts with smaller values. This value is an integer.

id

The ID of the script. This attribute is read-only.

isdeletable

Indicates if this script can be deleted by a user. This attribute is read-only.

label

The label used for the script. This attribute is read-only.

parameters

A list of parameters defined for this script. This attribute is read-only. Each parameter is a dict object with the following properties:

defaultvalue

The default value assigned to the parameter.

key

The key of the parameter.

locked

Indicates whether the value for the userConfigurable parameter can be changed.

This property is read-only.

UserConfigurable

Indicates whether the value of the parameter can be changed at deployment time.

Changes to the dict object have no effect on the script. To change a parameter of the script, use the setParameter() method.

ppart

The part that contains this script. This attribute is read-only. For more information about the properties and methods supported by pattern_part objects, enter the following command:

>>> help(deployer.pattern_part)

startsafter

The set of scripts in the virtual system pattern that must start before this script. For additional information on manipulating script startup order, enter the following command:

     >>> help(deployer.pattern_script.StartsAfter)

type

The type of this script. This attribute is read-only.

Pscript Methods

The pattern_script part has the following methods:

getParameter

Returns information about a particular parameter of a script. This method accepts the following parameters:

key

The key of the parameter to be retrieved. This parameter is required.

wantMetadata

An optional boolean value indicating if the method returns metadata about the parameter (True) or just the value of the parameter (False), as shown in the following example:

>>> mypattern.parts[0].scripts[0].getParameter('key1', True)

setParameter

Sets the value and (optionally) metadata for a script parameter. This method accepts the following parameters:

key

The key of the parameter to be set. This parameter is required.

defaultvalue

An optional value to be set for the parameter. If not specified, the current value of the parameter is unchanged.

metadata

An optional dict object that can contain the following key:

UserConfigurable

A boolean value that indicates if users can change the value of this parameter at deployment time, as shown in the following example:

>>> mypattern.parts[0].scripts[0].setParameter('key1', \
   ...   'new value', **{ 'userConfigurable': False })

StartsAfter object

A list-like object that represents the parts in the pattern that must start before this part.

StartsAfter methods

The StartsAfter object has the following methods:

__contains__

This method is invoked implicitly by Jython when you use the in operator on a StartsAfter object. Its single parameter must be a virtual system pattern script from the same virtual system pattern. The method returns True or False to indicate if the specified virtual system pattern script is in the set of virtual system pattern scripts that must start before the virtual system pattern script to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

 >>> firstScript = mypattern.parts[0].scripts[0]
    >>> secondScript = mypattern.parts[1].scripts[0]
    >>> if firstScript in secondScript.startsafter:
    >>>    # firstScript starts before secondScript

__delitem__

This method is invoked implicitly by Jython when you use the del operator on a StartsAfter object. Its single parameter must be the index of the virtual system pattern script to be removed from the set of virtual system pattern scripts that must start before the virtual system pattern script to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

     >>> del mypattern.parts[0].scripts[0].startsafter[0]

__getitem__

This method is invoked implicitly by Jython when you use the [] operator on a StartsAfter object. Its single parameter must be the non-negative index of the virtual system pattern script to be returned from the set of virtual system pattern scripts that must start before the virtual system pattern script to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

     >>> mypattern.parts[0].scripts[0].startsafter[0]

__iadd__

This method is invoked implicitly by Jython when you use the += operator on the StartsAfter attribute of a virtual system pattern script. It accepts a single parameter that can be either a virtual system pattern script or list of virtual system pattern scripts. All virtual system pattern scripts must belong to the same virtual system pattern. All scripts passed as arguments are added to the set ofvirtual system pattern scripts that must start before the virtual system pattern script to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

    >>> firstScript = mypattern.parts[0].scripts[0]
    >>> secondScript = mypattern.parts[1].scripts[0]
    >>> secondScript.startsafter += firstScript

This method returns StartsAfter to allow chained operations.

__isub__

This method is invoked implicitly by Jython when you use the -= operator on the StartsAfter attribute of a virtual system pattern script. It accepts a single parameter that can be either a virtual system pattern script or list of virtual system pattern scripts. All virtual system pattern scripts must belong to the same virtual system pattern. All scripts passed as arguments are removed from the set of virtual system pattern scripts that must start before the virtual system pattern script to which the StartsAfter attribute belongs. Invocation of this method is shown in the following example:

    >>> firstScript = mypattern.parts[0].scripts[0]
    >>> secondScript = mypattern.parts[1].scripts[0]
    >>> secondScript.startsafter -= firstScript

This method returns the StartsAfter attribute to allow chained operations.

__iter__

This method is invoked implicitly by Jython when a StartsAfter object is used in a context that requires iterating over its elements. It returns an iterator over the virtual system pattern scripts required to start before the original virtual system pattern script.

__len__

Returns the number of virtual system pattern scripts that are explicitly required to start before the virtual system pattern script to which the StartsAfter object belongs. This method is invoked implicitly by Jython when you use the len() function, as shown in the following example:

    >>> len(mypattern.parts[0].scripts[0].startsafter)

__lshift__

This method is invoked implicitly by Jython when you use the left shift operator ('<<') on a StartsAfter object. Its single parameter can be either a virtual system pattern script or a list of virtual system pattern scripts. All virtual system pattern scripts must belong to the same virtual system pattern. All scripts passed as arguments are added to the set of virtual system pattern scripts that must start before the virtual system pattern script to which the StartsAfter object belongs. Invocation of this method is shown in the following example:

    >>> firstScript = mypattern.parts[0].scripts[0]
    >>> secondScript = mypattern.parts[1].scripts[0]
    >>> secondScript.startsafter << firstScript

This method returns StartsAfter to allow chained operations.

__repr__

Returns a string representation of the virtual system pattern scripts that must start before a particular virtual system pattern script.

__rshift__

This method is invoked implicitly by Jython when you use the right shift operator ('>>') on a StartsAfter object. Its single parameter can be either a virtual system pattern script or a list of virtual system pattern scripts. All virtual system pattern scripts must belong to the same virtual system pattern. All scripts passed as arguments are removed from the set of virtual system pattern scripts that must start before the virtual system pattern script to which the StartsAfter belongs. Invocation of this method is shown in the following example:

    >>> firstScript = mypattern.parts[0].scripts[0]
    >>> secondScript = mypattern.parts[1].scripts[0]
    >>> secondScript.startsafter >> firstScript

This method returns the StartsAfter object to allow chained operations.

__str__

Returns a string representation of the virtual system pattern scripts that must start before a particular virtual system pattern script.

__unicode__

Returns a string representation of the virtual system pattern scripts that must start before a particular virtual system pattern script.

7.13.6. Parts on the CLI

You can work with the Part object on the IBM PureApplication System W1500 CLI.

Part object

A Part object represents a particular part defined to PureApplication System. Use the Part object to query and manipulate the part definition. Attributes of the part and relationships between the part and other resources in PureApplication System are represented as Jython attributes on the Part object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding data on the IBM PureApplication System.

Help is available for the Part object on the CLI. To get help, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.part)

Part attributes

The Part object has the following attributes:

created

The creation time of the part, as number of seconds since midnight, January 1, 1970 UTC. When the part is displayed, this value is shown as the date and time in the local timezone. This value is numeric and is automatically generated by the system. This attribute is read-only.

currentmessage

The message associated with the currentstatus of the part. This field is an eight character string value that is automatically generated by the system. This attribute is read-only.

currentmessage_text

Textual representation of the currentmessage attribute. This field is a string representation of the currentmessage attribute in the preferred language of the requester and is automatically generated by the system. This attribute is read-only.

currentstatus

Specifies a string constant representing the currentstatus of the virtual system pattern. This field is an eight character string value that is automatically generated by the system.

currentstatus_text

Textual representation of currentstatus. This string represents the currentstatus in the preferred language of the requester and is automatically generated by the system. This attribute is read-only.

description

The description of the part. This field is a string value with a maximum of 1024 characters. This attribute is read-only.

id

The ID of the part. This numeric value is automatically generated by the system. This attribute is read-only.

label

The label of this part. This field is a string value with a maximum of 1024 characters. This attribute is read-only.

name

The name of this part. This field is a string value with a maximum of 1024 characters. This attribute is read-only.

owner

A User object that references the owner of this part. For more information about the properties and methods supported by User objects, enter the following command:

>>> help(deployer.user)

productids

This attributes specifies all of the product IDs associated with this virtual image part.

updated

The time the part was last updated, as number of seconds since midnight, January 1, 1970 UTC. When the part is displayed, this value is shown as the date and time in the local timezone. This value is numeric and is automatically generated by the system. This attribute is read-only.

validationmessage

The message associated with the validationstatus attribute of the part. This attribute is read-only.

validationmessage_text

The textual representation of the validationmessage attribute. This attribute is read-only.

validationstatus

The status associated with validation of the part. This attribute is read-only.

validationstatus_text

The textual representation of the validationstatus attribute. This attribute is read-only.

virtualimage

A reference to the virtual image that defined this part. For more information about the properties and methods supported by virtualimage objects, enter the following command:

 >>> help(deployer.virtualimage)

This value is automatically generated and cannot be changed.

Part methods

The Part object has the following methods:

isConceptual

Indicates if this part is conceptual. A conceptual part is not tied to any particular virtual image until deployment time.

addProductid

Add a new product ID to the virtual image part. This method accepts the following parameters:

productid

The product ID to add. This parameter is required.

licensetype

The license type for this product ID. Valid values are:

• PVU
• Server

The default value is PVU. This parameter is required.

licensecpu

The CPU count limit for this server license. This parameter is required for the server license type.

licensememory

The memory limit in GB for this server license. This parameter is required for the server license type, as shown in the following example:

 >>> mypart[0].addProductid('5724-X89', 'PVU')
 >>> mypart[0].addProductid('5724-X89', 'Server', 4, 32)

deleteProductid

Delete a product ID from the virtual image part. This method accepts the following parameters:

productid

The product ID to delete. This parameter is required.

licensetype

The license type for this product ID. Valid values are:

• PVU
• Server

The default value is PVU. This parameter is required.

The following example shows the deleteProductid method:

>>> mypart[0].deleteProductid('5724-X89', 'PVU')

Plug-in CLI reference

You can administer plug-ins in the catalog using the CLI.

For information about working with the CLI, see the Using the CLI topic.

Plugin object

A Plugin object represents a particular plug-in defined on IBM PureApplication System W1500. Use the plug-in object to query and manipulate the plug-in definition. Attributes of the plug-in and relationships between the plug-in and other resources on PureApplication System are represented as Jython attributes on the plug-in object. Manipulate these Jython attributes using standard Jython mechanisms to make changes to the corresponding data on the product.

To get help for the Plugin object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.plugin)

Plugin attributes

The Plugin object has the following attributes:

create_time

The creation time of the plug-in.

creator

Creator of the plug-in.

description

The description of the plug-in.

last_modified

Time the plug-in was updated.

last_modifier

The last user who updated the plug-in.

name

The name of the plug-in.

Plugin methods

The Plugin and Plugin object has the following methods:

list

List all plugins

deployer.plugins or deployer.plugins.list

For example, >>>deployer.plugins

Get a single plug-in by index:

deployer.plugins[<index>]

For example, >>>deployer.plugins[0]

get

Get a single plug-in by plug-in name:

deployer.plugins.get(<plugin name>)

For example, >>>deployer.plugins.get("osgiebaosgirepo/1.0.0.0")

create

Create a plug-in

deployer.plugins.create(<file local path>)

For example, >>> deployer.plugins.create("C:\\testplugin-1.0.0.0.tgz")

Power CLI reference

You can administer the power settings of the IBM PureApplication System using the CLI.

Power object

The Power object is used to request a shutdown or restart of the IBM PureApplication System. Referencing any of the Power object attributes triggers the requested shutdown or restart. None of the following attributes can be set and all have a value of None.

restart

Restart the server by waiting until the active tasks have completed.

restartnow

Restart the server immediately.

shutdown

Shuts down the server by waiting until the active tasks have completed.

shutdownnow

Shuts down the server immediately.

Use the CLI for problem determination

You can use the CLI to access problem determination and diagnostics information.

Diagnostics object

Returns the Diagnostics object representing the diagnostics package for the system.

Help is available on the CLI for the Diagnostics object. To get help, pass the Diagnostics object as an argument to the help() function, as shown in the following example:

>>> help(deployer.diagnostics)

The Diagnostics object has two methods, the get method, and the getLatest method. The get method downloads the diagnostics package as a compressed file. This method takes an optional path where the file is stored; the default path is ./trace.zip, as shown in the following examples:

>>> deployer.diagnostics.get()

>>> deployer.diagnostics.get('/some/path/diagnostics.zip')

The getLatest method downloads a diagnostics package as a compressed file that only contains the latest version of the diagnostics files. By using this method, you can obtain a diagnostics package that contains only the latest information and has a much smaller file size. This method takes an optional path where the file is stored; the default path is ./trace.zip, as shown in the following examples:

>>> deployer.diagnostics.getLatest()

>>> deployer.diagnostics.getLatest('/some/path/diagnostics.zip')

Trace object

The Trace object returns a TraceFile object representing the running trace file on the system.

Help is available for the Trace object on the CLI. To get help, pass the Trace object as an argument to the help() function, as shown in the following example:

>>> help(deployer.trace)

Trace methods

The Trace object has the following methods:

add

Adds a logger and optional log level to the trace file specification. Logger names use Java. package name syntax and log levels are one of the following values:

• OFF
• SEVERE
• WARNING
• CONFIG
• INFO
• FINE
• FINER
• FINEST

The default value is OFF. The add method is shown in the following examples:

>>> deployer.trace.add('com.ibm.ws.deployer', 'FINE')

>>> deployer.trace.add('com.ibm.ws.deployer.not.interested')

remove

Removes an existing logger from the trace file specification. Logger names use Java package name syntax, as shown in the following example:

>>> deployer.trace.remove('com.ibm.ws.deployer.not.interested')

set

Sets the log level for an existing logger in the trace file specification. Logger names use Java package name syntax and log levels are one of the following values:

• OFF
• SEVERE
• WARNING
• CONFIG
• INFO
• FINE
• FINER
• FINEST

The set method is shown in the following examples:

>>> deployer.trace.set('com.ibm.ws.deployer', 'FINE')

>>> deployer.trace.set('com.ibm.ws.deployer', 'SEVERE')

spec

Returns a map with the trace file specification for the system. The map has key-value pairs in which the key is the package name and the value is the log level.

tail

Prints the last <n> lines of the file, where <n> is an integer, as shown in the following example:

>>> deployer.trace.tail()

>>> deployer.errors.tail(100)

The default value is 10 (ten).

Errors object

The Errors object returns an ErrorFile object representing the running error file on the system.

Help is available for the Errors object on the CLI. To get help, pass the Errors object as an argument to the help() function, as shown in the following example:

>>> help(deployer.errors)

The Errors object has one method, the tail method. The tail method prints the last <n> lines of the file, in which <n> is an integer. The tail method is shown in the following example:

>>> deployer.trace.tail()

>>> deployer.errors.tail(100)

The default value is 10 (ten).

Script package CLI reference

You can administer script packages using the IBM PureApplication System W1500 CLI.

For information about working with the CLI, see the related links.

Scripts object

A Scripts object represents the collection of script packages defined to PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for script packages on IBM PureApplication System.

Help is available for the Scripts object on the CLI. To get help, pass the Scripts object as an argument to the help() function, as shown in the following example:

>>> help(deployer.scripts)

For more information about working with resource, resource collections, and methods, see the related links.

Script object

A Script object represents a particular script defined on the IBM PureApplication System. Use the Script object to query and manipulate the script definition on the PureApplication System. Attributes of the script and relationships between the script and other resources in PureApplication System are represented as Jython attributes on the Script object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding data in PureApplication System.

Help is available for the Script object on the CLI. To get help, pass the Script object as an argument to the help() function, as shown in the following example:

>>> help(deployer.script)

Script attributes

The pattern Script object has the following attributes:

acl

The access control list for this script. This field is read-only. For additional help on using this ACL object, see the related links or enter the following command:

     >>> help(deployer.acl)

archive

The script archive object associated with this script. See Script.Archive object. This field is read-only.

command

The command to be run for this script package. This field contains a string value with a maximum of 4098 characters.

commandargs

The arguments passed to the command. This field contains a string value with a maximum of 4098 characters.

created

The creation date and time of the script package, stored as the number of seconds since midnight, January 1, 1970 UTC. When details of the script package are displayed, this value is shown as the date and time in the local timezone. This field is read-only.

currentstatus

The status of the script package. This field contains an eight character string value that is generated by the PureApplication System.

currentstatus_text

A textual representation of currentstatus in the preferred language of the requester. This string is automatically generated by the PureApplication System. This field is read-only.

description

The description of the script package. This field contains a string value with a maximum of 1024 characters.

environment

Manages the key/value pairs that define the environment, or parameters, of the script. The environment property holds the script keys and default values for the script package. It is used such as a Jython dict object, as shown in the following example:

   >>> myscript.environment
   {
     "scriptkey1": "value for scriptkey1",
     "scriptkey2": "value for scriptkey2"
   }
   >>> myscript.environment['scriptkey1']
   'value for scriptkey1'
   >>> myscript.environment['foo'] = 'bar'
   >>> myscript.environment
   {
     "foo": "bar",
     "scriptkey1": "value for scriptkey1",
     "scriptkey2": "value for scriptkey2"
   }
   >>> del myscript.environment['foo']
   >>> myscript.environment
   {
     "scriptkey1": "value for scriptkey1",
     "scriptkey2": "value for scriptkey2"
   } 

This attribute is read-only.

execmode

This attribute specifies when the script package is run on the virtual machine. The following values can be used for this attribute:

deployer.script.VIRTUAL_SYSTEM_CREATION_EXECMODE

This value specifies that the script is run when the virtual system instance is created.

deployer.script.VIRTUAL_SYSTEM_DELETION_EXECMODE

This value specifies that the script is run when the virtual system instance is deleted.

deployer.script.USER_INITIATED_EXECMODE

This value specifies that the script is run when requested by the user. The script can be run an unlimited number of times on a virtual machine.

filename

The name of the script package archive file.

id

The ID of the script. The value of this attribute is an integer and is read-only.

label

The label for the script.

location

The directory, on the virtual machine, into which files for this script package are to be placed. This field contains a string value with a maximum of 4098 characters.

log

The directory on the virtual machine to hold the log files generated by this script package. This field contains a string value with a maximum of 4098 characters.

name

The name associated with this script package. Each script package must have a unique name. This field contains a string value with a maximum of 1024 characters.

owner

A user object that references the owner of this script package. For more information about the properties and methods supported by user objects, see the related links, or enter the following command:

>>> help(deployer.user)

timeout

The maximum amount of time to wait for this script package to finish running on the virtual machine. Specify the timeout, as the number of milliseconds to wait, or 0 (zero) to wait indefinitely for the script package to complete. The value of this attribute is an integer. If timeout occurs, Status.TIMEOUT_FAILED is returned, and execution is stopped.

updated

The date and time when the script package was last updated, stored as the number of seconds since midnight, January 1, 1970 UTC. When the script is displayed, this value is shown as the date and time in the local timezone. This field is read-only.

version

The version of the script package archive file. This attribute is read only.

Script methods

In addition to the methods shared with other resources, the Script object has the following methods:

clone

Creates a copy of this script package with all the same files, fields, and settings. The name of the new script is provided and the acl attribute is empty.

isDraft

Indicates if this script is in draft mode.

isReadOnly

Indicates if this script is read-only.

makeReadOnly

Makes this script read-only. When the script is made read-only, the script cannot be modified.

Script.Archive object

A Script.Archive object represents the archive file associated with a particular script in PureApplication System. This object supports methods to query and manipulate the script archive on the PureApplication System.

Script.Archive methods

The Script.Archive object supports the following methods:

get

This method retrieves the archive currently associated with the script. This method has one required parameter that indicates where the script archive is to be saved. It can be either of the following values:

• A string containing the name of a file in which to save the archive. If the file name does not end in .zip, .zip is automatically appended to the file name.
• A Jython file object, as shown in the following example:

  >>> myscript.archive.get('/path/to/foo.zip')
  

  You must ensure that the file object can correctly handle binary data. The script archive is returned in a compressed (.zip) file format.

__lshift__

This method is started implicitly when the Archive object is used as the left argument of a left shift operator ( << ). It calls the set() method with the right argument of the operator. This method is shown in the following example:

>>> myscript.archive << '/path/to/file'

__rshift__

This method is started implicitly when the Archive object is used as the left argument of a right shift operator ( >> ). It calls the get() method with the right argument of the operator. This method is shown in the following example:

>>> myscript.archive >> '/path/to/file.zip'

set

This method sets the archive associated with the script. It has one required parameter that indicates the source of the script archive to be uploaded. It can be either of the following values:

• A string containing the name of a file from which to get the archive.
• A Jython file object.

Ensure that the file object can correctly handle binary data. This method is shown in the following example:

>>> myscript.archive.set('/path/to/foo')

Here is an interactive example showing the use of the scripts.create method to first create a script package named MyScriptPackage, and then use the archive.set method to upload the compressed file MyCompressedFile.zip:

>>> scriptPackageName = 'MyScriptPackage'
>>> filePath = '/uploaded/test/MyCompressedFile.zip'
>>> scriptPackage = deployer.scripts.create({'name' : scriptPackageName})
>>> scriptPackage.archive.set(filePath)

Here is another example, which assumes that the script package has already been created. It uses a single line to find the first script package containing the string MyScriptPackage, and then applies the set method to upload the compressed file.

>>> deployer.scripts['MyScriptPackage'][0].archive.set('/uploaded/test/MyCompressedFile.zip')

For more information about working with resource objects, see the related links.

You can control the users and user groups access to scripts with the ACL object. For more information about the ACL object, see the related links.

Virtual images CLI reference

You can manage virtual images in the catalog using the IBM PureApplication System W1500 CLI. Virtual images provide the operating system and product binary files to create a virtual system instance.

VirtualImages object

A VirtualImages object represents the collection of virtual images defined to PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for virtual images on the IBM PureApplication System.

You can work with virtual images on the command line and help is available. To get help for the VirtualImages object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.virtualimages)

VirtualImages attributes

progressIndicators

This boolean attribute specifies if a progress indicator displays when uploading a virtual image from the CLI. The default value of the progressIndicators attribute is false.

VirtualImages methods

The VirtualImages object has the methods described for a typical resource collection. The following methods are unique to VirtualImages as their parameters and return values differ from what is expected:

create

Imports a new virtual image or images to the IBM PureApplication System. The attributes to import the new virtual images can be specified in any of the following ways:

• As a string specifying the URL from which the virtual image can be downloaded, as shown in the following example:

  >>> deployer.virtualimages.create('http://server.xyz.com/path/to/foo.ova')
  

• As the name of a local virtual image open virtual appliance (OVA) file to be uploaded to the IBM PureApplication System, as shown in the following example:

  >>> deployer.virtualimages.create('/path/to/foo.ova')
  

  Passing the OVA file to the PureApplication System takes up more space on the PureApplication System than specifying the URL of the OVA file. If space is an issue, consider pointing to the OVA file with a string specifying the URL instead.

• As a Jython file object that references the local OVA file, as shown in the following example:

  >>> deployer.virtualimages.create(open('/path/to/foo.ova', 'rb'))
  

• As a dictionary (dict) object with the required keys, as shown in the following example:

  >>> deployer.virtualimages.create({'url': 'http://...' })
  

• As the name of a file containing a Jython expression that evaluates to one of the values in this list.
• As the value deployer.wizard or a wizard instance created by calling deployer.wizard(). If either of these values is supplied, the CLI prompts interactively for the values to create the resource.
• As a list of any of these options, in which case multiple virtual images are imported, as shown in the following example:

  >>> deployer.hypervisors.create(['/path/to/foo1.ova',
                                     '/path/too/foo2.ova'])
  

This method returns a VirtualImage object for the newly created virtual image, or a list of VirtualImage objects if multiple virtual images were created. Because of their size, importing virtual images takes several minutes. If the location of the OVA file was specified using a local file name or file object, the OVA file is uploaded to the IBM PureApplication System before this method returns. Otherwise, this method queues the operation on the IBM PureApplication System and returns immediately. The returned VirtualImage objects can be used to track the status of the import process on the IBM PureApplication System.

import

The import method is an alias for the create() method and uses the same parameters and return values.

VirtualImage object

A VirtualImage object represents a particular virtual image defined to PureApplication System. Use the VirtualImage object to query and manipulate the virtual image definition on the PureApplication System. Attributes of the virtual image resource and relationships between the virtual image and other resources in PureApplication System are represented as Jython attributes on the VirtualImage object. Manipulate these Jython attributes using standard Jython mechanisms to change to the corresponding data on the IBM PureApplication System.

You can work with a virtual image on the command line and help is available. To get help for the VirtualImage object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.virtualimage)

VirtualImage attributes

The VirtualImage object has the following attributes, all which are read only:

acl

The access control list for this virtual image.

advancedoptionsaccepted

This attribute specifies if the virtual images advanced options are enabled. The default value for this boolean attribute is false.

build

The build number of the virtual image, automatically determined. This field contains a string value with a maximum of 1024 characters.

created

The creation time of the virtual image, as number of seconds since midnight, January 1, 1970 UTC. When the virtual image displays, this value is shown as the date and time in the local time zone.

currentmessage

The message associated with the status of the virtual image. This field contains an eight character string value that is generated by the PureApplication System.

currentmessage_text

This attribute is a string representation of currentmessage in the preferred language of the requester. This attribute is automatically generated by the PureApplication System.

currentstatus

The status of the virtual image. This field contains an eight character string value that is generated by the appliance.

currentstatus_text

This attribute is a string representation of currentstatus in the preferred language of the requester. This attribute is automatically generated by the appliance.

description

The description of the virtual image. This field contains a string value with a maximum of 1024 characters.

hardware

The default hardware configuration for the virtual image.

id

The ID of the virtual image. This attribute is an integer value.

license

The license attribute contains complete information about the licenses defined in the virtual image. A virtual image contains some number of licenses organized into some number of collections. Exactly one license from each collection must be accepted before the virtual image can be used. The value of the licenses attribute is a Python dict object. Each key in the dict object is the string ID of a collection of licenses. Each value is a nested Python dict object with the following keys and values:

label

A localized label for the collection of licenses.

licenses

An array of Python dict objects, each of which describes one license. These dict objects have the following keys and values:

label

A localized label for the license.

licenseid

The ID of the license.

text

The localized text of the license.

The value of the licenses attribute is generated by the appliance and cannot be set. The value of the dict object is not protected against updates, but such changes have no effect.

licenseaccepted

This attribute indicates if the license from this virtual image has been accepted. PureApplication System does not allow a virtual image to be used until the license is accepted. The license from the virtual image must be retrieved before it can be accepted. The following values are valid:

'T'

The virtual image license has been accepted.

'F'

The virtual image license has not been accepted.

name

The display name associated with this virtual image. This attribute is generated automatically when the virtual image is imported. This field contains a string value with a maximum of 1024 characters.

operatingsystemdescription

This attribute specifies a textual description of the operating system used by the virtual image. The value of this attribute is a string and might be None if the OVA of the virtual image does not supply a value.

operatingsystemid

The read.only attribute specifies the ID of the guest operating system used by the virtual image. The value of this attribute is an integer that corresponds to one of the constants defined for CIM_OperatingSystem.OSType.

operatingsystemversion

This read-only attribute specifies the version of the guest operating system used by the virtual image. The value of this attribute is a string and might be None if the OVA of the virtual image does not supply a value.

owner

A user object that references the owner of this virtual image. This attribute is an integer value. For more information about the properties and methods supported by user objects, enter the following command:

 >>> help(deployer.user)

parts

The parts that can be realized by this virtual image. You can also get help for deployer.parts, as shown in the following example:

>>> help(deployer.parts)

pmtype

The type of machine supported by this virtual image. This field contains a string value with a maximum of eight characters.

productids

This attribute specifies all of the product IDs associated with this virtual image.

servicelevel

The service level of the attribute. This field contains a string value with a maximum of 1024 characters.

updated

The time the virtual image was last updated, as number of seconds since midnight, January 1, 1970 UTC. When the virtual image is displayed, this value is shown as the date and time in the local time zone.

version

The version of the virtual image. This field contains a string value with a maximum of 1024 characters.

VirtualImage methods

The VirtualImage object has the following methods:

acceptLicense(licenses)

This method accepts the license presented by the virtual image. The IBM PureApplication System cannot use a virtual image until you have accepted its license. This method accepts a single optional parameter that allows you to specify which license for this virtual image is being accepted. The value for this parameter must be a Python dict object in which each key is a license collection ID for the virtual image. Each value is the license ID for the license to be accepted from that collection. If this parameter is not supplied, the appliance behaves as if an arbitrary license from each license collection has been accepted. The following example shows the usage of this method:

>>> myvi.acceptLicense({ 'collection1': 'license3', 'collection2': 'license17' })

For more information about virtual image licenses, enter the following command:

>>> help(deployer.virtualimage.license)

addProductid

Adds a new product ID to all the virtual image parts. This method accepts the following parameters:

productid

The product ID to add. This parameter is required.

licensetype

The license type for this product ID. Valid values are:

• PVU
• Server

The default value is PVU. This parameter is required.

licensecpu

The processor count limit for a server license. This parameter is required for the server license type.

licensememory

The memory limit in GB for a server license. This parameter is required for the server license type.

The following example shows the addProductid method:

>>> myimage[0].addProductid('5724-X89', 'PVU')
>>> myimage[0].addProductid('5724-X89', 'Server', 4, 32)

capture()

Captures a virtual image that was created by extending another virtual image. The virtual image is copied from the hypervisor where it is currently running back to the IBM PureApplication System and prepared for future deployments.

deleteProductid

Delete a product ID from all of the virtual image parts. This method accepts the following parameters:

productid

The product ID to delete. This parameter is required.

licensetype

The license type for this product ID. Valid values are:

• PVU
• Server

The default value is PVU. This parameter is required.

The following example shows the deleteProductid method:

>>> myimage[0].deleteProductid('5724-X89', 'PVU')

export (d)

This method starts the asynchronous process of exporting a virtual image to a remote appliance or a local directory. The various pieces of the image are extracted from the internal repository and used to generate an OVA file. This file is then copied to the given location, as shown in the following example:

>>> image = deployer.virtualimages[0]
>>> image.export({
          'host': 'example.com',
          'path': '/archive/images/',
          'userid': 'root',
          'password': 'secret'
       })

extend(d)

Extends this virtual image to create a new virtual image. The extension process begins by deploying the existing virtual image to the cloud. After login to the virtual machine and making any necessary changes, the capture() method is called on the new virtual image. The capture() method copies the virtual machine back to the IBM PureApplication System and prepares it for future deployments. This method accepts a single Jython dict object argument with the following keys:

cloud

A reference to the cloud to which the virtual image is being deployed for modifications. This key is required.

description

A string containing a description for the new virtual image. This key is optional. If it is not specified, the new virtual image description is empty.

name

A string containing a name for the new virtual image. This key is required.

password

A string containing the password to use for the deployed virtual image. This key is required.

version

A string specifying a version for the new virtual image. The value must be a sequence of dot-separated integers that are not negative values, as shown in the following examples:

• '1', '0.4' 
  

• '1.2.3.4'
  

This key is required.

hardware

A dictionary that specifies changes to the hardware resource definition of the images. The main resources that can change are disk sizes and number of network interfaces. This allows the user to increase the size of the specific disk in a virtual image during the extension process. For example:

 vi  = deployer.virtualimages("MyImage")
 hardware-params-to-resize-image = vi.hardware
 hardware.diskDetails[0].size = xyz where xyz is new size in bytes.
 ext = vi.extend({'name':'name of ext image', 'cloud':cloud-object-to-deploy-into,'password':'password for ext image', 'version':'version to assign to image','hardware': hardware-params-to-resize-image })

This method returns a VirtualImage object for the newly created virtual image. Use the waitFor() method on the new VirtualImage to determine when it has been deployed.

clone(d)

Clones a virtual image to create a new virtual image. This method accepts a single Jython dict object argument with the following keys:

description

A string containing a description for the new virtual image. This key is optional. If it is not specified, the new virtual image description is empty.

name

A string containing a name for the new virtual image. This key is required.

version

A string specifying a version for the new virtual image. The value must be a sequence of dot-separated integers that are not negative values, as shown in the following examples:

• '1', '0.4' 
  

• '1.2.3.4'
  

This key is required.

hardware

A dictionary that specifies changes to the hardware resource definition of the images. The main resources that can change are disk sizes and number of network interfaces. This allows the user to increase the size of the specific disk in a virtual image during the extension process. For example:

baseImage = deployer.virtualimages[1]
 
newImage = baseImage.clone({'name':'Medium DB image','version':'1.1','hardware':{"diskDetails": [{"size": 128849018880, "label": "disk1"}],'niccount': 1}})

This method returns a VirtualImage object for the newly created virtual image. Use the waitFor() method on the new VirtualImage to determine when it has been deployed.

You can control the users and user groups access to virtual images with the ACL object.

Virtual machines on the CLI

This topic provides a reference for administering virtual machines using the IBM PureApplication System W1500 CLI.

VirtualMachines object

A VirtualMachines object represents the collection of virtual machines within a virtual system instance on PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for virtual machines within a virtual system instance on PureApplication System.

Help is available on the CLI for theVirtualMachines object. To get help, pass the VirtualMachines object as an argument to the help() function, as shown in the following example:

>>> help(deployer.virtualmachines)

VirtualMachine object

A VirtualMachine object represents a particular virtual machine defined on the PureApplication System. Use the VirtualMachine object to query and manipulate the virtual machine definition on the PureApplication System. Attributes of the virtual machine are represented as Jython attributes on the VirtualMachine object. Relationships between the virtual machine and other resources on the IBM PureApplication System are also represented as Jython attributes on the VirtualMachine object. Manipulate these Jython attributes using standard Jython mechanisms to change to the corresponding data on the IBM PureApplication System.

Help is available on the CLI for the VirtualMachine object. To get help, pass the name of the object as an argument to the help() function, as shown in the following example:

>>> help(deployer.virtualmachine)

VirtualMachine attributes

The VirtualMachine object has the following attributes:

cpucount

The number of virtual processors defined for this virtual machine. This value is an integer.

created

The creation time of the virtual machine, as number of seconds since midnight, January 1, 1970 UTC. When the virtual machine is displayed, this value is shown as the date and time in the local timezone. This value is numeric and is automatically generated by the system.

currentmessage

The message associated with the status of the virtual machine. This field contains an eight character string value that is generated by the system.

currentmessage_text

Textual representation of the currentmessage attribute. This attribute is a string representation of the currentmessage attribute in the preferred language of the requester. This status message is automatically generated by the system.

currentstatus

The status of the virtual machine. This field contains an eight character string value that is generated by the system.

currentstatus_text

Textual representation of the currentstatus attribute. This attribute is a string representation of the currentstatus attribute in the preferred language of the requester. This status message is automatically generated by the system.

desiredstatus

The intended status of the virtual machine. This field contains an eight character string value that is generated by the system.

displayname

The display name associated with this virtual machine in the hypervisor. This field contains a string value with a maximum of 1024 characters.

environment

The environment property shows the environment variables defined on the virtual machine. The value of this property is a Jython dictionary (dict) object.

This dict object is intended only for reading. Nothing prevents updates to the dict object, but updates are not sent back to the PureApplication System. Therefore, updates have no effect on the virtual machine.

hardware

The hardware details for the virtual machine.

hypervisor

A reference to the hypervisor on which this virtual machine is running. For more information on the properties and methods supported by Hypervisor objects, enter:

>>> help(deployer.hypervisor)

If the hypervisor has been put in quiesce mode, the virtual machine can be migrated to a new hypervisor by assigning a new Hypervisor to this attribute, as shown in the following example:

>>> assert myvm.hypervisor.isQuiesced()
>>> myvm.hypervisor = newhypervisor

A list of suitable hypervisors can be obtained using the migrationtargets attribute of the virtual machine. Setting the hypervisor attribute to None causes PureApplication System to select a new hypervisor for the virtual machine.

hypervisormachineid

ID assigned to the virtual machine by the hypervisor. This field contains a string value with a maximum of 1024 characters.

id

The ID of the virtual machine. This value is numeric and is automatically generated by the system.

ip

A reference to the IP address used by this virtual machine. For more information about the properties and methods supported by IP objects, see IP CLI reference or enter the following command:

>>> help(deployer.ip)

ips

A reference to the IP addresses assigned to this virtual machine. See IP CLI reference or enter the following command:

>>> help(deployer.ip) 

memory

The amount of memory allocated to this virtual machine, in megabytes. This value is an integer.

migrationtargets

A list of hypervisors to which the virtual machine can be migrated. A value of None indicates that the hypervisor hosting the virtual machine has not been quiesced. An empty list indicates no suitable hypervisors were found. The returned list is mutable, but changes to the list have no effect.

name

The display name associated with this virtual machine. This field contains a string value with a maximum of 1024 characters.

runtimeid

The runtime ID generated by the hypervisor on which this virtual machine is running. This field contains a string value with a maximum of 1024 characters.

scripts

The scripts that have been run on the virtual machine, both during and after deployment.

storageid

The hypervisor storage ID of the storage on which this virtual machine resides. This field contains a string value with a maximum of 1024 characters.

updated

The time the virtual machine was last updated, as number of seconds since midnight, January 1, 1970 UTC. When the virtual machine is displayed, this value is shown as the date and time in the local timezone. This value is numeric and is automatically generated by the system.

virtualimage

A reference to the VirtualImage object from which this virtual machine originated. See Virtual images CLI reference or enter the following command:

 >>> help(deployer.virtualimage)

virtualsystem

A VirtualSystem object that references the virtual system instance to which this virtual machine belongs. For more information about the properties and methods supported by VirtualSystem objects enter the following command:

>>> help(deployer.virtualsystem)

VirtualMachine methods

The VirtualMachine object has the following methods:

delete

Deletes the resource represented by this object.

start()

Starts a virtual machine.

stop()

Stops a virtual machine. The virtual machine continues to reserve the resource used by that virtual machine.

You can control user and user group access to virtual system instances using the ACL object.

Virtual system instances CLI reference

This topic provides a reference for administering virtual system instances using the IBM PureApplication System W1500 CLI.

VirtualSystems object

A VirtualSystems object represents the collection of virtual system instances defined to the IBM PureApplication System. Objects of this type are used to create, delete, iterate over, list and search for virtual system instances on the IBM PureApplication System.

Help is available on the CLI for the VirtualSystems object. To get help, pass the VirtualSystems object as an argument to the help() function, as shown in the following example:

>>> help(deployer.virtualsystems)

VirtualSystems methods

The VirtualSystems object has the following method:

create

Creates a virtual system instance based on a pattern. This method accepts a single parameter that describes the virtual system instance to be created. This parameter can be any of the following:

• A dictionary (dict) object with the required and optional keys, as shown in the following example:

       >>> deployer.virtualsystems.create({'name': 'my virtual system',
      ...   'cloud': myCloud, 'pattern': thepattern,
      ...   '*.*.password': 'mypassword'})  
  

  If a dict object is supplied, the following keys are recognized:

  endtime

  The time at which the virtual system instance is stopped, expressed as the number of seconds since midnight, January 1, 1970 UTC. See the description of the starttime method for additional details. This key is optional. If it is not specified, the virtual system instance runs until it is manually stopped.

  environmentprofile

  A reference to the EnvironmentProfile object that specifies the environment profile to be used for the virtual system instance. See deployer.environmentprofiles help for more information about obtaining an EnvironmentProfile object. Either this key or the cloud key is required. If this key is specified, the supplied dict object must also include additional information. The dict object must include the cloud groups, IP groups, IP address, and host names to be used for deployment.

  name

  The name for the virtual system instance as a string. This key is required.

  pattern

  A reference to the Pattern object for the new virtual system instance. See deployer.patterns help for more information about obtaining a Pattern object. This key is required.

  starttime

  The time at which the virtual system instance is started, expressed as the number of seconds since midnight, January 1, 1970 UTC. This value is most easily obtained using the Jython time module, particularly the time.time() and time.mktime() functions, as shown in the following example:

           >>> # April 15th, 2009, 7am local time          >>> time.mktime((2009,4,15,7,0,0,0,0,-1))
           >>> # 1 hour (3600 seconds) from now
           >>> time.time() + 3600     
  

  This key is optional. If it is not specified, the IBM PureApplication System attempts to start the virtual system instance immediately.

  The dict object can also supply additional keys that specify the values for part properties and script parameters required by the pattern. The set of required properties and parameters depend on the pattern. Some patterns might supply default values for all properties and parameters, in which case no additional values are needed. If the pattern you specified requires properties or parameters that you have not specified, this method raises an exception. The exception indicates which additional properties and parameters require values. You can also use the listConfig() method on the pattern object to determine which part properties and script parameters the pattern recognizes.

  To specify a value for a part property, use a key in the following format:

  part-<part_id>.<property_pclass>.<property_key>
  

  The following example shows this format:

  { ..., 'part-1.ConfigPWD_ROOT.password': 'mypassword', ... }
  

  Parameters for scripts are specified using a similar syntax, as the following example shows:

  part-<part_id>.script-<script_id>.<parameter_key>
  

  The following example shows this format:

  { ..., 'part-1.script-1.NUM_WIDGETS': '10', ... }
  

  For both part properties and script parameters, any of the three pieces of the key can be an asterisk (*) to match any value for that piece. See the following examples:

  part-1.ConfigPWD_ROOT.password

  Value for the root password on the part with ID 1.

  *.ConfigUSER_ROOT.password

  User password for all the parts.

  part-3.*.password

  Specifies a value to be used for all the passwords for part 3, including any script parameters that have a key of password.

  *.*.password

  Specifies a value to be used for all part properties and script parameters with a key of password.

  *.*.*

  Specifies a value to be used for all part properties and script parameters. This idiom is handled by the CLI, but it is rarely useful.

  If more than one key in the dict object can be used for a given part property or script parameter, the most specific matching key is used. A key with a wildcard closer to the end is considered less specific. For example, when attempting to discover a value for part-1.ConfigPWD_ROOT.password, the dict keys are considered in the following order:

  1. part-1.ConfigPWD_ROOT.password
  2. *.ConfigPWD_ROOT.password
  3. part-1.*.password
  4. *.*.password
  5. part-1.ConfigPWD_ROOT.*
  6. *.ConfigPWD_ROOT.*
  7. part-1.*.*
  8. *.*.*

  If an environment profile is used for the deployment, the dict object must include specific information. The dict object must include information about the cloud groups and IP groups to be used for each part in the pattern. If the environment profile specifies that the IP addresses are to be specified by the person deploying the pattern, then the dict object must specify additional information. The dict object must also include IP addresses for each part and can also include host names for each part. This information is supplied in the dict object using a syntax like that described for part properties and script parameters. The following conventions are used for these keys:

  part-<part_id>

  Indicates the part to which the information applies, as with part properties and script parameters.

  vm-<vm_number>

  For group parts, indicates a particular virtual machine to be built when the part is deployed. The vm_number must be in the range [1..part.count], inclusive. For example, if a group part has a count value of 5 then the virtual machines are designated vm-1 through vm-5. For parts that do not belong to a group, part.count is None, vm_number must always be 1. A single virtual machine is designated vm-1.

  nic-<nic_number>

  Indicates a particular network interface on the virtual machine. All parts have at least one network interface, designated nic-1. Additional network interfaces are designated in numeric order, for example nic-2 and nic-3, if additional NIC add-ons have been added to the part. The network interfaces are ordered the same as the corresponding add-on pattern scripts in part.scripts.

  The following keys in the dict object are used as the source of environment profile deployment data:

  part-<part_id>.cloud

  Specifies a Cloud object for the cloud group to be used for the part. The cloud group must be associated with the environment profile.

  If a part represents a group of virtual machines, all virtual machines must be in the same cloud group.

  part-<part_id>.vm-<vm_number>.nic-<nic_number>.ipgroup

  IPGroup object to be used for the network interface. The IP group must be associated with the cloud group in the environment profile.

  part-<part_id>.vm-<vm_number>.nic-<nic_number>.ipaddress

  If the environment profile indicates that the user deploying the pattern is to supply IP addresses, this key is used to supply the IP address, or addresses, to be used for the network interface.

  part-<part_id>.vm-<vm_number>.nic--<nic_number>.hostname

  This key behaves like the IP address key, but it is used to provide host names. Unlike IP addresses, host names are never required. The semantics and syntax for single and multiple values are identical to IP addresses. As with part properties and script parameters, an asterisk (*) can be used to specify a value that applies to more than one part, as shown in the following example:

  { ..., \n
       'environmentprofile': myenvpro,
       '*.cloud': mycloud,            # all parts to one cloud      '*.*.nic-1.ipgroup': ipgroup1, # all built-in intfs to ipgroup1
       'part-1.vm-1.nic-1.ipaddress: '1.2.3.4',
       'part-1.vm-2.nic-1.ipaddress: '1.2.3.5',
       'part-3.vm-1.nic-1.ipaddress: '1.2.3.6',
       'part-3.*.nic-2.ipgroup': ipgroup2, # extra nic goes to ipgroup2
       'part-3.vm-1.nic-2.ipaddress': '5.6.7.8'
       'part-3.vm-1.nic-2.hostname': 'foo.mycompany.com',
       ... }
  

• The name of a file containing a Jython expression that evaluates to one of the values in this list.
• The value deployer.wizard or a wizard instance created by calling deployer.wizard(). If either of these values is supplied, the CLI prompts interactively for the values to create the virtual system instance.
• A list of any of the items previously listed, in which case multiple virtual system instances are created, as shown in the following example:

  >>> deployer.virtualsystems.create(['vs1', {'name':'foo',...}])
  

VirtualSystem object

A VirtualSystem object represents a particular virtual system instance defined on PureApplication System. Use the VirtualSystem object to query and manipulate the virtual system instance definition on the IBM PureApplication System. Attributes of the virtual system instance and relationships between the virtual system instance and other resources on the IBM PureApplication System are represented as Jython attributes on the VirtualSystem object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding data on the IBM PureApplication System.

To get help on the CLI for the VirtualSystem object, pass the VirtualSystem object as an argument to the help() function, as shown in the following example:

>>> help(deployer.virtualsystem)

VirtualSystem Attributes

The VirtualSystem object has the following attributes:

acl

The access control list for this virtual system instance. This field is read-only. For additional help on using this object, enter the following command:

     >>> help(deployer.acl)

created

The creation time of the virtual system instance, as number of seconds since midnight, January 1, 1970 UTC. When the virtual system instance is displayed, this value is shown as the date and time in the local time zone. This read-only value is numeric and is automatically generated by the system.

currentmessage

The message associated with the status of the virtual system instance. This read-only attribute has an eight character string value that is automatically generated by the system.

currentmessage_text

Textual representation of the currentmessage attribute. The currentmessage_text attribute is a string representation of the currentmessage attribute in the preferred language of the requester. The currentmessage attribute is automatically generated by the system.

currentstatus

The status of the virtual system instance. This read-only attribute has an eight character string value that is automatically generated by the system.

currentstatus_text

Textual representation of the currentstatus attribute. The currentstatus_text attribute s a string representation of the currentstatus attribute in the preferred language of the requester. The currentstatus_text attribute is automatically generated by the system.

desiredstatus

Indicates the status in which you want the virtual system instance to be. Setting this value causes PureApplication System to initiate the steps to get the virtual system instance to this state.

desiredstatus_text

Textual representation of the desiredstatus attribute. The desiredstatus_text attribute is a string representation of the desiredstatus attribute in the preferred language of the requester. The desiredstatus_text attribute is automatically generated by the system.

environmentprofile

An environment profile object that references the profiles used to create this virtual system instance.

     >>> help(deployer.environmentprofile)

id

The ID of the virtual system instance. This value is numeric and is automatically generated by the system. This field is read-only.

maintenances

A resource collection containing the fixes applied to this virtual system instance.

>>> help(deployer.maintenances)

name

The name associated with this virtual system instance. Each virtual system instance must have a unique name. This field contains a string value with a maximum of 1024 characters. When a virtual system instance is created, its name cannot be changed. This field is read-only.

owner

A User object that references the owner of this virtual system instance.

>>> help(deployer.user)

pattern

A reference to the Pattern object from which this virtual system instance was created.

>>> help(deployer.pattern)

snapshots

A resource collection containing the snapshots taken of this virtual system instance.

>>> help(deployer.snapshots)

updated

The time the virtual system instance was last updated, as number of seconds since midnight, January 1, 1970 UTC. When the virtual system instance is displayed, this value is shown as the date and time in the local time zone. This value is numeric and is automatically generated by the system. This field is read-only.

virtualmachines

A resource collection containing the virtual machines within this virtual system instance.

>>> help(deployer.virtualmachines)

VirtualSystem methods

The VirtualSystem object has the following methods:

applyFixes(fixes, start=0)

This method creates a maintenance request using the list of fixes provided and an optional start time. The fixes are applied in the order they are shown in the list. If no start time is provided, the fixes are applied immediately.

>>> fixes = vs.findFixes()
>>> vs.applyFixes(fixes)  # start right now
>>> vs.applyFixes(fixes, time() + 360000)  # start in an hour

applyUpgrade(image, start=0):

Creates a maintenance request using the virtual image name provided and an optional start time. If no start time is provided, the image upgrade is applied immediately.

>>> images = vs.findUpgrades()
>>> vs.applyUpgrade(images[0])                   # start right now
>>> vs.applyUpgrade(images[0], time() + 360000)  # start in an hour

createSnapshot()

Creates a snapshot of this virtual system instance. This method takes an optional dictionary that can contain a description for the snapshot.

delete()

Deletes the virtual system instance. This method accepts the following optional parameters:

deleteRecord

This boolean parameter controls whether records and logs associated with the virtual system instance are left on the system after the virtual system instance is deleted. The default value, True, deletes all information associated with the virtual system instance. A value of False leaves those records on the system for future inspection.

ignoreErrors

This boolean parameter controls whether the system continues attempting to delete a virtual system instance after an error is encountered. The default value, False, causes the attempted delete to fail if an error is encountered.

Supply values for these parameters using Python named arguments, as shown in the following example:

>>> myvirtsystem.delete(ignoreErrors=True, deleteRecord=False)

CAUTION:

Use the ignoreErrors parameter is helpful in specific situations only, so use this option with caution. You might know that the virtual machines cannot be deleted and you choose to clean them up manually, for example. Or you might know that the server hosting the virtual machine is no longer available. Therefore, deletion would not occur if the errors blocked it. You can use the ignoreErrors parameter in these circumstances to force deletion of a virtual system instance, even if the virtual machines cannot be deleted.

findFixes()

This method returns the list of fixes that can be applied to this virtual system instance. When a fix has been applied to a system, it is no longer displayed in this list.

findUpgrades()

This method returns the list of virtual image upgrades that can be applied to this virtual system instance. When a system has been upgraded, the image, and any of its predecessors, are no longer displayed in this list.

start()

Starts this virtual system instance.

stop()

Stops this virtual system instance.

store()

Stores this virtual system instance.

You can control user and user group access to virtual system instances using the ACL object.

Snap shots on the CLI

Use this information as a reference for administering snap shots of virtual system instances using the IBM PureApplication System W1500 CLI.

Snapshots object

A Snapshots object represents the collection of snapshots taken for a particular virtual system instance. Objects of this type are accessed using the snapshots property of the VirtualSystem object in which they are contained, as shown in the following example:

>>> myvs = deployer.virtualsystems['my virtualsystem'][0]
>>> myvs.snapshots

Objects of this type are used to create, delete, iterate over, list and search for snapshots on the system.

Snapshots are created, as shown in the following example:

VirualSystem.createsnapshot()

The following example accesses snapshots:

VirtualSystem.snapshots

To get help on the CLI for the snapshots object, pass the name of the object as an argument to the help() function. See the following example:

>>> help(deployer.snapshots)

Snapshot object

A Snapshot object represents a particular snapshot defined on the system. Use the Snapshot object to query and manipulate the snapshot definition on the system. Attributes of the Snapshot object are represented as Jython attributes on the Snapshot object. Relationships between the Snapshot object and other resources on the system are also represented as Jython attributes on the Snapshot object. Manipulate these Jython attributes using standard Jython mechanisms to change the corresponding data on the system.

Help is available on the CLI for the Snapshot object. To get help, pass the Snapshot object as an argument to the help() function, as shown in the following example:

>>> help(deployer.snapshot)

The Snapshot object has the following method:

restore()

Restores this snapshot.

The Snapshot object has the following attribute:

virtualsystem

A VirtualSystem object that references the virtual system instance to which this Snapshot object belongs. For more information about the properties and methods supported by VirtualSystem objects, enter the following command:

>>> help(deployer.virtualsystem)

10. Resources, resource collections, and methods

A IBM PureApplication System W1500 manages different types of resources, for example hypervisors, patterns, virtual images, and virtual system instances. Within the CLI, Jython objects are used to represent these resources and collections of these resources. Methods control the behavior of the Jython objects.

An individual resource managed by a IBM PureApplication System is represented in the CLI by a Jython object. This object has the same attributes as the PureApplication System resource on the graphical interface, with some additional methods and attributes to make it simpler to work with in the CLI environment. Help is available for resource objects, in general, and for each type of resource. You can get help for resources by entering the following command:

>>> help(deployer.resource)

There are additional Jython objects that represent collections of resources within the PureApplication System. These resource collections (Jython objects) can be used to perform actions such as creating a resource or searching for an existing resource. Help is available for resource collection objects, in general, and for each type of resource collection. You can get help for resource collections by entering the following command:

>>> help(deployer.resourcecollection)

Methods on the Jython objects support the operations that can be performed on the resource within the IBM PureApplication System. When you call one of these methods within the CLI tool, the request is sent over HTTPS to the IBM PureApplication System where it is run. The result passes back over the HTTPS connection to the CLI tool and is shown in one of the following ways:

• As return values from the methods
• As an updated state in the Jython objects
• As Jython exceptions (if the result indicates an error condition)

All Jython classes, objects, and fields within the CLI are documented using standard Jython doc strings. The help() function provided in the CLI can be used to display the doc strings, as shown in the following examples:

>>> help(deployer.ipgroups)
An IPGroups object represents the collection of IP groups defined to the PureApplication System.  Objects of this type are used to create, delete, iterate over, list and search for IP groups on the system.
 
Additional help is available for the following methods:
   __contains__, create, delete, __delitem__, __getattr__, __getitem__,
   __iter__, __len__, list, __lshift__, __repr__, __rshift__, __str__,
   __unicode__

>>> help(deployer.ipgroup) 
An IPGroup object represents a particular IP group defined on the PureApplication System.  Use the IP group object to query and manipulate the IP group definition on the PureApplication System.  Attributes of the IP group and relationships between the IP group and other resources on the PureApplication System are represented as Jython attributes on the IPGroup object.  Manipulate these Jython attributes using standard Jython mechanisms to make changes to the corresponding data on the PureApplication System.
 
Additional help is available for the following methods:
   __contains__, __delattr__, delete, __eq__, __hash__, isStatusTransient,
   __nonzero__, refresh, __repr__, __str__, __unicode__, waitFor
 
Additional help is available for the following properties:
   created, gateway, id, ips, name, netmask, networks, primarydns,
   secondarydns, subnetaddress, updated
 
Remember to append an underscore to the property name when asking for help using a specific instance of a resource rather than the class.
For example, "help(deployer.pattern.name)" or "help(mypattern.name_)"
will work, but "help(mypattern.name)" will resolve the name of the pattern referenced by mypattern and attempt to provide help for the resulting
string rather than the property itself.

>>> help(deployer.ipgroup.subnetaddress)
Subnet address associated with the IP group, represented as a string in dotted decimal notation ('192.168.98.0', for example).

Resources, resource collections, and methods are explained more thoroughly in the following information:

10.1. Resources on the command line

Any IBM PureApplication System W1500 functional object is a resource object on the CLI. Within the CLI, Jython objects are used to represent these resources. The CLI manages different types of resources, for example hypervisors, patterns, virtual images, and virtual system instances.

The CLI uses resources to represent discrete objects managed by the IBM PureApplication System. For example, a particular hypervisor, the WebSphere Application Server single server pattern, and the virtual system instance you started yesterday would each be a resource.

A resource has a number of properties that describe it. Properties are used to describe not only the attributes of the resource, such as its name or the time it was created, but also its relationships to other resources. For example, many types of resources have an owner property the value of which is the resource representing the user that owns the resource. The following simple example shows a resource:

>>> deployer.self()
{
  "currentmessage": "RM02012",
  "currentmessage_text": "Inactive for more than five minutes",
  "currentstatus": "RM01062",
  "currentstatus_text": "Inactive",
  "email": "",
  "fullname": "Administrator",
  "groups": (nested object),
  "id": 1,
  "parts": (nested object),
  "password": (write-only),
  "patterns": (nested object),
  "roles": (nested object),
  "scripts": (nested object),
  "username": "cbadmin",
  "virtualimages": (nested object),
  "virtualsystems": (nested object)
}

When displayed as a string, the properties of a resource are always shown within curly brackets. In the previous example, the deployer.self() function returns a single user resource that represents the current user. The following properties have simple string or numeric values:

• currentmessage
• currentmessage_text
• currentstatus
• currentstatus_text
• email
• fullname
• id
• username

The password property has a special value that indicates it can be written to, but not displayed. The remaining properties all have a value of '(nested object)' that indicates they have complex values which are not suitable for displaying, either because doing this would require time-consuming data retrieval from the server or because doing so would generate too much text. In the previous example, all these additional properties are references to other resources or resource collections.

Resources are Jython objects and they can be used such as other Jython objects. Jython variables can hold references to resource objects, as shown in the following example:

   >>> me = deployer.self()

The properties of the object can be read using the Jython dot operator, as shown in the following example:

>>> me.fullname
'Administrator'
>>> me.id
1L

The properties of the object can be similarly updated, as shown in the following example:

   >>> me.email
   ''
   >>> me.email = 'myemail@mycompany.com'
   >>> me.email
   'myemail@mycompany.com'

When you update a resource, the change is immediately sent to the IBM PureApplication System.

The CLI keeps a local cache of the properties of the resource that are not relationship-based. This cache is automatically refreshed whenever any of these properties are updated, and can be manually refreshed at any time using the refresh() method.

If you try to perform operations not allowed by the PureApplication System, a Jython exception is raised, as shown in the following example:

   >>> me.id = 143
   Traceback (innermost last):
     File "<console>", line 1, in ?
   AttributeError: can't set attribute 

Some errors are detected by the CLI and others are detected by the IBM PureApplication System.

If you need more information about a particular resource, you can pass the resource to the CLI help function, as shown in the following example:

   >>> everyone = deployer.everyone()
   >>> help(everyone)

To get help for a property of a resource object, append an underscore to the property name, as shown in the following example:

   >>> help(everyone.created_)

Most resources defined to PureApplication System automatically track the time and date they were created and last modified. Within the IBM PureApplication System, these timestamps are tracked as the number of milliseconds since January 1, 1970 UTC. Because the Jython time and date libraries define timestamps as the number of seconds since this epoch, the CLI code converts the number of milliseconds returned from the IBM PureApplication System to seconds. The CLI formats these timestamps in the local timezone whenever a string representation is generated for a resource object. The following example retrieves the first ipgroup resource and displays the created property for it, then the entire object is displayed from the interactive mode:

>>> ipg = deployer.ipgroups[0]
>>> ipg.created
1.242243975898E9
>>> ipg
{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 13, 2009 3:46:15 PM
}

Many types of PureApplication System resources also have status attributes that reflect the current and intended status of the resource. The IBM PureApplication System manages these status values and automatically adds an additional attribute with _text appended to the name and containing a textual representation of this status, as shown in the following example:

>>> ipg.ips[0].currentstatus
'RM01017'
>>> ipg.ips[0].currentstatus_text
'Inactive'

There are different types of relationships among the types of resources defined to a IBM PureApplication System. When an individual resource is related to other resources, additional attributes are added to the resource object pointing to the related resource objects. If the relationship is to a single other resource, the attribute is named the same as the type of other resource (singular) and its value is the other resource object. If the relationship is to multiple other resources, the name of the attribute is the type of the other resource (plural) and its value is a resource collection. In the following example, the relationship between an IP group and the IP addresses it contains is represented by the ips property on the IP group object.

>>> ipg = deployer.ipgroups[0]
>>> ipg
{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 13, 2009 3:46:15 PM
}
>>> ipg.ips
[
  {
    "created": May 13, 2009 3:47:54 PM,
    "currentmessage": None,     "currentmessage_text": None,     "currentstatus": "RM01017",
    "currentstatus_text": "Inactive",
    "id": 5,
    "ipaddress": "10.1.2.3",
    "ipgroup": (nested object),
    "updated": May 13, 2009 3:47:54 PM
  },
  {
    "created": May 13, 2009 3:47:54 PM,
    "currentmessage": None,     "currentmessage_text": None,     "currentstatus": "RM01017",
    "currentstatus_text": "Inactive",
    "id": 6,
    "ipaddress": "10.1.2.4",
    "ipgroup": (nested object),
    "updated": May 13, 2009 3:47:54 PM
  }
]

In the previous example the value of the ips property is a list of IP address objects.

Conversely, an IP address is related to a single IP group. This relationship is represented by the ipgroup property on the IP object, as shown in the following example:

>>> ip = ipg.ips[0]
>>> ip
{
  "created": May 13, 2009 3:47:54 PM,
  "currentmessage": None,   "currentmessage_text": None,   "currentstatus": "RM01017",
  "currentstatus_text": "Inactive",
  "id": 5,
  "ipaddress": "10.1.2.3",
  "ipgroup": (nested object),
  "updated": May 13, 2009 3:47:54 PM
}
>>> ip.ipgroup
{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 13, 2009 3:46:15 PM
}

10.2. Resource collections on the command line

A IBM PureApplication System W1500 manages different types of resources, for example hypervisors, patterns, virtual images, and virtual system instances. These resources can be collected into groups of like objects called resource collections. Within the CLI, Jython objects are used to represent these resource collections.

Resource collections are Jython objects that represent collections of PureApplication System resources which have a specific characteristic in common. Resource collections can be used to perform actions such as creating new resources, deleting resources, listing resources, or searching for an existing resource. The CLI uses many different types of resource collections, but they fall into two broad categories.

The first type of resource collection corresponds roughly to the top-level resources in PureApplication System. These are the resource types you can select directly when using the PureApplication System console. These types of resource collections are accessed directly with objects defined in the PureApplication System Jython package.

The second type of resource collection represents collections of resources defined by a relationship with another resource. For example, all the virtual machines contained within a virtual system instance, the users in a user group, or the set of hypervisors attached to a particular storage device. These resource collections are accessed with properties on the resource object that anchors the relationship. The resource collections from the previous examples are accessed using the virtualmachines property of a virtual system instance resource, the users property of a group resource, and the hypervisors property of a storage resource.

Regardless of the type, resource collections all share the same basic ability to list and search for resources within the collection. One important difference between the types of resource collections is the semantics of their create or add and delete or remove operations:

• Top-level resource collections have create and delete operations. Create defines a resource to PureApplication System that did not exist previously. Similarly, delete completely erases a resource from PureApplication System.
• Relationship-based resource collections have both add operations and remove operations. Add causes an existing resource to be included in the resource collection. Remove takes the resource out of the collection. The resource must exist before being added to the collection and it continues to exist after it has been removed.

The resource collections you are most likely to use are the resource collections that represent all resources of a given type, for example all patterns, or all IP groups. These resource collections are available as attributes on the PureApplication System package, as shown in the following example:

>>> deployer.ipgroups
[
  {
   "created": May 13, 2009 3:46:15 PM,
   "gateway": "10.0.0.1",
   "id": 2,
   "ips": (nested object),
   "name": "ten",
   "netmask": "255.0.0.0",
   "networks": (nested object),
   "primarydns": "10.0.0.2",
   "secondarydns": "10.0.0.3",
   "subnetaddress": "10.0.0.0",
   "updated": May 13, 2009 3:46:15 PM
  },
  {
   "created": May 13, 2009 4:51:02 PM,
   "gateway": "",
   "id": 4,
   "ips": (nested object),
   "name": "192.168.0.0",
   "netmask": "255.255.255.0",
   "networks": (nested object),
   "primarydns": "192.168.0.1",
   "secondarydns": "",
   "subnetaddress": "192.168.0.0",
   "updated": May 13, 2009 4:51:02 PM
  }
]

The PureApplication System package defines one of these types of resource collections for each type of resource that PureApplication System manages. The previous example also shows another type of resource collection. When a resource is related to other resources of a given type, the resources to which it is related are represented as a resource collection. In the previous output, for example, the networks attribute on each IP group represents the networks attached to the IP group and the ips attribute represents the IP addresses defined within the IP group. These types of resource collections can only be accessed through a resource object.

10.3. Resource methods on the CLI

All IBM PureApplication System W1500 resources share methods that can be used to work with resource objects.

Purpose

This topic describes the methods shared by all PureApplication System resources.

The help for each type of resource indicates what methods and properties are defined for that type of resource. To get additional help on a particular method, use the help function with the method name appended to the resource in one of the following ways:

• You can use the generic type of the resource, as shown in the following example:

  >>> help(deployer.group)
  >>> help(deployer.group.refresh)
  

• You can use a specific resource instance, as shown in the following example:

  >>> everyone = deployer.everyone()
  >>> help(everyone)
  >>> help(everyone.refresh)
  

Do not put parentheses after the method name, for example help(everyone.refresh()). This format causes the method to be invoked and the help function attempts to provide help about whatever value the method returned instead of the function method itself.

The provided examples assume the following IP groups are defined:

>>> ipg = deployer.ipgroups[0]
>>> ipg
{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 13, 2009 3:46:15 PM
}

Properties

Each PureApplication System resource is represented by a Jython object in the CLI. Attributes of the resource are represented as properties of the Jython object and can be accessed and updated using the typical Jython mechanisms. Use the Jython dot operator or built-in getattr() function to obtain the value of a property, as shown in the following example:

>>> ipg.name
'ten'
>>> getattr(ipg, 'name')
'ten'

The Jython dot operator or built-in setattr() function can be used to update the value of a property, as shown in the following example:

>>> ipg.primarydns = '10.0.0.10'
>>> ipg.primarydns
'10.0.0.10'
>>> setattr(ipg, 'name', 'new name for ten')
>>> ipg.name
'new name for ten'

The Jython built-in hasattr() function can be used to determine if a resource has a given property, as shown in the following example:

>>> hasattr(ipg, 'netmask')
1
>>> hasattr(ipg, 'undefinedproperty')
0

Different types of resources have different properties defined.

Methods

PureApplication System resource methods include:

__contains__(item)

Indicates if this resource object has a value for the specified attribute. This method is invoked implicitly by the Jython in operator, as shown in the following example:

>>> 'address' in ipg
1
>>> 'foo' in ipg
0

__delattr__(name)

Removes an attribute for this resource on the IBM PureApplication System. The update is sent immediately to the PureApplication System and the cached attributes are updated if the request is successful. This method is invoked implicitly by the Jython del operator, as shown in the following example:

>>> ipg 
{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 13, 2009 3:46:15 PM
}
>>> del ipg.secondarydns
>>> ipg
{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": None,   "subnetaddress": "10.0.0.0",
  "updated": May 14, 2009 10:11:27 AM
}

delete()

Deletes a resource from the IBM PureApplication System, as shown in the following example:

>>> ipg in deployer.ipgroups
1
>>> ipg.delete()
>>> ipg in deployer.ipgroups
0

__eq__(other)

Indicates if another resource object represents the same resource as this object.

This method tests if the two objects see the same resource on the IBM PureApplication System. It does not check for a match between the cached attributes of the two objects. This method is invoked explicitly for the Jython == operator and other situations in which Jython determines if two objects are equal, as shown in the following example:

>>> ipg == deployer.ipgroups[0]
1
>>> ipg == deployer.ipgroups[1]
0

__hash__()

Called implicitly by Jython when a resource object is used as a key in a dictionary (dict) or when the built-in hash() function is called with a resource object. This method returns a hash value for the resource.

If two resource objects represent the same resource, the __hash__() functions always return the same value. You cannot make any other assumptions about the value returned by this function. The __hash__() function is shown in the following example:

>>> hash(ipg)
1929121056

isStatusTransient()

Indicates if the currentstatus of this resource is transient. A status is considered transient if PureApplication System eventually brings the resource out of this state without any user interaction. This method is invoked with no parameters and returns the True or False values.

If the resource object does not have a currentstatus property, an exception is raised.

This method examines the cached value of the currentstatus property.

If you are polling the object to check its status, then use the refresh() method to update the currentstatus from the PureApplication System, as shown in the following example:

>>> while myvirtualsystem.refresh().isStatusTransient():
...     time.sleep(5)

Alternatively, use the waitFor() method. The waitFor() method encapsulates the refresh() and isStatusTransient() idiom into a single call.

__nonzero__()

Called implicitly by Jython when a resource object is used in a boolean context, this method always returns True, as shown in the following example:

>>> if ipg:
...     print 'true'
... else:
...     print 'false'
... 
true

refresh()

Updates the attributes of a resource. To reduce network traffic, the CLI caches a local copy of the attributes, but not the relationships, of a resource. Use this method to update resource attributes with current data from the IBM PureApplication System, as shown in the following example:

>>> ipg.gateway
'10.0.0.1'
 
(change ipgroup gateway from a different CLI or GUI)
 
>>> ipg.gateway
'10.0.0.1'
>>> ipg.refresh()
{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.43",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": None,   "subnetaddress": "10.0.0.0",
  "updated": May 14, 2009 10:27:23 AM
}
>>> ipg.gateway
'10.0.0.43'

__repr__()

This method is invoked implicitly by Jython when an expression entered in interactive mode returns a resource object or when a resource object is passed to the Jython repr() function. It returns a representation of the resource, as shown in the following example:

>>> ipg
{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 26, 2009 10:15:56 PM
}

__str__()

Returns a string representation of this resource. Attributes representing other resources or resource collections are shown as (nested object) to avoid recursive loops. Attributes representing timestamps are automatically formatted in the local time zone. This method is called implicitly when a resource is printed, for example if a Jython expression entered in interactive mode returns a resource. It can also be invoked explicitly by passing a resource collection to the Jython str() function.

>>> ipg                          
{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 14, 2009 10:33:17 AM
}

__unicode__()

Returns a Jython Unicode string containing a string representation of the resource. This method is called implicitly when a resource object is passed to the Jython unicode() function or used in a context that requires a Unicode string, as shown in the following example:

>>> unicode(ipg)
u'{\n  "created": May 13, 2009 3:46:15 PM,\n  "gateway": "10.0.0.1",\n  "id": 2,\n  "ips": (nested object),\n  "name": "ten",\n  "netmask": "255.0.0.0",\n  "networks": (nested object),\n  "primarydns": "10.0.0.2",\n  "secondarydns": "10.0.0.3",\n  "subnetaddress": "10.0.0.0",\n  "updated": May 26, 2009 10:15:56 PM\n}'

waitFor(condition, maxWait, interval)

The waitFor() method can be used to wait until a certain condition is true for a particular resource. It accepts the following parameters:

condition

An optional object that can be called. The waitFor() method calls this object periodically until it returns a value that evaluates to true. The object that is called accepts the resource object as its only parameter. If it is not specified, the following example shows the default value:

lambda r: not r.refresh().isStatusTransient()

That is, the default behavior is to refresh the cached properties of the resource, and wait until the resource enters a non-transient state.

This default value is only useful for resources that have a currentstatus property. For other types of resources, you must override the default condition with one of your own.

maxWait

The maximum amount of time to wait, in seconds, for the specified condition to become true. Fractional seconds can be specified by supplying a floating point value. A negative value causes this method to wait indefinitely. The default value is -1.

interval

The interval at which to check the specified condition. The interval is specified in seconds. Fractional seconds can be specified by supplying a floating point value. The default value is 10, which causes the condition to be evaluated once every 10 seconds.

The waitFor() method returns the value returned by the condition the last time it was invoked. Arbitrary conditions can be supplied to this method, but it is most often used to make a script wait for completion of a long-running background process in PureApplication System, such as importing a virtual image or deploying a virtual system instance, as shown in the following example:

>>> myvs = mypattern.runInCloud(...)
>>> myvs.waitFor()
>>> # myvs is now in either a started or failed state

10.4. Resource collections methods on the CLI

All IBM PureApplication System W1500 resource collections share methods that you can use to work with these objects.

Purpose

This topic describes the methods shared by all PureApplication System resource collections. The provided examples assume the following IP groups are defined:

>>> deployer.ipgroups
[
  {
    "created": May 13, 2009 3:46:15 PM,
    "gateway": "10.0.0.1",
    "id": 2,
    "ips": (nested object),
    "name": "ten",
    "netmask": "255.0.0.0",
    "networks": (nested object),
    "primarydns": "10.0.0.2",
    "secondarydns": "10.0.0.3",
    "subnetaddress": "10.0.0.0",
    "updated": May 14, 2009 1:28:19 PM
  },
  {
    "created": May 14, 2009 10:20:56 AM,
    "gateway": "192.168.0.1",
    "id": 6,
    "ips": (nested object),
    "name": "192.168.0.0",
    "netmask": "255.255.255.0",
    "networks": (nested object),
    "primarydns": "192.168.0.2",
    "secondarydns": "192.168.0.3",
    "subnetaddress": "192.168.0.0",
    "updated": May 14, 2009 1:28:52 PM
  }
]

Methods

Resource collections methods include:

add(other)

Adds the specified resource or resources to this collection. This method accepts a single parameter that can be either a resource or a list of resources. This method has no return value; exceptions are raised to indicate any problems adding the resources.

This method does not create new resources. All resources passed to this method must exist. The following example shows the add(other) method:

>>> mygroup = deployer.groups['mygroup'][0] 
>>> joe = deployer.users['joe'][0] 
>>> mygroup.users.add(joe)

For relationship-based resource collections, the left shift operator ("<<") can be used as an alias for the add() method, as shown in the following example:

>>> mygroup.users << joe

__contains__(item)

Indicates if this resource collection contains the specified item. Because resource collections contain resource objects, this method returns false unless the item parameter is a resource object of the correct type. This method is invoked implicitly by the Jython in operator, as shown in the following example:

>>> ipg = deployer.ipgroups[0]
>>> ipg in deployer.ipgroups
1
>>> ipg in deployer.hypervisors
0

create(other)

Creates a resource or new resources and places them in this collection. The attributes for the new resources can be specified in any of the following ways:

• As a dict object with the required keys, as shown in the following example:

  >>> deployer.groups.create({'name': 'new user group', 'description': 'description of new group'})
  

• As the name of a file containing a Jython expression that evaluates to one of the values in this list.
• As the value deployer.wizard or a wizard instance created by calling deployer.wizard(). If either of these values is supplied, the CLI prompts interactively for the values required to create the resource.
• As a list of any of the previous items in this list, in which case multiple resources are created, as shown in the following example:

  >>> deployer.groups.create([{'name': 'new user group', 'description': 'description of new group'}, 'name_of_file_containing_jython_dict'])
  

This method returns a resource object for the newly created resource, or a list of resource objects if multiple resources were created.

For type-based resource collections, the left shift operator, <<, can be used as an alias for the create() method, as shown in the following example:

>>> deployer.groups << { 'name': 'new user group', 'description': 'description of new group' }

delete(other)

Deletes a resource in this collection. All information about this resource is deleted from PureApplication System. The resource to be deleted can be specified in any of the following ways:

• As an int or long that specifies the ID of the resource to be deleted, as shown in the following example:

  >>> deployer.patterns.delete(17)
  

• As the resource object representing the resource to be deleted, as shown in the following example:

  >>> mypattern = deployer.patterns[4]
  >>> deployer.patterns.delete(mypattern)
  
  

This method raises exceptions to indicate any problems with deleting resources.

For type-based resource collections, the right shift operator, >>, can be used as an alias for the delete() method, as shown in the following example:

>>> deployer.patterns >> mypattern

__delitem__(key)

Deletes an item from this resource collection. For resource collections based on relationships, this removes the relationship between the resources; for resource collections based on types, this method deletes the definition of the resource on the IBM PureApplication System. The key parameter can be any type recognized by the delete() or remove() methods.

The __delitem__(key) method is invoked implicitly by the Jython del statement, as shown in the following example:

 >>> for ipg in deployer.ipgroups:
...     print 'id %d: %s' % (ipg.id, ipg.name)        
... 
id 2: ten
id 6: 192.168.0.0
>>> del deployer.ipgroups[6]
>>> for ipg in deployer.ipgroups:           
...     print 'id %d: %s' % (ipg.id, ipg.name)
... 
id 2: ten

__getattr__(name)

Searches for a resource in the resource collection by name. Returns a list of resource objects that matched the search criteria and returns an empty list if none are found. For most types of resources, the string is matched against the name of the resource.

This match is a partial match therefore the returned list of resources can include any names that contained the specified string anywhere in the name. If any of the resources exactly match the specified string, they are provided at the beginning of the returned list. The descriptions for various types of resources specify if the __getattr__() method searches on a different attribute. This method is invoked implicitly by the Jython dot operator, as shown in the following example:

>>> deployer.ipgroups.te 
[{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 14, 2009 1:28:19 PM
}]

__getitem__(key)

Returns a single resource from the collection. Unless otherwise indicated for a specific type of resource collection, this method recognizes two types of key values. If the value of the key parameter is an integer or long value, it is used as an index into the collection and the specified item is returned. If the value of the key parameter is a string, this method behaves as __getattr__(key). This method is invoked explicitly by Jython when square brackets are used with a resource collection, as shown in the following example:

>>> deployer.ipgroups[1].subnetaddress
'192.168.0.0'
>>> deployer.ipgroups['en']
[{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 14, 2009 1:28:19 PM
}]

__iter__()

Returns an iterator that can be used to iterate over all resources in this collection. This method is invoked implicitly by numerous Jython idioms including:

• list comprehensions
• the for..in construct
• filter() function
• iter() function
• map() function
• reduce() function
• zip() function

The iterator is shown in the following example:

 >>> [ ipg.name for ipg in deployer.ipgroups ]
['ten', '192.168.0.0']
>>> for ipg in deployer.ipgroups:
...     print ipg.subnetaddress
... 
10.0.0.0
192.168.0.0
>>> filter(lambda ipg: ipg.name != ipg.subnetaddress, deployer.ipgroups)
[{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 14, 2009 1:28:19 PM
}]

__len__()

Returns the number of resources in the collection. In addition to the Jython len() function, this method is invoked implicitly when a resource collection is used in a boolean context. A resource collection that contains no resources is considered false; a collection that contains at least one resource is considered true, as shown in the following example:

 >>> len(deployer.ipgroups) 
2 
>>> if deployer.ipgroups: 
...     print 'true' 
... else: 
...     print 'false' 
... 
true 
>>> len(deployer.hypervisors) 
0 
>>> if deployer.hypervisors: 
...     print 'true' 
... else: 
...     print 'false' 
... 
false

list(filt)

Returns a list of resources in this collection. An optional dict parameter can be supplied to filter the list of resources returned. The keys and values in the dict parameter are passed to PureApplication System. The supported keys and values within the dict parameter depend on the type of resource collection. The list(filt) method is shown in the following example:

>>> deployer.ipgroups.list({'name': 't'})
[{
  "created": May 13, 2009 3:46:15 PM,
  "gateway": "10.0.0.1",
  "id": 2,
  "ips": (nested object),
  "name": "ten",
  "netmask": "255.0.0.0",
  "networks": (nested object),
  "primarydns": "10.0.0.2",
  "secondarydns": "10.0.0.3",
  "subnetaddress": "10.0.0.0",
  "updated": May 14, 2009 1:28:19 PM
}]

remove(other)

Removes a resource from this collection.

The resource is not deleted from PureApplication System, it is just dissociated from this collection. The resources to be removed can be specified in any of the following ways:

• As an int or long containing the ID of the resource to be removed.
• As the resource object for the resource to be removed, as shown in the following example:

  >>> mygroup = deployer.groups.mygroup[0]
  >>> joe = deployer.users.joe[0]
  >>> mygroup.users.remove(joe)
  

For relationship-based resource collections, the right shift operator, >>, can be used as an alias for the remove() method, as shown in the following example:

>>> mygroup.users >> joe

__repr__()

This method is invoked implicitly by Jython when an expression entered in interactive mode returns a resource object or when a resource object is passed to the Jython repr() function. It returns a string representation of the resource collection, as shown in the following example:

>>> deployer.ipgroups
[
  {
    "created": May 13, 2009 3:46:15 PM,
    "gateway": "10.0.0.1",
    "id": 2,
    "ips": (nested object),
    "name": "ten",
    "netmask": "255.0.0.0",
    "networks": (nested object),
    "primarydns": "10.0.0.2",
    "secondarydns": "10.0.0.3",
    "subnetaddress": "10.0.0.0",
    "updated": May 14, 2009 1:28:19 PM
  },
  {
    "created": May 14, 2009 2:13:59 PM,
    "gateway": "192.168.0.1",
    "id": 7,
    "ips": (nested object),
    "name": "192.168.0.0",
    "netmask": "255.255.255.0",
    "networks": (nested object),
    "primarydns": "192.168.0.2",
    "secondarydns": "192.168.0.3",
    "subnetaddress": "192.168.0.0",
    "updated": May 14, 2009 2:13:59 PM
  }
]

__str__()

Returns a string representation of the resource collection. The returned string is readable, though it might be a lengthy string if the resource collection contains many resources. This method is called implicitly when a resource collection is printed, for example if a Jython expression entered in interactive mode returns a resource collection as was seen in the earlier example. It can also be invoked explicitly by passing a resource collection to the Jython str() function.

>>> print str(deployer.ipgroups)
[
  {
    "created": May 13, 2009 3:46:15 PM,
    "gateway": "10.0.0.1",
    "id": 2,
    "ips": (nested object),
    "name": "ten",
    "netmask": "255.0.0.0",
    "networks": (nested object),
    "primarydns": "10.0.0.2",
    "secondarydns": "10.0.0.3",
    "subnetaddress": "10.0.0.0",
    "updated": May 14, 2009 1:28:19 PM
  },
  {
    "created": May 14, 2009 2:13:59 PM,
    "gateway": "192.168.0.1",
    "id": 7,
    "ips": (nested object),
    "name": "192.168.0.0",
    "netmask": "255.255.255.0",
    "networks": (nested object),
    "primarydns": "192.168.0.2",
    "secondarydns": "192.168.0.3",
    "subnetaddress": "192.168.0.0",
    "updated": May 14, 2009 2:13:59 PM
  }
]

__unicode__()

Returns a Jython Unicode string containing a string representation of the resource collection. This method is called implicitly when a resource collection is passed to the Jython unicode() function or used in a context that requires a Unicode string, as shown in the following example:

>>> unicode(deployer.ipgroups)

10.5. Wizard objects on the CLI

The wizard object interactively prompts you for the set of information you must enter to create a resource. The class is supported by the create() method of most resource collections.

Usage

Use the wizard class as part of the create() method of a resource collection to create a resource. The wizard class presents a series of prompts for information used when creating a resource object.

The wizard object is supported by resource collection create methods as:

A temporary wizard object

>>> deployer.<resource_collection>.create(deployer.wizard)

A wizard object that you explicitly create

>>> w = deployer.wizard() 
>>> deployer.<resource_collection>.create(w)

After you have entered the information requested by a prompt, click enter to proceed to the next prompt. Prompts that are not required are indicated with the inclusion of (optional) in the prompt. If you do not want to enter a value for an optional prompt, click Enter to advance to the next prompt. For some other prompts, a list of possible values can be accessed. The prompt for these fields includes (* to select from list)". If you enter *, then a list of values is display. Enter the number associated with the option you would like to select.

>>> w = deployer.wizard() 
>>> deployer.virtualsystems.create(w)
 
Enter ?? for help using the wizard.
 
 
name: MyVirtualSystem
pattern (* to select from list): *
1. MyPattern1
2. MyPattern2
3. MyPattern3
pattern (* to select from list):1

Help is available when using the wizard class

• Enter ?? for additional help on how to use the wizard
• Enter ? for additional help with a specific prompt. Additional information about the information expected from this prompt is displayed.
• Enter ! to exit the wizard

Validation logic is used to ensure that a valid value has been entered. If the entered value is not valid for a particular prompt, then an error is displayed and you are then reprompted. After the last prompt has been completed, the resource is created based on the information provided.

Examples

See the following example of the screen output when creating an user object using the wizard class.

>>> w = deployer.wizard()
>>> deployer.users.create(w)
 
Enter ?? for help using the wizard.
 
username: joeuser 
fullname: Joe User password (optional): 
email: joe@mycompany.com
{
  "clouds": (nested object),
  "currentmessage": "RM02013",
  "currentmessage_text": "User has not logged in yet",
  "currentstatus": "RM01062",
  "currentstatus_text": "Inactive",
  "email": "joe@mycompany.com",
  "fullname": "Joe User",
  "groups": (nested object),
  "id": 2,
  "parts": (nested object),
  "password": (write-only),
  "patterns": (nested object),
  "roles": (nested object),
  "scripts": (nested object),
  "username": "joeuser",
  "virtualimages": (nested object),
  "virtualsystems": (nested object)
}

Methods

toDict

If a wizard object was explicitly constructed, use the toDict() method of the wizard class to create a dictionary (dict) object with the required keys. The following example shows how to use the toDict() method to create a dict object as a continuation of the wizard example.

>>> w.toDict()
{'fullname': u'Joe User', 'email': u'joe@mycompany.com', 'username': u'joeuser'} 

10.6. ACL object

You can use the access control list (ACL) object to set and control user access for other IBM PureApplication System W1500 resources.

Purpose

Use the access control list (ACL) object to set and control user access for the following objects:

AddOns

For more information about Add-ons, see AddOn CLI reference.

EnvironmentProfiles

For more information about environment profiles, see Environment profiles on the CLI.

Fixes

For more information about fixes, see Emergency fix CLI reference.

Patterns

For more information about patterns, see Pattern CLI reference.

Scripts

For more information about scripts, see Script package CLI reference.

VirtualAppliances

For more information about virtual appliances, see Virtual appliance CLI reference.

Virtual images

For more information about virtual images, see Virtual images CLI reference.

ACL object

The ACL object represents the ACL associated with a PureApplication System resource. The IBM PureApplication System manages access to resources with a hierarchical set of permissions. These permissions are represented by constants in the PureApplication System package. From the least access to greatest access, these permissions are:

NO_PERMISSIONS

The user or group cannot access the resource.

READ_PERMISSION

The user or group can view the resource and use it in a read-only manner, but cannot alter the resource.

UPDATE_PERMISSION

In addition to viewing and using the resource, the user or group is permitted to alter the resource.

CREATE_PERMISSION

Typically applied to collections of resources, with this permission the user or group can create new resources.

DELETE_PERMISSION, ALL_PERMISSION

The user or group is granted full access to the resource.

ACL objects are accessed using the ACL property of the resource to which they apply, as shown in the following example:

>>> mypattern = deployer.patterns[0]
>>> mypattern.acl
{
  (group Everyone): all,
  (user cbadmin): all }

ACL methods

The ACL object provides the following methods:

check(entity)

Queries the IBM PureApplication System to determine what permissions the specified user or group has been granted to the resource associated with this ACL. The following example shows this method:

>>> deployer.patterns[0].acl.check(deployer.self())

__contains__(item)

Indicates if a specific permission has been defined for the specified user or group, as shown in the following example:

>>> deployer.everyone() in deployer.virtualimages[0].acl

__delitem__(key)

Removes any explicit permissions set for the specified user or group for this resource. This method is called implicitly by the Jython del statement, as shown in the following example:

>>> user = deployer.users['user2'][0]
>>> del deployer.patterns[0].acl[user]

The user might still have access to this resource through a user group to which the user belongs.

__getitem__(key)

Returns the permission explicitly set for the specified user or group for this resource. This method is started implicitly when a user or group is used as an index to an ACL, as shown in the following example:

>>> deployer.virtualimages[0].acl[deployer.everyone()]

This method considers only permissions that have been explicitly granted. To determine the level of access a user has within the groups to which the user belongs, use the check() method instead.

__iter__()

This method is started implicitly when you reference an ACL object in a context that requires iterating over all the entries. This method is also started implicitly when you are explicitly passing the ACL object to the Jython iter() function. The following example shows this method:

>>> for userorgroup in myvirtualsystem.acl:
...     print userorgroup.name

__len__()

Returns the number of permissions explicitly set for this resource, as shown in the following example:

>>> len(deployer.scripts[0].acl)

refresh()

Refreshes the cached ACL entries with current data from the IBM PureApplication System.

__repr__()

This method is started implicitly by Jython when an expression entered in interactive mode returns an ACL or when an ACL is passed the Jython repr() function. It returns a string representation of the resource. The following example shows this method being implicitly started:

>>> deployer.scripts[0].acl

__setitem__(key, value)

Sets an explicit ACL for the specified user or group. This method is started implicitly when you use the []= construct, as shown in the following example:

>>> myscript.acl[deployer.everyone()] = deployer.READ_PERMISSION

The value specified inside the square brackets must be a User or Group object. The value to the right of the equal sign must be one of the following values:

• deployer.NO_PERMISSIONS
• deployer.READ_PERMISSION
• deployer.UPDATE_PERMISSION
• deployer.CREATE_PERMISSION
• deployer.DELETE_PERMISSION
• deployer.ALL_PERMISSIONS

__str__()

Returns a string representation of this ACL. This method is started implicitly by Jython when a resource object is used as a value in a string formatting operation. This method is also started implicitly by Jython when it is passed as a parameter to the Jython str() function. The following example shows this method:

>>> print 'Here is the ACL: %s' % deployer.patterns[0].acl
>>> str(deployer.patterns[1].acl)

__unicode__()

Returns a string representation of this ACL. This method is started implicitly by Jython when a resource object is used as a value in a string formatting operation. This method is also started implicitly when it is passed as a parameter to the Jython unicode() function. The following example shows this method:

>>> print 'Here is the ACL: %s' % deployer.patterns[0].acl
>>> str(deployer.patterns[1].acl)

Additional CLI utilities

The IBM PureApplication System W1500 CLI includes a set of utilities that can help you with various tasks you are performing.

Purpose

This topic provides a listing of utilities you can use with IBM PureApplication System W1500 CLI to accomplish the following tasks:

deployer.admin . get the administrative user

You can use the deployer.admin function as a convenience method to get the administrative user. The deployer.admin function requires no argument and it returns the user object for the administrative user on the IBM PureApplication System. For additional help on the user object returned, enter the following command:

>>> help(deployer.admin())

deployer.cliversion . obtain the CLI version

You can use the deployer.cliversion function to determine the version of the CLI code you are using, as shown in the following example:

>>> deployer.cliversion

This function returns an object with a string representation that is the version of the CLI code, as shown in the following example:

1.0.0.0-11703

This object is not a string, but can be converted to a string using the str() command, as shown in the following example:

>>> if str(deployer.cliversion).startswith('1.0.0'):
...     print 'running 1.0.0 deployer CLI'
...
running 1.0.0 deployer CLI

deployer.diagnostics.getLatest (). download the latest log files

You can use the deployer.diagnostics.getLatest() function as to download the latest diagnostic log files. This function returns a .zip file named "trace.zip" that contains the latest diagnostic log files to the \deployer.cli\bin directory. For additional help on the user object returned, enter the following command:

>>> help(deployer.diagnostics.getLatest())

deployer.everyone . return the everyone group

You can use the deployer.everyone function to return the everyone group. The deployer.everyone function takes no arguments and returns the Group object for the Everyone group on the IBM PureApplication System. For additional help on the Group object returned, enter the following command:

>>> help(deployer.everyone())

deployer.exit . exit the CLI

The deployer.exit function exits the CLI. In interactive mode, you can use exit without the deployer prefix to end an interactive CLI session. In interactive mode, enter the following command:

 >>> exit

In batch mode, enter the following command:

>>> deployer.exit

deployer.self . obtain the current user

Use the deployer.self function to return a user object for the current user. The deployer.self function takes no argument and returns the user object corresponding to the user specified when the CLI was started. For additional help on the user object returned, enter the following command:

>>> help(deployer.self())

deployer.version . obtain the PureApplication System version

You can use the following command to obtain the version of PureApplication System with which your CLI session is communicating:

>>> deployer.version

This function returns the following object:

PureApplication System at deployer.xyz.com, firmware version x.0.0.0-11703

This object is not a string but you can convert it to a string using str(), as shown in the following example:

   >>> if str(deployer.version).find('1.0.0') >= 0:
   ...     print 'System is version 1.0.0'
   ...
   System is version 1.0.0

deployer.waitFor . order operation processing

You can use the waitFor function to specify the order of function processing. This function is like resource.waitFor(), but it is not tied to a particular resource; it is a generic utility function to periodically check a condition that you supply. The deployer.waitFor function can assist you in writing scripts that must wait for the IBM PureApplication System to complete a particular action. The deployer.waitFor function periodically evaluates a particular expression until the expression evaluates to a true value or a timeout expires. The function accepts the following arguments:

condition

The condition to wait for. If o is an object that can be called, it is invoked at the start of each interval to determine whether to continue waiting. A true value causes this function to return, a false value causes the function to continue waiting.

maxWait

The maximum wait time, expressed as a number of seconds. Floating point values can be used to indicate fractions of a second. A negative value causes this function to wait indefinitely. If a value is not supplied, the default value is -1.

interval

The interval at which o is evaluated, expressed as a number of seconds. Floating point values can be used to express fractions of a second. The default value is 10 seconds.

The deployer.waitFor returns the value obtained the last time the condition was evaluated.