WebSphere UK User Group - October 2004
WebSphere Administration
A practical guide to WebSphere scripted administration options
Andrew Simms, Consulting IT Specialist IBM SWG WebSphere Services
What we\u2019re going to do . . .
\ u e 0 0 0
Talk through and demonstrate
configuration
scripts that:
o o o o
set the initial heap and maximum heap size add or change environment entries
set the maximum requests per keep-alive value of a particular transport display the changed values
\ u e 0 0 0
Talk through and demonstrate
application deployment
Tool 1: The Admin Console
You could avoid writing scripts by using the Admin Console
configuration tasks and install applications
If y u like ty ing and don’t make mistakes, this is the tool
o
p
Going to:
o o o o select server1navigate to P ocess Definition + Java Virtual Machine and change heap sizesr navigate to P ocess Definition + Environment Entries and change envvarsr navigate to Web Container + HTTP Transports, select the SSL-disabled transport, select Custom P operties and add a new propertyr
o install an application
Similar navigation on v4
Admin Console: Comments
Different look and feel in v4 and v5
v5.1 & v6 have same look and feel as v5
Use for ad hoc configuration and operational tasks, e.g.:
o o o o
building a play en environmentp examining transactions
examining product information
controlling trace and examining logs
Avoid for bulk and repetitive tasks
Useful early in the test cy le
c
So why not just use the Admin Console?
Consider:
o o o o o y u have N domains/cellso 1 N2 test environmentsN3 application servers or server groups (clusters) in each domain/cell N4 enterprise applications
N5 drops received from develop ent for each appm
If N 1 for each i, then y u could use the Admin Console
io
When N >> 1 then using Admin Console becomes tedious and error prone
iSolution: script domain/cell builds and enterprise application
installations
Up front cost but in the long term y u save administrator
o
provide a more reliable service.
Tool 2: wscp
What is it?
o v4’s configuration and runtime scripting language
Main features:
o Extension of Tcl, the Tool Command Language
• • •
Tcl is portable across many platforms
Tcl widely used for scripting tasks, not just WebSphere Simple to learn, powerful to use
o Interactive or scripted access
o Ty ically used for bulk and repeatable tasks, e.g.:p
• Add a set of definitions in a repeatable manner
• Change the value of a s stem property on all servers in all domains (buty not easily)
wscp: Sty e of usage
l
Command line /script
Three modes of operation:
o o o
interactive
single command (-c option) run a script (-f option)
Access resources using <class> <verb> <object> <options>, e.g.:
o J2CResourceAdapter create <name> –attribute {{Name fred} {ArchiveFile freda}}
Names look like this:
o /Node:ajsnode/Server:server1/
o /JDBCDriver:schumacher/DataSource:button/
Lots of curly brackets!!, e.g.:
o ServerGroup show <name> –attribute EJBServerAttributes
o ServerGroup modify <name> -attribute {{EJBServerAttributes {WebContainerConfig {SessionManagerConfig {EnableUrlRewriting true}}}}}
wscp: Example Code
Code:
o sample_wscp.tcl (about 90 lines)
o sample_wscp_install.tcl (about 20 lines)
Reset before running:
o sample_ wan_reset_wscp.bats
Run it:
o sample_wscp.bat
Tool 3: XMLConfig
What is it?
o v4’s XML configuration utilityMain features:
o o o o o o oP ivate to WebSphere, unlike Tclr
Exports full or partial repository to an XML file Imports from XML file with arbitrary substitutions
Not interactive (but can be called interactively from wscp) Can create, update or delete objects
Can start/stop objects
Ty ically used for repeatable tasks, e.g.:p
• Add a set of definitions in a repeatable manner
XMLConfig: Sty e of Usage
l
Command
Run
xmlconfig –exportto export the entire domain to an XML file
Run
xmlconfig –export –partial <file>to export part of a domain to
an XML file, where
<file>directs what is to be exported
Edit the generated XML file:
o remove unwanted bits
o change values to variable names to allow substitution
Run
xmlconfig –importto import from the XML file to a new
same domain, usually with substitutions
Can also build the XML file by hand
XMLConfig: Example Code
Code:
o o o o osample_ mlconfig_ artial_export.xmlx p (7 lines)
sample_ mlconfig_ artial_export_output.xmlx p (c200 lines, generated) sample_ mlconfig_import.xmlx (50 lines, edited)
sample_ mlconfig_ artial_export_install.xmlx p (5 lines)
sample_ mlconfig_ artial_export_output_install.xmlx p (c70 lines, generated & edited)
Reset before running:
o sample_ wan_reset_wscp.bats
Run it:
o sample_ mlconfig.batx
wscp is better than XMLConfig is better than wscp
Export+partial can do some ad hoc tasks Can be used for ad hoc purposes interactively
(but not alway easilys )
Is dependent on creating something first
manually (unless y u create the XML by hand)o Is not dependent on having something built
manually first
Is a good choice for repetitive tasks where changes are simple substitutions
Is a natural choice for doing any hing in bulk ort repetitive
P aces actions in XML attributes (rather likel ANT)
Represents WebSphere objects as commands (e.g. ) with verbs (e.g.
“start”, “modify )ApplicationServer”
Its output is XML, but the utility is unique to WebSphere
Is based on a Java implementation of a popular scripting language (Tcl)
Is autility that allows simple substitutions and has limited actions
Is a powerful procedural scripting language
with variables
XMLConfig wscp
Scripted options in v5 & v5.1 & v6
Gone!
Replacement for wscp: wsadmin
o But provides a completely different set of objects
o wscp scripts are not migratable to wsadmin
Replacement for XMLConfig: nothing
o o o o
Repository now a set of XML files
Expectation that customers would copy edit directories/files/ P oved too hardr
Some as is scripts available on WebSphere Developer Domain for doing -XMLConfig- ike things (v5.1.2)l
Tool 4: wsadmin
What is it?
o v5’s scripting language
Main features:
o Uses the Bean Scripting Framework (BSF)
• P ovides access to Java objects and methods from supported scriptingr languages.
• Architecture for easily incorporating scripting into Java applications and applets
• Applications independent and not bound to a single scripting language
• Different language scripts can access Java objects using wsadmin
o Current supported languages for wsadmin:
• Jacl - Java Command Language based on Tcl scripting
Tool 4: wsadmin
How is it different from wscp?
o o o
The WebSphere objects are completely different from wscp Tcl is eas to learn, but wsadmin is complexy
Separates static configuration from dy amic changesn
Ty ically used for bulk and repeatable tasks, e.g.:
p
o Add a set of definitions in a repeatable manner
o Change the value of an environment variable on all servers in all cells
Can do every hing in the Admin Console, but not in a necessarily
t
manner
wsadmin: JMX MBeans
wsadmin acts as an interface to Java objects for access by scripts
o Objects communicate with MBeans (JMX management objects)
Objects perform different operations. There are four built-in objects:
o $AdminConfig (Jacl) or AdminConfig(Jy hon)t •Create or change the WebSphere configuration
o $AdminApp (Jacl) or AdminApp (Jy hon)t •Install, modify or administer applications,
o $AdminControl(Jacl) or AdminControl (Jy hon)t
•Work with live running objects and perform traces and data ty e conversionp
o $Help (Jacl) or Help (Jy hon)t
•Display general help information and details about which MBeans are running
Separation between Configuration and Control
wsadmin MBean MBean MBean H elp Admin App AdminConfig AdminControl MBean Script Script
wsadmin: Sty e of usage
l
Command line / script
Three modes of operation:
o o o
interactive
single command (-c option) run a script (-f option)
Connect over SOAP or RMI
P ss language identifier to wsadmin command – Jacl assumeda Access configuration resources using AdminConfig. In Jacl:
o set id [$AdminConfig getid <name>]
o $AdminConfig modify $id {{name fred} {desc “fred bloggs”}}
And in Jy hon:t
o id = AdminConfig.getid(<name>)
o AdminConfig.modify(id, “[[name fred], [desc ““fred bloggs””]]”
Configuration names look like this:
o /Cell:ajs_cell/Node:ajsnode/Server:server1/
wsadmin: Sty e of usage (2)
l
Access runtime resources using
AdminControl. In Jacl:
o set mbeanId [$AdminConfig getObjectName $id]
o $AdminControl invoke $mbeanId getState
And in Jy hon:
t
o mbeanId = AdminConfig.getObjectName($id)
o AdminControl.invoke(mbeanId, getState)
Runtime names look like this:
o WebSphere:platform=common,cell=ajs_cell,version=5.0.1,name=NodeAgen
t,mbeanIdentifier=NodeAgent,type=NodeAgent,node=ajsnode1,process=no deagent
wsadmin: Some Operations and Functions
$AdminConfig o o o o o o o o o o o o o o o o o o o attributes convertToCluster create createClusterMember createUsing emplateT defaults getid getObjectName installResourceAdapter list listTemplates modify parents reset save show showall showAttribute ty esp $AdminApp o o o o o o o o o o o o o deleteUserAndGroupEntries edit editInteractive export exportD LD install installInteractive list listModules options publish SDW L taskInfo uninstall $AdminControl o o o o o o o o o o o o o o o o o o o completeObjectName getAttribute getAttributes getCell getConfigId getHost getMBeanCount getNode getP rto getTy ep invoke makeObjectName query amesN setAttribute setAttributes startServer stopServer testConnection trace $Help o o o o o o o o o o o attributes operations constructors description classname all AdminControl AdminApp AdminConfig wsadmin messagewsadmin: Miscellaneous
Commands are case-sensitive
Configuration changes not persisted until "save" call
If multiple scripts or clients (Administrative Console) are saving
configuration changes at the same time, exception thrown on
Save call
o No changes will be persisted
Upon "save" call, validation procedure verifies updates
o Create two servers with the same name throws exception
wsadmin -f "
xxxxx
" much faster than wsadmin -c "
xxxxx
o Better to run multiple commands in a file than individual commands
o Call "save" in file periodically to persist configurations updates
wsadmin: Installing an Application
Use $AdminApp
Can use interactively inside a command
Can get the configurable options from an EAR file
o $AdminApp options myapp.ear
Then can get the task information for each option:
o $AdminApp taskInfo myapp.ear MapWebModToVH
Could then use this info to help build the relevant options for installation:
o $AdminApp install myapp.ear {-appname freda -MapWebModToVH
{{{Default Application} default_app.war,WEB-INF/web.xml myvhost}} -<lots of other options . . .>}
wsadmin: Example Code
JACL Code:
o sample_wsadmin.tcl (about 90 lines)
o sample_wsadmin_install.tcl (about 25 lines)
Jy hon Code:t
o sample_wsadmin.py (about 90 lines)
Reset before running:
o sample_ wan_reset_wsadmin.bats
Run JACL:
o sample_wsadmin_jacl.bat
o sample_wsadmin_install_jacl.bat
Reset before running:
o sample_ wan_reset_wsadmin.bats
Run Jy hon:t
Jacl is better than Jy hon is better than Jacl
t
Not that different
If y u can program in one y u can probably program in the other
o
o
Jacl may suit shell script programmers
Jy hon may suit those with OO background
t
Tool 5: ws_ant (ANT)
What is it?
o ANT – Java-based, platform- eutral, open source build tooln
o ws_ant: Copy of Apache ANT with task extensions to support WebSphere-specific capabilities
Main Features:
o Tasks provided include:
• • •
Install and uninstall applications Start and stop servers
Run administration scripts or commands
o But the admin task is just a call to wsadmin – y u still have to write theo wsadmin code to do the actual configuration
o Main advantage is ability to build the EAR, run a configuration script and then install the EAR, all from a single ws_ant build.xml.
ws_ant: Sty e of Usage
l
Command-oriented
Specify tasks, targets and dependencies between targets
Connect over SOAP or RMI
ws_ant: Example Code
Code:
o build.xml (45 lines) o sample.props (20 lines)Reset:
o sample_ wan_reset_wsadmin.batsRun it:
o sample_wsant_wsadmin.bat o sample_wsant_install.batTool 6: WsAdmin Automation P atform (WAP
l
)
What is it?
o Set of utility functions sitting over wsadmin
o Eases a lot of wsadmin hassle
Main features:
o o o o
Available from IBM Techdoc , the Tech ical Sales Librarys n Not supported by IBM: provided “as is”
Greatly simplifies many wsadmin scripting tasks
P ovides a library of Tcl procedures for creating, modify ng and deleting WebSpherer i objects (e.g. application servers, data sources)
o Runs on 5.0 and 5.1
o Sy tax (on Windows):n
• • • set WAP_SOURCE=/installed/wap set PATH=%PATH%;%WAP_SOURCE% jwap.bat
WAP Sty e of usage
:
l
Command line / script
Runs over wsadmin, so:
o Three modes of operation:
• • •
interactive
single command (-c option) run a script (-f option)
o Connect over SOAP or RMI
Jacl only (not Jy hon)
t
Set subsequent commands’ scope:
o setNode ajsnode1
o setServer server1
P ovides a number of Jacl procedures named:
r
o createXXX, removeXXX, modifyXXX
o e.g. createCustomService, modifyJDBCProvider
WAP Sty e of usage (2)
:
l
Names become simpler (no need for
/Cell:xxx/Node:xxx/Server:xxx/)
Not all documented:
o getIDByListing & modifyConfigObject are not documented but very useful
Mainly aimed at create/ odify delete
m
/
o little support for display & list
WAP Example Code
:
Code:
o sample_wap.tcl (c90 lines)Reset:
o sample_ wan_reset_wsadmin.batsRun it:
o sample_wap.batWAP Installing an application
:
Use the installApplication command
P ss customisations in same way as wsadmin’sa $AdminApp install:
installApplication -appname fred -earfile
/installed/websphere/appserver/base5.1/installableApps/ivtApp.ear \ {-MapModulesToServers {{{IVT Application}
ivt_app.war,WEB-INF/web.xml WebSphere:cell=ajs_cell,node=ajsnode1,server=server1}}}
-interact option to customise by answering questions (could ’t get this to work)n
Can install then customise afterwards using the editApplication command Not really any different from $AdminApp
Tool 7: JMX
What is it?
o Java Management Extensions (JMX) is a framework oriented at managing applications and resources (like application servers)
• • •
Allows for exposing y ur application to remote or local management toolso JMX is a specification oriented to the application and network management P rt of J2SEa
Main Features:
o Some of the JMX functionality:
• • •
Allows y u to query the configuration settings and change them at runtimeo P ovides services such as monitoring, event notification, timers,r ....
Allows y u to load, initialize, change, and monitor application components ando resources
o Structured in three lay rs:e
• • •
Instrumentation lay r - MBeanse
Agent lay r - MBeanServer and agentse
Distributed Services (this part is still out of the scope of the current level of the spec )s
About JMX: How does JMX work?
Resources are managed by Managed Beans (MBeans)
o These are simple JavaBeans that perform operational or configuration changes on resources
MBeans provide AP s to the external world to manage its resourcesI
o Each JMX-enabled JVM contains a MBean Server (Managed Bean Server) that registers all the MBeans in the s stemy
• MBean Server provides access to all of its registered MBeans
o External programs access MBeans registered on the MBean Server via Connectors/Adapters
Resources JVM
JMX Benefits
Enables Java applications to be managed without heavy investment
o Relies on a core managed object server that act as a ‘management agent’
o Java application simply needs to embed a managed object server and make some of its
functionality available as one or several Manageable Beans registered in the object server
P ovides a scalable management architecturer
o Every JMX agent service is an independent module that can be plugged into the management agent
Integrates existing management solutions
o JMX smart agents are capable of being managed through HTML browsers or by
various management protocols such as Web Services, JMS, SNMP etc.,
JMX: Architectural P inciples
r
MBean Server
Connector Adapter Agent Services (as MBeans) AgentServices ServicesAgent
Resource 1 MBean Manages Resource 2 MBean Manages Management Application Instrumentation Layer Agent Layer
WebSphere JMX Architecture
All WebSphere 5.0 processes run the JMX agent
All WebSphere 5.0 runtime administration is done through JMX
W ebSphere Application Server Process MBean Server MBean Proxy MBean Proxy HTTP JMX Adapter MBeans MBeans SNMP JMX Adapter RMI/IIOPJMX Connector SOAP JMX Connector internal runtime objects External MBeanServer
External tools and programs
Internal MBeans register with local MBeanServer.
External MBeans have local proxy to their MBeanServer. Proxy registers with local MBeanServer.
Illustrates possibilities or future plans
WebSphere Distributed Administration
Node Mgr
MBean Server
Clients, Multi-cell mgmt, & other EMS
(Tivoli, BMC) MBean Proxy App Server tmx4j MBean MBean Proxy JMX Connector config files MBean MBeans MBeans JMX Connector MBean Server MBean Proxy MBean Proxy JMX Connector MBeans MBeans Deployment Mgr Config Distribution Service Config Repository Service To Other App Servers To Other Nodes Master files Master files Master files
JMX: Some MBeans
Cell Node ManagedObject ApplicationServer ServerCluster JMSServer Application, EJBModuleConfig, WebModuleConfig EJBContainer, WebContainer ListenerP rto JMSP oviderr JMS onnectionFactoryC JMSDestination J2 ResourceAdapterC J2 ConnectionFactoryC JavaMailP oviderr MailSession URLP oviderr URL JDBCP oviderr DataSource, WAS40DataSource ConnectionP olo OR P uginB l JavaVirtualMachine Security ermissionP NameServer LocalOSUserRegistryThese Mbeans are built into WebSphere – 224
How Can Customers Use JMX?
All WAS 5.0 Admin client programs use JMX
o o o o
Web Admin console wsadmin scripting Admin Client Java API
Included in both B se App Server package and Advanced Deploy enta m
Use the AP s to control WebSphere runtimeI
Extend the set of managed objects with custom JMX MBeans
Attach Admin clients to Cell Manager in order to access entire Admin domain Node Agents start & monitor individual App Servers
JMX: Example Code
Code:
o sample_jmx.java (c160 lines)Reset:
o sample_ wan_reset_wsadmin.batsRun it:
o sample_jmx.batTool 8: SWAN
What is it?
o Simplified WebSphere AdministratioN
o Greatly eases wscp and wsadmin hassle
Main features:
o o o o o o oRuns in wscp and wsadmin Obtainable from the author
Runs on WebSphere v4, v5, v5.1
Runs on Windows, AIX (probably all UNIXes) and z/OS Simplifies writing wscp and wsadmin scripts
Simplifies interactive access
SWAN Sy tax
n
<class> <verb> [<object>] [<options>] [<attributes>]
Examples:
o o o o o o o o o appserv listdsource list –format -short jcafact delete jack –ra jill
resadapt create ada –rarfile /usr/product/somefile.rar cluster show clouseau +maxheap +minheap
appserv show jeeves +webhttpbacklog –constraint {Host * P rt 9080}o
appserv modify jeeves +webhttpbacklog 53 –constraint {Host * P rt 9080}o appserv modify –constraint {Host * P rt 9080} +webhttpbacklog 57 jeeveso jmsdest exists jack –jmsprov jill
SWAN is better than wscp/wsadmin is better than SWAN
In wscp/wsadmin y u have to know how to reach a particular
o
o Not a problem for many cases
• e.g. JDBCP ovider has no attribute hierarchyr
o Big problem for server groups and application servers
• have to understand the hierarchy to navigate through it
o SWAN solves this by hiding the hierarchy
In wscp/wsadmin y u have long names:
o
o Long names for configuration and runtime objects
o Much of which is probably constant in y ur script (e.g. cell name & nodeo name)
o SWAN solves this by setting a scope and providing the – hort options
In wscp/wsadmin y u need long Tcl lists to set attributes:
o
SWAN is better than wscp/wsadmin is better than SWAN
SWAN does not implement all of the object ty es:
p
o o o
There are 224 in wsadmin in v5.1
SWAN implements the most commonly used object ty esp
SWAN can be extended to implement the others – easily if they follow the patterns of the current SWAN ty esp
o You can alway use the wsadmin ty es directly in y ur scriptss p o
SWAN is not supported by IBM:
o SWAN is provided as is
SWAN: Further Examples
Getting help:
o o o o o o o o o o help dsource help jdbcdrv help create jcafact attributesjcafact attributes -details
cluster create clouseau -member sellers –vertical 3 cluster showmembers clouseau
appserv makecluster jeeves –cluster wooster cluster start wooster
SWAN: Coverage
Resource adapters resadapt JMS connection factories jmsfact Generic JMS providers jmsprov Java mail mail Node agents nagent J2 connection factoriesC jcafact Virtual hosts vhost JMS destinations jmsdest JDBC drivers (providers) jdbcdrv Enterprise applications entapp Data sources dsourceClusters (server groups) cluster
Domain or cell cell
Application servers appserv
Installing enterprise applications using SWAN
P ckager or Deploy r runs "entapp produceaid":
a
e
o Creates an XML file called an nterpriseE Archive pplication nstallationA I
Descriptor (EAR AID)
o EAR AID houses all of the deployable options from the EAR file's deploy ent descriptorsm
Intention is that the Deploy r then edits this file using an
e
editor to set appropriate values (as would be done through the console)
Deploy r then runs "entapp create":
e
o takes the EAR file and uses the AID file to install the enterprise app
o same procedure whether v4 or v5, but different EAR AID file
Non-SWAN software available to produce an Excel spreadsheet
containing the EAR AID file, and to transform it back
SWAN: Example Code
Code:
o sample_ wan.tcls (25 lines, does both v4 and v5)
Reset:
o sample_ wan_reset_wscp.bats o sample_ wan_reset_wsadmin.batsRun it:
o sample_ wan_wscp.bats o sample_ wan_wsadmin.batsSWAN Internals: Code Size
1500 Other common code
11,400 Total non-com entary codem
4,300 P us comment linesl 900 Common v5 code 1400 Common v4 code 3600 v5 code 3700 v4 code 800 Configuration files
# lines non-com entary codem File Type
Configuration & Deploy ent Using SWAN (1)
m
P oject-Specificr
Configuration Spreadsheet iwf_acm iiw_app.c g.xls_ f
.ear .zip ArtefactsOther Default Configuration Spreadsheet 1 P CSV 2 Release Note
Edit in Excel
Configuration & Deploy ent Using SWAN (2)
m
.ear
3
4
entapp
produceaid
EARAIDGenerate
Spreadsheet
5
Edit in Excel
P oject-Specificr6
P CSV AID Spreadsheet iwf_acm iiw_ap_ p.xlsConfiguration & Deploy ent Using SWAN (3)
m
7
9
Generator
P oject-Specific Configuration Spreadsheet r Configuration scripts Configuration scripts Configuration scripts.ear .zip ArtefactsOther ReleaseNote EditedEAR AID
zip
P ckagea P CSV AID Spreadsheet Generator8
Configuration & Deploy ent Using SWAN (4)
m
P ckagea Tivoli SoftwareDistribution
P ckage on node A a 10 Configurator Configuration scripts Configuration scripts Configuration scripts 12 .ear EditedEAR
AID 13 14 i..edApps EAR 15 Node A Tivoli Software Distribution 11
Tool 9: J2EE 1.4 Management and Deploy ent
m
What is it?
o J2EE 1.4 AP s for product-independent configuration & deploy entI m
Main features:
o No standard up to J2EE 1.3
o J2EE 1.4 (WebSphere v6) introduces:
• J2EE Management Specification (JSR-77)
• ability to configure and control J2EE objects in a Java-application-server-independent manner
• J2EE Deploy ent Specification (JSR- 8)m 8
• ability to install enterprise applications in a Java-application-server-independent manner
• wsadmin still works
• write programs to these spec to lessen vendor lock-ins
•
• • • •
many configuration/ eploy ent possibilities:d m Admin Console
wsadmin scripts in Jacl and Jy hont P ograms written to the JMX APr I
Comparison: Lines of code
4 ? ? 25 75 20 Installation 6 50 ? 30 8 (but displays every hingt ) 30 Display 3 40 ? 23 43 Transport 6 35 19 24 60 16 Environment 2 9 45 (plus wsad min) 6 4 2 Heap sizes SWAN JMX ws_ant wsadmin Jy hont wsadmin Jacl XmlConfig wscpSummary
References
o “IBM WebSphere Sy tem Administration” by Leigh Williamson et al (ISBN: 0-s 13-144604-5)
o “IBM WebSphere Deploy ent and Advanced Configuration” bym B rcia Hines/Alcott/Botzum (ISBN: 0-13-146862-6)a /
o WAP:
• http://www-1.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/PRS981
o SWAN:
