Generated by Jive on 2013-03-22+01:001

Tobias Winterhalter's Blog: Command linecontrol for SAP Web Dispatcher

Posted by Tobias Winterhalter Mar 21, 2013

Web Dispatcher installations typically come in two variants: with and without SAP Start Service. The availability ofcommand line control tools is slightly different between these two installation types. In this article, I want to exploresome of the available tools and introduce a third-party (non-SAP) tool.

Standard toolsThese are the tools that stand-alone and SAP Start Service installations have in common:

Controlling the sapwebdisp process with signals

The following signals can be sent to the sapwebdisp process:USR1 Lowers the current trace level by oneUSR2 Raises the current trace level by oneINT

Shutdown (If the sapwebdisp process is controlled by the SAP Start Service, a new process will likely be started

immediately.)

To send a signal on Unix systems, you can use the regular kill command. On Windows, you can use the programsapntkill.exe which is part of each Web Dispatcher installation, e.g.:

sapntkill.exe -USR2 <pid>

Obviously, this method is only available locally on the machine on which the process is running.

Using the monitoring tool wdispmon

The wdispmon executable is part of any Web Dispatcher installation. It attaches to the sapwebdisp process throughshared memory and can therefore be used only locally. There are two ways to employ wdispmon: as a commandline tool and in an interactive menu-driven mode. Since I am focusing on command line controls for Web Dispatcher,I will not go into details about the interactive mode. Essentially, the interactive mode has the same functionality asthe Web Admin Interface. This includes but is not limited to: increasing/decreasing the trace level and resetting thetrace file, viewing overall and thread status, as well as some statistics, displaying and changing profile parameters,displaying and resetting session tables. The command line mode is much more limited and offers the followingfunctions:

Usage: wdispmon<options> pf=<profile>with the following options: -version Display version info and

exit -info Return status of ICM/WebDisp through shared memory -ping Return status of

ICM/WebDisp with request/response -checkhealth Attach to ICM/WebDisp and return in case of error

-a Maintain authentication file -function <function> call monitoring function (like sapcontrol)

ICMGetThreadList ICMGetConnectionList ICMGetConnectionList2 ICMGetProxyConnectionList

ICMGetCacheEntries ICMGetAllCacheEntries

The -function option offers fewer commands than sapcontrol (see SAP Start Service below.) The -a option is actuallynot a real command line option because it will launch another interactive mode to maintain users and groups in the

Tobias Winterhalter's Blog: Command line control for SAP Web Dispatcher

Generated by Jive on 2013-03-22+01:002

authentication file (usually: icmauth.txt.) One option that is unique to wdipmon is -checkhealth: when started withthis option, wdispmon will attach to the sapwebdisp process and will block and wait until the sapwebdisp processterminates (for whatever reason.) This might be useful in scripting environments to detect Web Dispatcher downsituations.

SAP Start Service

The SAP Start Service framework contains a tool called sapcontrol, which adds a few more possibilities for commandline control. sapcontrol -h will print the list of all known commands, but only a limited number actually makes sensefor Web Dispatcher. Some of them are related to the start service itself.

SYNOPSIS sapcontrol [-prot <protocol>] [-trace <filename>] [-debug] [-user <user>

<password>] [-queryuser] [-repeat <N> <D>] [-format <format>] [-host

<hostname>] -nr <instance number> -function <webmethod> [parameter list] DESCRIPTION

Control and monitor SAP instances via WebService interface of SAP Start Service. OPTIONS -prot

<protocol> Specify the protocol for the communication with the SAP instance. Available protocols

are: NI_HTTP HTTP using SAP NI sockets (default, prefer Unix domain sockets) NI_HTTPS

HTTPS using SAP NI sockets (prefer Unix domain sockets) GSOAP_HTTP HTTP using gsoap build in

sockets WINHTTP HTTP using Windows winhttp WINHTTPS HTTPS using Windows winhttp

PIPE Windows named pipes (on Unix same as NI_HTTP) -trace <filename> Trace SOAP request/

response -debug Write local trace to stderr -user <user> <password> OS user and password for

Webservice authentication -queryuser Query interactively for user and password -repeat <N> <D>

Repeat webmethod call <N> times (-1=forever) with <D> sec delay -format <format> Specify the format for

the output of the webmethod. Available formats are: list List output format (default) script Script

