Technical Articles

March 21, 2013 7 minute read

Command line control for SAP Web Dispatcher

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

Standard tools

These 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 one

USR2         Raises the current trace level by one

INT          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 program sapntkill.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 through shared memory and can therefore be used only locally. There are two ways to employ wdispmon: as a command line 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 as the Web Admin Interface. This includes but is not limited to: increasing/decreasing the trace level and resetting the trace 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 following functions:

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 actually not a real command line option because it will launch another interactive mode to maintain users and groups in the authentication file (usually: icmauth.txt.)

One option that is unique to wdipmon is -checkhealth: when started with this option, wdispmon will attach to the sapwebdisp process and will block and wait until the sapwebdisp process terminates (for whatever reason.) This might be useful in scripting environments to detect Web Dispatcher down situations.

SAP Start Service

The SAP Start Service framework contains a tool called sapcontrol, which adds a few more possibilities for command line control. sapcontrol -h will print the list of all known commands, but only a limited number actually makes sense for 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 Dispatcher instance must be started separately.
StopService	Stops the start service, but not the Web Dispatcher instance.
RestartService
StartSystem	A Web Dispatcher system usually consists of only one instance, so this command is equivalent to InstanceStart.
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 and instance number.
InstanceStop <hostname> <instance number> [<softtimeout sec>]	Stops the instance with the given hostname and instance number.
RestartInstance [<softtimeout sec>]
GetProcessList	Prints info about the sapwebdisp process, e.g. running status and pid.
SendSignal <pid> <signal>	Sends an OS signal to the sapwebdisp process. The pid can be determined with GetProcessList. See previous section for a list of valid signals.
GetVersionInfo	Determines release and patch level for Web Dispatcher and Start Service.
GetEnvironment	Prints a list of the environment variables used by the Web 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 specific parameter.
GetAccessPointList	Prints a list of access points (ports), including those of the start service.
GetQueueStatistic	Prints request queue statistics (peak, max).
ICMGetThreadList	Prints the status of all sapwebdisp threads, including the main thread, watchdog thread, and worker threads.
ICMGetConnectionList	Prints a list of current front-end connections. (This does not include the connections to the back-end application servers.)
ICMGetCacheEntries	Prints a list of cached entries (in case the Web Dispatcher has an active cache handler.)
WebDispGetServerList	Prints a list of back-end application servers.
ListDeveloperTraces	Prints a list of developer traces, including their file size and 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 Dispatcher remotely by using the -host parameter. The sapcontrol executable does not have any dependencies and can be easily copied to other machines.

Third-party tools

The 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 why I 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 is accessed 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

+ 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 the interface 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/wdcontrol

usage: 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 configuration parameters.

A typical scenario would be the following configuration:

All parameters for the connection to the Admin Interface go into the default configuration file wdcontrol.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 an appropriate command.
N.B.: The default configuration file wdcontrol.wdc does not have to be specified, as it is loaded automatically. 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 maintenance mode.
leaveMaintenance	Puts the Web Dispatcher into normal mode.
refresh	Triggers a refresh of the configuration (server info, …)
shutdown	Sends a shutdown command to the Web Dispatcher. This will terminate the sapwebdisp process. If Web Dispatcher is controlled by SAP Start Service, it will likely be 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, then prints the current level.
downloadTrace	Downloads and prints the trace file dev_webdisp.
listPorts	Prints a JSON formatted list of all known ports.
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 known application servers.
isNodeActive	Prints ‘True’/’False’ if the application server is active/inactive.
activateNode	Activates the application server, then prints its status (see ‘isNodeActive’.)
deactivateNode	Deactivates the application server, then prints its status (see ‘isNodeActive’.)

The printed output of most of the commands is designed to be used in scripting environments. Complex data for example is formatted in JSON, which is both

human readable and easily consumed by calling applications.

Summary

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