Writing Management Scripts
|
WebSphere supports scripting of administrative operations through the wsadmin command utility. The syntax for starting the wsadmin command utility is:
wsadmin [-c <command>] [-p <properties_file_name>] [-profile <profile_script_name>] [-f <script_file_name>] [-lang <language>] [-wsadmin_classpath <classpath>] [-conntype <type>] [-host <host_name>] [-port <port_number>] [-user <userid>] [-password <password>] [<script parameters>]
You can execute a single script command with the c parameter. You should supply a single script statement with this option.
You can execute an entire script contained within its own file with the f parameter. Specify the script file with this option. We'll come back to this in a bit.
You can create a common script – referred to as a profile script – that you want always executed in front of anything else you run. You can create a profile script, and specify it with the profile parameter. This is useful, for example, for setting up standard path statements, recording activities, and so forth.
If you have special classpath needs within your script, you can extend the classpath with the wsadmin_classpath parameter.
Any parameters you need to pass into the script should be specified last – they will be passed into the script as specified on the command line.
By default wsadmin operates with the Jacl language. This is the only language supported by WebSphere at this time, but we expect this will be expanded in the future to include other languages such as Jython and JavaScript. You will be able to specify the scripting language you prefer to write with in the lang parameter.
A common use of the wsadmin command utility is to run it as a shell. Simply specifying wsadmin without the c or f parameters will bring up the shell:
c:\Program Files\WebSphere\AppServer\bin>wsadmin WASX7029I: For help, enter: "$H WASX7209I: Connected to process "server1" on node rhighlt1 using SOAP connector; The type of process is: UnManagedProcess elp help" wsadmin>
This, of course, assumes you know the Jacl language. WebSphere provides basic information on programming in Jacl in the InfoCenter. Another document worth looking at is at: http://www.usenix.org/publications/library/proceedings/tcl97/full_papers/lam/lam.pdf. Beyond that, the first thing you will want to know is the $Help object – this object can be used to get information about the other predefined objects introduced by WebSphere. It can also be used to discover the attributes, operations, notifications and other details of the MBeans registered in the WebSphere environment.
To get information about a particular MBean you can use the all operation on the $Help object, passing in a fully qualified MBean ObjectName. For this and any other operation that requires an ObjectName, you can generate a fully qualified name using the completeObjectName parameter of the $AdminControl object. The command:
wsadmin> $Help all [$AdminControl completeObjectName "WebSphere:type=Server,process=server1,*"]
will return all of the object information about the server MBean representing server1. Notice the use of square brackets – these are used to enclose a sub-expression in the Jacl language.
The other key objects to know about are:
-
$AdminControl – supports operations that can be performed on specified MBeans
-
$AdminConfig – introduces operations that manage the configuration of the application server or cell
-
$AdminApp – supports application management operations
AdminControl
The AdminControl command supports the following operations:
| Operation | Argument(s) | Usage |
|---|---|---|
| completeObjectName | <name-template> | Returns a string version of ObjectName that best matches the template name. |
| getAttribute | <name-string><attribute-name> | Returns the value of the attribute for the MBean best matching the template name. |
| getAttribute_jmx | <ObjectName><attribute-name> | Returns the value of the attribute for the specified ObjectName. |
| getAttributes | <name-string><attribute-name-list> | Returns a string of name-value pairs. |
| getAttributes_jmx | <ObjectName><attribute-name-list> | Returns a list of attribute values; one for each of the attribute names listed. |
| getCell | none | Returns the cell name of the |
| getConfigId | <name-template> | Returns a config ID for the corresponding configuration object, if any. The resulting identity is used with the AdminConfig object. |
| getDefaultDomain | none | Returns "WebSphere". |
| getDomainName | none | Returns "WebSphere". |
| getHost | none | Returns a string representation of connected host. |
| getMBeanCount | none | Returns the number of MBeans registered in WebSphere. |
| getMBeanInfo_jmx | <ObjectName> | Returns MBeanInfo for the |
| getNode | none | Returns node name of the connected server. |
| getPort | none | Returns the port in use. |
| getPropertiesForDataSource | <config-id> | Returns the properties that may be used in testing the connection to the specified data source. |
| getType | none | Returns the connection type in use. |
| help | [<operation>] | Gets help information. Will provide a summary of all operations supported if no arguments are provided. Otherwise, will returns specific information about the specified operation. |
| invoke | <name-string><operation> [<args> [<signature>]] | Invokes the specified operation on the MBean identified by <name-string>. If the operation takes arguments, you can specify those as <args>. If the operation is overloaded, you must qualify which form to use by supplying a <signature>. |
| invoke_jmx | <ObjectName><operation><args><signature> | Invokes the specified operation on the specified MBean. You must supply an <args> Java Object array (null if the operation does not take any arguments), and <signature> Java Object array (null if the operation does not take any arguments). The results of the invoked operation, if any, are returned from this request. |
| isRegistered | <name-string> | Returns true (1) if supplied MBean <name-string> is registered. |
| isRegistered_jmx | <ObjectName> | Returns true (1) if supplied <ObjectName> is registered. |
| makeObjectName | <name-string> | Returns an ObjectName object built with the given string. |
| queryNames | <name-string><QueryExp> | Returns the set of ObjectNames that match the <QueryExp> on the MBean specified by <name-string>. The <QueryExp> is a javax.management.QueryEval generated from a Query object. |
| queryNames_jmx | <ObjectName><QueryExp> | Returns the set of ObjectNames that match the <QueryExp> on the specified MBean. The <QueryExp> is a javax.management.QueryEval generated from a Query object. |
| reconnect | none | Reconnects with the server if the server should have gone down for some reason. |
| setAttribute | <name-string><attribute> | Sets the <attribute> on the specified MBean. <attribute> is a javax.management.Attribute object. |
| setAttribute_jmx | <ObjectName><attribute> | Sets the <attribute> on the specified MBean. <attribute> is a javax.management.Attribute object. |
| setAttributes | <name-string><attributes> | Sets the <attributes> on the specified MBean. <attributes> is an array of javax.management.Attribute objects. |
| setAttributes_jmx | <ObjectName><attributes> | Sets the <attributse> on the specified MBean. <attributes> is an array of javax.management.Attribute objects. |
| startServer | <server> [<node-name>] [<wait-time>] | Starts the specified <server>. You must specify the <node-name> when operating on a deployment manager. The <wait-time> (in seconds) is optional. |
| stopServer | <server> [<node-name>] | Stops the specified <server>. You must specify the <node-name> when operating on a deployment manager. |
| testConnection | <datasource-config-id> | Tests the connection to a DataSource object. |
| trace | <trace-spec> | Sets the wsadmin trace specification. |
The <name-template> argument is a partially qualified name-string representing the MBean.
For example:
"type=Server,process=server1,*"
is sufficient for identifying the application server named server1.
The <name-string> argument is a fully qualified name-string representing the MBean. A fully qualified name contains a complete list of keys and values that identify the MBean object – as registered from the MBean when it was created. Each MBean may be registered with a different set of name keys and so it is usually difficult to guess (or even type out) the fully qualified MBean name. For example, the fully qualified name for a server might look like:
WebSphere:name=server1,process=server1,platform=common,node=rhighlt1,version=5.0,type=Server,mbeanIdentifier=cells/rhighlt1/nodes/rhighlt1/servers/server1/server.xml#Server_1,cell=rhighlt1,processType=UnManagedProcess
The easiest way of forming this is with the $AdminControl completeObjectName <name-template> command. For example:
set server1 [$AdminControl completeObjectName "type=Server,process=server1,*"]
The <ObjectName> argument is a javax.management.ObjectName object. The easiest way of forming this is with the $AdminControl makeObjectName <name-string> command. For example:
set server1name [$AdminControl makeObjectName $server1]
Starting a Server
Starting a server can be done with the startServer operation.
wsadmin> $AdminControl startServer server1 rhighlt1 WASX7262I: Start completed for server "server1" on node "rhighlt1"
will start server1 on node rhighlt1.
Stopping a Server
Stopping a server be done with the stopServer operation:
wsadmin> $AdminControl stopServer server1 rhighlt1 WASX7337I: Invoked stop for server "server1" Waiting for stop completion. WASX7264I: Stop completed for server "server1" on node "rhighlt1"
will stop server1 on node rhighlt1.
AdminConfig
The operations supported by AdminConfig are:
| Operation | Argument(s) | Usage |
|---|---|---|
| attributes | <type> | Shows the attributes for a given type. |
| checkin | <documentURI><filename><digest> | Checks a file into the config repository at the specified URI. This should be the same digest returned from the extract operation. |
| convertToCluster | <server-name><cluster-name> | Converts a server to be the first member of a new server cluster. |
| create | <type><parent><attributes> [<parent-attribute-name>] | Creates a configuration object, given a type, a parent, and a list of attributes, and optionally an attribute name for the new object. |
| CreateCluster | <cluster-name><node-name><member-attributes><template-id> | Creates a new server that is a member of an existing cluster. |
| createDocument | <documentURI><filename> | Creates a new document in the |
| createUsingTemplate | <type><parent><attributes><template-object> | Creates an object using a particular template type – the <template-object> should be produced from the listTemplates operation. |
| defaults | <type> | Displays the default values for attributes of a given type of MBean. |
| deleteDocument | <documentURI> | Deletes a document from the |
| existsDocument | <documentURI> | Tests for the existence of a document in the config repository. |
| extract | <documentURI><filename> | Extracts a file from the config repository. |
| getCrossDocumentValidationEnabled | None | Returns true if cross-document validation is enabled |
| getid | <containment-string> | Show the config ID of an object, given a string version of its containment. |
| getObjectName | <config-id> | Given a config ID, returns a string version of the ObjectName for the corresponding running MBean, if any. |
| getSaveMode | None | Returns the mode used when "save" |
| GetValidation | None | Returns the validation used when files are extracted from the repository. |
| getValidationSeverityResult | <severity> | Returns the number of messages of a given severity from the most recent validation. <severity> is a numeric value. |
| hasChanges | None | Returns true if unsaved configuration changes exist. |
| help | None | Shows help information. |
| InstallResource | <rar-filename><node><options> | Installs a J2C resource adapter with the given RAR file name and an option string in the node. |
| list | <type> [<scope>] | Lists all configuration objects of a given type. |
| listTemplates | <type> [<match>] | Lists all available configuration templates of a given type. Will be subsetted to those templates whose name contains the <match> string, if specified. |
| modify | <config-id><attributes> | Change specified attributes of a given configuration object. |
| parents | <type> | Show the objects that contain a given type. |
| queryChanges | None | Returns a list of unsaved files. |
| remove | <config-id> | Removes the specified configuration object. |
| required | <type> | Displays the required attributes of a given type. |
| reset | None | Discard unsaved configuration changes |
| save | None | Commit unsaved changes to the configuration repository. |
| setCrossDocumentValidationEnabled | None | Sets the cross-document validation |
| setSaveMode | rollbackOnConflict | overwriteOnConflict | Changes the mode used when "save" |
| setValidationLevel | none | low | medium | high | highest | Sets the validation used when files are extracted from the repository. |
| show | <config-id> [<attr-list>] | Shows the attributes of a given configuration object. If <attr-list> is provided, then only show those attributes in the list. |
| showall | <config-id> [<attr-list>] | Recursively show the attributes of a given configuration object, and all the objects contained within each attribute. |
| showAttribute | <config-id><attribute> | Displays only the value for the single attribute specified. |
| types | None | Shows the possible types for configuration. |
| validate | None | Invokes validation on the repository (as controlled by the Validation Level – see setValidationLevel). |
The <type> argument is the class name of a registered MBean. For example:
wsadmin> $AdminConfig attributes Server
The <documentURI> is the name of a configuration document in the repository. For example:
wsadmin> $AdminConfig existsDocument /cells/rhighlt1Network/nodes/rhighlt1/servers/server1/server.xml
The <containment-string> refers to an MBean in the system, represented by its configuration path. For example:
wsadmin> $AdminConfig getid /Node:rhighlt1/Server:server1/
You should think of the $AdminConfig object being used two ways – one to modify the configuration of the network, and the other to extract and check-in documents in the configuration repository. The former involves operations likes convertToCluster, create, getObjectName, modify, save, show, reset, etc. The latter involves operations like checkin, createDocument, extract, remove, etc.
Modifying the configuration allows you to change the configuration documents without actually having to extract and check-in the actual documents – WebSphere will make the document changes for you. Similar to the Admin UI, when you make a configuration change with these operations, the changes are saved in a workspace and won't change the actual repository until you save.
Handling documents in the repository allows you to get or put the entire configuration document, or any other document held in the repository. Don't forget, if you make any changes to the configuration or repository, including creating new documents in the repository, these changes only actually change your workspace – you must invoke the save operation to write these changes back into the repository.
AdminApp
The AdminApp object supports the following operations:
| Operation | Argument(s) | Usage |
|---|---|---|
| DeleteUserAndGroup | <appname> | Deletes all the user/group information for all the roles and all the username/ password information for run-as roles for a given application. |
| edit | <appname><options> | Edits the properties of an application. |
| editInteractive | <appname> [<options>] | Edits the properties of an application interactively. |
| export | <appname><filename> | Exports application to a file. |
| exportDDL | <appname><filename> | Exports DDL from application to a directory. |
| help | [<operation>] | Shows help information. Will list a summary of operations if no arguments are specified. Otherwise, will provide detailed information of the operation specified. |
| install | <filename><options> | Installs an application, given a file name and an option string. |
| installInteractive | <filename> [<options>] | Installs an application in interactive mode, given a file name and an option string. |
| list | none | Lists all installed applications. |
| listModules | <appname> | List the modules in a specified application. |
| options | [<filename>] | Shows the options available, either for a given file, or in general. |
| taskInfo | <filename><task> | Shows detailed information pertaining to a given install task for a given file. The following are valid tasks for this operation: MapRolesToUsers, MapRunAsRolesToUsers, CorrectUseSystemIdentity, BindJndiForEJBNonMessageBinding, BindJndiForEJBMessageBinding, MapEJBRefToEJB, MapResRefToEJB, MapResEnvRefToRes, DataSourceFor10EJBModules, DataSourceFor20EJBModules, DataSourceFor10CMPBeans, DataSourceFor20CMPBeans, MapWebModToVH, MapModulesToServers, EnsureMethodProtectionFor10EJB, EnsureMethodProtectionFor20EJB, CorrectOracleIsolationLevel, AppDeploymentOptions, EJBDeployOptions. |
| uninstall | <appname> | Uninstalls the specified application. |
| updateAccessIDs | <appname><all> | Updates the user/group binding information with accessID from user registry for a given application. If <all> is true (1), all users and groups will be updated in the bindings. If <all> if false (0), only new users and groups (those not previously specified in the bindings) will be updated. Note: Using this operation has security tradeoffs that should be understood. Read the Granting Principals to Roles section in Chapter13 to understand these implications better. |
Options
The valid options for any of the $AdminApp operations listed above include:
| Option | Description |
|---|---|
| appname <appname> | The name of the application. |
| BindJndiForEJBMessageBinding { <ejbmodulename><ejbname><uri><lpjndiname> }+ | The listener port JNDI name you want given to your Message Bean. |
| BindJndiForEJBNonMessageBinding { <ejbmodulename><ejbname><uri><ejbjndiname> }+ | The JNDI name you want given to your (non-MDB) EJB. |
| cell <cellname> | The name of the cell. |
| cluster <clustername> | The name of the cluster. |
| contextroot <contextrootname> | The context root for the web application. |
| CorrectOracleIsolationLevel { <modulename><referencebinding><jndiname><isolationlevel> }+ | The isolation level for Oracle data sources. |
| CorrectUseSystemIdentity { <ejbname><ejbmodulename><uri><methodsignature><role><username><password> }+ | The run-as-role policy to use. |
| DataSourceFor10CMPBeans { <ejbmodulename><ejbname><uri><dsjndiname><username><password> }+ | The data source to use for a specific 1.x CMP EJB. |
| DataSourceFor20CMPBeans { <ejbmodulename><ejbname><uri><dsjndiname><resauthpolicy> }+ | The data source to use for a specific 2.0 CMP EJB. The resauthpolicy can one of: |
| DataSourceFor10EJBModules { <ejbmodulename><uri><dsjndiname><username><password> }+ | The default data source to use for the 1.x EJBs in the specified module. |
| DataSourceFor20EJBModules { <ejbmodulename><uri><dsjndiname><resauthpolicy> }+ | The default data source to use for the 2.0 EJBs in the specified module. The resauthpolicy can one of: "per connection factory", "container". |
| defaultbinding.cf.jndi <cfjndiname> | The JNDI name of the default |
| defaultbinding.cf.resauth <resauthpolicy> | The resauth policy to assume for the default connection factory. |
| defaultbinding.datasource.jndi <dsjndiname> | The JNDI name of the default data source. |
| defaultbinding.datasource.password <password> | The password to assume for the default data source. |
| defaultbinding.datasource.username <username> | The username to assume for the default data source. |
| defaultbinding.ejbjndi.prefix <jndiprefix> | The default JNDI prefix to assume for EJBs. |
| defaultbinding.force | Use to force the default bindings to be used in place of the existing bindings. |
| defaultbinding.strategy.file <filename> | The name of the default bindings file. |
| defaultbinding.virtual.host <virtualhost> | The default virtual host. |
| depl.extension.reg <filename> | The deployment extensions property file. |
| deployejb | Deploy the EJBs in the application |
| deployejb.classpath <classpath> | Additional classpaths to use for EJB deploy. |
| deployejb.dbschema <dbschemaname> | The schema to use for EJB deploy |
| deployejb.dbtype <dbtype> | The DB type for the EJB deploy. Can be one of: |
| deployejb.rmic <rmicoptions> | The RMIC options to use for EJB deploy. |
| distributeApp | Whether to distribute the application binaries. |
| EnsureMethodProtectionFor10EJB { <ejbmodulename><uri><protectpolicy> }+ | Ensure 1.x EJBs in the application are protected. The protection policy can be one of: |
| EnsureMethodProtectionFor20EJB { <ejbmodulename><uri><protectpolicy> }+ | Ensure 2.0 EJBs in the application are protected. The protection policy can be one of: |
| installdir <install-directory> | The directory to install the application. |
| MapEJBRefToEJB { <modulename><ejbname><uri><ejbreference><targetclassname><targetejbjndiname> }+ | Maps the EJB reference to an EJB JNDI name. |
| MapModulesToServers { <modulename><uri><servername> }+ | Maps individual modules of the application to specific application servers (overriding the server option). |
| MapResEnvRefToRes { <modulename><ejbname><uri><resenvreference><resenvtype><resenvjndiname> }+ | Maps resource environment references in your application to environment resources in the configuration. |
| MapResRefToEJB { <modulename><ejbname><uri><resreference><restype><resjndiname> }+ | Maps the resource references in your application to resources in the configuration. |
| MapRolesToUsers { <role><isEveryone><isAllauthnusers><username><groupname> }+ | Maps the roles in your application to users or groups. You should specify either "Yes" or "No" for isEveryone and isAllauthnusers. Setting isEveryone to Yes indicates the role is granted to everyone; isAllauthnusers should be set to No and the username and groupname should be blank. Setting isAllauthnusers to Yes indicates the role is granted to all authenticated users; isEveryone should be set to No and the username and groupname should be blank. You can specify multiple users and groups by separating them by | and surrounding the list in double-quotes. |
| MapRunAsRolesToUsers { <role><username><password> }+ | Maps the run-as-role policy in your application to a specified user principal. |
| MapWebModToVH { <webmodulename><uri><virtualhostname> }+ | Maps web modules in your application to defined virtual hosts. |
| nocreateMBeansForResources | Do not create MBeans for resources (including JSPs, servlets, EJBs, etc.) in |
| node <nodename> | The name of the node. |
| nodeployejb | Do not deploy the EJBs in your application. |
| nodistributeApp | Do not distribute your application binaries to the servers on which they're configured. |
| nopreCompileJSPs | Do not pre-compile the JSPs in your application. |
| noreloadEnabled | Do not enable servlet re-loading. |
| nousedefaultbindings | Do not use default bindings. |
| nouseMetaDataFromBinary | Do not use the configuration information from the application binaries (use only the configuration information stored for the application in the configuration repository). |
| preCompileJSPs | Pre-compile the JSPs in your application. |
| reloadEnabled | Enable servlet re-loading. |
| reloadInterval <interval> | The re-load interval. |
| server <servername> | The server name. |
| update | Updates the installed application with a new version of the EAR. |
| update.ignore.new | Ignore bindings from the new EAR. |
| update.ignore.old | Replace the existing bindings with those in the new EAR. |
| usedefaultbindings | Use default bindings. |
| useMetaDataFromBinary | Use the configuration information stored in the application binaries (overriding the configuration information stored in the configuration repository for the application). |
| verbose | Provide additional information during |
Required fields are underlined in the table above. To leave a field blank you specify it as a double-quoted empty string (""). You must put double-quotes around any field entries that contain blanks.
Options are always entered with a leading "-" (dash). For example:
$AdminApp install "C:/Program Files/WebSphere/AppServer/samples/lib/PlantsByWebSp here/PlantsByWebSphere.ear" {-cell rhighlt1Network -node rhighlt1 –usedefaultbind ings -server server2} The following example demonstrates a couple of options listed above:
$AdminApp install "C:/Program Files/WebSphere/AppServer/samples/lib/PlantsByWebSphere/PlantsByWebSphere.ear" {-BindJndiForEJBNonMessageBinding {{"PlantsByWebSphere EJB Module" ShoppingCart PlantsByWebSphereEJB.jar,META-INF/ejb-jar.xml plantsby/ShoppingCartHome}} –DataSourceFor20CMPBeans {{"PlantsByWebSphere EJB Module" Inventory PlantsByWebSphereEJB.jar,META-INF/ejb-jar.xml eis/jdbc/PlantsByWebSphereDataSource_CMP container}}} The –BindJndiForEJBNonMessageBinding option binds the JNDI name for the ShoppingCart bean in the "PlantsByWebSphere EJB Module". The URI for this is PlantsByWebSphereEJB.jar,meta_inf/ejb-jar.xml. The EJB will be bound with a JNDI name of plantsby/ShoppingCartHome.
The –DataSourceFor20CMPBeans establishes the data source for the Inventory bean in the "PlantsByWebSphere EJB Module". The URI for this is PlantsByWebSphereEJB.jar,meta_inf/ejb-jar.xml. The data source for this bean is eis/jdbc/PlantsByWebSphereDataSource_CMP, and the last argument instructs the container to authenticate with the data source on behalf of the application.
|
EAN: N/A
Pages: 135