output format -host <hostname> Host to connect to (default: localhost)

Here is a list of "webmethods" that are useful for the control of Web Dispatcher:

command description

StartService <SID> Launches the start service. The Web Dispatcherinstance must be started separately.

StopService Stops the start service, but not the Web Dispatcherinstance.

RestartService

StartSystem A Web Dispatcher system usually consists of onlyone instance, so this command is equivalent toInstanceStart.

StopSystem Usually equivalent to InstanceStop.

RestartSystem

GetSystemInstanceList [<timeout sec>] Prints a list of instances known to this system.

InstanceStart <hostname> <instance number> Starts the instance with the given hostname andinstance number.

InstanceStop <hostname> <instance number>[<softtimeout sec>]

Stops the instance with the given hostname andinstance number.

RestartInstance [<softtimeout sec>]

Tobias Winterhalter's Blog: Command line control for SAP Web Dispatcher

Generated by Jive on 2013-03-22+01:003

GetProcessList Prints info about the sapwebdisp process, e.g. runningstatus and pid.

SendSignal <pid> <signal> Sends an OS signal to the sapwebdisp process. The pidcan be determined with GetProcessList. See previoussection for a list of valid signals.

GetVersionInfo Determines release and patch level for Web Dispatcherand Start Service.

GetEnvironment Prints a list of the environment variables used by theWeb Dispatcher system.

GetStartProfile Prints the start profile that is used by the start service.

ParameterValue [<parameter>] Prints a list of all profile parameters or one specificparameter.

GetAccessPointList Prints a list of access points (ports), including those ofthe start service.

GetQueueStatistic Prints request queue statistics (peak, max).

ICMGetThreadList Prints the status of all sapwebdisp threads, including themain thread, watchdog thread, and worker threads.

ICMGetConnectionList Prints a list of current front-end connections. (This doesnot include the connections to the back-end applicationservers.)

ICMGetCacheEntries Prints a list of cached entries (in case the WebDispatcher has an active cache handler.)

WebDispGetServerList Prints a list of back-end application servers.

ListDeveloperTraces Prints a list of developer traces, including their file sizeand last modified time stamp.

ReadDeveloperTrace <filename> <filesize> Downloads and prints the specified developer trace.

ABAPReadSyslog Prints the content of the SYSLOG.

ABAPReadRawSyslog Prints the unformatted content of the SYSLOG.

sapcontrol usually connects to the SAP Start Service over TCP/IP. It is therefore possible to control Web Dispatcherremotely by using the -host parameter. The sapcontrol executable does not have any dependencies and can beeasily copied to other machines.

Third-party toolsThe available standard tools are still missing a few features that could sometimes be useful, such as activating/deactivating specific application servers or ports, or putting the Web Dispatcher into maintenance mode. That is whyI decided to write a simple Python application that provides some of these missing features.

wdcontrol

The idea is to connect to the Web Admin Interface that is usually available for each Web Dispatcher. This interface isaccessed through a specific URL prefix, such as /sap/wdisp/admin or /sap/admin (see profile parameter icm/HTTP/admin_0). Using this method to "web scrape" the Admin Interface has advantages and disadvantages:

+ remote control over the network

Tobias Winterhalter's Blog: Command line control for SAP Web Dispatcher

Generated by Jive on 2013-03-22+01:004

+ one tool can attach to multiple Web Dispatcher installations

+ all commands available through the Admin Interface could be used

- the stability of the application depends on the stability of the Admin Interface; each time theinterface changes, the application might require adaption or fail to work

- there is no official support by SAP

wdcontrol can be downloaded here: https://github.com/wtobia/wdcontrolusage: wdcontrol.py [-h] [--command {info,...}] [--node NODE] [--stack

{ABAP,J2EE,BOTH}] [--sid SID] [--port PORT] [--admin ADMIN] [--proxy PROXY] [--log

{ERROR,WARN,INFO,DEBUG,OFF}] [--version] [conf [conf ...]] positional arguments: conf

Configuration file(s) (default: wdcontrol.wdc) optional arguments: -h, --help show this help message and

exit --command {info,...} Command (default: info) --node NODE Server node name (for

'isNodeActive' etc.) --stack {ABAP,J2EE,BOTH} Stack type (default: BOTH) --sid SID

System ID (default: None) --port PORT Port number (for 'isPortActive' etc.) --admin ADMIN Web

Admin Interface URL (format: http|https://user:pass@host[:port][/prefix]) --proxy PROXY HTTP proxy used to

connect to Web Admin Interface (format: host:port; default: None) --log {ERROR,WARN,INFO,DEBUG,OFF} log

level (default: INFO) --version Print version information and exit

wdcontrol is designed to be called with either command line arguments, configuration files, or a combination of both.The built-in help (wdcontrol.py -h) provides detailed information about all command line arguments and configurationparameters. A typical scenario would be the following configuration:

• All parameters for the connection to the Admin Interface go into the default configuration filewdcontrol.wdc:

{

"admin.host": "my.wd.host.com",

"admin.port": 8000,

"admin.password": "secret"

}

• All parameters to identify a specific instance go into one configuration file for each instance, e.g.DEV_J2EE3565100.wdc:

{

"node.name": "J2EE3565100",

"node.stack": "J2EE",

"system.id": "DEV"

}

• Now it is easily possible to control instance related functions by using the configuration file and anappropriate command.

Tobias Winterhalter's Blog: Command line control for SAP Web Dispatcher

Generated by Jive on 2013-03-22+01:005

N.B.: The default configuration file wdcontrol.wdc does not have to be specified, as it is loadedautomatically. Examples:wdcontrol.py DEV_J2EE3565100.wdc --command isNodeActive

All other commands that are not related to a specific instance can skip the configuration file. Examples:wdcontrol.py --command refresh

wdcontrol.py --commmand isPortActive --port 8000

List of currently supported commands:

command description

info Prints the status info for Web Dispatcher.

enterMaintenance Puts the Web Dispatcher into maintenancemode.

leaveMaintenance Puts the Web Dispatcher into normal mode.

refresh Triggers a refresh of the configuration(server info, ...)

shutdown Sends a shutdown command to theWeb Dispatcher. This will terminate thesapwebdisp process. If Web Dispatcher iscontrolled by SAP Start Service, it will likelybe restarted immediately.

downloadDefaultProfile Downloads and prints the default profile.

downloadInstanceProfile Downloads and prints the instance profile.

traceLevel0, traceLevel1, traceLevel2,traceLevel3

Sets the trace level to 0, 1, 2, or 3, thenprints the current level.

downloadTrace Downloads and prints the trace filedev_webdisp.

listPorts Prints a JSON formatted list of all knownports.

isPortActive Prints 'True'/'False' if the port is active/inactive.

activatePort Activates the port, then prints its status (see'isPortActive'.)

deactivatePort Deactivates the port, then prints its status(see 'isPortActive'.)

listNodes Prints a JSON formatted list of all knownapplication servers.

Tobias Winterhalter's Blog: Command line control for SAP Web Dispatcher

Generated by Jive on 2013-03-22+01:006

isNodeActive Prints 'True'/'False' if the application serveris active/inactive.

activateNode Activates the application server, then printsits status (see 'isNodeActive'.)

deactivateNode Deactivates the application server, thenprints its status (see 'isNodeActive'.)

The printed output of most of the commands is designed to be used in scripting environments. Complex data forexample is formatted in JSON, which is both human readable and easily consumed by calling applications.

SummaryThere are quite a few standard command line tools available to control SAP Web Dispatcher, both locally andremotely. However, the most powerful tools that offer the most comprehensive set of features work only in aninteractive mode, such as wdispmon and the Web Admin Interface. That is why I decided to write wdcontrol, whichconnects to the Web Admin Interface and could eventually provide the same functionality in the command line. Sofar, the program is a first version with a limited set of commands. New commands can be added on demand.

Further Reading

• SAP Web Dispatcher• Using Command Line Program “wdispmon”• SAP Start Service• wdcontrol - command line control interface for SAP Web Dispatcher

17 Views Tags: web_dispatcher

Mar 22, 2013 9:46 AM Andy Silvey

Hi Tobias,

that's an interesting blog.

We've written our own scripts for the simplest tasks of stopping and starting WebDispatchersbut still use the Web Interface for removing Instances etc.

Thanks,

Tobias Winterhalter's Blog: Command line control for SAP Web Dispatcher

Generated by Jive on 2013-03-22+01:007

Andy.