Pacific

Application Server for

OpenEdge :
Administration Guide

Notices
2014 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.
These materials and all Progress software products are copyrighted and all rights are reserved by Progress Software Corporation. The information in these materials is subject
to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear therein. The references in these materials to specific
platforms supported are subject to change.
Business Making Progress, Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirect XML Converters, DataDirect XQuery,
Easyl, Fathom, Making Software Work Together, OpenEdge, Powered by Progress, Progress, Progress Control Tower, Progress RPM, Progress Software Business Making
Progress, Progress Software Developers Network, Rollbase, RulesCloud, RulesWorld, SequeLink, SpeedScript, Stylus Studio, and WebSpeed are registered trademarks of
Progress Software Corporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, AppsAlive, AppServer, BusinessEdge, DataDirect Spy,
DataDirect SupportLink, , Future Proof, High Performance Integration, Modulus, OpenAccess, Pacific, ProDataSet, Progress Arcade, Progress Pacific, Progress Profiles,
Progress Results, Progress RFID, Progress Progress Software, ProVision, PSE Pro, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects,
SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, WebClient, and Who Makes Progress are
trademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or
its affiliates. Any other marks contained herein may be trademarks of their respective owners.
Please refer to the Release Notes applicable to the particular Progress product release for any third-party acknowledgements required to be provided in the documentation
associated with the Progress product.
The Release Notes can be found in the OpenEdge installation directory and online at:
https://community.progress.com/technicalusers/w/openedgegeneral/1329.openedge-product-documentation-overview.aspx.
For the latest documentation updates see OpenEdge Product Documentation on Progress Communities: (https://community.progress.com/technicalusers/w/openedgegeneral/
1329.openedge-product-documentation-overview.aspx).

December 2014

Last updated with new content: Release 11.5.0

Pacific Application Server for OpenEdge: Administration Guide

Notices

Pacific Application Server for OpenEdge: Administration Guide

Table of Contents
Preface.............................................................................................................9
Purpose...................................................................................................................................................9
Audience.................................................................................................................................................9
Organization..........................................................................................................................................10
Using this manual..................................................................................................................................10
References to ABL compiler and run-time features....................................................................10
References to ABL data types....................................................................................................11
Typographical conventions....................................................................................................................11
Examples of syntax descriptions...........................................................................................................12
Long syntax descriptions split across lines................................................................................14
Complex syntax descriptions with both required and optional elements....................................14
OpenEdge messages............................................................................................................................15
Obtaining more information about OpenEdge messages...........................................................15

Chapter 1: Overview of PAS for OpenEdge administration......................17

Administrative utilities............................................................................................................................18
TCMAN.......................................................................................................................................18
OEPAS........................................................................................................................................18
OpenEdge Management and OpenEdge Explorer.....................................................................19
JMX and JConsole.....................................................................................................................19
Administrative scripts..................................................................................................................19
Development servers compared to production servers.........................................................................22
Tomcat logging......................................................................................................................................22
Configuration and properties files.........................................................................................................23
Pacific Application Server properties.....................................................................................................24
Pacific Application Server directories....................................................................................................33

Chapter 2: Working with Instances.............................................................35

Overview of instances in PAS for OpenEdge .......................................................................................36
Instance management with TCMAN......................................................................................................37
Creating instances with TCMAN............................................................................................................38
Installing and running an instance as a UNIX daemon.........................................................................40
Installing and running an instance as a Windows service.....................................................................40

Chapter 3: Web application deployment and management......................43

Web application management with TCMAN..........................................................................................43
OpenEdge Web application deployment...............................................................................................44

Pacific Application Server for OpenEdge: Administration Guide

REST service deployment (deployREST.sh)..............................................................................44

SOAP service deployment (deploySOAP.sh)..............................................................................45
Packaging web applications..................................................................................................................45

Chapter 4: Security overview......................................................................47

Pacific Application Server production server customizations................................................................47
HTTPS support.....................................................................................................................................48
The Spring Security Framework in PAS for OpenEdge ........................................................................49
JVM security manager..........................................................................................................................49
Realms and roles..................................................................................................................................50
Managing users and roles for Manager and Host Manager applications...................................50
Remote access filters............................................................................................................................52
Development server and production server security issues..................................................................52

Chapter 5: Web application security configurations.................................55

Spring Security configuration templates................................................................................................56
Applying a Spring Security model to a Web application........................................................................58
Enabling Spring Security for APSV and SOAP Web applications.........................................................59
Updating apsv-basic.xml............................................................................................................60
Updating soap-basic-local.xml....................................................................................................61
Local configurations..............................................................................................................................62
Adding new users in local security configurations......................................................................62
Using Jacksum to generate hashed and salted passwords........................................................63
Access control in local security configurations...........................................................................64
SPA security configurations...................................................................................................................65
Creating an OERealm service interface.....................................................................................66
Updating the SPA configuration file............................................................................................68
SPA security considerations.......................................................................................................73
LDAP security configurations................................................................................................................75
SAML security configurations................................................................................................................76
Creating and configuring metadata files.....................................................................................77
Registering the metadata file with an Identity Provider..............................................................78
Updating the SAML configuration file.........................................................................................79
Container security configurations..........................................................................................................83
CORS support.......................................................................................................................................83
Adding CORS support................................................................................................................84
OECORSFilter properties...........................................................................................................87
Single sign-on (SSO) support in PAS for OpenEdge ............................................................................89
Configuring the ClientPrincipal...................................................................................................89
Enabling SSO for Web applications............................................................................................91

Chapter 6: TCMAN Reference......................................................................93

Using TCMAN........................................................................................................................................93

Pacific Application Server for OpenEdge: Administration Guide

The tcman command..................................................................................................................94

Extending TCMAN......................................................................................................................96
Manager actions....................................................................................................................................99
List deployed applications (list)...................................................................................................99
Display OS and server information (info)..................................................................................100
Deploy a Web application (deploy)...........................................................................................101
Undeploy a Web application (undeploy)...................................................................................102
Reload a Web application (reload)...........................................................................................103
Display detailed server status (status)......................................................................................104
Display memory leaks (leaks)...................................................................................................106
Start a Web application (enable)..............................................................................................106
Stop a Web application (disable)..............................................................................................107
Display global server resources (resources)............................................................................108
Display Web application HTTP sessions (sessions).................................................................109
Server actions.....................................................................................................................................110
Create an instance (create)......................................................................................................110
Delete an instance (delete).......................................................................................................112
Display and manage an instance's configuration (config)........................................................113
Display or modify the server features of an instance (feature).................................................115
Clean up or archive server log files (clean)..............................................................................117
Display server instances (instances)........................................................................................117
Register an instance for tracking (register)...............................................................................119
Stop tracking an instance (unregister)......................................................................................120
Start an instance (start)............................................................................................................121
Stop an instance (stop).............................................................................................................123
Display server, OS, and runtime version information (version).................................................124
Test a server configuration (test)..............................................................................................125
General actions...................................................................................................................................126
Display help (help)....................................................................................................................126
Display runtime environment information (env)........................................................................127

Chapter 7: REST API Reference for oemanager.war...............................129

Session management..........................................................................................................................130
Get session information............................................................................................................130
Get client information................................................................................................................131
Get current request information................................................................................................133
Get configuration properties.....................................................................................................134
Update configuration properties...............................................................................................135
Get runtime metrics..................................................................................................................136
Reset runtime metrics..............................................................................................................137
Cancel a request......................................................................................................................138
Terminate a session.................................................................................................................139
Agent management.............................................................................................................................140
List agents................................................................................................................................140

Pacific Application Server for OpenEdge: Administration Guide

Get agent status information....................................................................................................141

Get session metrics..................................................................................................................142
Get connection information.......................................................................................................143
Get request information............................................................................................................145
Get configuration properties.....................................................................................................149
Update configuration properties...............................................................................................150
Stop an agent...........................................................................................................................151
Transport management.......................................................................................................................152
Get transport configuration properties (SOAP/REST)..............................................................152
Update properties of a transport (SOAP/REST).......................................................................154
Enable or disable a transport (SOAP/REST)............................................................................155
Enable or disable a transport (APSV).......................................................................................156
Get runtime metrics of a transport (SOAP/REST)....................................................................157
Get runtime metrics of a transport (APSV)...............................................................................159
Reset runtime metrics for a transport (SOAP/REST)...............................................................160
Reset runtime metrics of a transport (APSV)...........................................................................161
List deployed services (SOAP/REST)......................................................................................162
Get information about a service (SOAP/REST)........................................................................163
Get configuration properties of a service (SOAP)....................................................................165
Deploy a new service (REST)..................................................................................................166
Deploy a new service (SOAP)..................................................................................................167
Update runtime properties of a service (SOAP).......................................................................168
Get runtime metrics for a service (SOAP)................................................................................169
Reset runtime metrics for a service (SOAP).............................................................................170
Enable or disable a service (SOAP).........................................................................................171
Remove a service (SOAP/REST).............................................................................................172
Application management.....................................................................................................................174
List ABL application information...............................................................................................174
Get information about a specific ABL application.....................................................................176
List Web applications deployed to an ABL application.............................................................178
Get information about a specific Web application.....................................................................180

Index............................................................................................................183

Pacific Application Server for OpenEdge: Administration Guide

Preface
For details, see the following topics:

Purpose

Audience

Organization

Using this manual

Typographical conventions

Examples of syntax descriptions

OpenEdge messages

Purpose

This is a guide to administering Pacific Application Server for OpenEdge that focuses on the
use of command line utilities (TCMAN) and management APIs (oemanager). For information on
administration with OpenEdge Management or OpenEdge Explorer, see OpenEdge Management:
Pacific Application Server for OpenEdge Configuration.

Audience
This manual is intended for any OpenEdge application server administrators or ABL developers
who need to create. configure, or administer instances of the Pacific Application Server for
OpenEdge.

Pacific Application Server for OpenEdge: Administration Guide

Preface

Organization
Overview of PAS for OpenEdge administration on page 17
Introduces the administrative tools and concepts for Pacific Application Server (PAS) for OpenEdge.
Working with Instances on page 35
Explains how to create and manage instances of the core PAS for OpenEdge server.
Web application deployment and management on page 43
Explains how to deploy, manage, and package PAS for OpenEdge Web applications.
Security overview on page 47
Provides an overview of security features and concepts in PAS for OpenEdge.
Web application security configurations on page 55
Explains how to implement Spring Security models, authentication and authorization protocols,
and single sign-on for Web applications deployed to a PAS for OpenEdge instance.
TCMAN Reference on page 93
A command reference for the TCMAN command line management utility.
REST API Reference for oemanager.war on page 129
An API reference describing the REST services that can be used to manage a PAS for OpenEdge
instance.

Using this manual

OpenEdge provides a special purpose programming language for building business applications.
In the documentation, the formal name for this language is ABL (Advanced Business Language).
With few exceptions, all keywords of the language appear in all UPPERCASE, using a font that is
appropriate to the context. All other alphabetic language content appears in mixed case.
For the latest documentation updates see the OpenEdge Product Documentation Overview page
on Progress Communities:
https://community.progress.com/technicalusers/w/openedgegeneral/
1329.openedge-product-documentation-overview.aspx .

References to ABL compiler and run-time features

ABL is both a compiled and an interpreted language that executes in a run-time engine. The
documentation refers to this run-time engine as the ABL Virtual Machine (AVM). When the
documentation refers to ABL source code compilation, it specifies ABL or the compiler as the actor
that manages compile-time features of the language. When the documentation refers to run-time
behavior in an executing ABL program, it specifies the AVM as the actor that manages the specified
run-time behavior in the program.

10

Pacific Application Server for OpenEdge: Administration Guide

Preface

For example, these sentences refer to the ABL compiler's allowance for parameter passing and
the AVM's possible response to that parameter passing at run time: "ABL allows you to pass a
dynamic temp-table handle as a static temp-table parameter of a method. However, if at run time
the passed dynamic temp-table schema does not match the schema of the static temp-table
parameter, the AVM raises an error. The following sentence refers to run-time actions that the
AVM can perform using a particular ABL feature: "The ABL socket object handle allows the AVM
to connect with other ABL and non-ABL sessions using TCP/IP sockets."

References to ABL data types

ABL provides built-in data types, built-in class data types, and user-defined class data types.
References to built-in data types follow these rules:

Like most other keywords, references to specific built-in data types appear in all UPPERCASE,
using a font that is appropriate to the context. No uppercase reference ever includes or implies
any data type other than itself.

Wherever integer appears, this is a reference to the INTEGER or INT64 data type.
Wherever character appears, this is a reference to the CHARACTER, LONGCHAR, or CLOB data
type.

Wherever decimal appears, this is a reference to the DECIMAL data type.

Wherever numeric appears, this is a reference to the INTEGER, INT64, or DECIMAL data type.
References to built-in class data types appear in mixed case with initial caps, for example,
Progress.Lang.Object. References to user-defined class data types appear in mixed case,
as specified for a given application example.

Typographical conventions
This manual uses the following typographical and syntax conventions:
Convention

Description

Bold

Bold typeface indicates commands or characters the user types,

provides emphasis, or the names of user interface elements.

Italic

Italic typeface indicates the title of a document, or signifies new

terms.

SMALL, BOLD CAPITAL

LETTERS

Small, bold capital letters indicate OpenEdge key functions and

generic keyboard keys; for example, GET and CTRL.

KEY1+KEY2

A plus sign between key names indicates a simultaneous key

sequence: you press and hold down the first key while pressing the
second key. For example, CTRL+X.

KEY1 KEY2

A space between key names indicates a sequential key sequence:

you press and release the first key, then press another key. For
example, ESCAPE H.

Pacific Application Server for OpenEdge: Administration Guide

11

Preface

Convention

Description

Syntax:
Fixed width

A fixed-width font is used in syntax, code examples, system output,

and file names.

Fixed-width italics

Fixed-width italics indicate variables in syntax.

Fixed-width bold

Fixed-width bold italic indicates variables in syntax with special

emphasis.

UPPERCASE fixed width ABL keywords in syntax and code examples are almost always
shown in upper case. Although shown in uppercase, you can type
ABL keywords in either uppercase or lowercase in a procedure or
class.
Period (.) or colon (:)

All statements except DO, FOR, FUNCTION, PROCEDURE, and REPEAT

end with a period. DO, FOR, FUNCTION, PROCEDURE, and REPEAT
statements can end with either a period or a colon.

[ ]

Large brackets indicate the items within them are optional.

[]

Small brackets are part of ABL.

{ }

Large braces indicate the items within them are required. They are
used to simplify complex syntax diagrams.

{}

Small braces are part of ABL. For example, a called external

procedure must use braces when referencing arguments passed by
a calling procedure.

A vertical bar indicates a choice.

...

Ellipses indicate repetition: you can choose one or more of the

preceding items.

Examples of syntax descriptions

In this example, ACCUM is a keyword, and aggregate and expression are variables:

Syntax
ACCUM aggregate expression

12

Pacific Application Server for OpenEdge: Administration Guide

Preface

FOR is one of the statements that can end with either a period or a colon, as in this example:
FOR EACH Customer NO-LOCK:
DISPLAY Customer.Name.
END.

In this example, STREAM stream, UNLESS-HIDDEN, and NO-ERROR are optional:

Syntax
DISPLAY

STREAM stream

][

UNLESS-HIDDEN

][

NO-ERROR

In this example, the outer (small) brackets are part of the language, and the inner (large) brackets
denote an optional item:

Syntax
INITIAL [ constant

, constant

A called external procedure must use braces when referencing compile-time arguments passed
by a calling procedure, as shown in this example:

Syntax
{ &argument-name }

In this example, EACH, FIRST, and LAST are optional, but you can choose only one of them:

Syntax
PRESELECT

EACH

FIRST

LAST

record-phrase

In this example, you must include two expressions, and optionally you can include more. Multiple
expressions are separated by commas:

Syntax
MAXIMUM ( expression , expression

, expression

] ...

In this example, you must specify MESSAGE and at least one expression or SKIP
and any number of additional expression or SKIP

Pacific Application Server for OpenEdge: Administration Guide

[(

n )

[(

n ) ,

] is allowed:
13

Preface

Syntax
MESSAGE

expression

SKIP

( n )

] } ...

In this example, you must specify {include-file, then optionally any number of argument or
&argument-name = "argument-value", and then terminate with }:

Syntax
{ include-file

argument

&argument-name = "argument-value"

] ...

Long syntax descriptions split across lines

Some syntax descriptions are too long to fit on one line. When syntax descriptions are split across
multiple lines, groups of optional and groups of required items are kept together in the required
order.
In this example, WITH is followed by six optional items:

Syntax

] [ expression DOWN ]
[ CENTERED ] [ n COLUMNS ] [ SIDE-LABELS ]
[ STREAM-IO ]

WITH

ACCUM max-length

Complex syntax descriptions with both required and

optional elements
Some syntax descriptions are too complex to distinguish required and optional elements by
bracketing only the optional elements. For such syntax, the descriptions include both braces (for
required elements) and brackets (for optional elements).
In this example, ASSIGN requires either one or more field entries or one record. Options
available with field or record are grouped with braces and brackets:

Syntax

{ [ FRAME frame ] { field [ = expression ] }

[ WHEN expression ] } ...
| { record [ EXCEPT field ... ] }

ASSIGN

14

Pacific Application Server for OpenEdge: Administration Guide

Preface

OpenEdge messages
OpenEdge displays several types of messages to inform you of routine and unusual occurrences:

Execution messages inform you of errors encountered while OpenEdge is running a procedure;
for example, if OpenEdge cannot find a record with a specified index field value.

Compile messages inform you of errors found while OpenEdge is reading and analyzing a
procedure before running it; for example, if a procedure references a table name that is not
defined in the database.

Startup messages inform you of unusual conditions detected while OpenEdge is getting ready
to execute; for example, if you entered an invalid startup parameter.
After displaying a message, OpenEdge proceeds in one of several ways:

Continues execution, subject to the error-processing actions that you specify or that are assumed
as part of the procedure. This is the most common action taken after execution messages.

Returns to the Procedure Editor, so you can correct an error in a procedure. This is the usual
action taken after compiler messages.

Halts processing of a procedure and returns immediately to the Procedure Editor. This does
not happen often.

Terminates the current session.

OpenEdge messages end with a message number in parentheses. In this example, the message
number is 200:
** Unknown table name table. (200)

If you encounter an error that terminates OpenEdge, note the message number before restarting.

Obtaining more information about OpenEdge messages

In Windows platforms, use OpenEdge online help to obtain more information about OpenEdge
messages. Many OpenEdge tools include the following Help menu options to provide information
about messages:

Choose Help > Recent Messages to display detailed descriptions of the most recent OpenEdge
message and all other messages returned in the current session.

Choose Help > Messages and then type the message number to display a description of a
specific OpenEdge message.

In the Procedure Editor, press the HELP key or F1.

On UNIX platforms, use the OpenEdge pro command to start a single-user mode character
OpenEdge client session and view a brief description of a message by providing its number.
To use the pro command to obtain a message description by message number:

Pacific Application Server for OpenEdge: Administration Guide

15

Preface

1. Start the Procedure Editor:

OpenEdge-install-dir/bin/pro

2. Press F3 to access the menu bar, then choose Help > Messages.
3. Type the message number and press ENTER. Details about that message number appear.
4. Press F4 to close the message, press F3 to access the Procedure Editor menu, and choose
File > Exit.

16

Pacific Application Server for OpenEdge: Administration Guide

1
Overview of PAS for OpenEdge
administration
To implement the Pacific Application Server, Progress-specific extensions were added to the
standard administrative scripts and configuration files of Apache Tomcat. In addition, Apache
Tomcat was extended to include new scripts, configuration files, and directories.
These extensions to the standard Apache Tomcat server were added in order to:

Automate the setting of environment variables.

Automate the configuration of the Pacific Application Server for specific Progress products (the
OpenEdge ABL Service, for example).

Re-configure Tomcat be primarily a production server rather than a development server. (An
advantage of the Pacific Application Server is that it simplifies deployment and administration.)
Note:
Do not modify any of the scripts or configuration files in the installed instance of the Pacific
Application Server located in $CATALINA_HOME. It is safer to create a new instance (using
$CATALINA_HOME/bin/ tcman.sh create). Edit files in the new instance, which is located
in $CATALINA_BASE. You will preserve the original files in case you need to restore anything.
Also note that the Windows versions of these scripts have the same file name, but have a .bat
extension.
For details, see the following topics:

Administrative utilities

Pacific Application Server for OpenEdge: Administration Guide

17

Chapter 1: Overview of PAS for OpenEdge administration

Development servers compared to production servers

Tomcat logging

Configuration and properties files

Pacific Application Server properties

Pacific Application Server directories

Administrative utilities
This section provides an overview of the utilities you can use to manage and administer PASOE.

TCMAN
the Pacific Application Server implements the TCMAN command line utility as an interface to
administrative functionality provided by core Tomcat scripts. You will find extended administrative
functionality that is easier to find and to use if you run TCMAN rather than running the Tomcat
scripts directly.

See also
TCMAN Reference on page 93

OEPAS
Purpose
OEPAS is a command line utility to display and manage properties in the server's
conf/openedge.properties file.
Note: Use TCMAN (tcman config) to manage the properties in conf/appserver.properties
or to view the properties in conf/jvm.properties.

Syntax

{$CATALINA_HOME|$CATALINA_BASE}/conf/oeprop[.sh|.bat] [help]
[prop_name|prop_name=value|+prop_name=value|~prop_name]
Parameters
help
Display the help for the oepas command.

18

Pacific Application Server for OpenEdge: Administration Guide

Administrative utilities

prop_name
Display the specified property and its value.
prop_name=value
Set the value of a property that exists in .../conf/openedge.properties.
+prop_name=value
Add a new property to .../conf/openedge.properties and set its value.
~prop_name
Remove the specified property from .../conf/openedge.properties.

OpenEdge Management and OpenEdge Explorer

Much of the functionality supplied by command-line utilities like TCMAN and OEPAS is also
implemented in the OpenEdge Management (OEM) and OpenEdge Explorer (OEE) browser-based
tools. You can also use OEM/OEE to monitor PAS server performance and display performance
statistics.
For more information, see Configuring and Administering PAS for OpenEdge with OEE/OEM.

JMX and JConsole

The Pacific Application Server supports the use of The Java Management Extensions (JMX)
technology, which facilitates dynamic access to applications and other resources. This access is
accomplished through the use of Java objects called Managed Beans, or MBeans. One or more
MBeans instrument a resource through the use of the MBean's attributes, actions (defined as
methods), and notifications. For more detailed information on JMX and MBeans, see the Java
documentation at http://docs.oracle.com/javase/8/docs/technotes/guides/jmx/index.html.
JConsole, which is an application included with Java, can be used to monitor and manage MBeans.
JConsole can be used for development and debugging, but you should not use JConsole on a
local production server because JConsole itself uses significant resources. Using JConsole with
a remote connection avoids this problem, although this usage requires more attention to security.

Administrative scripts
This topic is a brief overview of some of the administrative utilities for the Pacific Application Server,
which are implemented as scripts in the Tomcat server's /bin directory. Each script has a UNIX
(.sh extension) and a Windows (.bat extension) version.
Notice that the Pacific Application Server implements the TCMAN command line utility as an
interface to administrative functionality provided by core Tomcat scripts. You will find extended
administrative functionality that is easier to find and to use if you run TCMAN rather than running
the Tomcat scripts directly.
The following table lists the standard Tomcat utilities in $CATALINA_HOME/bin that were tailored
by Progress to set the value of CATALINA_HOME and CATALINA_BASE to values appropriate for
the Pacific Application Server and its instances.

Pacific Application Server for OpenEdge: Administration Guide

19

Chapter 1: Overview of PAS for OpenEdge administration

Table 1: Standard Tomcat utilities modified for Pacific Application Server

startup.sh(.bat)

Initiates the start up of the Tomcat server and

its web applications.
Functionality of this utility is also available
through tcman.sh start

shutdown.sh(.bat)

Initiates the Tomcat servers shutdown process,

beginning with a graceful termination of any
running web applications.
Functionality of this utility is also available
through tcman.sh stop

version.sh(.bat)

A standard Tomcat script that displays version

and system information.
Functionality of this utility is also available
through tcman.sh info

configtest.sh(.bat)

Displays the Tomcat servers configuration and

environment information.
Functionality of this utility is also available
through tcman.sh test

In addition, there are a number of supporting scripts that are called by Tomcat administrative
utilities. Some of these supporting scripts are described in the following table.
Table 2: Supporting administrative scripts for Pacific Application Server
catalina.sh(.bat)

20

Called by administrative utilities on startup or

shutdown of the Tomcat server. Calls
setenv.sh(.bat) (if it exists) and
setclasspath.sh(.bat) to set environment.

Pacific Application Server for OpenEdge: Administration Guide

Administrative utilities

setclasspath.sh(.bat)

Called by catalina.sh(.bat) to set

JAVA_HOME or JRE_HOME if not already set.
If they are set, it validates to ensure that the
values are consistent with startup options.

setenv.sh(.bat)

An optional file called by catalina.sh(.bat)

on startup. Deploying this file is the standard
way to customize the server environment for
each running instance.
setenv.sh performs the following operations:
1. Set JVM memory size and the CATALINA
environment variables common to all
Progress product Web applications.
2. Load Java system properties from
conf/server.xml.
3. Find and run any
progress_product_setenv.sh(.bat)
files.

In addition to the standard Tomcat administrative utilities and supporting scripts described above,
Pacific Application Server The following table lists the utility scripts in the Pacific Application Server
/bin directory that were added by Progress to the standard Tomcat server.
Table 3: Pacific Application Server scripts
tcman.sh(.bat)

Runs the TCMAN administrative utilities

necessary to manage the Pacific Application
Server. tcman.sh is a command-line wrapper
for tools that are implemented in tcmanager.sh
and it also manages the instance variables,
$CATALINA_HOME and in $CATALINA_BASE.

tcmanager.sh(.bat)

Called by tcman.sh to implement the TCMAN

administrative utilities necessary for managing
the Pacific Application Server. This script is a
wrapper for the built-in Tomcat utilities, including
startup.sh , shutdown.sh , version.sh,
and configtest.sh. In addition, TCMAN adds
new administrative functionality specifically for
the Pacific Application Server.

progress_product_setenv.sh(.bat)

Called by the Tomcat setenv script to set

Progress product-specific environment variables
and make them available to Java processes.
If this file exists in $CATALINA_HOME/bin and
in $CATALINA_BASE/bin, the file in
$CATALINA_BASE takes precedence.

Pacific Application Server for OpenEdge: Administration Guide

21

Chapter 1: Overview of PAS for OpenEdge administration

Development servers compared to production servers

Pacific Application Server for OpenEdge can be installed as either a server for developing and
testing Web applications or as a production server for application deployment.
The difference between a development server and a production server is largely a matter of security.
Typically, a server in a development environment allows unrestricted access to and control by a
user or group of users. A production server, on the other hand, is configured to restrict access to
authorized users and to limit control to system administrators. For example, in a development
environment anyone might be allowed to shut down the server, whereas, in a production
environment, only an administrator with appropriate privileges would be allowed to stop a running
server.
In addition, you should be aware that the development server includes a number of Tomcat and
Progress configuration and management tools. A production server, to avoid unauthorized
tampering, would not include those tools.

See also
Development server and production server security issues on page 52

Tomcat logging
The core Pacific Application Server (PAS) uses the standard logging technology employed by the
Apache Tomcat Web server. For system logging, Tomcat uses an implementation of the Apache
Commons Logging library based on the java.util.logging(JULI) framework. JULI is
implemented in $CATALINA_HOME/bin/tomcat-juli.jar.
Note: This topic only applies to the standard JULI-based logging implemented for the core Tomcat
Web server Web application logging may be based on a different framework (Log4j for example).
Log files are written to the /logs directory of a running instance ($CATALINA_BASE/logs). The
default log files for PAS are:

catalina.log, a log with entries that describe server activity

catalina.out, a log for system output and standard error messages
localhost.log, a log file for tracking Web application activity
localhost_access.log, a log for tracking requests processed by the server
host_manager.log, a log for Tomcat's host-manager.war Web application
manager.log, a log for Tomcat's manager.war Web application
Log files, with the exception of catalina.out, are saved daily with the date appended to the
filename (MM-DD_YYYY). catalina.out persists while the server is running. You can delete or
archive all of the log files with the TCMAN clean action.

22

Pacific Application Server for OpenEdge: Administration Guide

Configuration and properties files

The default log files and logging levels are defined in /conf/logging.properties. For example,
the following entry from logging.properties instantiates the catalina.log file:

1catalina.org.apache.juli.FileHandler.level = INFO
1catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
1catalina.org.apache.juli.FileHandler.prefix = catalina.

Notice that the logging level is set to INFO which is the default for all log files in PAS. The following
is a list of the JULI logging levels that apply to Tomcat.
Table 4: JULI logging levels for Tomcat
Level

Log content

SEVERE

Serious failures

WARNING

Potential problems

INFO

Informational messages

CONFIG

Static configuration messages

FINE

Trace messages

FINER

Detailed trace messages

FINEST

Highly detailed trace messages

The list is arranged in order by level of detail from the least (SEVERE) to the greatest (FINEST).
Note that a level includes all the content of previous levels. For example, INFO specifies that the
log should include informational messages, potential problems (WARNING), and serious failures
(SEVERE).

Configuration and properties files

The following table lists the configuration files that are located in the Pacific Application Server's
/conf directory. Where noted, standard Tomcat configuration files were extended to support
configuration of the Pacific Application Server.
Note: Although these files can be edited in a text editor, it is always safer to use a utility like
tcman.sh config to set, add, or remove properties.

Pacific Application Server for OpenEdge: Administration Guide

23

Chapter 1: Overview of PAS for OpenEdge administration

Table 5: Pacific Application Server properties files

appserver.properties

An added Progress properties file that sets

custom Pacific Application Server properties. It
is called on startup by conf/server.xml and
is also used by Progress web applications.
For more information, open the
conf/appserver.properties.README file.

catalina.properties

A standard Tomcat properties file that was

extended to access common shared libraries
and to supply external Java properties used by
server.xml.
For more information, open the
conf/catalina.properties.README file.

jvm.properties

A standard properties file that sets JVM options

for the Java Virtual Machine that a PAS instance
runs in.
Note: You cannot use tcman.sh(.bat)
config to modify this file.

openedge.properties

An added Progress properties file that contains

OpenEdge-specifc settings for debugging,
logging, and other properties.
For more information, open the
conf/openedge.properties.README file.

server.xml

A standard Tomcat configuration file that was

tailored for the Pacific Application Server to use
Java system properties that are defined
externally configured in the
catalina.properties and the
appserver.properites files.

web.xml

Standard Tomcat configuration files that contain

defaults common to all the Web applications
deployed in the server.

context.xml

Pacific Application Server properties

The following tables list the configuration properties for a Pacific Application Server. Except where
noted, use the TCMAN utility to set, add, or remove properties.
Note: Where indicated in the table, more information can be found in the Tomcat configuration
reference at http://tomcat.apache.org/tomcat-7.0-doc/config/.

24

Pacific Application Server for OpenEdge: Administration Guide

Pacific Application Server properties

Table 6: PAS properties

catalina.base

A read-only string containing the path to the PAS

instance's root directory. This property cannot be
configured using TCMAN.

catalina.home

A read-only string containing the path to the PAS home

server's root directory. This property cannot be
configured using TCMAN.

com.sun.management.jmxremote.access.file

A readable/writable string containing the absolute path

to where the PAS instance JMX console access control
file is stored.

com.sun.management.jmxremote.password.file

A readable/writable string containing the absolute path

to where the PAS instance JMX console password is
stored.

com.sun.management.jmxremote.ssl

A readable/writable Boolean indicating whether SSL

is enabled for JMX console connections. The possible
values are true (use SSL) and false (no SSL).

java.io.tmpdir

A read-only string containing the path to the PAS home

server's temp directory, where transitory files are
created.

psc.as.ajp13.maxconnections

A readable/writable numeric value containing the

maximum number of client connections for the AJP13
connector. When the maximum number is reached,
new connections are queued. The minimum value is
100. For more information, see "Connector" in the
Apache Tomcat documentation.

psc.as.ajp13.maxqueuesize

A readable/writable numeric value containing the

maximum number of incoming requests in the AJP13
connector's queue. For more information, see
"Connector" in the Apache Tomcat documentation.

psc.as.ajp13.port

A readable/writable numeric containing the TCP port

number for the AJP13 protocol used by a load
balancing server. The value can range from 1 to the
maximum port number. For more information, see
"Connector" in the Apache Tomcat documentation.

psc.as.ajp13.tomcatauth

A readable/writable Boolean indicating whether the

AJP13 client's authentication feature is enabled. The
possible values are true (enabled) and false
(disabled). For more information, see "Connector" in
the Apache Tomcat documentation.

Pacific Application Server for OpenEdge: Administration Guide

25

Chapter 1: Overview of PAS for OpenEdge administration

psc.as.alias

A read-only string containing the server's alias name,

as used in TCMAN's -I option and with cluster and
load balancing configurations. If the property contains
home, then the server is a full PAS installation.

psc.as.autodeploy

A readable/writable Boolean indicating whether the

PAS server automatically deploys web applications
placed into its web application deployment directory
(see property psc.as.webappdir). The possible
values are true (autodeploy, less secure) and false
(no autodeploy more secure). For more information,
see "Host" in the Apache Tomcat documentation.

psc.as.clust.expireOnShut

A readable/writable Boolean indicating whether

sessions expire on all nodes when one node is shut
down. The possible values are true (all sessions
expire) and false (do not expire). For more
information, see "ClusterManager" in the Apache
Tomcat documentation.

psc.as.clust.inactivetimeout

A readable/writable numeric value containing the

number of seconds a Tomcat cluster session can be
inactive before it is marked expired. The minimum
value is 10 seconds. For more information, see
"ClusterManager" in the Apache Tomcat
documentation.

psc.as.clust.manager

A readable/writable string indicating the Tomcat cluster

manager type. The possible values are
DeltaManager and BackupManager. For more
information, see "Cluster" in the Apache Tomcat
documentation.

psc.as.clust.mcast.addr

A readable/writable string containing the Tomcat

cluster multicast address, formatted as an IPv4
address. For more information, see
"Channel/Membership" in the Apache Tomcat
documentation.

psc.as.clust.mcast.dropafter

A readable/writable numeric value containing the

amount of time a cluster member can be
non-responsive before timing out. The minimum value
is 10 milliseconds. For more information, see
"Channel/Membership" in the Apache Tomcat
documentation.

psc.as.clust.mcast.freq

A readable/writable numeric value containing the

Tomcat cluster multicast heartbeat frequency. The
minimum value is 10 milliseconds. For more
information, see "Channel/Membership" in the Apache
Tomcat documentation.

26

Pacific Application Server for OpenEdge: Administration Guide

Pacific Application Server properties

psc.as.clust.mcast.port

A readable/writable numeric value containing the

Tomcat cluster multicast port number. For more
information, see "Channel/Membership" in the Apache
Tomcat documentation.

psc.as.clust.notifyListeners

A readable/writable Boolean indicating whether Tomcat

notifies session listeners when sessions are created
or expired across the node. The possible values are
true (notify) and false (do not notify). For more
information, see "ClusterManager" in the Apache
Tomcat documentation.

psc.as.clust.recv.addr

A readable/writable string containing the Tomcat

cluster multicast receiver address, formatted as an
IPv4 address. For more information, see
"Channel/Receiver" in the Apache Tomcat
documentation.

psc.as.clust.recv.autobind

A readable/writable numeric value containing the

number of times Tomcat will increment upward if the
port in psc.as.clust.recv.port is unavailable .
For more information, see "Channel/Receiver" in the
Apache Tomcat documentation.

psc.as.clust.recv.maxthreads

A readable/writable numeric value containing the

maximum number of threads in the Tomcat cluster
message receiver (NioReceiver). The possible values
range from 10 to 10,000. For more information, see
"Channel/Receiver" in the Apache Tomcat
documentation.

psc.as.clust.recv.nodelay

A readable/writable Boolean indicating whether the

Tomcat cluster message receiver uses the
TCP_NODELAY option. The possible values are true
(option on) and false (option off). For more
information, see "Channel/Receiver" in the Apache
Tomcat documentation.

psc.as.clust.recv.port

A readable/writable numeric value containing the

Tomcat cluster multicast receiver port number. For
more information, see "Channel/Receiver" in the
Apache Tomcat documentation.

psc.as.clust.recv.selectortimeout

A readable/writable numeric value containing the time

in milliseconds for timeout of the Tomcat cluster
message receiver (NioReceiver). The possible values
range from 10 to 10,000. For more information, see
"Channel/Receiver" in the Apache Tomcat
documentation.

Pacific Application Server for OpenEdge: Administration Guide

27

Chapter 1: Overview of PAS for OpenEdge administration

psc.as.clust.recv.timeout

A readable/writable numeric value containing the

Tomcat cluster message receiver timeout in
milliseconds. The minimum value is 10. For more
information, see "Channel/Receiver" in the Apache
Tomcat documentation.

psc.as.clust.sendoptions

A readable/writable bitmask for the Tomcat cluster

channel send options. The possible values are
synchronized_ack, 0x0004; asynchronous, 0x0008;
and use ack, 0x0002. For more information, see
"Cluster" in the Apache Tomcat documentation.

psc.as.commonlib

A readable/writable string containing a classpath of

directories and JAR files that the PAS server uses with
the web application class loader.The value is a comma
separated list of absolute paths to directories or JAR
files. For example:
/local/server/common/*.jar,/local/server/common/x.jar

psc.as.executor.maxthreads

A readable/writable numeric value containing the

maximum number of threads in the server's HTTP
thread pool. The minimum value is 100. For more
information, see "Executor" in the Apache Tomcat
documentation.

psc.as.executor.minsparethreads

A readable/writable numeric value containing the

minimum number of threads in the HTTP/HTTPS
connector's thread pool. The range of values is from
10 to psc.as.executor.maxthreads. For more
information, see "Executor" in the Apache Tomcat
documentation.

psc.as.http.connectiontimeout

A readable/writable numeric value containing the

maximum number of milliseconds the PAS will wait
from when the client HTTP connection is made until
the URI is received. The minimum value is 1000.

psc.as.http.maxconnections

A readable/writable numeric value containing the

maximum number of client connections for the HTTP
connector. When the maximum number is reached,
new connections are queued. The minimum value is
100. For more information, see "Connector" in the
Apache Tomcat documentation.

psc.as.http.maxqueuesize

A readable/writable numeric value containing the

maximum number of incoming requests in the HTTP
connector's queue. For more information, see
"Connector" in the Apache Tomcat documentation.

28

Pacific Application Server for OpenEdge: Administration Guide

Pacific Application Server properties

psc.as.http.port

A readable/writable numeric containing the TCP port

number for the HTTP protocol. For more information,
see "Connector" in the Apache Tomcat documentation.

psc.as.https.clientauth

A readable/writable Boolean indicating whether the

SSL (HTTPS) client's authentication feature is enabled.
The possible values are true (enabled) and false
(disabled). For more information, see "Connector" in
the Apache Tomcat documentation.

psc.as.https.connectiontimeout

A readable/writable numeric value containing the

maximum number of milliseconds the PAS will wait
from when the client HTTPS connection is made until
the URI is received. The minimum value is 1000.

psc.as.https.keyalias

A readable/writable string containing the alias to the

server's private key stored in the SSL's keystore. For
more information, see "Connector" in the Apache
Tomcat documentation.

psc.as.https.keypass

A readable/writable string containing the password to

the server's private key stored in the SSL's keystore.
For more information, see "Connector" in the Apache
Tomcat documentation.

psc.as.https.maxconnections

A readable/writable numeric value containing the

maximum number of client connections for the HTTPS
connector. When the maximum number is reached,
new connections are queued. The minimum value is
100. For more information, see "Connector" in the
Apache Tomcat documentation.

psc.as.https.maxqueuesize

A readable/writable numeric value containing the

maximum number of incoming requests in the HTTPS
connector's queue. For more information, see
"Connector" in the Apache Tomcat documentation.

psc.as.https.maxthreads

A readable/writable numeric value containing the

maximum number of threads in the server's HTTPS
thread pool. The minimum value is 100. For more
information, see "Connector" in the Apache Tomcat
documentation.

psc.as.https.port

A readable/writable numeric value containing the TCP

port number for the HTTPS protocol. For more
information, see "Connector" in the Apache Tomcat
documentation.

psc.as.https.protocol

A readable/writable string indicating the default HTTPS

protocol. The possible values are SSLv3 and TLS. For
more information, see "Connector" in the Apache
Tomcat documentation.

Pacific Application Server for OpenEdge: Administration Guide

29

Chapter 1: Overview of PAS for OpenEdge administration

psc.as.https.storeType

A readable/writable string indicating the type of

keystore used for storing SSL private keys and
certificates. The possible values are PKCS12 and JKS.
For more information, see "Connector" in the Apache
Tomcat documentation.

psc.as.msg.maxpipeline

A readable/writable numeric value containing the

maximum number of pipelined HTTP keepAlive
requests before the socket is closed. A value of -1
disables the limit. For more information, see
"Connector" in the Apache Tomcat documentation.

psc.as.msg.maxpostsize

A readable/writable numeric value containing the

maximum size in bytes of a connector's POST
message body. A value of 0 disables the limit. For
more information, see "Connector" in the Apache
Tomcat documentation.

psc.as.msg.timeout

A readable/writable numeric value containing a

connector's asynchronous timeout in milliseconds.The
minimum value is 10. For more information, see
"Connector" in the Apache Tomcat documentation.

psc.as.os

A read-only string indicating the system PAS was

installed on. The possible values are unix and
windows.

psc.as.parent

A read-only string containing the path to the home

server. If psc.as.alias is home, then
psc.as.parent is blank.

psc.as.shut.port

A readable/writable numeric containing the TCP port

number for shutting down the server via a TCP network
client. A value of -1 is only supported on UNIX for
disabling shutdown using a network client (which is
more secure). Windows requires a port number greater
than or equal to 1. For more information, see "Server"
in the Apache Tomcat documentation.

psc.as.shut.pwd

A readable/writable string containing the shared secret

required by the PAS server before it will accept a
shutdown command from a network client. The secret
can be any non-blank ASCII string, and it is required
in Windows. For more information, see "Server" in the
Apache Tomcat documentation.
Caution: The value of this property is stored as
cleartext.

30

Pacific Application Server for OpenEdge: Administration Guide

Pacific Application Server properties

psc.as.stuckthreadthreshold

A readable/writable numeric value containing the

maximum number of seconds to wait before a thread
is considered stuck. The minimum value is 0 (off). For
more information, see "Stuck Thread Detection Valve"
in the Apache Tomcat documentation.

psc.as.type

A readable/writable string indicating the type of server.

standard indicates a full PAS installation, and
instance indicates a PAS instance.

psc.as.unpackwars

A readable/writable Boolean indicating whether the

PAS server automatically unpacks WAR archives
placed in its web application deployment directory (see
property psc.as.webappdir). The possible values
are true (automatic unpacking) and false (no
automatic unpacking). For more information, see
"Host" in the Apache Tomcat documentation.

psc.as.usersfile

A readable/writable string containing the path where

the PAS server finds the local user account storage
file. The path can be absolute or relative to the server
(instance) CATALINA_BASE configuration value. For
more information, see "Resources" in the Apache
Tomcat documentation.

psc.as.version

A read-only string containing the PAS release version

in the format
major-version.minor-version.patch-version.

psc.as.webappdir

A readable/writable string containing the path for where

the PAS server finds and loads web applications and
WAR files from. If the path is not absolute, it is relative
to the CATALINA_BASE path for the server (instance).
For more information, see "Host" in the Apache Tomcat
documentation.

psc.dns.name

A read-only string containing the server's fully qualified

DNS name. This property cannot be configured using
TCMAN.

psc.host.name

A read-only string containing the server's configured

host name. This property cannot be configured using
TCMAN.

The properties in the following table control the enabling and disabling of PAS features. All of them
are settable using TCMAN, and the possible values are on and off.
Table 7: PAS features
AccessLog

Indicates whether client HTTP message and response

code logging is enabled.

Pacific Application Server for OpenEdge: Administration Guide

31

Chapter 1: Overview of PAS for OpenEdge administration

AJP13

Indicates whether the AJP13 protocol network port is

enabled on the server for load balancing by a Apache
HTTPD or IIS web server.

Cluster

Indicates whether Tomcat cluster support (which needs

to be manually configured) is enabled.

CrawlerSessionManager

Indicates whether reduction of the impact of web

crawler session creation (so as not to overrun the
server) is enabled.

HTTP

Indicates whether the HTTP protocol network port is

enabled on the server.

HTTPS

Indicates whether the HTTPS protocol network port is

enabled on the server.

JAASRealm

Indicates whether the use of JAAS plug-in

authentication modules for container user
authentication (which requires manual configuration)
is enabled.

JMXLifecycle

Indicates whether network ports used for remote JMX

console are fixed. Otherwise, standard RMI
connections are used.

LDAPRealm

Indicates whether the use of an LDAP/Active-Directory

service for container user authentication (which
requires manual configuration) is enabled.

RemoteAddrValve

Indicates whether connections are restricted to a list

of specific TCP/IP addresses.

RemoteHostValve

Indicates whether connections are restricted to a list

of specific DNS host names.

SecurityListener

Indicates whether security checking at server startup

is enabled, which prevents the server from starting if
any of the checks fail.

SingleSignOn

Indicates whether Tomcat's single-sign on feature is

enabled.

StuckSessionValve

Indicates whether messages will be logged about

requests that do not appear to be completing.

UserDatabase

Indicates whether the use of a flat file for container

user authentication is enabled.

32

Pacific Application Server for OpenEdge: Administration Guide

Pacific Application Server directories

Pacific Application Server directories

The following table lists the PAS directories added to the standard Tomcat directory structure.
Table 8: Pacific Application Server directory structure extensions
rd

$CATALINA_HOME/common/lib/

Contains general 3 party libraries that are

shared by a server, its instances, and its web
applications.

$CATALINA_BASE/common/lib/

Contains general 3 party libraries that are used

by a single instance and its web applications.

$CATALINA_HOME/extras/

Contains the WAR files of the default Tomcat

web applications, host-manager.war,
manager.war, and ROOT.war.

rd

It can also contain the WAR files that support

Progress products. (For example: oeabl.war
and oemanager.war, which can optionally be
deployed to an instance to support OpenEdge
applications and management.)

Pacific Application Server for OpenEdge: Administration Guide

33

Chapter 1: Overview of PAS for OpenEdge administration

34

Pacific Application Server for OpenEdge: Administration Guide

2
Working with Instances
Instances are a standard Apache Tomcat feature. They allow you to create individual deployment
and/or development servers that share the core Pacific Application Server that you installed.
Instances are independently running copies of the core Pacific Application Server. Each instance
runs on its own JVM, has its own configuration with unique ports, and hosts its own web applications.
However, each instance runs a Tomcat server that uses a number of common files from the same
$CATALINA_HOME directory. Each instance has an alias. The default value is the directory in which
the instance was created, but it can be set to some other string.
As a best practice, Progress recommends that you deploy your web applications to an instance
of the Pacific Application Server, rather than deploying to the Pacific Application Server that you
installed.This practice prevents accidental corruption of the core executables, configuration settings,
and libraries. It also prevents accidental deletion of web applications if the core Pacific Application
Server is removed during an OpenEdge uninstall.
For details, see the following topics:

Overview of instances in PAS for OpenEdge

Instance management with TCMAN

Creating instances with TCMAN

Installing and running an instance as a UNIX daemon

Installing and running an instance as a Windows service

Pacific Application Server for OpenEdge: Administration Guide

35

Chapter 2: Working with Instances

Overview of instances in PAS for OpenEdge

After you install the core Pacific Application Server, you can create an instance.
Instances are a standard Apache Tomcat feature. They allow you to create individual deployment
and/or development servers that are based on the core Pacific Application Server that you installed.
The following figure illustrates the creation of multiple instances using the TCMAN command-line
utility (with syntax simplified).
Figure 1: Generating PAS instances

Instances are independently running copies of the core Pacific Application Server. Each instance
runs on its own JVM, has its own configuration with unique ports, and hosts its own web applications.
However, each instance runs a Tomcat server that uses a number of common files from the same
$CATALINA_HOME directory.
There are a number of advantages when you deploy your web applications to an instance of the
Pacific Application Server, rather than deploying to the Pacific Application Server that you installed.
This practice prevents accidental corruption of the core executables, configuration settings, and
libraries. It also prevents accidental deletion of web applications if the core Pacific Application
Server is removed when you uninstall a Progress PAS product.
Some additional advantages of instances are:

Updates to the core Apache Tomcat server libraries and executables do not affect your web
applications. You avoid the necessity of updating the applications and/or re-configuring them.

You can establish different security policies for each of the instances.
You can tailor the JVM for individual applications, since each instance runs in its own JVM with
its own configuration.

Instances provide you with quick way to create a test server for experimenting with new
configurations and applications without the danger of permanently corrupting an existing server.

36

Pacific Application Server for OpenEdge: Administration Guide

Instance management with TCMAN

You can package an instance as a Web application and deploy it to other PAS core servers.
You use $CATALINA_HOME/bin/tcman.sh create command to create a new instance.
When you create an instance, the root directory of the instance is assigned to the CATALINA_BASE
environment variable within the scripts in its /bin directory. The root directory of the installed
(core) Pacific Application Server is assigned to the CATALINA_HOME environment variable in the
scripts in the instance's /bin directory. (Notice that the scope of these environment variables is
limited to the context of an individual instance's /binscripts.)
All instances of a core Pacific Application Server execute a set of common JAR files, scripts, and
libraries from the following directories on the parent server:

$CATALINA_HOME/lib
$CATALINA_HOME/common/lib
$CATALINA_HOME/bin
However, each instance is created with :

A $CATALINA_BASE/bin/ directory with its own copy of some of the scripts from the core
PAS. These include scripts for start up, shut down, deployment, running TCMAN actions, and
so on.

A $CATALINA_BASE/conf/ directory with its own copy of properties and configuration files.
A $CATALINA_BASE/webapps/ which initially only contains the ROOT Web application.
A number of directories that are initially empty. These include /logs, /temp, /work, and
/common/lib.

Instance management with TCMAN

TCMAN includes actions for configuring, starting, stopping, monitoring, and deleting instances.
The following table is a brief description of the instance management actions that you can perform
with TCMAN. Entries link to the reference topics that provide more details, syntax, and examples.
Action

Purpose

create

Create an instance of the Pacific Application Server.

delete

Remove the directory tree and all of the files in an instance.

start

Start an instance of a Pacific Application Server.

stop

Stop a running instance.

config

View, add, update, or delete the property values specified in

../conf/appserver.properties.

test

Displays information on the configuration and environment of an instance. It

also displays information about error conditions.

Pacific Application Server for OpenEdge: Administration Guide

37

Chapter 2: Working with Instances

Action

Purpose

instances

Display all the instances created from the Pacific Application Server installed
in $CATALINA_HOME.

unregister

Stop tracking an instance by removing the instance's entry from the

$CATALINA_HOME/conf/instances.[unix|windows] file.

register

Register an instance for tracking purposes. (Note that instances are registered
for tracking by default when they are created. The register action is only
necessary if you explicitly unregistered an instance.)

clean

Truncate, move, or delete the log files located in the /logs directory of either
the core server or an instance.

version

Show the Apache Tomcat runtime version and OS information for an instance.

Creating instances with TCMAN

Before you can create an instance of the Pacific Application Server (PAS) using the TCMAN
command line utility, you must:

Install the core Pacific Application Server

Install JDK or JRE version 1.7 or later
Set the JAVA_HOME or JRE_HOME environment variable to the JDK/JRE install directory .
Note: TCMAN is a Progress extension of the basic Tomcat administrative utilities.TCMAN simplifies
instance creation and management.
An instance runs the Tomcat executable of a core PAS, but it runs in a separate JVM, is configured
with its own unique ports, and other properties. (You should not attempt to use the installed, core
PAS as a development or production server.) Instances allow you to run a variety of server
configurations without corrupting the files in the core server. They also allow you to update the
core server without re-deploying or re-configuring your Web applications.
To create an instance using the TCMAN utility:
1. Open a command shell and navigate to $CATALINA_HOME/bin.
$CATALINA_HOME is the directory where you installed the core Pacific Application Server.
2. Run tcman.sh create basepath (or tcman.bat on Windows systems) .
The base_path parameter specifies the path name where you will create the instance. It is
the only required parameter for the create action. If you are creating multiple running instances,
you should override the default port assignments by specifying the following parameters:

38

Options

Description

p port_num

Specify the TCP port that listens for HTTP messages. The
default is 8080.

Pacific Application Server for OpenEdge: Administration Guide

Creating instances with TCMAN

Options

Description

P port_num

Specify the TCP port that listens for HTTPS messages. The
default is 8443.

You can also activate these ports:

Options

Description

s port_num

Specify the TCP port to use to stop an instance. (Required on Windows

systems, optional on UNIX )

j port_num

Specify the TCP port that listens for AJP13 messages, an Apache
protocol for handling requests from a web server to an application
server. (Optional on both Windows and UNIX systems)

See Create an instance (create) on page 110 for information about other parameters.
3. (Optional) Deploy remote management applications from $CATALINA_HOME/extras to the
instance.
Remote management applications are not pre-installed, and installing them is a security decision.
For example, you might want to eliminate access to the configuration and control of instances
by not deploying management applications to production servers, while deploying management
applications to development servers.
To deploy a management application:
a) Open a command shell and navigate to $CATALINA_BASE/bin.
b) Run tcman.sh deploy '$CATALINA_HOME/extras/admin_webapp.war'.
The admin_webapp.war can be one of the following:
Options

Description

host-manager.war

A Tomcat administration application used to get server information

and provide other functionality. It should not be necessary to deploy
host-manager.war if you are using the TCMAN utilities.

manager.war

A Tomcat administration application which you must deploy in order

to run some TCMAN actions. See the TCMAN Reference on page
93 for information on which TCMAN actions require deployment of
manager.war.

Progress applications

Progress products can have web applications that enable the use of
their own administrative tools.

For example the following command line creates an instance of /psc/pashome in /psc/acme1
and specifies its ports:
$: /psc/pashome/bin/tcman.sh create -p 8501 -P 8601 -s 8701 /psc/acme1
Server instance acme1 created at /psc/acme1

See also
Server actions on page 110
Pacific Application Server for OpenEdge: Administration Guide

39

Chapter 2: Working with Instances

Create an instance (create) on page 110

Delete an instance (delete) on page 112
Display and manage an instance's configuration (config) on page 113
Display or modify the server features of an instance (feature) on page 115
Clean up or archive server log files (clean) on page 117
Display server instances (instances) on page 117
Register an instance for tracking (register) on page 119
Stop tracking an instance (unregister) on page 120
Start an instance (start) on page 121
Stop an instance (stop) on page 123
Display server, OS, and runtime version information (version) on page 124
Test a server configuration (test) on page 125

Installing and running an instance as a UNIX daemon

A daemon process (called a service on Windows systems) is an application without a user interface
that runs in the background and responds to requests. Web servers like PAS and Tomcat typically
run as Windows services or UNIX daemons.
Note: If you run a PAS instance with tcman.sh start, the instance runs in the context of the
command shell process. It is not available as a system service that can handle external client
requests. The instance must be installed as a daemon process before you can run it as a functioning
Web server.
The file $CATALINA_HOME/bin/daemon.sh can be used as a template for starting Tomcat
automatically at boot time as a child of the init process. For more information, see:
https://tomcat.apache.org/tomcat-7.0-doc/setup.html#Unix_daemon
However, you will need to consult with a system administrator before you can configure and run
PAS as a daemon process due to differences among UNIX systems and because you need
administrative privileges for access to the system.

Installing and running an instance as a Windows

service
To install a Pacific Application Server (PAS) instance as a Windows service, you must have
administrator privileges. On systems with User Account Control (UAC), you must disable UAC as
well.
In addition, the instance must be registered with a core PAS server, which you can accomplish
with the tcman.bat register action.
A service (called a daemon process on UNIX systems) is an application without a user interface
that runs in the background and provides core operating system functionality. Web servers like
PAS and Tomcat typically run as Windows services or UNIX daemons.

40

Pacific Application Server for OpenEdge: Administration Guide

Installing and running an instance as a Windows service

Note: If you run a PAS instance with tcman.bat start, the instance runs in the context of the
command shell process. It is not available as a system service that can handle external client
requests.The instance must be installed as a Window service before you can run it as a functioning
Web server.
This is a summary of how to install and run a PAS instance as a Windows service:
1. Open a command prompt (cmd.exe) window.
2. Navigate to the core PAS /bin directory ($CATALINA_HOME/bin).
3. Run the service.bat script using the following syntax:
service.bat install instance_name

instance_name is the name of an existing instance of the core PAS.

Note: See the Windows service HOW-TO help topic in the Apache Tomcat Documentation (
http://tomcat.apache.org) for more information about installing instances as Windows services.
4. Use the Services Microsoft Management Console (MMC) or the sc config command to start
the service.
Note: Refer to Windows help for more information on starting, stopping, and other administrative
tasks with regard to Windows Services.

Pacific Application Server for OpenEdge: Administration Guide

41

Chapter 2: Working with Instances

42

Pacific Application Server for OpenEdge: Administration Guide

3
Web application deployment and
management
For details, see the following topics:

Web application management with TCMAN

OpenEdge Web application deployment

Packaging web applications

Web application management with TCMAN

TCMAN includes a number of actions for deploying and managing Web applications to instances.
The following table is a brief description of the Web application management actions that you can
perform with TCMAN. Entries link to the reference topics that provide more details, syntax, and
examples.
Action

Purpose

list

Display all the Web applications that are deployed on an instance.

info

Display server and OS information for a running instance.

Pacific Application Server for OpenEdge: Administration Guide

43

Chapter 3: Web application deployment and management

Action

Purpose

deploy

Deploy a Web application (.war file) to a Pacific Application Server

instance whether the server is running (online) or is not running
(offline).

undeploy

Remove a Web application from running (online) or stopped

(offline) instances.

reload

Restart a deployed, running web application so that the application

can pick up changes to its classes or libraries.

status

List information from the core servers memory, including web

application statistics.

leaks

List Web applications with potential memory leaks.

enable

Start a Web application that is deployed but not running.

disable

Stop a running Web application.

resources

List the global resources used by the core server.

sessions

Display how many sessions are active for the specified Web
application, categorized by their duration.

OpenEdge Web application deployment

The deployREST.sh and deploySOAP.sh scripts allow you to add REST or SOAP services to
a deployed OpenEdge ABL Web application (oeabl.war). When you invoke either of the scripts,
the OpenEdge ABL Web application must be running. After you deploy the service, you must stop
and restart the Pacific Application Server instance to run the new service.

REST service deployment (deployREST.sh)

Purpose
Deploys REST services.

Syntax
$CATALINA_BASE/bin/deployREST.sh source_descriptor service_name

44

Pacific Application Server for OpenEdge: Administration Guide

Packaging web applications

Parameters
source_descriptor
Specify the path of the source descriptor, which can be either a PAAR file containing the
descriptor for the REST service or a ZIP file containing Mobile catalog files (or other static
files).
service_name
Specify the target service name.

Example
$CATALINA_BASE/bin/deployREST.sh CustomerService.paar ROOT

SOAP service deployment (deploySOAP.sh)

Purpose
Deploy SOAP services.

Syntax
$CATALINA_BASE/bin/deploySOAP.sh source_descriptor service_name

Parameters
source_descriptor
Specify the path of the source descriptor, which is a WSM file.
service_name
Specify the target service name.

Example
$CATALINA_BASE/bin/deploySOAP.sh CustomerService.wsm ROOT

Packaging web applications

The Pacific Application Server supports a number of different ways for packaging web applications.
Web applications can be packaged as:

Pacific Application Server for OpenEdge: Administration Guide

45

Chapter 3: Web application deployment and management

a .war file
a .zip file that includes the necessary directory structure (see below for more information)
a UNIX .tar file that includes the necessary directory structure
a deep copy of the web application's directory
a soft link (symbolic link) to the web application's directory
The standard directory structure for a web application is:

/exampleapp - The root directory for the application is located in the server's /webapps
directory (default) or another location configured by the administrator. The root directory contains
the /WEB-INF folder and any files that have to be visible to the client browser, like HTML and
JSP pages. These files can be organized into a subdirectory for more complicated applications.

/exampleapp/WEB-INF - In addition to the directories listed below, this folder contains the
Web Application Deployment Descriptor (web.xml), which contains the configuration information
for the application in a standard format

/exampleapp/WEB-INF/classes - This folder contains any Java class files that are not
organized into .jar files, including servlet classes.

/exampleapp/WEB-INF/lib - This folder contains any .jar libraries needed for the
application.
Note: The minimum directory structure required for a web application includes the
/exampleapp/WEB-INF directory and the web.xml file. The /WEB-INF/classes and /lib
directories are only required when distributing loose Java class files and .jar files.
For more information on Tomcat directory structure, see
http://tomcat.apache.org/tomcat-7.0-doc/index.html.

46

Pacific Application Server for OpenEdge: Administration Guide

4
Security overview
The default security configuration for the core Pacific Application Server (PAS) includes some
standard Tomcat functionality, along with Progress customizations and new features.
For details, see the following topics:

Pacific Application Server production server customizations

HTTPS support

The Spring Security Framework in PAS for OpenEdge

JVM security manager

Realms and roles

Remote access filters

Development server and production server security issues

Pacific Application Server production server

customizations
Although it is based on Tomcat, the Pacific Application Server (PAS) is a web application server
that is configured to function as a production server. In contrast, the standard Tomcat product
download is configured as a development server.

Pacific Application Server for OpenEdge: Administration Guide

47

Chapter 4: Security overview

The difference between a development server and a production server is largely a matter of security.
Typically, a server in a development environment allows unrestricted access to and control by a
user or group of users. A production server, on the other hand, is configured to restrict access to
authorized users and to limit control to system administrators. For example, in a development
environment anyone might be allowed to shut down the server, whereas, in a production
environment, only an administrator with appropriate privileges would be allowed to stop a running
server.
Some of the security customizations that tailor PAS as a production server are:

Removal of manager and host-manager Web applications These are default Tomcat
applications that enable remote online administration. These applications are archived in the
$CATALINA_HOME/extras directory and can be redeployed to enable their functionality.

Replacement of the default Tomcat webapps/ROOT application Replaced by a ROOT

application that specifically supports Progress applications, including application security. The
Tomcat ROOT application is archived in the $CATALINA_HOME/extras directory.

Auto-deployment turned off by default Prevents the deployment of WAR files that are
maliciously or erroneously copied to the server. If turned on, the server automatically deploys
any new or updated WAR files in its Web application directory. (Note however that the server
will automatically unpack WAR files when they are legitimately deployed using TCMAN or
standard Tomcat utilities.)

Shutdown port disabled for UNIX Prevents unauthorized stopping of the server.
Note that a shutdown port is optional for servers running on UNIX systems. However, you must
specify a shutdown port when you create a server that runs on Windows systems. The TCMAN
utility supports specifying shutdown ports with the s option to the create action.

JMX remote access not enabled Although PAS includes JMX and JConsole support for
server management, the default is for local access only.

Web crawler filtering enabled Prevents server being overloaded by sessions initiated by
web crawlers.
Note: Although the default PAS is a production server, you can, some tailoring, run PAS as a
development server.You can, for example, enable remote administration by deploying the manager
applications to an instance, start an instance with a shutdown port enabled, and so on.

HTTPS support
The Pacific Application Server (PAS) supports HTTP over a Secure Sockets Layer (HTTPS) by
allowing you to configure an HTTPS port when you create an instance of a PAS server. The TCMAN
utility supports specifying HTTPS ports with the -P option to the create action.
For example, the following instance is created with an HTTP port of 8501 and an HTTPS port of
8601:
$: $CATALINA_HOME/bin/tcman.sh create -p 8501 -P 8601 /psc/acme1
Server instance acme1 created at /psc/acme1

48

Pacific Application Server for OpenEdge: Administration Guide

The Spring Security Framework in PAS for OpenEdge

In PAS (and in Tomcat as well) HTTPS port support is provided by the Secure Socket Layer (SSL)
implementation of the Java Secure Socket Extension (JSSE).
Important:
On a production server, you must replace the default SSL Server Certificate with a fully qualified
certificate from a Certificate Authority (CA).
Server access via HTTPS is dependent on having an SSL Server Certificate. To support initial
configuration and testing, PSC includes a self-signed server certificate in a Java keystore. (A key
store is basically a file that contains the encrypted keys required for encoding and decoding
information.) The PSC keystore is formatted according to the PKCS12 format and is maintained
using the Java Keytool utility.
However, the default server certificate should only be used on a non-production server, or as a
temporary certificate for setting up SSL a production server. Using the default certificate on a fully
functional and deployed production server, is a serious security risk.

The Spring Security Framework in PAS for OpenEdge

The Pacific Application Server (PAS) for OpenEdge employs the Spring Security framework to
provide enterprise-level application security with regard to:

Authentication verification that username and password combinations are valid.

Authorization enforcing access control (user accounts are granted permissions according
to their assigned roles).
Spring Security is a Java-based framework provided in the /common/lib directory of the core
PAS server. For general information about Spring Security, see http://www.springsource.org. For
reference and API information, see http://static.springsource.org/spring-security/site/reference.html

JVM security manager

When you run Tomcat, each instance of the server runs in the context of its own individual JVM
whose security can be managed with the Java Security Manger.
PAS is enabled with a default configuration of the standard JVM Security Manager. The JVM
security is configured in the /conf/catalina.policy file of a given PAS instance.
The catalina.policy file uses Permission classes, either the built-in JDK classes or customized
classes, to control what actions a class can take. The following are just a few examples of the
built-in classes:

java.io.FilePermissions: controls access to read, write, delete, and other actions for
files and directories

java.net.SocketPermissions: controls network access through sockets

java.security.SecurityPermissions: controls access to security methods
For more information on the JVM Security Manager in Tomcat, see
http://tomcat.apache.org/tomcat-7.0-doc/security-manager-howto.html

Pacific Application Server for OpenEdge: Administration Guide

49

Chapter 4: Security overview

Realms and roles

A realm is a collection of usernames and passwords, and it includes the roles associated with each
of those users. PAS can support one or more realm definitions. A role controls the amount of
access a given group of users has. All authorizations in The Pacific Application Server are
role-based; access privileges cannot be granted on a user-by-user basis.
PAS retains the roles defined in Tomcat's default MemoryRealm, but also adds a set of PAS roles
that map to the Tomcat roles and allows for consistency across the product. For example,
ROLE_PSCadmin allows unrestricted administrator access, and it maps to Tomcat's admin-gui,
admin-script, manager-gui, manager-script, and manager-status roles.

Managing users and roles for Manager and Host Manager

applications
For user authentication, the Pacific Application Server comes configured for use with Tomcat's
MemoryRealm. The MemoryRealm accesses user authentication information stored in an XML
file, conf/tomcat-users.xml.You can replace the MemoryRealm with a different type of realm,
such as JDBC or LDAP, and you can have multiple realms of different types configured at the
same time.
Note: The MemoryRealm configuration is not intended for use in a production environment. For
production, you should replace the MemoryRealm with a stronger source of user authentication.
PAS retains the roles defined in Tomcat's default MemoryRealm, but PAS also includes a new set
of roles that include the Tomcat roles. The following table lists the new roles and what existing
Tomcat roles they map to, if any:
Table 9: PAS roles mapped to Tomcat roles
PAS role

ROLE_PSCAdmin

Includes Tomcat
Manager and Host
Manager roles
admin-gui
admin-script
manager-gui
manager-script
manager-jmx

Description

Unrestricted administration access. The

Tomcat admin roles allow access to the HTML
GUI and text interfaces of the Host Manager
application, and the manager roles allow
access to the HTML GUI, text interface, JMX
proxy, and status pages of the Manager
application.

manager-status

50

Pacific Application Server for OpenEdge: Administration Guide

Realms and roles

PAS role

Includes Tomcat
Manager and Host
Manager roles

ROLE_PSCOper

admin-script
manager-script
manager-status

ROLE_PSCUser
ROLE_PSCNone

none
none

Description

Restricted operator administration access.

The Tomcat roles allow access to the text
interfaces of the Host Manager and Manager
applications as well as the status pages in
the Manager application.
Non-priviliged access
No access, for user account authorization
testing

Note: If you use a realm(s) other than the default MemoryRealm, that realm must have the roles
listed in the table above.
PAS comes with three default test accounts configured in conf/tomcat-users.xml, as described
in the following table:
Table 10: PAS default user accounts
Username
tomcat

tcuser1
tcuser2

Password
tomcat

tcuser
tcuser

Role(s)
ROLE_PSCAdmin, ROLE_PSCOper,
ROLE_PSCUser
ROLE_PSCUser
ROLE_PSCNone

The format for users entries in conf/tomcat-users.xml is shown below, with the tomcat default
user given as an example:
<user username="tomcat" password="tomcat"
roles="ROLE_PSCAdmin,ROLE_PSCOper,ROLE_PSCUser"/>

Pacific Application Server for OpenEdge: Administration Guide

51

Chapter 4: Security overview

Remote access filters

The Pacific Application Server (PAS) is configured with filters that allow you to deny access based
on IP addresses or host names. These filters are implemented as valves in the PAS instance's
/conf/server.xml file. The following snippet from the default server.xml shows that the
filters are set to allow access by anyone:
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow=".*"/>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow=".*"/>

The RemoteHostValve and RemoteAddrValve filters can take two attributes:

allow
A comma-delimited list of regular expressions that a client must match in order to be allowed
access.
deny
A comma-delimited list of regular expressions that, when matched, excludes a client from
access.

Development server and production server security

issues
The Pacific Application Server (PAS) for OpenEdge is a Web application server that is available
as either a development server or a production server product.
The difference between a development server and a production server is largely a matter of security.
Typically, a server in a development environment allows unrestricted access to and control by a
user or group of users. A production server, on the other hand, is configured to restrict access to
authorized users and to limit control to system administrators. For example, in a development
environment anyone might be allowed to shut down the server, whereas, in a production
environment, only an administrator with appropriate privileges would be allowed to stop a running
server.

52

Pacific Application Server for OpenEdge: Administration Guide

Development server and production server security issues

Some of the security customizations in the production server version of PAS for OpenEdge are:

Removal of manager and host-manager Web applications These are default Tomcat
applications that enable remote online administration. These applications are archived in the
$CATALINA_HOME/extras directory and can be redeployed to enable their functionality.

Replacement of the default Tomcat webapps/ROOT application Replaced by a ROOT

application that specifically supports Progress applications, including application security. The
Tomcat ROOT application is archived in the $CATALINA_HOME/extras directory.

Auto-deployment turned off by default Prevents the deployment of WAR files that are
maliciously or erroneously copied to the server. If turned on, the server automatically deploys
any new or updated WAR files in its Web application directory. (Note however that the server
will automatically unpack WAR files when they are legitimately deployed using TCMAN or
standard Tomcat utilities.)

Shutdown port disabled for UNIX Prevents unauthorized stopping of the server.
Note that a shutdown port is optional for servers running on UNIX systems. However, you must
specify a shutdown port when you create a server that runs on Windows systems. The TCMAN
utility supports specifying shutdown ports with the s option to the create action.

JMX remote access not enabled Although PAS includes JMX and JConsole support for
server management, the default is for local access only.

Web crawler filtering enabled Prevents server being overloaded by sessions initiated by
web crawlers.
Note: In PAS for OpenEdge, a ROOT application that specifically supports OpenEdge application
security replaces the default Tomcat ROOT application. The Tomcat ROOT application is archived
in the $CATALINA_HOME/extras directory.

Pacific Application Server for OpenEdge: Administration Guide

53

Chapter 4: Security overview

54

Pacific Application Server for OpenEdge: Administration Guide

5
Web application security configurations
In Pacific Application Server for OpenEdge, the Spring Security framework implements Web
application security.
Spring Security requires a separate authentication provider plug-in for each user account information
source, such as an RDBMS database or a local text file. The Spring Security authentication process
uses an object model that provides the following functionality:

Authentication manager: The manager is responsible for creating and calling one of more
authentication providers until the authentication process is complete (success or failure).

Authentication provider: The provider is called by the authentication manager and is

responsible for creating the user details service.

User details service: This service is created by the authentication provider and is responsible
for interacting with the account system to retrieve the user account along with the account
attributes information, such as password and user roles. This information is used for validating
the account password and for creating a Spring Security authentication token.

Authentication token: This token is created as the result of a successful Spring Security
authentication process. The token contains authenticated user information, such as user ID,
granted roles, and session ID.
Note: The authentication token is used to generate an OpenEdge ClientPrincipal token that
can be used further in the authorization process.

For details, see the following topics:

Spring Security configuration templates

Applying a Spring Security model to a Web application

Pacific Application Server for OpenEdge: Administration Guide

55

Chapter 5: Web application security configurations

Enabling Spring Security for APSV and SOAP Web applications

Local configurations

SPA security configurations

LDAP security configurations

SAML security configurations

Container security configurations

CORS support

Single sign-on (SSO) support in PAS for OpenEdge

Spring Security configuration templates

PAS for OpenEdge provides a number of Spring Security models for Web applications.The security
models included with PAS for OpenEdge are implemented in the templates described in the table
below.
Note: The Spring Security framework enables you to implement other types of authentication
systems. For more information on implementing authentication systems, see the Spring Security
framework documentation.
Table 11: Spring Security models and templates
Security Model
Basic

Configuration Template
oeablSecurity-basic-local.xml

Description
This is the default configuration model.
The Basic configuration authenticates
clients using HTTP Basic authentication
for user accounts, based on the user
information in the users.propertiesfile
of the Web application.

oeablSecurity-basic-ldap.xml

This configuration model authenticates

clients using HTTP Basic authentication
for user accounts, based on the user
information stored in the directory
governed by LDAP (Lightweight Directory
Access Protocol).

oeablSecurity-basic-oerealm.xml This configuration model authenticates

clients using HTTP Basic authentication
for user accounts managed by an
OpenEdge application server.
oeablSecurity-basic-saml.xml

56

This configuration model authenticates

clients using HTTP Basic authentication
for external user accounts represented by
a SAML token.

Pacific Application Server for OpenEdge: Administration Guide

Spring Security configuration templates

Security Model
Form

Configuration Template
oeablSecurity-form-local.xml

Description
This model authenticates clients using the
generic HTTP Form login authentication
for user accounts, based on the
users.properties file of the Web
application.
For more information on managing local
user accounts, see the Spring Security
framework documentation.

oeablSecurity-form-ldap.xml

This model authenticates clients using the

generic HTTP Form login authentication
for user accounts stored in the directory
governed by LDAP (Lightweight Directory
Access Protocol).

oeablSecurity-form-oerealm.xml This model authenticates clients using the

generic HTTP Form login authentication
for user accounts managed by an
OpenEdge application server.

Anonymous

oeablSecurity-form-saml.xml

This configuration model authenticates

clients using HTTP Form login
authentication for external user accounts
represented by a SAML token.

oeablSecurity-anonymous.xml

This is the default configuration model for

Web applications.
With the anonymous security model, you
make the Web service public. That is, any
user can make requests to the Web
service.

Container

oeablSecurity-container.xml

This model integrates Spring Security

framework with the authentication service
of the Java container.
The Java container authenticates, and the
Spring Security framework controls the
authorization to Web application
resources.
You apply security configurations in the
server's realm implementation in
conf/server.xml.
For more information on container
configuration, see the Apache Tomcat
Realm Configuration documentation.

The templates that you can use to implement a security model are located in:
$CATALINA_BASE/webapps/webapp_name/WEB-INF

Pacific Application Server for OpenEdge: Administration Guide

57

Chapter 5: Web application security configurations

You choose the security model for the Web application in:
$CATALINA_BASE/webapps/webapp_name/WEB-INF/web.xml

Applying a Spring Security model to a Web application

You implement a Spring Security model by supplying a reference to its configuration template in
a Web application's web.xml file.
To choose and apply a Spring Security configuration:
1. Open the Web application's $CATALINA_BASE/webapps/webapp_name/WEB-INF/web.xml
file.
2. Find the <context-param> tag.
3. Uncomment one of the configuration file templates from the list of security configurations in the
<param-value> code block.
For example, the following shows oeablSecurity-form-local.xml as the chosen security
model template.
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>
<!-/WEB-INF/oeablSecurity-basic-local.xml
/WEB-INF/oeablSecurity-basic-ldap.xml
/WEB-INF/oeablSecurity-basic-oerealm.xml
/WEB-INF/oeablSecurity-form-ldap.xml
/WEB-INF/oeablSecurity-form-oerealm.xml
/WEB-INF/oeablSecurity-anonymous.xml
/WEB-INF/oeablSecurity-container.xml
/WEB-INF/oeablSecurity-form-saml.xml
/WEB-INF/oeablSecurity-basic-saml.xml
-->
/WEB-INF/oeablSecurity-form-local.xml
</param-value>
</context-param>

Note: You cannot uncomment more than one security model template.
4. Save the web.xml file.
Note:

All security models, with the possible exception of oeablSecurity-anonymous.xml, require

further configuration with regard to setting up user accounts, roles, authentication, and
authorization.

Initial configuration enables Spring Security for REST Web applications. Additional configuration
is necessary if you want to enable Spring Security for the APSV and the SOAP transports.

Additional configuration steps are required to set up CORS support and Single sign-on.
For information on additional Spring Security configuration tasks, follow the link to the appropriate
topic listed below.

58

Pacific Application Server for OpenEdge: Administration Guide

Enabling Spring Security for APSV and SOAP Web applications

See also
Enabling Spring Security for APSV and SOAP Web applications on page 59
Local configurations on page 62
SPA security configurations on page 65
LDAP security configurations on page 75
SAML security configurations on page 76
Container security configurations on page 83
CORS support on page 83
Single sign-on (SSO) support in PAS for OpenEdge on page 89

Enabling Spring Security for APSV and SOAP Web

applications
After you apply and configure a Spring Security model for Web applications, Spring Security is
only enabled for REST Web applications. Additional configuration is necessary if you want to
enable Spring Security for APSV and SOAP Web applications.
By default, security is disabled for both APSV and SOAP transports. The following snippet from
oeablSecurity-xxxx.xml shows that security is disabled as a result of the import of
apsv-basic.xml and soap-none.xml:

<!-- To disable security for APSV, import apsv-none.xml (and comment out
import of apsv-basic.xml)-->
<!-- To enable security for APSV, import apsv-basic.xml (and comment out
import of apsv-none.xml) -->
<b:import resource="apsv-none.xml"/>
<!--<b:import resource="apsv-basic.xml"/> -->
<!-- To disable security for SOAP, import apsv-none.xml (and comment out
import of soap-basic.xml)-->
<!-- To enable security for SOAP, import apsv-basic.xml (and comment out
import of soap-none.xml) -->
<b:import resource="soap-none.xml"/>
<!--<b:import resource="soap-basic-local.xml"/> -->

Pacific Application Server for OpenEdge: Administration Guide

59

Chapter 5: Web application security configurations

The first step to enable security for APSV and/or SOAP Web applications is to comment out the
defaults and import apsv-basic.xml and/or soap-basic-local.xml. In the following example,
Spring Security is enabled for both APSV and SOAP:

<!-- To disable security for APSV, import apsv-none.xml (and comment out
import of apsv-basic.xml)-->
<!-- To enable security for APSV, import apsv-basic.xml (and comment out
import of apsv-none.xml) -->
<!-- <b:import resource="apsv-none.xml"/> -->
<b:import resource="apsv-basic.xml"/>
<!-- To disable security for SOAP, import apsv-none.xml (and comment out
import of soap-basic.xml)-->
<!-- To enable security for SOAP, import apsv-basic.xml (and comment out
import of soap-none.xml) -->
<!-- <b:import resource="soap-none.xml"/> -->
<b:import resource="soap-basic-local.xml"/>

After you enable security, you need to update the apsv-basic.xml and/or
soap-basic-local.xml template files.

See also
Applying a Spring Security model to a Web application on page 58
Updating apsv-basic.xml on page 60
Updating soap-basic-local.xml on page 61

Updating apsv-basic.xml
After you have enabled Spring Security for the APSV transport in an oeablSecurity-xxxx.xml
file, you can complete additional security configuration by updating the apsv-basic.xml file as
follows:

60

Pacific Application Server for OpenEdge: Administration Guide

Enabling Spring Security for APSV and SOAP Web applications

1. Optionally update user access by adding to or modifying the following defaults:

<intercept-url pattern="/apsv/**" method="HEAD"
access="hasAnyRole('ROLE_PSCUser')"/>
<intercept-url pattern="/apsv/**" method="GET"
access="hasAnyRole('ROLE_PSCUser')"/>
<intercept-url pattern="/apsv/**" method="POST"
access="hasAnyRole('ROLE_PSCUser')"/>

2. Optionally enable Single Sign-on by uncommenting the reference to OEPreauthfilter:

<!-- OpenEdge PRE AUTH Filter -->
<!-- USER EDIT: uncomment PRE_AUTH_FILTER filter
to enable pre-auth-->
<!-<custom-filter position="PRE_AUTH_FILTER"
ref="OEPreauthfilter" />
-->

3. If you enabled oeablSecurity-xxx-saml.xml, uncomment the references to

samlProcessingFilter and OESamlSSOProcessingFilter:
<!-<custom-filter before="BASIC_AUTH_FILTER"
ref="samlProcessingFilter" />
-->
.
.
.
<!-<custom-filter before="FORM_LOGIN_FILTER"
ref="OESamlSSOProcessingFilter"

/>-->

See also
Enabling Spring Security for APSV and SOAP Web applications on page 59

Updating soap-basic-local.xml
After you have enabled Spring Security for the SOAP transport in an oeablSecurity-xxxx.xml
file, you can optionally update user access by adding to or modifying the following defaults in
soap-basic.xml :
<intercept-url pattern="/soap/wsdl/**" method="GET"
access="hasAnyRole('ROLE_PSCUser')" />
<intercept-url pattern="/soap/**" method="POST"
access="hasAnyRole('ROLE_PSCUser')" />

Pacific Application Server for OpenEdge: Administration Guide

61

Chapter 5: Web application security configurations

See also
Enabling Spring Security for APSV and SOAP Web applications on page 59

Local configurations
After choosing a local security configuration model (oeablSecurity-XXXX-local.xml) for a
Web application, you can add, remove, modify users or user authentication settings by updating
the $CATALINA_BASE/webapps/webapp_name/users.properties file.
The following shows the syntax of entries in users.properties:

[role2, ...,

username=password, role1,

roleN,

]{

enabled

disabled

The following shows the content of the default users.properties file:

restuser=password,ROLE_PSCUser,enabled
restdebug=password,ROLE_PSCUser,ROLE_PSCDebug,enabled

The contents of the users.properties file are included as an example and they are not secure
since they are stored as plain text. Typically, for a production server, you would generate hashed
and salted passwords, and add the secure passwords to the users.properties file.
You can use the Open Source Jacksum utilities to generate hashed and salted passwords.

See also
Using Jacksum to generate hashed and salted passwords on page 63
Access control in local security configurations on page 64
Using Jacksum to generate hashed and salted passwords on page 63
Access control in local security configurations on page 64

Adding new users in local security configurations

To add a new user, update the users.properties with an entry in the following format:

[...,

username=password, ROLE1,

ROLEn,

] {enabled |

disabled

For example, the following shows the entries for the default users restuser and restdebug:
restuser=password,ROLE_PSCUser,enabled
restdebug=password,ROLE_PSCUser,ROLE_PSCDebug,enabled

62

Pacific Application Server for OpenEdge: Administration Guide

Local configurations

See also
Using Jacksum to generate hashed and salted passwords on page 63
Access control in local security configurations on page 64

Using Jacksum to generate hashed and salted passwords

To provide greater security for user accounts stored in users.properties, you can use the
Open Source Jacksum utility to generate hashed and salted passwords for the entries in the file.
For more information on hash and salt, search for hash and salt cryptography references on the
Web.
To use the Jacksum utility:
1. Download and install the Jacksum software by following the instructions in
http://www.jonelo.de/java/jacksum/#Installation.
2. Execute the following command to open the Jacksum installation directory:
CD <installation-dir>\jacksum <version>

3. Execute the following command to get an encoded password for the required string. In this
example, you are encoding the string newpassword{newuser}:
java -jar jacksum.jar -a sha -E base64 -q "txt:newpassword{newuser}"

In this example, you encoded the string newpassword{newuser}, and Jacksum returned the
encoded password, Y9+iCjOORQoqoTWdRgjd/81Ms9w=
Note:
This example uses the sha algorithm to hash the newpassword string, and the newuser string
in the curly braces as salt.
You can use any of the popular hashing techniques that Jacksum supports, such as CRC, SHA,
Tiger, sum and Whirlpool. And, you can use any string as salt in the encoding process.
4. Open the oeablSecurity-XXXX.xml configuration file you specified in the Web application's
web.xml file.
5. Uncomment the code snippet that implements password hashing in the Web application.
For example, assume that you are using the Basic security configuration file,
oeablSecurity-basic-local.xml. Do the following:

Pacific Application Server for OpenEdge: Administration Guide

63

Chapter 5: Web application security configurations

a) Navigate to and uncomment the code snippet in bold in the

oeablSecurity-basic-local.xml:
<authentication-manager id="RestApplicationtAuth"
<authentication-provider>
<!-- Uncomment to add strong password hashing in
users.properties
<password-encoder hash="sha" base64="true">
<salt-source user-property="username" />
</password-encoder>
-->
<user-service properties="/WEB-INF/users.properties" />
</authentication-provider>
</authentication-manager>

After uncommenting, the code snippet must look as follows:

<authentication-manager id="RestApplicationtAuth"
<authentication-provider>
<password-encoder hash="sha" base64="true">
<salt-source user-property="username" />
</password-encoder>
<user-service properties="/WEB-INF/users.properties" />
</authentication-provider>
</authentication-manager>

b) Save the security configuration file, oeablSecurity-basic-local.xml.

6. Add the new user account, newuser, and the encoded password (that you generated in Step
3 on page 63) to the users.properties file by appending the following line of code in it:
newuser=Y9+iCjOORQoqoTWdRgjd/81Ms9w=,ROLE_PSCAdmin,enabled

In this example, you assigned the existing ROLE_PSCAdmin role to the newuser and enabled
the user account newuser to work with the REST Management Agent.
Note: The users.properties file cannot store both plain text and encoded passwords.
Therefore, before adding a new user with an encoded password, you must ensure that all the
existing users and the users you add to the users.properties file have encoded passwords.
7. Save and close the users.properties file.

Access control in local security configurations

You can define access privileges to resources by adding Spring Security expressions in a
oeablSecurity-XXXX-local.xml configuration file.

64

Pacific Application Server for OpenEdge: Administration Guide

SPA security configurations

For example, the following snippet grants access to data from a status resource to any user who
has either ROLE_PSCAdmin or ROLE_PSCOper privileges:
<intercept-url pattern="/status" method="GET"
access="hasAnyRole('ROLE_PSCAdmin','ROLE_PSCOper')"/>

For more information, see Expression-Based Access Control in the Spring Security online
documentation.

See also
Adding new users in local security configurations on page 62

SPA security configurations

OpenEdge Single Point of Authentication (SPA) allows you to use an OpenEdge application server
as a source of user account information for the authentication process. You implement SPA when
you specify either oeablSecurity-basic-oerealm.xml or
oeablSecurity-form-oerealm.xm as the Spring Security model in the Web application's
web.xml file.
The OpenEdge SPA implementation extends the Spring Security authentication process. The
implementation consists of 2 components:

OpenEdge Realm (OERealm) Client: The client contains the Spring Security authentication
provider and user account service objects that interact with the application server to retrieve
the user account information. This information is then sent to the Spring Security authentication
process.
The OERealm Client does the following:
1. Connects to the application server.
2. Executes a request to locate the user account and retrieve the account unique numeric ID.
3. Executes requests to retrieve the user account details in the following order:
a. Granted roles
b. The account enabled state
c. The account locked state
d. The account expired state
Note: If the OErealm client finds that the account does not exist or if the account is in the
disabled, locked, or expired state, no additional AppServer requests are performed.

OERealm AppServer ABL interface:The service interface class that implements the OERealm
ABL interface must also implement the OERealm component on the AppServer.
The actions of the class is performed in the following order:

Pacific Application Server for OpenEdge: Administration Guide

65

Chapter 5: Web application security configurations

1. Search for the user account using the name (userid[@domain]).

2. Return the user account attributes for the user account.
3. Validate the user accounts password.
Optionally, authorize the OERealm client and enable it to receive user account information.

Creating an OERealm service interface

To implement OpenEdge SPA, you must create an OERealm service interface that finds user
account information, obtains user attributes, and validates a user account's password.
To configure an OERealm service:
1. Configure a OpenEdge Application Server to host the OERealm service interface class.
Note: Either a PAS for OpenEdge or an OpenEdge AppServer instance can host the OERealm
service interface class. If you are using the OpenEdge AppServer, it must be configured as a
STATE-FREE instance. (A PAS for OpenEdge instance functions in any operating mode.)
2. Create a singleton OOABL class that implements the OERealm HybridRealm interface. If you
have the OpenEdge Documentation and Samples installed, you can find a sample interface
implementation class, HybridRealm.cls, at
$DLC\src\samples\security\OpenEdge\security\Realm.
In the sample HybridRealm.cls file, the following methods are declared and defined:
Table 12: Methods defined in the HybridRealm.cls class
Method
GetAttribute

Yes

Description
This method retrieves an attribute for the specified user
account.

GetAttributeNames No

This method retrieves the name assigned to the attributes.

No

This method retrieves all the user names associated with

the user account.

GetUserNamesByQuery No

This method retrieves the user names that match the input
query string.

GetUserNames

66

Mandatory?

RemoveAttribute

No

This method deletes the value of the given attribute.

SetAttribute

No

This method assigns a new value to the given attribute.

Pacific Application Server for OpenEdge: Administration Guide

SPA security configurations

Method

Mandatory?

ValidatePassword Yes

Description
This method validates the client-supplied password of the
user account against the stored password.
Note: You can define both the clear-text and digest form
of the ValidatePassword() method.

ValidateUser

Yes

This method searches for the user account, validates

whether the account domain is valid and enabled, and
returns the account numeric ID.
Note: The OERealm service interface uses a numerical
user account ID as an ABL integer instead of the full user
account name. If the user account storage of your
OERealm service does not support the integer user
account IDs, it is recommended that you build a
mechanism to permanently assign unique ABL integer
values to each user account in the storage.

You can implement the GetAttribute() method to return the UNKNOWN or CHARACTER value.
If you have configured the Web application with an SPA security configuration model, the
OERealmUserDetailsImpl module of the OERealm client handles the UNKNOWN value by
replacing the value with a static, non-configurable default value. If a CHARACTER value is
returned, the OERealm service interface must encode the value in a format that the
OERealmUserDetailsImpl module can understand.
The known values of the OERealmUserDetailsImpl module are:
Table 13: OERealmUserDetailsImpl module attributes
Attribute
ATTR_ROLES

Data type

Character encoding format

string-extent "" or "xxxx[,yyyy,zzzz]"

Note: The OERealm service interface must return
roles without the ROLE_ prefix. For example, the
interface must return PSCUser instead of
ROLE_PSCUser.

ATTR_ENABLED

boolean

A character from the {T,t,F,f,Y,y,N,n,0,1} set.

T,t,Y,y,1 denotes that the user is enabled.
F,f,N,n,0 denotes that the user is disabled.

Pacific Application Server for OpenEdge: Administration Guide

67

Chapter 5: Web application security configurations

Attribute
ATTR_LOCKED

Data type

Character encoding format

A character from the {T,t,F,f,Y,y,N,n,0,1} set.

boolean

T,t,Y,y,1 denotes that the user is locked.

F,f,N,n,0 denotes that the user is not locked.
ATTR_EXPIRED

A character from the {T,t,F,f,Y,y,N,n,0,1} set.

boolean

T,t,Y,y,1 denotes that the user is expired.

F,f,N,n,0 denotes that the user is not expired.
Spring Security does not allow expired users.

Note:
If your OERealm Service Interface uses attribute names different from the ATTR_XXXX attributes,
update the attribute names in the OERealmUserDetails bean of the
oeablSecurity-xxxx-oerealm.xml file.
Also note that some of the OE Realm Service Interface clients (like Rollbase, for example) use
the default attribute names (i.e. in the ATTR_XXXX format) as shown in the table above. Do
not change the attribute names if clients depend on the default names.

3. Build and test your OERealm service interface. You can perform this step using an ABL client
test harness that calls the OERealm service interface.
Note: Errors returned to the client are generic. You can find error details that are more helpful
in the application's log file.

See also
SPA security considerations on page 73

Updating the SPA configuration file

After choosing an SPA security configuration model, you must edit the SPA configuration file in
order to update the properties of the authentication provider and the user details service. The
authentication provider, OERealmAuthProvider, is a bean that defines how to create a
ClientPrincipal after an OpenEdge database user account's authentication process is successful.
The user details service, OERealmUserDetails is a bean that specifies how the authenticated
users connect to PAS for OpenEdge.
To update the SPA configuration file:

68

Pacific Application Server for OpenEdge: Administration Guide

SPA security configurations

1. Open the SPA configuration file

($CATALINA_BASE/webapps/webapp_name/oeablSecurity-XXXX-oerealm.xml) and
find the following element:
<b:bean id="OERealmAuthProvider"
class="com.progress.rest.security.
OERealmAuthProvider" >

2. Update the properties of OERealmAuthProvider.

The following table describes the properties of OERealmAuthProvider:

Pacific Application Server for OpenEdge: Administration Guide

69

Chapter 5: Web application security configurations

Table 14: OERealmAuthProvider properties

Range of
accepted
values

Spring property

Default
value

createCOAuthn

"true"

"true"
"false"

Creates a Spring ClientPrincipal

authentication token when set to true.

key

""

"<Valid
string>"

Specifies the OpenEdge domain's access

code to seal the ClientPrincipal token
1
with the specified string.

userDomain

""

"<Valid
string>"

Specifies the OpenEdge domain name to

append to the user account name if the
name does not already contain a user
domain.

multiTenant

"false"

"true"
"false"

authz

"true"

properties

expires

Description

Prescribes the user to enter a fully qualified

OpenEdge user-id@domain tenant when
set to true.

"true"
"false"

Loads the user account's roles as Spring

authorities used in the Spring security
authorization process.

"empty"

"valid
name
and value"

Loads static client-principal properties by

name and value.

"0"

"0" or
"positive
integer"

Expires ClientPrincipal in the

specified number of seconds.

3. Find the following element:

<b:bean id="OERealmUserDetails"
class="com.progress.rest.security.
OERealmUserDetailsImpl">

4. Update the properties of OERealmUserDetails.

The following table describes the properties of OERealmAuthProvider:

70

The key property can also be in the "oech1::<hex-string>" where <hex-string> is the output from the OE genpassword
utility.

Pacific Application Server for OpenEdge: Administration Guide

SPA security configurations

Table 15: OERealmUserDetails properties

Spring property

Default value

Range of accepted values

Description

internal://localhost/nxgas
for a local PAS for OpenEdge
instance

http[s]://host:port/
oeabl_appname/apsv

for a remote PAS for

OpenEdge instance

realmURL

value must be
updated

http[s]://host:port/
aia_appname/aia

Specifies the URL of the

OpenEdge application server
where the realm is
implemented.

Note: The realm can be hosted

on either a PAS for OpenEdge
instance or an OpenEdge
AppServer. This allows you to
AppServer[s]://NameServer_host:NameServer_port/
retain legacy implementations
service_name
that were configured on an
for a remote OpenEdge
OpenEdge AppServer.
Appserver configured with a
NameServer
for a remote OpenEdge
AppServer using AIA

AppServerDC[s]://Appserver_host:Appserver_port
/service_name

for a remote OpenEdge

Appserver using Direct Connect

realmClass

grantedAuthorities

rolePrefix

roleAttrName

"OpenEdge.
Security.
Realm.
HybridRealm"

"ROLE_PSCUser"

"ROLE_"

"ATTR_ROLES"

"valid OOABL
path"

Specifies the realm service

interface's class path. SPA
security implementation for the
REST Web application must
specify the HybridRealm
interface class.

"ROLE_XXXX"

Specifies the static Spring roles

granted for the user if the
AppServer realm service
interface does not support roles.

"valid
string"

Specifies the role name's prefix

that the Spring security
framework must use when
converting external role names
into Spring roles names.

"valid
string"

Specifies the string name

supported by the realm service
interface to return a
comma-separated list of roles
names.

Pacific Application Server for OpenEdge: Administration Guide

71

Chapter 5: Web application security configurations

Spring property

enabledAttrName

lockedAttrName

expiredAttrName

realmPwdAlg

Default value

Range of accepted values

Description

"ATTR_ENABLED"

"valid
string"

Specifies the string name

supported by the realm service
interface to return an account's
enabled state.

"ATTR_LOCKED"

"valid
string"

Specifies the string name

supported by the realm service
interface to return an account's
locked state.

"ATTR_EXPIRED"

"valid
string"

Specifies the string name

supported by the realm service
interface to return an account's
expired state.

"0"

"0"
"3"

Specifies the format of the

password passed to the realm
service interface for
validation.Specify:

0 for clear-text passwords.

3 for HTTP digest
passwords.

realmTokenFile

""

""
"valid
token file"

Optionally specify a file that

holds a serialized
ClientPrincipal used to
authenticate the realm service
interface. If left blank,
authentication will not occur.

5. Save and close the configuration file.

6. Test the OERealm service:
a) In the WEB-INF/logging.xml file, uncomment the line following OEABL Security.
For example:
<!-- OEABL Security -->
<logger name="com.progress.appserv.services.security" level="INFO"/>

Note that you can change the level from INFO to DEBUG or TRACE to get more logging
information.
b) Start (or re-start) the PAS for OpenEdge instance.
c) Check the contents of the $CATALINA_BASE\logs\web_appname_date.log file for
startup errors related to your SPA security configuration.
d) In a Web browser or any HTTP client, test the user authentication process.

72

Pacific Application Server for OpenEdge: Administration Guide

SPA security configurations

SPA security considerations

The SPA security configuration process is used to authenticate users. The process itself must be
secure against unwarranted attacks.
The following considerations must be observed for security purposes:

OERealm service interface security

If the OERealm service requires authentication of the SPA client, then the SPA client must have
a realm token property configured with a file that contains a sealed ClientPrincipal that the
OERealm service is capable of validating.
Since the OERealm user details service can be configured to send a sealed ClientPrincipal to
the AppServer OERealm service interface on each method it invokes, the OERealm service
interface can wrongly intercept the ClientPrincipal from
SESSION:CURRENT-REQUEST-INFO:GET-CLIENT-PRINCIPAL and validate the client before
performing any OERealm operation.
Another security flaw occurs when you use the SECURITY-POLICY:SET-CLIENT() or
SET-DB-CLIENT() method for performing OERealm client identity checks. Using these methods
changes the current identity of the ABL session, which must then be reestablished after the
OERealm operation is complete.
To overcome this problem, it is recommended that you use the
CLIENT-PRINCIPAL:VALIDATE-SEAL() method along with encoded domain access codes
("oech1::xxxx") to validate the ClientPrincipal.You can apply this validation as an operation
at the beginning of each OERealm service interface method. This isolates the OERealm use
case from the other ClientPrincipal-related activities, such as a session, database, AppServer
connection, or BPM identity.

OERealmAuthProvider security
You can configure the OpenEdge domain access code to seal the ClientPrincipal in the Single
sign-on (SSO) mode. By default, the Spring Security OERealmAuthProvider bean creates
the ClientPrincipal as a single-tenant. The problem is that every Web application user of the
ClientPrincipal is a member of the same OpenEdge domain.
You can enhance OERealmAuthProvider security in one of the following ways:

Set the userDomain and key attributes.

You can enhance security by setting the following OERealmAuthProvider attributes while
sealing the ClientPrincipal:

The userDomain attribute to set the static OpenEdge domain.

The key attribute to set the domain access code.
These attributes are used to uniquely identify application users based on the user domain.
You can also disable access to the Web application just by disabling the domain. The
following table defines the available combinations of domain, domain access code, and user
ID:
Table 16: Available combinations of domain, domain access code, and user ID
Domain name
"" (default)

Key attribute
"" (default)

User ID
"uid"
("uid@")

Pacific Application Server for OpenEdge: Administration Guide

Signing operation
Seal the blank domain using the built-in
Domain Registry blank access code.

73

Chapter 5: Web application security configurations

Domain name

Key attribute

User ID

Signing operation

""

"<xxxx>"

"uid"
("uid@")

Seal the blank domain using the clear text

sting value, "<xxxx>".

""

"oech1::<xxxx>" "uid"
("uid@")

Seal the blank domain using the encoded

value, <xxxx>.

"abc"

"" (default)

"uid@abc" Seal the abc domain using the built-in

Domain Registry blank access code.

"abc"

"<xxxx>"

"uid@abc" Seal the abc domain using the clear text

sting value, "<xxxx>".

"abc"

"oech1::<xxxx>" "uid@abc" Seal the abc domain using the encoded

value, <xxxx>.

Set the multiTenant property.

If you enable the multiTenant attribute of the OERealmAuthProvider, all the user IDs
are appended with the userDomain attribute value. In this case, the same key can used
to seal the ClientPrincipal for all OE domains.

Set the External domain registry for multi-tenant applications.

The OERealmAuthProvider provides support for using an administrator-generated Domain
Registry file to sign and seal ClientPrincipals in multi-tenant applications. This file contains
a list of domains that are allowed to have access to the ClientPrincipal.
To use the Domain Registry file:
1. Use the gendomreg command, located at $DLC/bin, that takes a formatted text file as
input and creates a secure binary Domain Registry file. The text file lists OE domains
that are allowed to have access to the ClientPrincipal in the
Domain-name=Domain-access-code format. Each domain must be listed in a separate
line.
2. Copy the Domain Registry file to the OE REST Web applications /WEB-INF/classes
directory.
3. Configure the OERealmAuthProvider bean to load and sign a ClientPrincipal.

Preventing authorization before authentication

The ClientPrincipal that is generated by the Web applications OERealmAuthProvider
supercedes the one that is generated by the OEClientPrincipalFilter for SSO. This is
a problem when the OEClientPrincipalFilter authorizes the incorrect ClientPrincipal
without any processing. You can disable the OEClientPrincipalFilter by setting its
enableCP property to false.
Another potential security problem occurs if a client is able to call the OERealm service interface
without authentication. You can secure the service interface against such unwarranted client
access by using the ClientPrincipal object and validation technique that is similar to the one
that is used in the ABL business logic of your OpenEdge application server .To use this validation
technique, the Web application's OERealmUserDetailsImp module acts as a client and
identifies itself to the application server's OERealm service interface. The service interface
validates the client using a ClientPrincipal just like it is used in other parts of the ABL application.

74

Pacific Application Server for OpenEdge: Administration Guide

LDAP security configurations

To develop the Web application's OERealmUserDetails for acting as an OpenEdge application

server client:
1. Use the genspacp utility, at the $DLC/bin location, to create a sealed ClientPrincipal that
represents a OERealm service client. The utility requires the user ID, domain name, domain
access code, and output file name to create a binary file that contains the sealed
ClientPrincipal in the <file-name>.cp format. The domain name and domain access code
correspond to those that are then used in the OERealm service interface to validate clients.
2. Copy the output file from the $DLC/bin location to the Web application's WEB-INF/classes
directory.
3. Set the realmTokenFile configuration property of OERealmUserDetails to the output
file name.
4. In the OERealm service interface, add the ClientPrincipal validation code. The code can
reside in the AppServer activate procedure or as step in each of the OERealm class methods.
It is recommended that you use the
CLIENT-PRINCIPAL:VALIDATE-SEAL("domain-access-code") method for validation.
You must ensure that domain-access-code is in the encoded "oech1::xxxx" format.
When the OERealm service interface validates the ClientPrincipal in the created binary output
file, the following sequence occurs:
1. Once the Web application is loaded, if the realmTokenFile configuration property of
OERealmUserDetails contains the output file name, the file is used to load the
ClientPrincipal. If the output file does not load, an error is added to the error log.
2. For each user authentication request, OERealmUserDetails is used to send the
ClientPrincipal to the AppServer OERealm service interface methods.
3. The OERealm service interface validates the ClientPrincipal. The following validation
outcomes are possible:

If the ClientPrincipal is not sent to the interface, an error is returned.

If the ClientPrincipal is sent to the interface, the interface is used to validate the domain
access code. If the validation fails, an error is returned.

If the ClientPrincipal validation is successful, the execution of the ABL class method
continues.

LDAP security configurations

The Lightweight Directory Access Protocol (LDAP) is a protocol for authenticating user credentials
that are stored on an LDAP-compliant server. If you are not familiar with LDAP implementation
and user account management, refer to LDAP administration documentation online.
If you choose one of the LDAP security models supported in PAS for OpenEdge
(oeablSecurity-form-ldap.xml or oeablSecurity-basic-ldap.xml), you must update
the settings shown in the following table:

Pacific Application Server for OpenEdge: Administration Guide

75

Chapter 5: Web application security configurations

Table 17: LDAP security configuration settings

Find

Update

<ldap-server id="PrimayLDAP"
url="ldap://enter_hostname:389/root_dn_here"
manager-dn="uid=admin,ou=system"
manager-password="admin" />

<authentication-manager
id="RestApplicationtAuth" >
<ldap-authentication-provider
server-ref="PrimayLDAP"
group-role-attribute="cn"
role-prefix="ROLE_"
group-search-filter="(member={0})"
group-search-base=""
user-search-base=""
user-search-filter="(uid={0})" />
</authentication-manager>

The LDAP server's alias, URL, and

the distinguished name (dn) and
password of an LDAP account that
has search and read access.

All the properties of the LDAP

authentication manager based on
the design and implementation of
your directory services

Note: The LDAP UserDetails implementation in Spring Security automatically updates role names.
Ensure that role names are upper case since searches are case sensitive.
After configuring the LDAP model for your Web application, you can implement CORS support.

See also
CORS support on page 83

SAML security configurations

Security Assertion Markup Language (SAML) is an XML-based standard for exchanging
authentication and authorization data between business entities. It is a product of the OASIS
Security Services Technical Committee. For more information on SAML, start with the SAML
XML.org website.
If you choose one of the SAML security models supported in PAS for OpenEdge
(oeablSecurity-form-saml.xml or oeablSecurity-basic-saml.xml), you must configure
the security model after creating and registering Web application metadata. For more information,
follow the link to the appropriate topic listed below.

See also
Creating and configuring metadata files on page 77
Registering the metadata file with an Identity Provider on page 78
Updating the SAML configuration file on page 79

76

Pacific Application Server for OpenEdge: Administration Guide

SAML security configurations

Creating and configuring metadata files

For each Web application (Service Provider), a metadata file must be generated and sent to all
the Identity Providers that the user (Principal) wants to register with. A Service Provider metadata
contains keys, services, and URLs that define its SAML endpoints.
To create and configure a Service Provider metadata file:
1. Extract the $DLC/servlets/rest/saml.jar file from the $DLC/servlets/rest/ directory,
and then copy the contents to the WEB-INF folder of your REST Web application.
2. Create a new service provider metadata file for your Web application.
Note: You must generate your Service Provider metadata as expected by your Identity Provider.
The following is a sample Service Provider metadata file:
<!-- This is a demo Service Provider metadata file -->
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
entityID="<Entity ID>">
<md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate><Certificate information></ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
<md:AssertionConsumerService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="<Location
ID>" index="0" isDefault="true"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>

Pacific Application Server for OpenEdge: Administration Guide

77

Chapter 5: Web application security configurations

The Service Provider metadata file contains the following definitions (highlighted in bold in the
previous codeblock):
metadata

Description

entityId

Specify the unique identity of the REST Web application (Service

Provider).

AuthnRequestsSigned

Specify if the REST Web application (Service Provider) signs

authentication requests.

WantAssertionsSigned Specify if the REST Web application requires signed assertions.

Certificate

Specify the certificate that must be used by the IdP to register the
Service Provider. This can either be a self-signed or a Certificate
Authority (CA) signed certificate.
Specify the bindings to be included in the metadata for the
WebSSO profile. Supported values are POST, Artifact, and PAOS.
The order of bindings in the property determines the order of
endpoints in the generated metadata.

Binding

If the IdP does not require keys signed by a specific certification

authority, then you can generate your own self-signed key using
the Java utility keytool.
Note: The binding location does not have to be SSL-enabed.

3. Save and close the Service Provider metadata file.

Note: This metadata file is used to register the service provider with the IdP.

Registering the metadata file with an Identity Provider

After generating the [REST Web application (Service provider)] metadata file, you must register it
with your identity provider (IdP). Each identity provider makes its metadata available for you to
import into your service provider application.
An IdP administrator must provide you an IdP metadata file for your service provider based on the
configurations that you specified in your service provider metadata file. Therefore, no changes are
required in the IdP metadata file that you receive from your IdP administrator.
For instance, if you use the Progress Identity Provider, then you must register your REST Web
application metadata file with the Progress Identity Provider and import the Progress identity
provider file into your REST Web application as part of SAML specification. The Identity Provider
metadata file is in the application WEB-INF folder.
To register your service provider metadata file with your Identity provider:
1. Send the Service Provider metadata file to your IdP administrator.

78

Pacific Application Server for OpenEdge: Administration Guide

SAML security configurations

Note: The Service Provider metadata file is required to create an IdP metadata file.
2. Acquire the Identity Provider metadata file from your IdP administrator.
3. Copy the IdP metadata file in the WEB-INF folder of your REST Web application (Service
Provider) in your Web server directory.

Updating the SAML configuration file

After registering the [REST Web application (Service provider)] metadata file with the Identity
provider, you must configure your SAML security configuration to specify key management, [Service
provider metadata], and Identity provider metadata details.
To configure your SAML security configuration model:
1. Open the SPA configuration file
($CATALINA_BASE/webapps/web_application/oeablSecurity-XXXX-saml.xml)
and find the following code block:
<b:bean id="keyManager"
class="org.springframework.security.saml.key.JKSKeyManager">
<b:constructor-arg value="WEB-INF/samlKeystore.keystore"/>
<b:constructor-arg type="java.lang.String" value="password"/>
<b:constructor-arg>
<b:map>
<b:entry key="<key-alias>" value="<password>"/>
</b:map>
</b:constructor-arg>
<b:constructor-arg type="java.lang.String" value="<key-alias>"/>
</b:bean>

2. Update the following bean properties (highlighted in bold in the previous code block) as follows:
Bean property

Description

WEB-INF/samlKeystore.keystore

Specify the keystore file that stores the keys

for user authentication. This can be a
self-signed or a Certificate Authority (CA)
generated keystore.

key-alias

Specify the key alias, that is, a unique keystore

name that you set during keystore generation.

password

Specify the keystore password required to

authenticate the REST Web application.

Pacific Application Server for OpenEdge: Administration Guide

79

Chapter 5: Web application security configurations

3. Search for the following code block to configure the metadata bean:

80

Pacific Application Server for OpenEdge: Administration Guide

SAML security configurations

<b:bean id="metadata"
class="org.springframework.security.saml.metadata.CachingMetadataManager">
<b:constructor-arg>
<b:list>
<!-- IDP Metadata file -->
<b:bean
class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
<b:constructor-arg>
<b:bean
class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
<b:constructor-arg>
<b:value type="java.io.File"><IdP metadata
file name></b:value>
</b:constructor-arg>
<b:property name="parserPool" ref="parserPool"/>
</b:bean>
</b:constructor-arg>
<b:constructor-arg>
<b:bean
class="org.springframework.security.saml.metadata.ExtendedMetadata">
<b:property name="local" value="false"/>
<b:property name="alias" value="default"/>
<b:property name="securityProfile" value="metaiop"/>
<b:property name="requireArtifactResolveSigned"
value="false"/>
<b:property name="requireLogoutRequestSigned"
value="false"/>
<b:property name="requireLogoutResponseSigned"
value="false"/>
<b:property name="idpDiscoveryEnabled" value="false"/>
<b:property name="ecpEnabled" value="true"/>
</b:bean>
</b:constructor-arg>
</b:bean>
<!-- SP Metadata file -->
<b:bean
class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
<b:constructor-arg>
<b:bean
class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
<b:constructor-arg>
<b:value type="java.io.File"><Service
provider metadata file name></b:value>
</b:constructor-arg>
<b:property name="parserPool" ref="parserPool"/>
</b:bean>
</b:constructor-arg>
<b:constructor-arg>
<b:bean
class="org.springframework.security.saml.metadata.ExtendedMetadata">
<b:property name="local" value="true"/>
<b:property name="alias" value="default"/>
<b:property name="securityProfile" value="metaiop"/>
<b:property name="requireArtifactResolveSigned"
value="false"/>
<b:property name="requireLogoutRequestSigned"
value="false"/>
<b:property name="requireLogoutResponseSigned"
value="false"/>
<b:property name="idpDiscoveryEnabled" value="false"/>

Pacific Application Server for OpenEdge: Administration Guide

81

Chapter 5: Web application security configurations

<b:property name="ecpEnabled" value="true"/>

</b:bean>
</b:constructor-arg>
</b:bean>
</b:list>
</b:constructor-arg>
</b:bean>

4. Update the following bean properties (highlighted in bold in the previous code block) as follows:
Bean property

Description

IDP metadata file name

Specify the location of the IdP metadata file.

Service provider metadata file

name

Specify the location of the REST Web

application (Service provider) metadata file.

5. Search for the following code block to configure the processing filter bean:
<!-- Processing filter for WebSSO profile messages -->
<b:bean id="samlProcessingFilter"
class="com.progress.rest.security.OESamlProcessingFilter">
<b:property name="samlEntryPointHandler"
ref="initializeSAMLEntryPoint"/>
<b:property name="authenticationManager"
ref="RestApplicationtAuth"/>
<b:property name="authenticationSuccessHandler"
ref="successRedirectHandler"/>
<b:property name="defaultFilterProcessesUrl" value="<Entity ID>"/>
<b:property name="defaultIdpProcessingUrl" value="<IdP URL>"/>
</b:bean>

6. Update the following bean properties (highlighted in bold in the previous code block) as follows:
Bean property

Description

defaultFilterProcessesUrl

Specify, as a value, the URL where the

processing filter for WebSSO must be applied.

defaultIdpProcessingUrl

Specify, as a value, your IdP's URL. For

instance, if you use the Progress IdP, you
specify the value as
https://secure-test.progress.com.

7. Start (or re-start) your PAS for OpenEdge instance, in which the Web application is deployed,
for the security configurations to take effect.

82

Pacific Application Server for OpenEdge: Administration Guide

Container security configurations

Container security configurations

If you chose the Container security (/WEB-INF/oeablSecurity-container.xml) as your
security configuration model, you have enabled the Web application's use of the Tomcat container's
authenticated user account and role definitions, which are defined in
$CATALINA_BASE/conf/tomcat-users.xml.
Also, note that you must edit user accounts information in two configuration files, web.xml and
oeablSecurity-container.xml, for authorization to Web resources.
To edit user accounts information in the web.xml file:
1. Search for the following comment: <!-- BEGIN:container.security-->
To edit user accounts information in the web.xml file, search for the BEGIN tag (<!-BEGIN:container.security-->) in the web.xml code and follow the instructions given by
the NOTE, right below the BEGIN tag, in the code.
Note: The Spring Security configurations extends the Web application's security and uses the
container's authenticated user accounts and assigned roles for authorization. So, if you chose the
Container security model, you must edit user accounts information in two configuration files,
web.xml and oeablSecurity-container.xml, for authorization to Web resources. To edit
user accounts information in the web.xml file, search for <!-BEGIN:container.security-->) in the web.xml code and follow the . To edit user accounts
information in the oeableSecurity-container.xml, see [XREF].

CORS support
Cross-origin resource sharing (CORS) is a W3C group standard that allows an HTTP client to
access a Web page from one domain, and to access resources located in another domain. Such
"cross-domain" requests are otherwise forbidden by a Web browser's default, same-origin security
policy. The CORS standard defines a way in which a client can ask a Web server if it can access
the cross-origin request.The Web server's configuration determines if the cross-domain request
will be granted.
The CORS standard was designed primarily to support JavaScript clients, however it may be
applicable to other clients as well.
The CORS standard is implemented through HTTP headers that allow resource access to permitted
domains. Most modern browsers support these headers and enforce the restrictions these headers
establish. Additionally, for HTTP request methods that might affect user data (in particular, methods
other than GET or POST with certain MIME types), the specification mandates that the browser
preflight the request. Preflighting is a check to determine if the HTTP request is safe to send to
the other domain. The server solicits supported methods from the the other domain with an HTTP
OPTIONS request header. Upon approval of the preflight request, the actual HTTP request is sent.
Servers can also notify clients whether user credentials (including cookies and HTTP authentication
data) can be sent with requests.

Pacific Application Server for OpenEdge: Administration Guide

83

Chapter 5: Web application security configurations

Note: Although CORS support is extended to virtually all modern browsers, check to ensure that
your browser supports the CORS standard.
Also note that you must manage security constraints (roles, for example) in the Web application's
web.xml file. Refer to the Web servlet standard documentation online for more information.
A CORS enabled server or Web application classifies all HTTP requests as:

A CORS request that contains the HTTP Origin header

A preflight request that contains the Access-Control-Request-Method header in an
OPTIONS request

A generic request that does not contain any CORS HTTP headers
OpenEdge uses a third-party Java open source package, CORS Filter, in which all of the primary
CORS functionality resides. OpenEdge has integrated CORS filter into the Java container Web
applications by implementing a Spring Security filter bean so that the CORS filter can be configured
from within the Spring Security configuration files, with all of the other Web application security.
Therefore, the CORS support is already incorporated into the Web application security policy, and
is enabled for all generic requests and CORS requests from any domain.
For more information on CORS standard and the advances in the standard, see the documentation
at http://www.w3.org/TR/cors/.
Note: CORS can be used as an alternative to the JSON with padding (JSONP) pattern. While
JSONP supports only the GET request method, CORS also supports other types of HTTP requests.
Using CORS enables a Web programmer to use the XMLHttpRequest API, which supports better
error handling than JSONP. Also, while JSONP can cause XSS issues where the external site is
compromised, CORS allows Web sites to manually parse responses to ensure security.

Adding CORS support

To add CORS support:
1. Open the security configuration (oeablSecurity-XXX.xml) that you applied to your Web
application.
2. Find the OECORSFilter bean code snippet.
For example:
<b:bean id="OECORSFilter"
class="com.progress.appserv.services.security.OECORSFilter"
>
<!-- Examples:
<b:property name="allowAll" value="false" />
<b:property name="allowDomains"
value="http://studio.progress.com,http://mobile.progress.com" />
<b:property name="allowDomains" value="*" />
<b:property name="allowSubdomains" value="false" />
<b:property name="allowMethods" value="" />
<b:property name="messageHeaders" value="" />
<b:property name="responseHeaders" value="" />
<b:property name="supportCredentials" value="true" />
<b:property name="maxAge" value="-1" />
-->
</b:bean>

84

Pacific Application Server for OpenEdge: Administration Guide

CORS support

3. Uncomment only the required properties in the OECORSFilter bean code snippet and update
the value, if necessary.
Typically you only uncomment the allowAll and allowDomains properties, which allows
default settings on other properties.
Usually, you set allowAll to false to ensure that all HTTP clients make CORS requests by
sending an Origin header.
The allowDomains property limits CORS access to only certain HTTP clients.
Additionally, uncomment and use messageHeaders and responseHeaders properties if the
HTTP clients require sending/receiving headers not contained in the defaults.
The following table is a list of all the OECORSFilter properties.
Table 18: OECORSFilter properties
Property name

allowAll

Description

Data types

Specifies that CORS

filter allow every client
request. If this
property is set to
Boolean
true, all the other
CORS properties
values are ignored by
the CORS filter.

Default

true

Range

true or false

{ "*" |
allowDomains

Specifies the domains

that can make server String
requests.

[,domain2...]"
}

allowSubdomains

Specifies if
subdomains of the
permitted domains be Boolean
allowed to make
server requests.

false

true or false

"domain1

GET,
4

allowMethods

Specifies valid HTTP

method names.

PUT,
String

POST,

Valid HTTP
methods in
upper case.

DELETE

To begin active CORS access control for all clients, turn allowAll property to false. If this property is set to true, the CORS filter
grants access to all generic clients, that is, all generic requests (without CORS headers) are allowed to access the resources when the server
is using non-standard HTTP or HTTPS ports.
Ensure that you supply a fully qualified domain name. You must not append the path (/) separator in the domain name, and you must add a port
(#) because the allowDomains default value is *, that is, all client requests are allowed to access the resources.
Ensure that you specify the list of domains in the allowDomains property for the filter to restrict all client requests from domains other
than the domains listed in the allowDomains property.

This list of method names is for all resources in the web application and needs to be coordinated with the resource authorization controls.

Pacific Application Server for OpenEdge: Administration Guide

85

Chapter 5: Web application security configurations

Property name

Description

Data types

Default

Range

messageHeaders

Specifies the message

header to be passed
as a header to the
server. If you are
passing multiple
String
messages, you must
specify a
comma-separated list
of messages.

Refer to the Any valid

footnote.
string

responseHeaders

Specifies the message

header to be received
by the client as a
header from the
server. If you are
String
passing multiple
messages, you must
specify a
comma-separated list
of messages.

Refer to the Any valid

footnote.
string

supportCredentials

Controls whether the

CORS filter allows the
client to send user
Boolean
credentials in the form
of a COOKIE.

true

true or false

maxAge

Specifies the
maximum time (in
seconds) for an
application resource to
be granted on request.
After the specified
time, the resource
Integer
grant is revoked and
the client must request
access again. To set
maximum time to
infinity, set maxAge to
-1.

-1

{ -1 | +n }

4. Save the security configuration file.

5

This is for advanced HTTP client and server use. Use this only when the web application's clients are coded to use these headers.
By default, the messageHeaders has the following methods: Accept,

Accept-Language, Content-Language,
Content-Type, X-CLIENT-CONTEXT-ID, Origin,Pragma, Cache-Control,
Access-Control-Request-Headers, Access-Control-Request-Method.
6

This is for advanced HTTP client and server use. Use this only when the web application's clients are coded to use these headers.
By default, the responseHeaders has the following methods: Cache-Control,
Content-Type, Expires, X-CLIENT-CONTEXT-ID.

Content-Language,

The default is true, which allows the client to use user logic sessions via COOKIEs. If you do not want the client to send COOKIE user
credentials, set the property value to false.
By setting the property to false, you supply totally stateless resources to anonymous users.

86

Pacific Application Server for OpenEdge: Administration Guide

CORS support

Note: You must restart the Web server for the above security configuration updates to take effect.

OECORSFilter properties
The OECORSFilter is a standard Spring security filter bean. It is declared in the Spring security
configuration files (oeablSecurity-XXX.xml) in which its properties can be customized to
override the defaults.
Progress Software recommends that you uncomment only the properties you need to set. The
following table describes all the property names:
Table 19: OECORSFilter properties
Property name

Description

Data types

Default

Range

allowAll

Specifies that CORS Boolean

filter allow every client
request. If this property
is set to true, all the
other CORS properties
values are ignored by
the CORS filter.

true

true or false

allowDomains

Specifies the domains String

that can make server
requests.

{ "*" |
"domain1

[,domain2...]"
}
allowSubdomains

Specifies if subdomains Boolean

of the permitted
domains be allowed to
make server requests.

false

true or false

allowMethods

Specifies valid HTTP

method names.

GET,

Valid HTTP
methods in
upper case.

String

PUT,
POST,
DELETE

To begin active CORS access control for all clients, turn allowAll property to false. If this property is set to true, the CORS filter
grants access to all generic clients, that is, all generic requests (without CORS headers) are allowed to access the resources when the server
is using non-standard HTTP or HTTPS ports.
Ensure that you supply a fully qualified domain name. You must not append the path (/) separator in the domain name, and you must add a port
(#) because the allowDomains default value is *, that is, all client requests are allowed to access the resources.
Ensure that you specify the list of domains in the allowDomains property for the filter to restrict all client requests from domains other
than the domains listed in the allowDomains property.

10

This list of method names is for all resources in the web application and needs to be coordinated with the resource authorization controls.

Pacific Application Server for OpenEdge: Administration Guide

87

Chapter 5: Web application security configurations

Property name

11

Description

Data types

Default

Range

messageHeaders

Specifies the message String

header to be passed as
a header to the server.
If you are passing
multiple messages, you
must specify a
comma-separated list
of messages.

Refer to the
footnote.

Any valid
string

responseHeaders

Specifies the message String

header to be received
by the client as a
header from the server.
If you are passing
multiple messages, you
must specify a
comma-separated list
of messages.

Refer to the
footnote.

Any valid
string

supportCredentials

Controls whether the Boolean

CORS filter allows the
client to send user
credentials in the form
of a COOKIE.

true

true or false

maxAge

Specifies the maximum Integer

time (in seconds) for an
application resource to
be granted on request.
After the specified time,
the resource grant is
revoked and the client
must request access
again. To set maximum
time to infinity, set
maxAge to -1.

-1

{ -1 | +n }

This is for advanced HTTP client and server use. Use this only when the web application's clients are coded to use these headers.
By default, the messageHeaders has the following methods: Accept,

Accept-Language, Content-Language,
Content-Type, X-CLIENT-CONTEXT-ID, Origin,Pragma, Cache-Control,
Access-Control-Request-Headers, Access-Control-Request-Method.
12

This is for advanced HTTP client and server use. Use this only when the web application's clients are coded to use these headers.
By default, the responseHeaders has the following methods: Cache-Control,
Content-Type, Expires, X-CLIENT-CONTEXT-ID.

13

Content-Language,

The default is true, which allows the client to use user logic sessions via COOKIEs. If you do not want the client to send COOKIE user
credentials, set the property value to false.
By setting the property to false, you supply totally stateless resources to anonymous users.

88

Pacific Application Server for OpenEdge: Administration Guide

Single sign-on (SSO) support in PAS for OpenEdge

Single sign-on (SSO) support in PAS for OpenEdge

Single sign-on (SSO) in OpenEdge refers to the creation of a sealed security token called the
ClientPrincipal that represents a user identity within a security domain. The ClientPrincipal is
created after Spring Security successfully completes authentication and authorization. The
ClientPrincipal retains the user's credentials and remains available within a Web application,
eliminating the need for a user to login again.
This chapter describes how to configure the ClientPrincipal and how to enable SSO in the Pacific
Application Server (PAS) for OpenEdge.
Note: In PAS for OpenEdge, SSO is available for client access via the APSV and REST transports
but not for the SOAP transport.

Configuring the ClientPrincipal

In PAS for OpenEdge, basic Spring Security token generation is extended to create an OpenEdge
ClientPrincipal object. Creation of the ClientPrincipal is enabled by default. You can disable
ClientPrincipal creation or modify the properties of the ClientPrincipal.
To configure the ClientPrincipal:
1. Identify and open the security configuration you applied to your Web application.
Your Web application's security configuration is based on the security model specified for the
Web application in $CATALINA_BASE/webapps/Web_application/WEB-INF/web.xml.
In web.xml, find the <context-param> tag. Uncomment one of the <param-value> from
the list of security configurations in the <param-value> code block.
2. In the configuration file for the relevant security model (oeablSecurity-XXX.xml), find the
OEClientPrincipalFilter bean code snippet.
For example, the following shows code snippet in oeablSecurity-basic-ldap.xml:
<!-- The security filter that turns a Spring token into an OpenEdge
ClientPrincipal object -->
<b:bean id="OEClientPrincipalFilter"
class="com.progress.rest.security.OEClientPrincipalFilter" >
<!-<b:property name="enablecp" value="false" />
<b:property name="domain" value="sample" />
<b:property name="roles" value="sample" />
<b:property name="authz" value="false" />
<b:property name="expires" value="600" />
<b:property name="accntinfo" value="true" />
<b:property name="properties" >
<b:map>
<b:entry key="prop-1" value="string1"/>
<b:entry key="prop-2" value="string2"/>
</b:map>
</b:property>
<b:property name="ccid" value="true" />
<b:property name="anonymous" value="true" />
<b:property name="appName" value="OE" />
-->
</b:bean>

Pacific Application Server for OpenEdge: Administration Guide

89

Chapter 5: Web application security configurations

All the properties are commented out buy their default values are in effect. The following table
describes the properties and their defaults:
Table 20: OEClientPrincipal properties
Property name

Default

Range

Specifies if SSO is
enabled or disabled.

Boolean

true

true or false

domain

Specifies Web
application's domain
name

String

<webappname>

ASCII

key

Specifies the access code

String
for the domain

ASCII

roles

Specifies
comma-separated list of
ROLE names. You use
this to perform
String
Role-Based-Authentication
(RBA) inside your
business application.

ASCII

authz

Specifies
comma-separated list of
ROLE names

String

ASCII

expires

Specifies the data

expiration time in
seconds.

String integer

0 to n

accntinfo

Specifies the Spring token

Boolean
account state properties

true or false

Specifies a map, a
collection of property
name entries.

String property
name and
value

properties

15

Datatypes

enablecp

14

14

Description

15

Map

If you are using an anonymous security configuration model (appServer-anonymous.xml) for your Web application, you must
ensure that the roles property value is left blank because if you do not mention any value for the roles property, the Web application
assumes the default value, ROLE_ANONYMOUS.
The properties property is provided for you to pass any Spring token's state or any static information to PAS for OE. For instance, you
can include Spring token's state, isAccntLocked and isAuthenticated, properties as entries in your properties property.
Note that, if you are using an anonymous security configuration model (appServer-anonymous.xml), Spring tokens do not get
authenticated for any user account; which means that no Spring security state related entries in your properties property is passed to
PAS for OpenEdge .

90

Pacific Application Server for OpenEdge: Administration Guide

Single sign-on (SSO) support in PAS for OpenEdge

Property name

Description

Datatypes

Default

Range

ccid

Specifies if CCID is
enabled or disabled.

Boolean

true

true or false

anonymous

Specifies if the application

server is being called from
Boolean
an anonymous Web
application user or not.

true

true or false

16

3. Uncomment any properties you want to change and update the value attribute.
Note that you can disable ClientPrincipal creation by uncommenting the following line:
<b:property name="enablecp" value="false">

4. Save the security configuration file.

Note: You must restart the Web server for security configuration updates to take effect.

Enabling SSO for Web applications

To enable SSO, you must enable OEPreauthfilter Java bean in the configuration file of a
Spring Security model that supports SSO and specify the domain where the ClientPrincipal
will be validated.
The configuration templates that contain the OEPreauthfilter Java bean are:

oeablSecurity-basic-ldap.xml
oeablSecurity-basic-local.xml
oeablSecurity-basic-oerealm.xml
oeablSecurity-form-ldap.xml
oeablSecurity-form-local.xml
oeablSecurity-form-oerealm.xml
To enable SSO:
1. Open a oeablSecurity-xxx.xml configuration file and find the section labeled The
Pre-auth security filter for SSO.

16

In the case of certain clients where COOKIEs are not allowed and REST JSON data services do not perform URL rewriting of session-ids, the
clients use CCID functionality (available to other application server clients) to obtain the user's login session-id. The CCID support inserts a
X-CLIENT-CONTEXT-ID http header in each response message.The client may obtain the value and insert it into the next request's
URL as a "JSESSIONID" query option.

Pacific Application Server for OpenEdge: Administration Guide

91

Chapter 5: Web application security configurations

For example:
<!-- The Pre-auth security filter for SSO -->
<b:bean id="OEPreauthfilter"
class="com.progress.appserv.services.security.OERequestHeaderAuthenticationFilter">
<!-- USER-EDIT: To turn on SSO :
1. Set "enabled" property to true
2. For single-domain supply the Domain Access Code as the value for "key"
property
3. For multi-domain supply the absolute path of a 'registryFile' generated
using
OpenEdge's $DLC/bin/gendomreg.bat utility as "registryFile" property
-->
<b:property name="enabled" value="false"/>
<b:property name="key" value=""/>
<!-- <b:property name="registryFile" value= "" /> -->
<b:property name="encoding" value="OECP"/>
<b:property name="headername" value="X-OE-CLIENT-CONTEXT-ID"/>
<b:property name="authenticationManager" ref="authenticationManager"
/>
</b:bean>

2. Change the enabled property value from false to true.

<b:property name="enabled" value="true"/>

3. Set the domain(s) where the ClientPrincipal will be validated:

For validating the token against a single domain, set the domain access code as the value
attribute of the key property. The domain access code can be clear text or in the
oech1::<hex-string> format.
Note: You can generate the <hex-string> using the genpassword utility. For more
information about the genpassword utility, see OpenEdge Getting Started: Installation and
Configuration.

For validating the token against multiple domains:

1. Create a domain registry file using the Generate Domain Registry gendomreg.bat
utility that is located in the $DLC\bin folder.
2. Uncomment the registryFile property in the OEPreauthfilter bean code.
3. Set the value attribute of the registryFile property as the output file name generated
by the gendomreg.bat utility.

Note: If you set values for both key and registryFile properties, the ClientPrincipal
token is validated against multiple domains that are specified by the registryFile property
value.To validate the token against a single domain, comment out the registryFile property
in the OEPreauthfilter bean code.

92

Pacific Application Server for OpenEdge: Administration Guide

6
TCMAN Reference
TCMAN is a command-line utility for managing and administering the Pacific Application Server.
TCMAN extends the basic Tomcat scripts for starting, stopping, and managing server instances.
This TCMAN Reference contains usage information for the tcman command as well as syntax
information on all of the TCMAN actions.
For details, see the following topics:

Using TCMAN

Manager actions

Server actions

General actions

Using TCMAN
You use the TCMAN utility by running the tcman command, with specifed actions and options,
from either the core PAS ($CATALINA_HOME/bin) or from an instance ($CATALINA_BASE/bin).
You can run tcman from a command line, or in a script. Both Windows (tcman.bat) and UNIX
(tcman.sh) versions of TCMAN are implemented in the Pacific Application Server.

See also
The tcman command on page 94
Extending TCMAN on page 96
Manager actions on page 99
Pacific Application Server for OpenEdge: Administration Guide

93

Chapter 6: TCMAN Reference

Server actions on page 110

General actions on page 126

The tcman command

Purpose
TCMAN is a command-line utility for managing and administering the Pacific Application Server.
On UNIX systems, you run the tcman.sh script followed by appropriate TCMAN actions and
options. On Windows systems, you run the tcman.bat batch file, which is identical syntactically
and functionally with tcman.sh.
Note: For the sake of brevity, all the syntax statements and examples in this reference show the
tcman.sh script.

Syntax

{$CATALINA_HOME|$CATALINA_BASE}/bin/tcman.sh
[action_options ]

action

[general_options]

Parameters
$CATALINA_HOME|$CATALINA_BASE
Specify whether to run TCMAN from the root directory of the installed Pacific Application
Server ($CATALINA_HOME) or from the root directory of an instance ( $CATALINA_BASE).
The context of where you run TCMAN (whether from the /bin directory of the parent, or
the /bin directory of an instance) affects which server the utility acts on.
Note: TCMAN automatically determines the value of CATALINA_BASE from the directory
where you start it. When you run it from the /bin directory of an instance, the value of
CATALINA_BASE is the root directory of the instance. If you run it from the /bin directory
of the installed Pacific Application Server, the value of CATALINA_BASE is the root directory
of the installed server (which is the same value as CATALINA_HOME).
action
Specify which TCMAN action to invoke.
general_options
Specify one or more of the TCMAN common options that can apply to most actions. Note
that one or more of the general options may be required by a specific action. For example,
the list action requires u in order to pass a user name and password.
The output of tcman.sh help action includes a list of general options that are applicable
to a particular action.
The following table is a list of the common options:

94

Pacific Application Server for OpenEdge: Administration Guide

Using TCMAN

Table 21: TCMAN general options

Common options

Function

-u user_name:password

Pass a valid user name and a password for

HTTP Basic access authentication.

-v

Display verbose output.

-M URL

Override the default manager that manages

Web applications by specifying the URL of
an alternative manager. URL is expressed
in the following format:
{http|https}://host:port/manager_application

-B

Override default
CATALINA_BASE

environment settings.
-n

Debug the TCMAN action but do not execute

changes.

-I instance_name

Run TCMAN from the /bin directory of the

specified instance.

action_options
Specify an option that applies to the selected action. These options are explained in the
topics that describe each action.

Pacific Application Server for OpenEdge: Administration Guide

95

Chapter 6: TCMAN Reference

Example
Run the help action from the core server (/psc/pashome) to display a list of available TCMAN
actions:
/psc/pashome/bin/tcman.sh help
usage: tcman action [options...]
manager actions:
list
list deployed applications
info
list server info
deploy
deploy application
undeploy
undeploy application
reload
reload application
status
show server status
leaks
show server memory leaks
enable
start web application running
disable
stop running web application
resources
list server global resources
sessions
list a web application's sessions
server actions:
create
create a new server instance
delete
delete server instance
config
dump CATALINA_BASE configuration
clean
clean/archive log files
instances
list tracked server instances
register
manually register an instance
unregister manually unregister an instance
start
start this server
stop
stop this server
version
show the server version information
test
test the server's configuration
general actions:
env
show tcman execution environment
help
show this information

See also
Manager actions on page 99
Server actions on page 110
Extending TCMAN on page 96
General actions on page 126

Extending TCMAN
You can extend TCMAN by adding your own actions to the built-in actions of the TCMAN utility.
You implement actions as UNIX shell scripts, Windows batch files, or Windows PowerShell scripts.
Customizing TCMAN with your own actions allows you to unify all of your administrative tasks
under a single utility.

File name format

Name your TCMAN action scripts using the following convention:

{.sh |

action_nameCmd

96

.bat

.ps1

Pacific Application Server for OpenEdge: Administration Guide

Using TCMAN

where file name extensions .sh, .bat, and .ps1 are used for UNIX scripts, Windows batch files,
and PowerShell scripts respectively.

UNIX action scripts

UNIX action scripts must be executable. That is, the file must have execution permissions for the
current user. Each script must exit with a zero (0) status when successful, or a positive non-zero
value to indicate an error.
When the action script is in the core server's bin directory ($CATALINA_HOME/bin), it is available
to administrators of any instance. When the action scipt is in an instance's bin directory
($CATALINA_BASE/bin), it is only available to administrators of that instance.
The search order is:
1. $CATALINA_BASE/bin
2. $CATALINA_HOME/bin

Windows batch and PowerShell action scripts

On Windows, action scripts can be either DOS batch scripts (.bat) or PowerShell scripts (.ps1).
Batch scripts should return zero (0) for success, or a positive non-zero integer to indicate an error
level. Powershell scripts should return \$true for success or \$false to indicate an error.
When the action script is in the core server's bin directory ($CATALINA_HOME/bin), it is available
to administrators of any instance. When the action scipt is in an instance's bin directory
($CATALINA_BASE/bin), it is only available to administrators of that instance.
If you have both batch and PowerShell scripts, TCMAN gives precedence to batch files. The search
order is:
1. $CATALINA_BASE/bin/action_nameCmd.bat
2. $CATALINA_BASE/bin/action_nameCmd.ps1
3. $CATALINA_HOME/bin/action_nameCmd.bat
4. $CATALINA_HOME/bin/action_nameCmd.ps1

Command-line Syntax
You invoke an action script by specifying the action-name segment of a script's file name in a
TCMAN command line.

tcman.sh action-name

[general_options] [

action-name_options

Note: You do not include the Cmd.extension portion of the file name on the TCMAN command
line.
TCMAN first looks for action scripts in the instance ($CATALINA_BASE/bin) and then in the core
server ($CATALINA_HOME/bin). When it finds the action script, TCMAN passes all command
line options and parameters during execution.

Pacific Application Server for OpenEdge: Administration Guide

97

Chapter 6: TCMAN Reference

Example
The following command line runs a script file named viewCmd.sh and passes the -v option and
the logs/catalina.out argument.
tcman.sh view -v

logs/catalina.out

Notes
When TCMAN does not recognize action-name as one of the built-in actions, it looks for an
action script . If the specified action is not a built-in action or external action script it will exit
with an error.

When the external action script exits, TCMAN uses its return status to either issue an error or
to exit with success. Therefore, extension action scripts should always return a specific value
according to the platform type.

Before executing an external action script, TCMAN exports these environment variables for
consumption by the action script file:

JAVA_HOME : the root directory of the JAVA JDK (optional)

JRE_HOME : the root directory of the JAVA JRE (optional)
CATALINA_HOME : the root directory of where PAS was installed
CATALINA_BASE : the root directory of the PAS instance being managed (can be the same
as CATALINA_HOME)

CATALINA_TMPDIR : the temporary file directory for temp files

CATALINA_PID : the file where the PAS process-id is stored
tcman_osshell : The name of the OS and command line shell TCMAN is running in
tcman_instancebase : the name of the new instance base directory when executing a create
action

tcman_httpport : the HTTP network port command line option (-p)

tcman_httpsport : the HTTPS network port command line option (-P)
tcman_cfghttpport : the current instance's configured HTTP network port
tcman_cfghttpsport : the current instance's configuredHTTPS network port
tcman_cfgshutport : the current instance's shutdown network port (can be -1 if there is no
network shutdown port)

tcman_alias : the instance's alias name

tcman_type : the type of instance (home, service (on Windows), instance)
tcman_secmodel : the security model to apply ( default, production, or development
)

tcman_umask : the UNIX umask to use when creating new directories and files
tcman_verbose : the state of the TCMAN -v command line option
tcman_debug : The state of the TCMAN -g command line option

98

Pacific Application Server for OpenEdge: Administration Guide

Manager actions

Manager actions
This section details the actions available for deploying, running, and monitoring web applications
on a server instance.

See also
The tcman command on page 94

List deployed applications (list)

Purpose
Display all the web applications that are deployed on an instance.
Note: This command may be used whether the instance is online or offline. However, the output
differs. When used offline, TCMAN simply shows a list of deployed application directories in the
instance's web applications directory. When used online, it provides additional run-time details
about the deployed web applications.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance if the
instance is online. You can deploy manager.war from $CATALINA_HOME/extras.

Syntax
tcman.sh list

[general_options] [-u

user_id:password

Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The
default is -u tomcat:tomcat.)
Note: This option is required if the server is online. It is not required if the server is offline.

Pacific Application Server for OpenEdge: Administration Guide

99

Chapter 6: TCMAN Reference

Example
Show the Web applications deployed to acme1 when the instance is online:
/psc/acme1/bin/tcman.sh list -u tomcat:tomcat
OK - Listed applications for virtual host localhost
/:running:0:ROOT
/manager:running:4:manager
/oemanager:running:0:oemanager
/oeadapters:running:0:oeabl

Show the Web applications deployed to acme1 when the instance is offline:
/psc/acme1/bin/tcman.sh list
OK - Listing directories for /psc/acme1/webapps
/manager:stopped:0:manager
/oeadapters:stopped:0:oeabl
/oemanager:stopped:0:oemanager
/:stopped:0:ROOT

See also
Display Web application HTTP sessions (sessions) on page 109
Deploy a Web application (deploy) on page 101
Undeploy a Web application (undeploy) on page 102
Start a Web application (enable) on page 106
Stop a Web application (disable) on page 107
The tcman command on page 94

Display OS and server information (info)

Purpose
Display server and OS information for a running instance.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and
the instance must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Use the test action to show configuration information about a server that is not running.

Syntax
tcman.sh info

[general_options]

-u user_name:password

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help info to see
which general options are appropriate.

100

Pacific Application Server for OpenEdge: Administration Guide

Manager actions

-u user_name:password
Pass a valid user name and a password for HTTP Basic access authentication. (The default
is -u tomcat:tomcat.)

Example
Display the OS and server information for the running instance named acme1:
$: /psc/pashome/tcman.sh info -I acme1 -u tomcat:tomcat
OK - Server info
Tomcat Version: Apache Tomcat/7.0.42
OS Name: Linux
OS Version: 2.6.18-164.el5
OS Architecture: amd64
JVM Version: 1.7.0_02-b13
JVM Vendor: Oracle Corporation

See also
Display server, OS, and runtime version information (version) on page 124
Display detailed server status (status) on page 104
Test a server configuration (test) on page 125
The tcman command on page 94
Display or modify the server features of an instance (feature) on page 115
The tcman command on page 94

Deploy a Web application (deploy)

Purpose
Deploy a Web application (.war file) to a Pacific Application Server instance whether the server
is running (online) or is not running (offline). TCMAN copies the web application to the servers
web application directory. If the server is online, you must stop and restart it in order to complete
the deployment.

Syntax
tcman.sh deploy
war_file_path

[general_options] [-u

] [-a

user_id:password

app _name

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help deploy to
see which general options are appropriate.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication.
Pacific Application Server for OpenEdge: Administration Guide

101

Chapter 6: TCMAN Reference

Note: This option is required if the server in online. It is not required if the server is offline.
-a app _name
Specify a name for the web application. If you do not use this option, the application name
will be the same as the .war file name.
war_file_path
Specify the location of the web application .war file that you want to deploy.

Example
Deploy and rename oeabl.war (a web application that implements OpenEdge adapters) to the
acme1 instance of the core pashome server:
/psc/acme1/bin/tcman.sh deploy -a oeadapters /psc/pashome/extras/oeabl.war
OK - deployed /psc/pashome/extras/oeabl.war to local directory
/psc/acme1/webapps

Note: The $CATALINA_HOME/extras directory (/psc/pashome/extras in the example above)

also contains number of instance management applications, including host-manager.war,
manager.war, and oemanager.war.

See also
List deployed applications (list) on page 99
Undeploy a Web application (undeploy) on page 102
Reload a Web application (reload) on page 103
Start a Web application (enable) on page 106
Stop a Web application (disable) on page 107
The tcman command on page 94

Undeploy a Web application (undeploy)

Purpose
Remove a Web application from running (online) or stopped (offline) instances. If the instances
autodeploy option is off, you must stop and restart a running server to complete removal. Note
that the autodeploy option is set in the .../conf/appserver.properties file and is off by
default.

Syntax
tcman.sh undeploy

102

[general_options] [-u

user_id:password

app _name

Pacific Application Server for OpenEdge: Administration Guide

Manager actions

Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action. Run tcman.sh
help undeploy to see which general options are appropriate.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The
default is -u tomcat:tomcat.) This option is required if you are accessing an online
instance.
app_name
Specify the name of the web application to remove.

Example
Remove the oemanager application from the acme1 instance:
/psc/acme1/bin/tcman.sh undeploy -u tomcat:tomcat oemanager
OK - Undeployed application at context path /oemanager

See also
Deploy a Web application (deploy) on page 101
List deployed applications (list) on page 99
Reload a Web application (reload) on page 103
The tcman command on page 94

Reload a Web application (reload)

Purpose
Restart a deployed, running Web application so that the application can pick up changes to its
classes or libraries.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and
the instance must be running. You can deploy manager.war from $CATALINA_HOME/extras.
Note: The reload action does not reload the web application's web.xml file. To begin using
changes to web.xml, you must stop and restart the web application.

Syntax
tcman.sh reload

[general_options]

Pacific Application Server for OpenEdge: Administration Guide

-u user_id:password app_name

103

Chapter 6: TCMAN Reference

Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action. Run tcman.sh
help reload to see which general options are appropriate.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The
default is -u tomcat:tomcat.)
Note: This option is required if the server in online. It is not required if the server is offline.
app_name
Specify the name of the web application to restart.

Example
Reload the oemanager web application running on the acme1 instance:
/psc/acme1/bin tcman.sh reload -u tomcat:tomcat oemanager
OK - Reloaded application at context path /oemanager

See also
Start a Web application (enable) on page 106
Stop a Web application (disable) on page 107
List deployed applications (list) on page 99
The tcman command on page 94

Display detailed server status (status)

Purpose
List information from the core servers memory, including web application statistics. Information
includes memory pool usage, connector thread status, and connector status. Output is in XML
format. (Note that redirecting the output to an XML viewer makes it more readable.)
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and
the instance must be running. You can deploy manager.war from $CATALINA_HOME/extras.

Syntax
tcman.sh status

104

[general_options]

-u user_name:password

[-f]

Pacific Application Server for OpenEdge: Administration Guide

Manager actions

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help status to
see which general options are appropriate.
-u user_name:password
Pass a valid user name and a password for HTTP Basic access authentication. (The default
is -u tomcat:tomcat.)
-f
Return full status information.

Example
Display core server's memory and web application statistics and use xmllint to format for
readability:
$: tcman.sh status -u tomcat:tomcat | xmllint --format <?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="/manager/xform.xsl" ?>
<status>
<jvm>
<memory free="453196832" total="520028160" max="1051394048"/>
<memorypool name="PS Eden Space" type="Heap memory" usageInit="50331648"
usageCommitted="48758784" usageMax="55967744" usageUsed="1525560"/>
<memorypool name="PS Old Gen" type="Heap memory" usageInit="469762048"
usageCommitted="469762048" usageMax="1006632960" usageUsed="63861584"/>
<memorypool name="PS Survivor Space" type="Heap memory" usageInit="8388608"
usageCommitted="1507328" usageMax="1507328" usageUsed="1444184"/>
<memorypool name="Code Cache" type="Non-heap memory" usageInit="2555904"
usageCommitted="3407872" usageMax="50331648" usageUsed="3303104"/>
<memorypool name="PS Perm Gen" type="Non-heap memory" usageInit="67108864"
usageCommitted="67108864" usageMax="134217728" usageUsed="47406400"/>
</jvm>
<connector name="&quot;http-bio-8601&quot;">
<threadInfo maxThreads="150" currentThreadCount="0"
currentThreadsBusy="0"/>
<requestInfo maxTime="0" processingTime="0" requestCount="0" errorCount="0"
bytesReceived="0" bytesSent="0"/>
<workers/>
</connector>
<connector name="&quot;http-bio-8501&quot;">
<threadInfo maxThreads="300" currentThreadCount="10"
currentThreadsBusy="1"/>
<requestInfo maxTime="2008" processingTime="2116" requestCount="10"
errorCount="0" bytesReceived="0" bytesSent="5838"/>
<workers>
<worker stage="S" requestProcessingTime="2" requestBytesSent="0"
requestBytesReceived="0" remoteAddr="127.0.0.1" virtualHost="localhost"
method="GET" currentUri="/manager/status" currentQueryString="XML=true"
protocol="HTTP/1.1"/>
</workers>
</connector>
</status>

See also
Display OS and server information (info) on page 100

Pacific Application Server for OpenEdge: Administration Guide

105

Chapter 6: TCMAN Reference

Display memory leaks (leaks) on page 106

The tcman command on page 94

Display memory leaks (leaks)

Purpose
List Web applications with potential memory leaks.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and
the instance must be running. You can deploy manager.war from $CATALINA_HOME/extras.

Syntax
tcman.sh leaks

[general_options]

-u user_name:password

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help leaks to see
which general options are appropriate.
-u user_name:password
Pass a valid user name and a password for HTTP Basic access authentication. (The default
is -u tomcat:tomcat.)

Example
Display memory leaks for web applications deployed on the acme1 server instance:
/psc/acme1/bin/tcman.sh leaks -u tomcat:tomcat
OK - Found potential memory leaks in the following applications:
/warehouse

See also
List deployed applications (list) on page 99
The tcman command on page 94

Start a Web application (enable)

Purpose
Start a web application that is deployed but not running.
To use this action, the Tomcat manager (manager.war ) must be deployed on the instance and
the instance must be running. You can deploy manager.war from $CATALINA_HOME/extras.

106

Pacific Application Server for OpenEdge: Administration Guide

Manager actions

Syntax
tcman.sh enable

[general_options]

-u user_id:password app_name

Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action. Run tcman.sh
help start to see which general options are appropriate.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The
default is -u tomcat:tomcat.)
app_name
Specify the name of the web application to start.
Note: To start the ROOT web application, you can specify / or ROOT.

Example
Start the oeabl application deployed on the acme1 instance:
tcman.sh enable -u tomcat:tomcat oeabl
OK - Started application at context path /oeabl

See also
Stop a Web application (disable) on page 107
The tcman command on page 94
The tcman command on page 94

Stop a Web application (disable)

Purpose
Stop a running Web application.
To use this action, the Tomcat manager (manager.war ) must be deployed on the instance and
the instance must be running. You can deploy manager.war from $CATALINA_HOME/extras.

Syntax
tcman.sh disable

[general_options] [-u

Pacific Application Server for OpenEdge: Administration Guide

user_id:password

app_name

107

Chapter 6: TCMAN Reference

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help disable to
see which general options are appropriate.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The
default is -u tomcat:tomcat.)
app_name
Specify the name of the web application to disable.
Note: To disable the ROOT web application, you can specify / or ROOT.

Example title
Disable the oeabl application running on the acme1 instance:
/psc/acme1/bin/tcman.sh disable -u tomcat:tomcat oeabl
OK - Stopped application at context path /oeabl

See also
Start a Web application (enable) on page 106
The tcman command on page 94

Display global server resources (resources)

Purpose
List the global resources used by the core server.
To use this action, the Tomcat manager (manager.war) must be deployed on the instance and
the instance must be running. You can deploy manager.war from $CATALINA_HOME/extras.

Syntax
tcman.sh resources

[general_options]

-u user_name:password

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help resources
to see which general options are appropriate.

108

Pacific Application Server for OpenEdge: Administration Guide

Manager actions

-u user_name:password
Pass a valid user name and a password for HTTP Basic access authentication.
(The default is -u tomcat:tomcat.)

Example
Display global resources for the running instance, acme1:
$: /psc/acme1/bin/tcman.sh resources -u tomcat:tomcat
OK - Listed global resources of all types
ServiceRegistry/ServiceRegistryFactory:com.progress.appserv.services.naming.ServiceRegistry
UserDatabase:org.apache.catalina.users.MemoryUserDatabase

Display Web application HTTP sessions (sessions)

Purpose
Display how many sessions are active for the specified Web application, categorized by their
duration.
To use this action, the Tomcat manager (manager.war ) must be deployed on the instance and
the instance must be running. You can deploy manager.war from $CATALINA_HOME/extras.

Syntax
tcman.sh sessions

[general_options]

-u user_id:password app_name

Parameters
general_options
Specify one or more of the options that can be used with any TCMAN action.
-u user_id:password
Specify a valid user name and password for HTTP Basic access authentication. (The
default is -u tomcat:tomcat.)
app_name
Specify the name of the web application to analyze for session information.

Pacific Application Server for OpenEdge: Administration Guide

109

Chapter 6: TCMAN Reference

Example
Show the active sessions for the manager application deployed on the acme1 instance:
/psc/acme1/bin/tcman.sh sessions -u tomcat:tomcat manager
OK - Session information for application at context path /manager
Default maximum session inactive interval 30 minutes
<1 minutes: 1 sessions
8 - <9 minutes: 2 sessions
9 - <10 minutes: 1 sessions

See also
List deployed applications (list) on page 99

Server actions
This section details the actions available for creating and monitoring server instances.

See also
The tcman command on page 94

Create an instance (create)

Purpose
Create a new instance of the core Pacific Application Server server by running this action from
/bin directory of the core server ( $CATALINA_HOME/bin/tcman.sh create).

Syntax

[general_options][-f][p port_num] [-P port_num]

[-s port_num] [-j port_num] [-W pathname] [-N instance_name]
[-U user_id ] [G group_id] base_path

tcman.sh create

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help create to
see which general options are appropriate.
f
Copy all deployed web application archives (.war files) from $CATALINA_HOME to the
new instance.

110

Pacific Application Server for OpenEdge: Administration Guide

Server actions

p port_num
Specify the TCP port that listens for HTTP messages. The default is 8080.
P port_num
Specify the TCP port that listens for HTTPS messages. The default is 8443.
s port_num
Specify the TCP port to use to stop an instance. On Windows systems, you must specify
a shutdown port. On UNIX, shutdown ports are optional.
j port_num
Specify the TCP port that listens for AJP13 messages (an Apache protocol for handling
requests from a web server to an application server). The default is 8009.
W pathname
Specify the directory where web applications will be deployed. The default is
$CATALINA_BASE/webapps.
N instance_name
Specify a name for the instance. The default is the name of the directory where the instance
is created.
All instances are automatically registered for tracking when they are created. If you intend
to track an instance, the instance name cannot contain spaces or any of the following
characters: "[ . # | ] $ ? + = { / , }"
U user_id
Specify the user-id of the owner of all the files and directories of the instance. The default
is the user-id of the current process. G must be specified if you use this option.
G group_id
Specify the group-id of the owner of all the files and directories of the instance. The default
is the group-id of the current process. U must be specified if you use this option.
base_path
Specify the pathname where you will create the instance.

Example
Create an instance of /psc/pashome in /psc/acme1:
$: /psc/pashome/bin/tcman.sh create -p 8501 -P 8601 -s 8701 /psc/acme1
Server instance acme1 created at /psc/acme1

See also
Delete an instance (delete) on page 112

Pacific Application Server for OpenEdge: Administration Guide

111

Chapter 6: TCMAN Reference

Display and manage an instance's configuration (config) on page 113

Register an instance for tracking (register) on page 119
Start an instance (start) on page 121
Stop an instance (stop) on page 123

Delete an instance (delete)

Purpose
Remove the directory tree and all of the files in an instance. Alias tracking is disabled for servers
that are removed.
To execute this action, the instance cannot be running.
Note: You cannot recover any files or directories removed by the delete action. Backup anything
you want to save before launching this action.
Also note that you cannot use delete to remove the installed, root server ( $CATALINA_HOME ).

Syntax
tcman.sh delete

[general_options] [-y][base_path|alias_name]

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help delete to
see which general options are appropriate.
-y
Delete everything without prompting for confirmation.
base_path
Specify the pathname of the instance that you intend to delete.
alias_name
Refer to the instance that you intend to delete by its alias rather than its pathname.

112

Pacific Application Server for OpenEdge: Administration Guide

Server actions

Example
Delete the instance of pashome that was created in /psc/acme3:
$: /psc/pashome/bin/tcman.sh delete /psc/acme3
The following directory tree will be removed permanently:
( WARNING all deployed web applications will be DELETED!! )
/PAS/wrkdir/acme3
/PAS/wrkdir/acme3/conf
/PAS/wrkdir/acme3/temp
/PAS/wrkdir/acme3/common
/PAS/wrkdir/acme3/common/lib
/PAS/wrkdir/acme3/logs
/PAS/wrkdir/acme3/webapps
/PAS/wrkdir/acme3/webapps/ROOT
/PAS/wrkdir/acme3/webapps/ROOT/static
/PAS/wrkdir/acme3/webapps/ROOT/static/error
/PAS/wrkdir/acme3/webapps/ROOT/static/auth
/PAS/wrkdir/acme3/webapps/ROOT/META-INF
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/adapters
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/adapters/rest/PingService
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/adapters/soap
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/classes
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/classes/com
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/classes/com/progress
/PAS/wrkdir/acme3/webapps/ROOT/WEB-INF/classes/com/progress/appserv
/PAS/wrkdir/acme3/work
/PAS/wrkdir/acme3/bin
Type 'yes' to continue
yes
Delete operation complete
server removed at /PAS/wrkdir/acme3

See also
Create an instance (create) on page 110
Display server instances (instances) on page 117
The tcman command on page 94

Display and manage an instance's configuration (config)

Purpose
View, add, update, or delete the property values specified in ../conf/appserver.properties.
When you run tcman.sh config with no parameters, it displays the core Tomcat servers
configuration, and all the properties in both .../conf/appserver.properties and
.../conf/jvm.properties. Note, however, that you can only view jvm.properties. You
cannot modify its contents with the config action.

Syntax

[general_options]
[prop_name|prop_name=value|+prop_name=value|~prop_name]
tcman.sh config

Pacific Application Server for OpenEdge: Administration Guide

113

Chapter 6: TCMAN Reference

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help config to
see which general options are appropriate.
prop_name
Display the specified property and its value.
prop_name=value
Set the value of a property that exists in .../conf/appserver.properties.
+prop_name=value
Add a new property to .../conf/appserver.properties and set its value.
~prop_name
Remove the specified property from .../conf/appserver.properties.

Examples
Show the configuration and properties of acme1, an instance of the core server, pashome:
$: /psc/acme1/bin/tcman.sh config
Using CATALINA_BASE:
/psc/acme1
Using CATALINA_HOME:
/psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME:
/tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH:
/psc/pashome/bin/bootstrap.jar:/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID:
/psc/acme1/temp/catalina.pid
Server version: Apache Tomcat/7.0.42
Server built:
Jul 2 2013 08:57:41
Server number: 7.0.42.0
OS Name:
Linux
OS Version:
2.6.18-164.el5
Architecture:
amd64
JVM Version:
1.7.0_02-b13
...

Display the value of a single property:

$: /psc/acme1/bin/tcman.sh config psc.as.http.port
psc.as.http.port=8501

Update the value of a property that exists in the appserver.properties file and then check
the value:
$: /psc/acme1/bin/tcman.sh config psc.as.http.port=6543
$: tcman.sh config psc.as.http.port
psc.as.http.port=6543

114

Pacific Application Server for OpenEdge: Administration Guide

Server actions

Add a new property/value pair to the appserver.properties file and then check the value:
$: /psc/acme1/bin/tcman.sh config +my.home.dir=/home/jarhead
$: tcman.sh config my.home.dir
my.home.dir=/home/jarhead

Remove a property/value pair from the appserver.properties file and check if deletion was
successful:
$: /psc/acme1/bin/tcman.sh config ~my.home.dir
$: tcman.sh config my.home.dir
Property does not exist - my.home.dir

Caution: There are no restrictions to property removal. You can render the server unable to start
if you remove a property required by conf/server.xml.

Notes
All property names are case sensitive.
You cannot enter multiple property names (prop_name) on the command line to view, update,
or add properties to the appserver.properties file.

You cannot use the config action to update existing values or add new values to the
jvm.properties file

Display or modify the server features of an instance

(feature)
Purpose
View, enable, or disable the server features contained in the /conf/server.xml file of an
instance.
When you run tcman.sh feature with no parameters, it displays a list of the features (and their
current status) that you can enable or disable. You can also display the status of a single server
feature. After viewing the status of a feature, you can use tcman.sh feature to change its
setting.

Syntax
tcman.sh feature

[general_options] [feature_name[={on|off}]]

Pacific Application Server for OpenEdge: Administration Guide

115

Chapter 6: TCMAN Reference

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help feature to
see which general options are appropriate.
feature_name
Specify one of the features defined in an instance's conf/server.xml file. Running
tcman.sh feature without feature_name displays a list of all the features.
on
Enables the named feature.
off
Disables the named feature.

Example
Display the list of server feature settings for acme1, enable AJP13 (Apache JServ Protocol. version
1.3), and verify that the feature is enabled:
$: /psc/acme1/bin/tcman.sh feature
SecurityListener=off
JMXLifecycle=off
PSCRegistry=on
HTTP=onHTTPS=on
AJP13=off
Cluster=off
UserDatabase=on
JAASRealm=off
LDAPRealm=off
PASInstrument=off
RemoteHostValve=on
RemoteAddrValve=onSingleSignOn=on
AccessLog=on
CrawlerSessionManager=on
StuckSessionValve=on
$: /psc/acme1/bin/tcman.sh feature AJP13=on
$: /psc/acme1/bin/tcman.sh feature AJP13
AJP13=on

Notes
Server features for instances are set in $CATALINA_BASE/conf/server.xml. You can
change feature status by manually editing this file. However, it is safer to use tcman.sh
feature to avoid corrupting the file with erroneous entries.

Run tcman.sh feature when the instance is offline.

See also
Display and manage an instance's configuration (config) on page 113
Stop an instance (stop) on page 123

116

Pacific Application Server for OpenEdge: Administration Guide

Server actions

The tcman command on page 94

Clean up or archive server log files (clean)

Purpose
Truncate, move, or delete the log files located in the /logs directory of the core server or instance.
If the server is running, clean truncates log files to zero length. If the server is not running, clean
deletes the log files from the file system.
You have the option to save log files to a subdirectory of /logs.

Syntax
tcman.sh clean

[general_options][-A]

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help clean to see
which general options are appropriate.
-A
Archive log files to a subdirectory of $CATALINA_BASE/logs.The directory is automatically
named with a month-day-year-second (MM-DD-YYYY-ss) time-stamp format. If the server
is not running, the files in $CATALINA_BASE/logs are deleted.

Example
Archive the log files of acme1, an instance of the core server pashome, and save to a file:
/psc/pashome/tcman.sh clean -I acme1 -A

See also
The tcman command on page 94

Display server instances (instances)

Purpose
Show the names and locations of the instances created from the Pacific Application Server installed
in $CATALINA_HOME by displaying the contents of the file where instances are registered for
tracking.

Pacific Application Server for OpenEdge: Administration Guide

117

Chapter 6: TCMAN Reference

By default, instances are registered for tracking

$CATALINA_HOME/conf/instances.{windows|.unix}. The file name extension indicates
the OS platform where the PAS server is installed.

Syntax
tcman.sh instances

[general_options]

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help instances
to see which general options are appropriate.

Output format
The following is the format of the output from a TCMAN instances action:
alias-name | full-file-path | type | state

alias-name
The user-defined name for the instance.
full-file-path
The location, in the OS file system, of the instance's root directory.
type
The designation of the server instance type (for example: instance, service, . . .).
state
An indication of the instance's validity. OK is returned for a valid server and invalid is
returned for a corrupted or non-existant server.

Example
Display the instances of the core server installed in /psc/pashome:
/psc/pashome/bin/tcman.sh instances
acme1 | /psc/wrk/acme1 | instance | ok
acme2 | /psc/wrk/acme2 | instance | ok

118

Pacific Application Server for OpenEdge: Administration Guide

Server actions

Notes
By default, instances are registered when you execute a
$CATALINA_HOME/bin/tcman{.sh|.bat} create action, which automatically adds
instance entries to an instances file. TCMAN removes instance entries from the file when
you execute a delete action.
You can manually add or remove instance entries from instances by using the register
or unregister actions.

By default, the name and location of the file where instances are registered is
$CATALINA_HOME/conf/instances.{windows|.unix}.
You can change the location of the instance registration file by adding and setting the
psc.as.instdir property in the appserver.properties file. Use the TCMAN config
action as in the following example:
tcman.sh config '+psc.as.instdir=PATH'

where PATH is a path name or an evironment variable.

You can also change the location and/or name of instance registration files by setting the
environment variables, PAS_AS_INSTANCE_DIR, and PAS_AS_INSTANCE_FILE.

See also
Register an instance for tracking (register) on page 119
Stop tracking an instance (unregister) on page 120
The tcman command on page 94

Register an instance for tracking (register)

Purpose
Register an instance for tracking purposes.
Note:
Instances are automatically registered for tracking when you execute a create action. You use
the register action to restart tracking on instances after tracking was stopped.
A typical use for unregistering and then re-registering an instance is to make configuration changes
when moving instances from one location (core server) to another. The register action enables
tracking and also updates the value of CATALINA_HOME in all of the executable scripts in the
instance's /bin directory to refer to the new core server.

Syntax
tcman.sh register alias_name instance_path

Pacific Application Server for OpenEdge: Administration Guide

119

Chapter 6: TCMAN Reference

Parameters
alias_name
Specify a meaningful name for the instance.The alias name must be unique in the instances
file.
instance_path
Specify the OS file system path to where the instance exists. This value will be expanded
into a fully qualified OS directory path and will be verified to exist.

Example
Track test1, which is an alias for the instance /psc/acme1:
/psc/pashome/bin/tcman.sh register test1 /psc/acme1

Notes
When you register an instance for tracking or create a new instance with the create command,
an entry is created in the core Pacific Application Servers
$CATALINA_HOME/conf/instances.[unix|windows] file.
The instances.[unix|windows] file is a simple text file, which can be manually edited (with
care) in the event that it becomes out of date. The format for entries is:
instance_name = base_path

An instances.unix file uses Unix OS file path syntax (forward slashes), and an
instances.windows file uses Windows OS file path syntax (backslashes) to specify base_path.
Also note that in an instances file:

Any line starting with a pound-sign ( # ) is a comment line.

Blank lines are skipped.
Instance names cannot contain spaces or any of the following characters: "[ . # | ] $ ?
+ = { / , }"

See also
Stop tracking an instance (unregister) on page 120
The tcman command on page 94

Stop tracking an instance (unregister)

Purpose
Stop tracking an instance by removing the instance's entry from the
$CATALINA_HOME/conf/instances.[unix|windows] file.

120

Pacific Application Server for OpenEdge: Administration Guide

Server actions

Note:
You use the register action to restart tracking on instances after tracking was stopped with
unregister .
A typical use for unregistering and then re-registering an instance, is to make configuration changes
when moving instances from one location, or core server, to another. The register action not
only enables tracking, it also updates the value of CATALINA_HOME in all of the executable scripts
in the instance's /bin directory to refer to the new core server.

Syntax
tcman.sh unregister alias_name

Parameters
alias_name
Specify the alias name of the instance that you want to stop tracking. The alias name must
exist in an instances.[unix|windows] file.

Example
Stop tracking test1, which is an instance of /psc/pashome:
/psc/pashome/bin/tcman.sh unregister test1

See also
Register an instance for tracking (register) on page 119
The tcman command on page 94

Start an instance (start)

Purpose
Start an instance of a Pacific Application Server, optionally in debug mode.

Syntax
tcman.sh start

[general_options] [-D|-J]

Pacific Application Server for OpenEdge: Administration Guide

121

Chapter 6: TCMAN Reference

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help start to see
which general options are appropriate.
-D
Start the server in Tomcat debug mode. D overrides the J option.
-J
Start the server in debug mode using the JDPA (Java Platform Debugger Architecture)
APIs for debugging. J cannot be used if the D option is specified.
Before you run a server with the J option, you must define a port for the JDPA debugger
by setting the JDPA_ADDRESS environment variable to a unique TCP network port number.

Example
Start the server in /psc/acme1, which is an instance of the core server in /psc/pashome:
/psc/acme1/bin/tcman.sh start
Using CATALINA_BASE:
/psc/acme1
Using CATALINA_HOME:
/psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME:
/tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH:
/psc/pashome/bin/bootstrap.jar:/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID:
/psc/acme1/temp/catalina.pid

Notes
When the TCMAN utility starts the server, it verifies the creation of the OS process and then
records the server's process-id in a .pid file. The location of the .pid file is:
OS

PID File Path

UNIX

$CATALINA_BASE/temp/catalina-instance_name.pid

Windows

$CATALINA_BASE\logs\catalina-instance_name.pid

You can obtain the process id of a server by running the TCMAN env action.
See also
Stop an instance (stop) on page 123
The tcman command on page 94

122

Pacific Application Server for OpenEdge: Administration Guide

Server actions

Stop an instance (stop)

Purpose
Stop a running instance, either gracefully or forcibly.
Note: TCMAN supports stopping a server instance that is not configured with a shutdown port.
On UNIX platforms stopping the running server instance is accomplished by sending a UNIX signal
to the PAS process. Therefore, the administrator's process must have the UNIX permissions to
signal the PAS process. On Windows platforms, the instance is identified using an OS process id
that is used to stop server processes.

Syntax
tcman.sh stop

[general_options] [-F[-w

]]

seconds

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help stop to see
which general options are appropriate.
-F
Kill the sever process if it does not stop after a default wait time (5 seconds on UNIX, 10
seconds on Windows). Change the default wait interval by using the w option.
-w seconds
Optionally specify the number of seconds to wait before killing a server process.

Example
Stop the server in /psc/acme1, which is an instance of the core server in /psc/pashome:
/psc/acme1/bin/tcman.sh stop
Using CATALINA_BASE:
/psc/acme1
Using CATALINA_HOME:
/psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME:
/tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH:
/psc/pashome/bin/bootstrap.jar:/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID:
/psc/acme1/temp/catalina.pid

Notes
TCMAN supports stopping a server instance that is not configured with a shutdown port.

Pacific Application Server for OpenEdge: Administration Guide

123

Chapter 6: TCMAN Reference

On UNIX platforms stopping the running server instance is accomplished by sending a UNIX
signal to the PAS process. Therefore, the administrator's process must have the UNIX
permissions to signal the PAS process. On Windows platforms, the instance is identified using
an OS process id that is used to stop server processes.
The following is an example a message you would see after a forced shut down with no shut
down port:
Sep 23, 2013 4:10:47 PM org.apache.catalina.startup.Catalina stopServer
SEVERE: No shutdown port configured. Shut down server through OS signal.
Server not shut down.
Killing Tomcat with the PID: 14230

Process ids are stored in the following locations:

OS

PID File Path

UNIX

$CATALINA_BASE/temp/catalina-instance_name.pid

Windows

$CATALINA_BASE\logs\catalina-instance_name.pid

You can also obtain the process id of a server by running the TCMAN env action.
See also
Start an instance (start) on page 121
The tcman command on page 94

Display server, OS, and runtime version information

(version)
Purpose
Show the Apache Tomcat runtime version and OS information for an instance.
To execute this action, the instance cannot be running

Syntax
tcman.sh version

[general_options]

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help version to
see which general options are appropriate.

124

Pacific Application Server for OpenEdge: Administration Guide

Server actions

Example
Display the server and runtime information for acme1, an instance of the core server installed in
/psc/pashome:
$: /psc/pashome/bin/tcman.sh version -I acme1
Using CATALINA_BASE:
/psc/acme1
Using CATALINA_HOME:
/psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME:
/tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH:
/psc/pashome/bin/bootstrap.jar:/users/doc/agarbacz/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID:
/psc/acme1/temp/catalina.pid
Server version: Apache Tomcat/7.0.42
Server built:
Jul 2 2013 08:57:41
Server number: 7.0.42.0
OS Name:
Linux
OS Version:
2.6.18-164.el5
Architecture:
amd64
JVM Version:
1.7.0_02-b13
JVM Vendor:
Oracle Corporation

See also
Display OS and server information (info) on page 100
The tcman command on page 94

Test a server configuration (test)

Purpose
Displays information on the configuration and environment of an instance. It also displays information
about error conditions.
The test action starts a server (instance), loads all the configuration files, and then displays
information. The instance is stopped, exiting gracefully even if there is an error condition.
To execute this action, the instance cannot be running

Syntax
tcman.sh test

[general_options]

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help test to see
which general options are appropriate.

Pacific Application Server for OpenEdge: Administration Guide

125

Chapter 6: TCMAN Reference

Example
Run a test of the configuration of acme1, which is an instance of the core server installed at
/psc/pashome:
$: /psc/pashome/bin/tcman.sh -I acme1 test
Using CATALINA_BASE:
/psc/acme1
Using CATALINA_HOME:
/psc/pashome
Using CATALINA_TMPDIR: /psc/acme1/temp
Using JRE_HOME:
/tools/linuxx86_64/java64/jdk1.7.0_02/
Using CLASSPATH:
/psc/pashome/bin/bootstrap.jar:/psc/pashome/bin/tomcat-juli.jar
Using CATALINA_PID:
/psc/acme1/temp/catalina.pid
. . .

Notes
The test action is particularly useful for testing to verify that a server will start and run properly
after you make changes to configuration and properties files.

See also
The tcman command on page 94

General actions
This section details the actions available for displaying help and server runtime environment
information.

See also
The tcman command on page 94

Display help (help)

Purpose
Display summary or detailed help for all TCMAN actions, property names, and server features.

Syntax
tcman.sh help

[action|property|feature]

Parameters
action
Show the syntax and options of the specified action. If no action is specified, show a list
of all actions and the general options.

126

Pacific Application Server for OpenEdge: Administration Guide

General actions

property
Show the settings for specified property.
feature
Show if the specified feature is enabled or disabled.

Example
Display the usage help for the create action:
$: tcman.sh help create
usage: tcman create [options] -p <http-port> [instance-opts] <new-base-path>
instance-opts:
[-s <shutdown-port>]
[-P <https-port>]
[-j <ajp13-port>]
[-W <web-apps-dir>]
[-N <inst-alias-name>]
[-U <file-owner> -G <file-group>]
general options:
-u uid:pwd pass uid and pwd for HTTP BASIC authentication
-v
print verbose output
-M url
override the CATALINA_BASE manager's URL with
<{http|https}://<host>:<port>/<mgr-app>
-B
override CATALINA_BASE environment setting
-n
debug run action but do not execute changes

Display runtime environment information (env)

Purpose
Show details about a servers state.

Syntax
tcman.sh env

[general_options] [keyword]

Parameters
general_options
Specify one or more of the general TCMAN options. Run tcman.sh help env to see
which general options are appropriate.
keyword
Specify one or more keywords that represent the name of the state that you want to view.
If no keyword is specified, then all of the state information is displayed.
Keywords include:

Pacific Application Server for OpenEdge: Administration Guide

127

Chapter 6: TCMAN Reference

Keyword

Description

running

Indicate if a server is running ( 1 ) or not

running ( 0 ).

mgrurl

Display the URL of the manager application.

type

Display the server type.

alias

Display the servers alias.

parent

Display the pathname of the parent of an

instance.

tracking

Indicate if tracking is on (1) or off ( 0).

http

Display the servers http port number.

https

Display the servers https port number.

shut

Display the servers shutdown port number.

A value of -1 indicates that there is no
shutdown port.

pid

Display the servers process id. A hyphen (

- ) indicates that the server is not running.

Example
Display all of the state information for the instance created in /psc/acme1:
/psc/acme1/bin/tscman.sh env
catalina home:
/psc/pashome
catalina base:
/psc/acme1
java home:
/tools/linuxx86_64/java64/jdk1.7.0_02/
jre home:
manager http port: 8501
manager https port:8601
manager shut port: 8701
manager URL:
http://localhost:8501/manager
config type:
instance
config alias:
acme1
config parent:
/psc/pashome
server running:
0
instance tracking: 1
instance file:
/psc/pashome/conf/instances.unix
server process-id: -

128

Pacific Application Server for OpenEdge: Administration Guide

7
REST API Reference for oemanager.war
The oemanager.war Java Web application provides a REST API for remote management and
monitoring of ABL applications deployed on a Pacific Application Server for OpenEdge instance.
It is similar to the administration API supported by the Tomcat Web servers JMX interface, but it
uses JSON input/output payloads.

Requirements
To enable REST API access, either oemanager.war or tcmanager.war must be deployed.

Examples
The examples in this section show the use of curl, which is a common open software utility used
in command lines or scripts to transfer data. You can, however, employ the PAS for OpenEdge
REST management APIs with many other tools and utilities. For more information about curl,
see: http://curl.haxx.se/docs/.
For details, see the following topics:

Session management

Agent management

Transport management

Application management

Pacific Application Server for OpenEdge: Administration Guide

129

Chapter 7: REST API Reference for oemanager.war

Session management
This section describes the REST services that are available for managing Pacific Application Server
for OpenEdge sessions.

See also
Get session information on page 130
Get client information on page 131
Get current request information on page 133
Get configuration properties on page 134
Update configuration properties on page 135
Get runtime metrics on page 136
Reset runtime metrics on page 137
Cancel a request on page 138
Terminate a session on page 139

Get session information

Description
Query an ABL application to get a list of all its sessions including information on client and agent
connections.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/sessions

Media type
application/vnd.progress+json

Response codes
200 Success
404 Resource Not Found
500 Unexpected Server Error

Command-line example
curl -X GET -v http://localhost:16680/oemanager/applications/oepas1/sessions

Request body example

NA

130

Pacific Application Server for OpenEdge: Administration Guide

Session management

Response body example

{
"operation":"GET CLIENT SESSIONS",
"result":
{
"OEABLSession":
[
{
"elapsedTimeMs":3343,
"bound":false,
"requestState":
"RUNNING","requestID":"",
"agentConnInfo":
{
"state":"RESERVED",
"localAddr":"\/127.0.0.1:60464",
"agentID":"AG-\/5vs3eApTMiPV5M+W47T3w",
"connID":"AC-nRJgbuKtSNWcy6YWQknTbg",
"connPoolID":"CP-30BInu3FRwOGQB0u0LwJ\/g",
"agentAddr":"localhost\/127.0.0.1:62004"},
"ablSessionID":"5",
"sessionState":"RESERVED",
"agentID":"AG-\/5vs3eApTMiPV5M+W47T3w",
"clientConnInfo":
{
"elapsedTimeMs":5214,
"requestProcedure":"ngasPing.p",
"requestUrl":"http:\/\/localhost:16680\/apsv",
"clientName":"172.21.75.148",
"httpSessionId":"732277EE12485DDEC3A937DD30D7EF3267B3FE669C76.pas1",
"executerThreadId":"catalina-exec-8",
"reqStartTimeStr":"2014-09-17T08:41:48.138-0400",
"requestID":"ngasPing.p",
"adapterType":"HTTP",
"sessionID":"Iphz68lUQKexuHibyy6S+A"
},
"adapterType":"HTTP",
"sessionPoolID":"SP-RFplWI9\/Rta9j1pp+WcRyQ",
"sessionID":"Iphz68lUQKexuHibyy6S+A",
"sessionType":"SESSION_MANAGED",
"lastAccessStr":"2014-09-17T08:41:50.006-0400"
}
]
},
"outcome":"SUCCESS",
"errmsg":"",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

Get client information

Description
Query an ABL application to get a information on client connections.

HTTP Operation
GET

Pacific Application Server for OpenEdge: Administration Guide

131

Chapter 7: REST API Reference for oemanager.war

URI

[?timeoutms=n]

//host_name:port/oemanager/applications/ABL_app_name/clients

timeoutms
The period of time, specified in milliseconds (ranging from 1 to n), to report on client
connections, including hung clients.

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line examples
curl -X GET -v http://localhost:16680/oemanager/applications/oepas1/clients
curl -X GET -v
http://localhost:16680/oemanager/applications/oepas1/clients?timeoutms=100000

Request body example

NA

Response body example

{
"operation":"GET CLIENT CONNECTIONS",
"result":
{
"ClientConnection":
[
{
"elapsedTimeMs":427133,
"requestProcedure":"ngasPing.p",
"requestUrl":
"http:\/\/localhost.com:16680\/apsv",
"clientName":"172.21.75.148",
"httpSessionId":"732277EE12485DDEC3A937DD30D7EF3267B3FE669C76.pas1",
"executerThreadId":"catalina-exec-8",
"reqStartTimeStr":"2014-09-17T08:41:48.138-0400",
"requestID":"ngasPing.p",
"adapterType":"HTTP",
"sessionID":"Iphz68lUQKexuHibyy6S+A"
}
]
},
"outcome":"SUCCESS",
"errmsg":"",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

132

Pacific Application Server for OpenEdge: Administration Guide

Session management

Get current request information

Description
Query an ABL application to get a list of all the requests currently in process.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/requests

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v http://localhost:16680/oemanager/applications/oepas1/requests

Request body example

NA

Response body example

{
"operation":"GET ACTIVE REQUESTS ON SERVER",
"result":
{
"Request":
[
{
"requestElapsedTime":1889,
"requestStartTimeStamp":"2014-09-17T10:11:26.934-0400",
"requestState":"RUNNING",
"requestID":"xfJqPACGU4jqE4pd0Auzwg",
"sessionID":"8DvBtOplRHijAj7NcSAQKw"
}
]
},
"outcome":"SUCCESS",
"errmsg":"",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

Pacific Application Server for OpenEdge: Administration Guide

133

Chapter 7: REST API Reference for oemanager.war

Get configuration properties

Description
Query the conf/openedge.properties file to get the configuration properties of an application.
The information is specified in the AppServer.SessMgr.App_name section of
openedge.properties.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/App_name/properties

Media type
application/vnd.progress+json

Response codes
200 Success
404 Resource Not Found
500 Unexpected Server Error

Command-line example
curl -X GET -v http://localhost:16680/oemanager/applications/oepas1/properties

Request body example

NA

Response body example

{
"operation":"GET SESSION-MGR PROPERTIES",
"result":
{
"agentLogThreshold":"0",
"requestWaitTimeout":"15000",
"agentLogEntryTypes":"ASPlumbing,DB.Connects",
"idleAgentTimeout":"300000",
"idleConnectionTimeout":"300000",
"socketTimeout":"3000",
"agentListenerTimeout":"300000",
"applications":"oepas1",
"numInitialAgents":"1",
"agentLogFile":"\/wrk\/pas1\/logs\/oepas1.agent.log",
"collectMetrics":"1",
"agentExecFile":"\/localhost\/dlc\/bin\/_mproapsv",
"idleResourceTimeout":"0",
"allowRuntimeUpdates":"0",
"connectionWaitTimeout":"3000",
"maxAgents":"10",
"publishDir":"\/wrk",
"maxConnectionsPerAgent":"16",

134

Pacific Application Server for OpenEdge: Administration Guide

Session management

"idleSessionTimeout":"300000",
"agentStartupParam":"-T \/wrk\/pas1\/temp",
"statusEnabled":"1",
"maxABLSessionsPerAgent":"200",
"agentNumLogFiles":"3",
"agentLoggingLevel":"3",
"ipver":"IPv4"
},
"outcome":"SUCCESS",
"errmsg":"",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

Update configuration properties

Description
Update an application's configuration properties in the AppServer.SessMgr.App_name section
of the conf/openedge.properties file.

HTTP Operation
PUT

URI
//host_name:port/oemanager/applications/App_name/properties

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X PUT -v http://localhost:16680/oemanager/applications/oepas1/properties
-d '{"agentLogThreshold":"1"}' -H "Content-Type: application/vnd.progress+json"

Request body example

{
"operation":"SET BROKER PROPERTIES",
"result":
{
"agentLogThreshold":"1",
"requestWaitTimeout":"15000",
"agentLogEntryTypes":"ASPlumbing,DB.Connects",
"idleAgentTimeout":"300000",
"idleConnectionTimeout":"300000",
"socketTimeout":"3000",
"agentListenerTimeout":"300000",
"applications":"oepas1",

Pacific Application Server for OpenEdge: Administration Guide

135

Chapter 7: REST API Reference for oemanager.war

"numInitialAgents":"1",
"agentLogFile":"\/scratch\/prmundra\/17Sept\/wrk\/pas1\/logs\/oepas1.agent.log",
"collectMetrics":"1",
"agentExecFile":"\/view\/rdl115_linuxx86_64\/vobs_prgs\/linuxx86_64\/dlc\/bin\/_mproapsv",
"idleResourceTimeout":"0",
"allowRuntimeUpdates":"0",
"connectionWaitTimeout":"3000",
"maxAgents":"10",
"publishDir":"\/scratch\/prmundra\/17Sept\/wrk",
"maxConnectionsPerAgent":"16",
"idleSessionTimeout":"300000",
"agentStartupParam":"-T \/scratch\/prmundra\/17Sept\/wrk\/pas1\/temp",
"statusEnabled":"1",
"maxABLSessionsPerAgent":"200",
"agentNumLogFiles":"3",
"agentLoggingLevel":"3",
"ipver":"IPv4"
},
"outcome":"SUCCESS",
"errmsg":"",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

Response body examples

On success:
{
"operation":"SET SESSION-MGR PROPERTIES",
"result":"NA",
"outcome":"SUCCESS",
"errmsg":"NA",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

On failure:
{
"Operation":"SET SESSION-MGR PROPERTIES",
"Outcome":"FAILURE",
"ErrorMsg":"Invalid property name: "InvalidPropName". (PRPMsg009)"
}

Get runtime metrics

Description
Query the session manager for runtime metrics of an ABL application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/metrics

136

Pacific Application Server for OpenEdge: Administration Guide

Session management

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v http://localhost:16680/oemanager/applications/oepas1/metrics

Request body example

NA

Response body example

{
"operation":"GET SESSION-MGR METRICS",
"result":
{
"writeErrors":0,
"concurrentConnectedClients":0,
"maxQueueDepth":0,
"maxConcurrentClients":0,
"readErrors":0,
"reserveConnectionTimeouts":0,
"timesQueued":0,
"Writes":0,
"Requests":0,
"Reads":0,
"avgQueueDepth":0,
"type":"OE_BROKER",
"accessTime":"2014-09-17T10:26:12.693-04:00"
},
"outcome":"SUCCESS",
"errmsg":"",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

Reset runtime metrics

Description
Reset runtime metrics of the session manager.

HTTP Operation
DELETE

URI
//host_name:port/oemanager/applications/ABL_app_name/metrics

Pacific Application Server for OpenEdge: Administration Guide

137

Chapter 7: REST API Reference for oemanager.war

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X DELETE -v http://localhost:16680/oemanager/applications/oepas1/metrics

Request body example

NA

Response body example

{
"operation":"RESET SESSION-MGR METRICS",
"result":"","outcome":
"SUCCESS","errmsg":"",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

Cancel a request
Description
Cancel the request identified by a Request ID and a Session ID. You can obtain Request IDs and
Session IDs by executing the oemanager/applications/ABL_app_name/sessionsservice.

HTTP Operation
DELETE

URI
//host_name:port/oemanager/applications/App_name/requests?requestID=value&sessionID=value

Media type
NA

Response codes
200 Success
500 Unexpected Server Error

138

Pacific Application Server for OpenEdge: Administration Guide

Session management

Command-line example
curl -X DELETE -v "http://localhost:16680/oemanager/applications/pas1
/requests?requestID=z9WHoRgGY4fnExrFWKWVlw&sessionID=G1TTNRPT3KiSOhkbyeSow"

Request body example

NA

Response body example

{
"operation":"CANCEL ACTIVE REQUEST ON SERVER",
"result":"",
"outcome":"FAILURE",
"errmsg":"Session",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

Terminate a session
Description
Terminate the session identified by the specified sessionID.

HTTP Operation
DELETE

URI
//host_name:port/oemanager/applications/App_name

{0|1}

/sessions?sessionID=value&terminateOpt=

where a terminateOpt value of 0 causes a graceful termination and a value of 1 causes a forced
termination.

Media type
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X DELETE -v
"http://localhost:16680/oemanager/applications/pas1/sessions?sessionID=123&terminateOpt=1"

Request body example

NA

Pacific Application Server for OpenEdge: Administration Guide

139

Chapter 7: REST API Reference for oemanager.war

Response body example

{
"operation":"TERMINATE SESSIONS",
"result":"","outcome":
"FAILURE","errmsg":
"Session","versionStr":
"PASOE 11.5.0","versionNo":1
}

Agent management
This section describes the REST services that are available for managing Pacific Application Server
for OpenEdge agents.

See also
List agents on page 140
Get agent status information on page 141
Get session metrics on page 142
Get connection information on page 143
Get request information on page 145
Get configuration properties on page 149
Update configuration properties on page 150
Stop an agent on page 151

List agents
Description
Get a list of all the PAS Agents available to an ABL application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/agents

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

140

Pacific Application Server for OpenEdge: Administration Guide

Agent management

Command-line example
curl -X GET -v http://localhost:16680/oemanager/applications/pas1/agents

Request body example

NA

Response body example

{
"result": {
"agents": [
{
"agentId": "AG-sCIVXeFSQYmcb7RcHo10Zw",
"pid": "12924",
"state": "AVAILABLE"
}
]
},
"operation": "GET AGENTS",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Get agent status information

Description
Get a summary of sessions, connections and requests for an agent of an ABL application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/agents/agentID/status

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/agents/AG-sCIVXeFSQYmcb7RcHo10Zw/status

Pacific Application Server for OpenEdge: Administration Guide

141

Chapter 7: REST API Reference for oemanager.war

Request body example

NA

Response body example

{
"result": {
"threads": 6,
"sessions": 5,
"connections": 5,
"requests": 16
},
"operation": "GET AGENT STATUS",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Get session metrics

Description
Get session metrics for an agent of an ABL application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/agents/agentID/sessions

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/agents/AG-sCIVXeFSQYmcb7RcHo10Zw/sessions

Request body example

NA

Response body example

{
"result": {
"AgentSession": [

142

Pacific Application Server for OpenEdge: Administration Guide

Agent management

{
"SessionId": 1,
"SessionState": "LISTENER",
"StartTime": "2014-09-22T11:07:49.744",
"EndTime": null,
"ThreadId": 2,
"ConnectiondId": null,
"SessionExternalState": 0
},
{
"SessionId": 2,
"SessionState": "RESOURCE-MANAGER",
"StartTime": "2014-09-22T11:07:49.744",
"EndTime": null,
"ThreadId": -1,
"ConnectiondId": null,
"SessionExternalState": 0
},
{
"SessionId": 3,
"SessionState": "ADMINISTRATOR",
"StartTime": "2014-09-22T11:07:49.744",
"EndTime": null,
"ThreadId": 4,
"ConnectiondId": null,
"SessionExternalState": 0
},
{
"SessionId": 4,
"SessionState": "AUXILIARY",
"StartTime": "2014-09-22T11:07:49.744",
"EndTime": null,
"ThreadId": -1,
"ConnectiondId": null,
"SessionExternalState": 0
},
{
"SessionId": 5,
"SessionState": "WORKER",
"StartTime": "2014-09-22T11:07:49.744",
"EndTime": null,
"ThreadId": -1,
"ConnectiondId": null,
"SessionExternalState": 0
}
]
},
"operation": "GET SESSIONS METRICS",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Get connection information

Description
Get information on the connections of an agent of an ABL application.

HTTP Operation
GET

Pacific Application Server for OpenEdge: Administration Guide

143

Chapter 7: REST API Reference for oemanager.war

URI
//host_name:port/oemanager/applications/ABL_app_name/agents/agentID/connections

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/agents/AG-sCIVXeFSQYmcb7RcHo10Zw/connections

Request body example

NA

Response body example

{
"result": {
"AgentConnection": [
{
"ConnectionId": 7,
"ConnectionState": "LISTENER",
"SessionId": -1
},
{
"ConnectionId": 10,
"ConnectionState": "LISTENER",
"SessionId": -1
},
{
"ConnectionId": 11,
"ConnectionState": "ADMINISTRATOR",
"SessionId": -1
},
{
"ConnectionId": 19,
"ConnectionState": "ADMINISTRATOR",
"SessionId": -1
},
{
"ConnectionId": 22,
"ConnectionState": "REQUEST",
"SessionId": -1
}
]
},
"operation": "GET CONNECTIONS METRICS",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

144

Pacific Application Server for OpenEdge: Administration Guide

Agent management

Get request information

Description
Get request information for an agent of an ABL application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/agents/agentID/requests

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/agents/AG-sCIVXeFSQYmcb7RcHo10Zw/requests

Request body example

NA

Response body example

{
"result": {
"AgentRequest": [
{
"RequestProcName": "OpenEdge.Server.Admin.AgentInfo:getAgentThreadData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:07:49.744",
"EndTime": "2014-09-22T11:07:49.745",
"RequestNum": 0
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentSessionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:07:49.756",
"EndTime": "2014-09-22T11:07:49.757",
"RequestNum": 1
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentConnectionData",

Pacific Application Server for OpenEdge: Administration Guide

145

Chapter 7: REST API Reference for oemanager.war

"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:07:49.759",
"EndTime": "2014-09-22T11:07:49.760",
"RequestNum": 2
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentRequestData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:07:49.762",
"EndTime": "2014-09-22T11:07:49.763",
"RequestNum": 3
},
{
"RequestProcName": "OpenEdge.Server.Admin.AgentInfo:getAgentThreadData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:07:55.812",
"EndTime": "2014-09-22T11:07:55.813",
"RequestNum": 4
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentSessionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:07:55.814",
"EndTime": "2014-09-22T11:07:55.815",
"RequestNum": 5
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentConnectionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:07:55.817",
"EndTime": "2014-09-22T11:07:55.817",
"RequestNum": 6
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentRequestData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:07:55.819",
"EndTime": "2014-09-22T11:07:55.819",
"RequestNum": 7
},
{
"RequestProcName": "OpenEdge.Server.Admin.AgentInfo:getAgentThreadData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:09:22.652",
"EndTime": "2014-09-22T11:09:22.653",
"RequestNum": 8
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentSessionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:09:22.654",
"EndTime": "2014-09-22T11:09:22.655",
"RequestNum": 9
},

146

Pacific Application Server for OpenEdge: Administration Guide

Agent management

{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentConnectionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:09:22.657",
"EndTime": "2014-09-22T11:09:22.657",
"RequestNum": 10
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentRequestData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:09:22.659",
"EndTime": "2014-09-22T11:09:22.660",
"RequestNum": 11
},
{
"RequestProcName": "OpenEdge.Server.Admin.AgentInfo:getAgentThreadData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:09:23.001",
"EndTime": "2014-09-22T11:09:23.002",
"RequestNum": 12
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentSessionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:09:23.004",
"EndTime": "2014-09-22T11:09:23.005",
"RequestNum": 13
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentConnectionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:09:23.007",
"EndTime": "2014-09-22T11:09:23.007",
"RequestNum": 14
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentRequestData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:09:23.024",
"EndTime": "2014-09-22T11:09:23.025",
"RequestNum": 15
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentSessionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:10:23.689",
"EndTime": "2014-09-22T11:10:23.690",
"RequestNum": 16
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentSessionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:10:34.078",

Pacific Application Server for OpenEdge: Administration Guide

147

Chapter 7: REST API Reference for oemanager.war

"EndTime": "2014-09-22T11:10:34.079",
"RequestNum": 17
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentSessionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:10:34.389",
"EndTime": "2014-09-22T11:10:34.390",
"RequestNum": 18
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentConnectionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:12:03.324",
"EndTime": "2014-09-22T11:12:03.324",
"RequestNum": 19
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentConnectionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:12:44.784",
"EndTime": "2014-09-22T11:12:44.785",
"RequestNum": 20
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentConnectionData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:12:45.131",
"EndTime": "2014-09-22T11:12:45.132",
"RequestNum": 21
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentRequestData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:13:13.439",
"EndTime": "2014-09-22T11:13:13.440",
"RequestNum": 22
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentRequestData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:14:49.335",
"EndTime": "2014-09-22T11:14:49.336",
"RequestNum": 23
},
{
"RequestProcName":
"OpenEdge.Server.Admin.AgentInfo:getAgentRequestData",
"SessionId": 3,
"ConnectionId": 19,
"StartTime": "2014-09-22T11:14:49.690",
"EndTime": null,
"RequestNum": 24
}
]
},
"operation": "GET REQUESTS METRICS",

148

Pacific Application Server for OpenEdge: Administration Guide

Agent management

"versionStr": "PASOE 11.5.0",

"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Get configuration properties

Description
Get configuration information (properties) of agents for an ABL application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/App_name/agents/properties

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/agents/properties

Request body example

NA

Response body example

{
"result": {
"workDir": "/wrk/pas1/work",
"keyAliasPasswd": "",
"sslAlgorithms": "",
"agentMinPort": "62002",
"infoVersion": "9010",
"sessionDisconnProc": "",
"sslEnable": "0",
"applications": "pas1",
"PROPATH": "/wrk/pas1/openedge,/dlc/tty",
"collectStatsData": "0",
"agentStartupProcParam": "",
"agentShutdownProc": "",
"sessionShutdownProc": "",
"collectMetrics": "1",
"sessionStartupProcParam": "",

Pacific Application Server for OpenEdge: Administration Guide

149

Chapter 7: REST API Reference for oemanager.war

"noSessionCache": "0",
"flushStatsData": "0",
"sessionDeactivateProc": "",
"keyStorePath": ".\\keys\\",
"sessionActivateProc": "",
"allowRuntimeUpdates": "0",
"sessionConnectProc": "",
"sessionTimeout": "180",
"sessionStartupProc": "",
"statusEnabled": "1",
"agentMaxPort": "62202",
"keyAlias": "",
"uuid": "http://localhost:9999/oepas1",
"agentStartupProc": ""
},
"operation": "GET AGENT PROPERTIES",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Update configuration properties

Description
Update the configuration properties in conf/openedge.properties for agents for an ABL
application.

HTTP Operation
PUT

URI
//host_name:port/oemanager/applications/App_name/agents/properties

{"prop_name"=value[,

[,

"prop_name"=value

[,...]]}

"prop_name"=value

[,...]]

prop_name"=value

Set one or more properties expressed as name/value pairs in a comma-separated list. See
the /conf/openedge.properties.README file for a description of properties and their
possible values.

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

150

Pacific Application Server for OpenEdge: Administration Guide

Agent management

Command-line example
curl -X PUT -v
http://localhost:16680/oemanager/applications/pas1/agents/properties
-d '{"collectMetrics":0}' -H "Content-Type: application/vnd.progress+json"

Request body example

{"collectMetrics":0}

Response body example

NA

Stop an agent
Description
Stop an agent belonging to a ABL application. Note that you identify the agent by the agentID,
which can be obtained by executing /oemanager/applications/ABL_app_name/agents.

HTTP Operation
DELETE

URI
//host_name:port/oemanager/applications/App_name/agents/agentID

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X DELETE -v
http://localhost:16680/oemanager/applications/oepas1/agents/AG-sCIVXeFSQYmcb7RcHo10Zw
-H "Content-Type: application/vnd.progress+json"

Request body example

NA

Response body example

{
"result": {
"agentID": "AG-sCIVXeFSQYmcb7RcHo10Zw"
},
"operation": "STOP AGENT ",

Pacific Application Server for OpenEdge: Administration Guide

151

Chapter 7: REST API Reference for oemanager.war

"versionStr": "PASOE 11.5.0",

"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Transport management
This section describes the REST services that are available for managing Pacific Application Server
for OpenEdge SOAP, REST, and APSV transports.

See also
Get transport configuration properties (SOAP/REST) on page 152
Update properties of a transport (SOAP/REST) on page 154
Enable or disable a transport (SOAP/REST) on page 155
Enable or disable a transport (APSV) on page 156
Get runtime metrics of a transport (SOAP/REST) on page 157
Get runtime metrics of a transport (APSV) on page 159
Reset runtime metrics for a transport (SOAP/REST) on page 160
Reset runtime metrics of a transport (APSV) on page 161
List deployed services (SOAP/REST) on page 162
Get information about a service (SOAP/REST) on page 163
Get configuration properties of a service (SOAP) on page 165
Deploy a new service (REST) on page 166
Deploy a new service (SOAP) on page 167
Update runtime properties of a service (SOAP) on page 168
Get runtime metrics for a service (SOAP) on page 169
Reset runtime metrics for a service (SOAP) on page 170
Enable or disable a service (SOAP) on page 171
Remove a service (SOAP/REST) on page 172

Get transport configuration properties (SOAP/REST)

Description
Get configuration properties of a REST or SOAP transport of a Web application belonging to an
ABL application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/

{soap|rest}/properties

ABL_app_name/webapps/Web_app_name/transports/

152

Pacific Application Server for OpenEdge: Administration Guide

Transport management

Media type
application/vnd.progress+json

Request body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example (SOAP)

curl -X GET -v
http://localhost:16680/oemanager/server/oeservices/ROOT/transports/soap/properties

Response body example (SOAP)

{"result":
{"idleSessionTimeout":0,
"waitIfBusy":0,
"connectionLifetime":0,
"requestWaitTimeout":-1,
"staleO4GLObjectTimeout":0,
"clientASKActivityTimeout":60,
"initialSessions":1,
"clientASKResponseTimeout":60,
"minIdleConnections":0,
"maxSessions":0,
"minSessions":1,
"appServerKeepalive":"denyClientASK,allowServerASK",
"serviceFaultLevel":2
},
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":
"PASOE 11.5.0",
"operation":"GET SOAP TRANSPORT PROPERTIES"
}

Command-line example (REST)

curl -X GET -v
http://localhost:16680/oemanager/server/oeservices/ROOT/transports/rest/properties

Response body example (REST)

{
"result": {
"appServerKeepalive": "denyClientASK,allowServerASK",
"idleSessionTimeout": 0,
"minSessions": 1,
"requestWaitTimeout": -1,
"initialSessions": 1,
"waitIfBusy": 0,
"staleO4GLObjectTimeout": 0,
"minIdleConnections": 0,
"connectionLifetime": 0,

Pacific Application Server for OpenEdge: Administration Guide

153

Chapter 7: REST API Reference for oemanager.war

"serviceFaultLevel": 2,
"clientASKResponseTimeout": 60,
"maxSessions": 0,
"clientASKActivityTimeout": 60
},
"operation": "GET REST TRANSPORT PROPERTIES",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": "

Update properties of a transport (SOAP/REST)

Description
Update the properties of a SOAP or REST transport of a Web application belonging to an ABL
application.

HTTP Operation
PUT

URI
//host_name:port/oemanager/applications/

{soap|rest}/properties

ABL_app_name/webapps/Web_app_name/transports/

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example (SOAP)

curl -X PUT -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/properties
-H "Content-Type: application/vnd.progress+json" -d '{"waitIfBusy":1}'

Request body example (SOAP)

{"waitIfBusy":1}

Response body example (SOAP)

{"result":
{"idleSessionTimeout":0,
"waitIfBusy":1,
"connectionLifetime":0,
"requestWaitTimeout":-1,
"staleO4GLObjectTimeout":0,
"clientASKActivityTimeout":60,

154

Pacific Application Server for OpenEdge: Administration Guide

Transport management

"initialSessions":1,
"clientASKResponseTimeout":60,
"minIdleConnections":0,
"maxSessions":0,
"minSessions":1,
"appServerKeepalive":"denyClientASK,allowServerASK",
"serviceFaultLevel":2
},
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":
"PASOE 11.5.0",
"operation":"SET SOAP TRANSPORT PROPERTIES"
}

Command-line example (REST)

curl -X PUT -v
http://localhost:16680/oemanager/server/oeservices/ROOT/transports/rest/properties
-H "Content-Type: application/vnd.progress+json" -d '{"maxSessions":1}'

Request body example (REST)

{"maxSessions":1}

Response body example (REST)

{
"operation":"SET REST TRANSPORT PROPERTIES",
"result":{"appServerKeepalive":"denyClientASK,allowServerASK",
"idleSessionTimeout":0,
"minSessions":1,
"requestWaitTimeout":-1,
"initialSessions":1,
"waitIfBusy":0,
"staleO4GLObjectTimeout":0,
"minIdleConnections":0,
"connectionLifetime":0,
"serviceFaultLevel":2,
"clientASKResponseTimeout":60,
"maxSessions":1,
"clientASKActivityTimeout":60
},
"outcome":"SUCCESS",
"errmsg":"NA",
"versionStr":"PASOE 11.5.0",
"versionNo":1
}

Enable or disable a transport (SOAP/REST)

Description
Enable or disable the REST or SOAP transport of a Web application belonging to an ABL application.

HTTP Operation
PUT

Pacific Application Server for OpenEdge: Administration Guide

155

Chapter 7: REST API Reference for oemanager.war

URI
//host_name:port/oemanager/applications/

{soap|rest}/state

ABL_app_name/webapps/Web_app_name/transports/

Media type
application/vnd.progress+json

Request body
{

{ENABLED |

"STATE" : "

}"

DISABLED

Response codes
200 Success
500 Unexpected Server Error

Command-line example (SOAP)

curl -X PUT -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/state
-d '{"state":"ENABLED"}'

-H "Content-Type: application/vnd.progress+json"

Response body example (SOAP)

{"state":"ENABLED"}

Command-line example (REST)

curl -X PUT -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/rest/state
-d '{"state":"DISABLED"}'

-H "Content-Type: application/vnd.progress+json"

Response body example (REST)

{"state":"DISABLED"}

Enable or disable a transport (APSV)

Description
Enable or disable the APSV transport of a Web application belonging to an ABL application.

HTTP Operation
PUT

156

Pacific Application Server for OpenEdge: Administration Guide

Transport management

URI
//host_name:port/oemanager/applications/ABL_app_name
/webapps/Web_app_name/transports/state

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X DELETE -d '{"state":"DISABLED"}' -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/state

Request body example

{"state":"DISABLED"}

Response body example

{
"operation":"SET APSV TRANSPORT STATE",
"result":"NA",
"versionNo":1,
"versionStr":"PASOE 11.5.0",
"outcome":"SUCCESS",
"errmsg":"NA"
}

Get runtime metrics of a transport (SOAP/REST)

Description
Get runtime metrics for a REST or SOAP transport of a Web application deployed in an ABL
application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/

{soap|rest}/metrics

ABL_app_name/webapps/Web_app_name/transports/

Media type
application/vnd.progress+json

Pacific Application Server for OpenEdge: Administration Guide

157

Chapter 7: REST API Reference for oemanager.war

Request body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example (SOAP)

curl -x GET -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/metrics

Response body example (SOAP)

{"result":
{
"serviceDisabled":0,
"soapProcessorErrors":0,
"httpRequestErrors":0,
"httpRequests":0,
"statusRequest":0,
"methodNotAllowederrors":0,
"soapRequests":0,
"successfulSoapRequests":0,
"wsdlRequest":0,
"activeRequests":0,
"urlNotFoundErrors":0,
"type":"OE_SOAP_TRANSPORT",
"startTime":"2014-07-17T08:40:03.422-04:00",
"accessTime":"2014-07-17T10:34:00.295-04:00"
},
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":"PASOE 11.5.0",
"operation":"GET OE_SOAP_TRANSPORT METRICS"
}

Command-line example (REST)

curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/rest/metrics

Response body example (REST)

{
"result":{"successfulConnectRequests":0,
"serviceNotFound":0,
"numRequests":0,
"serviceUnavailableRequests":0,
"statusRequests":0,
"runRequest":0,
"connectRequests":0,
"successfulRequests":0,
"ExpressionError":0,
"failedRequests":0,
"successfulRunRequest":0,
"type":"OE_REST_TRANSPORT",
"accessTime":"2014-07-17T08:40:58.315-04:00"
},

158

Pacific Application Server for OpenEdge: Administration Guide

Transport management

"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":"PASOE 11.5.0",
"operation":"GET OE_REST_TRANSPORT METRICS"
}

Get runtime metrics of a transport (APSV)

Description
Get the runtime metrics for the APSV transport for a Web application deployed in an ABL application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name
/webapps/Web_app_name/transports/metrics

Media type
application/vnd.progress+json

Request body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/metrics

Response body example

{
"operation":"GET OE_APSV_TRANSPORT METRICS",
"result":{"sessionErrors":0,
"sessionRequest":0,
"disconnectRequest":0,
"connectErrors":0,
"connectRequest":0,
"statusRequest":0,
"disconnectErrors":0,
"forbiddenErrors":0,
"type":"OE_APSV_TRANSPORT",
"accessTime":"2014-07-18T04:34:40.743-04:00",
"lastResetTime":"2014-07-18T04:34:22.314-04:00"
},
"versionNo":1,

Pacific Application Server for OpenEdge: Administration Guide

159

Chapter 7: REST API Reference for oemanager.war

"versionStr":"PASOE 11.5.0",
"outcome":"SUCCESS",
"errmsg":"NA"
}

Reset runtime metrics for a transport (SOAP/REST)

Description
Reset aggregate runtime metrics for a SOAP or REST transport of a Web application deployed in
an ABL application.

HTTP Operation
DELETE

URI
//host_name:port/oemanager/applications/

{soap|rest}/metrics

ABL_app_name/webapps/Web_app_name/transports/

Media type
application/vnd.progress+json

Request body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example (SOAP)

curl -X DELETE -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/rest/metrics

Response body example (SOAP)

{
"result":"NA",
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":"PASOE 11.5.0",
"operation":"RESET OE_REST_TRANSPORT METRICS"
}

Command-line example (REST)

curl -X DELETE -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/metrics

160

Pacific Application Server for OpenEdge: Administration Guide

Transport management

Response body example (REST)

{
"result":"NA",
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":"PASOE 11.5.0",
"operation":"RESET OE_SOAP_TRANSPORT METRICS"
}

Reset runtime metrics of a transport (APSV)

Description
Reset aggregate runtime metrics for an APSV transport of a Web application deployed in an ABL
application.

HTTP Operation
DELETE

URI
//host_name:port/oemanager/applications/ABL_app_name
/webapps/Web_app_name/transports/metrics

Media type
application/vnd.progress+json

Request body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X DELETE -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/metrics

Response body example

{
"result":"NA",
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":"PASOE 11.5.0",
"operation":"RESET OE_APSV_TRANSPORT METRICS"
}

Pacific Application Server for OpenEdge: Administration Guide

161

Chapter 7: REST API Reference for oemanager.war

List deployed services (SOAP/REST)

Description
Get a list all the deployed SOAP or REST services in a Web application deployed in an ABL
application.

HTTP Operation
GET

URI

{ | }

//host_name:port/oemanager/applications/App_name/webapps/Web_app_name/transports/ soap rest /oeservices

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

Request body
NA

Command-line example (SOAP)

curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/oeservices

Response body example(SOAP)

{
"result": {
"OESoapServiceDesc": [
{
"archiveLocation":
"/webapps/ROOT/WEB-INF/adapters/soap/ROOT/SimpleTest.wsdl",
"archiveName": "SimpleTest.wsm",
"accessUrl": "urn:nxgas:simpletestsf",
"oetype": "SOAP_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge SOAP Service Artifact",
"name": "SimpleTest",
"state": "ENABLED",
"type": "OPENEDGE"
}
]
},
"operation": "GET SOAP TRANSPORT DESCRIPTORS",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",

162

Pacific Application Server for OpenEdge: Administration Guide

Transport management

"errmsg": ""
}

Command-line example (REST)

curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/rest/oeservices

Response body example(REST)

{
"result": {
"OERestServiceDesc": [
{
"archiveLocation":
"/webapps/ROOT/WEB-INF/adapters/rest/_oepingService/_oepingService.paar",
"archiveName": "_oepingService.paar",
"accessUrl": "/rest/_oepingService",
"oetype": "REST_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge REST Service Descriptor",
"name": "_oepingService",
"type": "OPENEDGE",
"uri": "http://localhost:16680/rest/_oepingService"
}
]
},
"operation": "GET REST TRANSPORT DESCRIPTORS",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Get information about a service (SOAP/REST)

Description
Get details about a named SOAP or REST service in a Web application deployed in an ABL
application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name

/webapps/Web_app_name/transports/ soap rest /oeservices/ SoapServiceName RestSeviceName

Media type
application/vnd.progress+json

Pacific Application Server for OpenEdge: Administration Guide

163

Chapter 7: REST API Reference for oemanager.war

Response codes
200 Success
500 Unexpected Server Error

Request body
NA

Command-line example (SOAP)

curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/oeservices/SimpleTest

Response body example (SOAP)

{
"result": {
"OESoapServiceDesc": [
{
"archiveLocation": "/WEB-INF/adapters/soap/ROOT/",
"archiveName": "SimpleTest.wsm",
"accessUrl": "urn:nxgas:simpletestsf",
"oetype": "SOAP_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge SOAP Service Artifact",
"name": "SimpleTest",
"state": "ENABLED",
"type": "OPENEDGE"
}
]
},
"operation": "GET SOAP TRANSPORT DESCRIPTOR",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Command-line example (REST)

curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/rest/oeservices/_oepingService

Response body example (REST)

{
"result": {
"OERestServiceDesc": [
{
"archiveLocation":
"/webapps/ROOT/WEB-INF/adapters/rest/_oepingService/",
"archiveName": "_oepingService.paar",
"accessUrl": "/rest/_oepingService",
"oetype": "REST_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge REST Service Descriptor",
"name": "_oepingService",
"type": "OPENEDGE",
"uri": "http://localhost:16680/rest/_oepingService"
}

164

Pacific Application Server for OpenEdge: Administration Guide

Transport management

]
},
"operation": "GET REST TRANSPORT DESCRIPTOR",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Get configuration properties of a service (SOAP)

Description
Get configuration properties of a named SOAP service in a Web application deployed in an ABL
application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/webapps/Web_app_name
/transports/soap/oeservices/SoapServiceName/properties

Media type
application/vnd.progress+json

Response body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/oeservices/SimpleTest/properties

Request body example

{"result":
{"idleSessionTimeout":0,
"waitIfBusy":0,
"connectionLifetime":0,
"requestWaitTimeout":-1,
"staleO4GLObjectTimeout":0,
"clientASKActivityTimeout":60,
"initialSessions":1,
"clientASKResponseTimeout":60,
"minIdleConnections":0,

Pacific Application Server for OpenEdge: Administration Guide

165

Chapter 7: REST API Reference for oemanager.war

"maxSessions":0,
"minSessions":1,
"appServerKeepalive":"denyClientASK,allowServerASK",
"serviceFaultLevel":2
},
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":
"PASOE 11.5.0",
"operation":"GET SOAP TRANSPORT PROPERTIES"
}

Deploy a new service (REST)

Description
Deploy a new REST service in a WebApp deployed in an ABL application.

HTTP Operation
POST

URI
//host_name:port/oemanager/applications/ABL_app_name/webapps
/Web_app_name/transports/rest/oeservices/

Media type
application/vnd.progress.paar+zip

Content disposition

attachment; filename=

AppNewService.paar

AppNewService.zip

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X POST -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/rest/oeservices
-data-binary @PingService1.paar
-H "Accept: application/vnd.progress+json"
-H "Content-Type:application/vnd.progress.paar+zip"
-H "Content-Disposition: attachment; filename=PingService1.paar"

Request body example

application/vnd.progress.paar+zip

166

Pacific Application Server for OpenEdge: Administration Guide

Transport management

Response body example

{
"result": {
"OERestServiceDesc": [
{
"archiveLocation":
"WEB-INF/adapters/rest/PingService1/PingService1.paar",
"archiveName": "PingService1.paar",
"accessUrl": "/rest/PingService1",
"oetype": "REST_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge REST Service Descriptor",
"name": "PingService1",
"type": "OPENEDGE",
"uri": "http://localhost:16680/rest/PingService1"
}
]
},
"operation": "DEPLOY REST TRANSPORT DESCRIPTOR",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg"

Deploy a new service (SOAP)

Description
Deploy a new SOAP service in a WebApp deployed in an ABL application.

HTTP Operation
POST

URI
//host_name:port/oemanager/applications/ABL_app_name/webapps
/Web_app_name/transports/soap/oeservices/

Media type
application/vnd.progress.wsm+xml

Content disposition
attachment; filename=AppNewService.wsm

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X POST -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/oeservices
-data-binary @SimpleTest2.wsm

Pacific Application Server for OpenEdge: Administration Guide

167

Chapter 7: REST API Reference for oemanager.war

-H "Accept: application/vnd.progress+json"
-H "Content-Type: application/vnd.progress.wsm+xml"
-H "Content-Disposition: attachment; filename=SimpleTest2.wsm"

Request body example

application/vnd.progress.wsm+xm

Response body example

{
"result": {
"OESoapServiceDesc": [
{
"archiveLocation": "WEB-INF/adapters/soap/ROOT/SimpleTest.wsdl",
"archiveName": "SimpleTest.wsm",
"accessUrl": "urn:nxgas:simpletestsf",
"oetype": "SOAP_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge SOAP Service Artifact",
"name": "SimpleTest",
"state": "ENABLED",
"type": "OPENEDGE"
}
]
},
"operation": "DEPLOY SOAP TRANSPORT DESCRIPTOR",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Update runtime properties of a service (SOAP)

Description
Update the runtime properties of a SOAP service in the Web application of a deployed ABL
application.

HTTP Operation
PUT

URI
//host_name:port/oemanager/applications/ABL_app_name
/webapps/Web_app_name/transports/soap/oeservices/SoapServiceName/properties

Media type
application/vnd.progress+json

Response codes
200 Success
500 Unexpected Server Error

168

Pacific Application Server for OpenEdge: Administration Guide

Transport management

Command-line example
curl -X PUT -v
http://oelxdev03.bedford.progress.com:16680/oemanager/server/oeservices/ROOT/transports/soap/service/TestService2/properties
-H "Content-Type: application/vnd.progress+json" -d '{"maxSessions":1}'

Request body example

{"maxSessions":1}

Response body example

{"result":
{"idleSessionTimeout":0,
"waitIfBusy":1,
"connectionLifetime":0,
"requestWaitTimeout":-1,
"staleO4GLObjectTimeout":0,
"clientASKActivityTimeout":60,
"initialSessions":1,
"clientASKResponseTimeout":60,
"minIdleConnections":0,
"maxSessions":1,
"minSessions":1,
"appServerKeepalive":"denyClientASK,allowServerASK",
"serviceFaultLevel":2
},
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":
"PASOE 11.5.0",
"operation":"SET SOAP TRANSPORT PROPERTIES"
}

Get runtime metrics for a service (SOAP)

Description
Update the runtime metrics of a SOAP service in the Web application deployend in an ABL
application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name
/webapps/Web_app_name/transports/soap/oeservices/SoapServiceName/metrics

Media type
application/vnd.progress+json

Request body
NA

Pacific Application Server for OpenEdge: Administration Guide

169

Chapter 7: REST API Reference for oemanager.war

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/oeservices/SimpleTest/metrics

Response body example

{"result":
{"requests":0,
"appserverConnections":0,
"nameserverError":0,
"activeRequests":0,
"providerError":0,
"subAppObjects":0,
"objPoolFull":0,
"objPoolExpired":0,
"connectError":0,
"faults":0,
"ABLClientError":0,
"procObjects":0,
"startTime":"2014-07-17T08:40:07.315-04:00",
"appObjects":0,
"objNotFound":0,
"ABLServerError":0,
"accessTime":"2014-07-18T02:27:07.212-04:00",
"ABLAppError":0,
"clientError":0,
"type":"OE_SOAP_TRANSPORT_APP"
},
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":"PASOE 11.5.0",
"operation":"GET OE_SOAP_TRANSPORT_APP METRICS"
}

Reset runtime metrics for a service (SOAP)

Description
Reset runtime metrics for a SOAP service in a Web appplication deployed in an ABL application.

HTTP Operation
DELETE

URI
//host_name:port/oemanager/applications/ABL_app_name
/webapps/Web_app_name/transports/soap/oeservices/SoapServiceName/metrics

Media type
application/vnd.progress+json

170

Pacific Application Server for OpenEdge: Administration Guide

Transport management

Request body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X DELETE -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/oeservices/SimpleTest/metrics

Response body example

{
"result":"NA",
"outcome":"SUCCESS",
"versionNo":1,
"errmsg":"NA",
"versionStr":"PASOE 11.5.0",
"operation":"RESET OE_SOAP_TRANSPORT_APP METRICS"
}

Enable or disable a service (SOAP)

Description
Enable or disable a SOAP service in a Web application deployed in an ABL application.

HTTP Operation
PUT

URI
//host_name:port/oemanager/applications/ABL_app_name/webapps
/Web_app_name/transports/soap/oeservices/SoapServiceName/state

Media type
application/vnd.progress+json

Request body
{

{ENABLED |

"STATE" : "

}"

DISABLED

Response codes
200 Success
500 Unexpected Server Error

Pacific Application Server for OpenEdge: Administration Guide

171

Chapter 7: REST API Reference for oemanager.war

Command-line example
curl -X PUT -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/oeservices/SimpleTest/state
-H "Content-Type: application/vnd.progress+json" -d '{"state":"DISABLED"}'

Response body example

{"state":"DISABLED"}

Remove a service (SOAP/REST)

Description
Remove a specified SOAP or REST service from a Web application deployed in an ABL application.

HTTP Operation
DELETE

URI

{ | }

//host_name:port/oemanager/applications/ABL_app_name/webapps/Web_app_name/transports/ soap rest /oeservices SoapServiceName RestSeviceName

Media type
application/vnd.progress+json

Response codes
500 Unexpected Server Error

Request body
NA

Command-line example (SOAP)

curl -X DELETE -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/soap/oeservices/SimpleTest

Response body example (SOAP)

{
"result": {
"OESoapServiceDesc": [
{
"status": "INITIALIZED",
"descriptors": [],
"oetype": "SOAP",
"version": "11.4ALPHA",
"description": "PAS OpenEdge SOAP Service.",
"name": "SOAP",
"state": "ENABLED",

172

Pacific Application Server for OpenEdge: Administration Guide

Transport management

"type": "OPENEDGE",
"uri": "http://localhost.com:16680/soap"
}
]
},
"operation": "UNDEPLOY SOAP TRANSPORT DESCRIPTOR",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Command-line example (REST)

curl -X DELETE -v
http://localhost:16680/oemanager/applications/pas1/webapps/ROOT/transports/rest/oeservices/_oepingService

Response body example (REST)

{"result":
{
"OERestServiceDesc":[
{
"status":"INITIALIZED",
"contextPath":"\/\/wrk\/pas1\/webapps\/ROOT",
"descriptors":[
{
"archiveLocation":"WEB-INF\/adapters\/rest\/_oepingService\/_oepingService.paar",
"archiveName":"_oepingService.paar",
"accessUrl":"\/rest\/_oepingService",
"oetype":"REST_DESCRIPTOR",
"version":"11.5.0",
"description":"PAS OpenEdge REST Service Descriptor",
"name":"_oepingService",
"type":"OPENEDGE",
"uri":"http:\/\/localhost.com:16680\/rest\/_oepingService"
}
],
"oetype":"REST",
"version":"v11.4.0 (12-Dec-2013)",
"description":"PAS OpenEdge REST Transport.",
"name":"REST",
"state":"DISABLED",
"type":"OPENEDGE",
"uri":"http:\/\/localhost.com:16680\/rest"
}
]
},
"operation":"UNDEPLOY REST TRANSPORT DESCRIPTOR",
"versionStr":"PASOE 11.5.0",
"versionNo":1,
"outcome":"SUCCESS",
"errmsg":""
}

Pacific Application Server for OpenEdge: Administration Guide

173

Chapter 7: REST API Reference for oemanager.war

Application management
This section describes the REST services that are available for managing ABL and Web applications
deployed on the Pacific Application Server.

See also
List ABL application information on page 174
Get information about a specific ABL application on page 176
List Web applications deployed to an ABL application on page 178
Get information about a specific Web application on page 180

List ABL application information

Description
Get information about ABL applications from the OEManager.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/

Media type
application/vnd.progress+json

Request body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v http://localhost:16680/oemanager/applications/

Response body example

"result": {
"Application": [
{
"webapps": [
{

174

Pacific Application Server for OpenEdge: Administration Guide

Application management

"applicationName": "pas1",
"transports": [
{
"status": "INITIALIZED",
"descriptors": [
{
"archiveLocation":
"/wrk/pas1/webapps/ROOT/WEB-INF/adapters/soap//ROOT/SimpleTest.wsdl",
"archiveName": "SimpleTest.wsm",
"accessUrl": "urn:nxgas:simpletestsf",
"oetype": "SOAP_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge SOAP Service Artifact",
"name": "SimpleTest",
"state": "DISABLED",
"type": "OPENEDGE"
}
],
"oetype": "SOAP",
"version": "11.4ALPHA",
"description": "PAS OpenEdge SOAP Service.",
"name": "SOAP",
"state": "DISABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/soap"
},
{
"status": "INITIALIZED",
"oetype": "APSV",
"version": "v115.PASOE (11-SEPT-2014)",
"description": "PAS OpenEdge APSV Transport.",
"name": "APSV",
"state": "ENABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/apsv"
},
{
"status": "INITIALIZED",
"contextPath": "//wrk/pas1/webapps/ROOT",
"descriptors": [
{
"archiveLocation":
"WEB-INF/adapters/rest/_oepingService/_oepingService.paar",
"archiveName": "_oepingService.paar",
"accessUrl": "/rest/_oepingService",
"oetype": "REST_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge REST Service Descriptor",
"name": "_oepingService",
"type": "OPENEDGE",
"uri": "http://localhost:16680/rest/_oepingService"
}
],
"oetype": "REST",
"version": "v11.4.0 (12-Dec-2013)",
"description": "PAS OpenEdge REST Transport.",
"name": "REST",
"state": "ENABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/rest"
}
],
"oetype": "WEBAPP",
"version": "11.5.0",
"description": "PAS OpenEdge WebApp",
"name": "ROOT",
"state": "STARTED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/"

Pacific Application Server for OpenEdge: Administration Guide

175

Chapter 7: REST API Reference for oemanager.war

}
],
"oetype": "APPLICATION",
"version": "11.5.0",
"description": "PAS Application",
"name": "pas1",
"type": "OPENEDGE"
}
]
},
"operation": "GET OEABL SERVICES",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Get information about a specific ABL application

Description
Get information about a specified application from the OEManager.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name

Media type
application/vnd.progress+json

Request body example

NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v http://localhost:16680/oemanager/applications/pas1

Response body example

{
"result": {
"Application": [
{
"webapps": [
{
"applicationName": "pas1",

176

Pacific Application Server for OpenEdge: Administration Guide

Application management

"transports": [
{
"status": "INITIALIZED",
"descriptors": [
{
"archiveLocation":
"/wrk/pas1/webapps/ROOT/WEB-INF/adapters/soap//ROOT/SimpleTest.wsdl",
"archiveName": "SimpleTest.wsm",
"accessUrl": "urn:nxgas:simpletestsf",
"oetype": "SOAP_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge SOAP Service Artifact",
"name": "SimpleTest",
"state": "DISABLED",
"type": "OPENEDGE"
}
],
"oetype": "SOAP",
"version": "11.4ALPHA",
"description": "PAS OpenEdge SOAP Service.",
"name": "SOAP",
"state": "DISABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/soap"
},
{
"status": "INITIALIZED",
"oetype": "APSV",
"version": "v115.PASOE (11-SEPT-2014)",
"description": "PAS OpenEdge APSV Transport.",
"name": "APSV",
"state": "ENABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/apsv"
},
{
"status": "INITIALIZED",
"contextPath": "/wrk/pas1/webapps/ROOT",
"descriptors": [
{
"archiveLocation":
"WEB-INF/adapters/rest/_oepingService/_oepingService.paar",
"archiveName": "_oepingService.paar",
"accessUrl": "/rest/_oepingService",
"oetype": "REST_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge REST Service Descriptor",
"name": "_oepingService",
"type": "OPENEDGE",
"uri": "http://localhost:16680/rest/_oepingService"
}
],
"oetype": "REST",
"version": "v11.4.0 (12-Dec-2013)",
"description": "PAS OpenEdge REST Transport.",
"name": "REST",
"state": "ENABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/rest"
}
],
"oetype": "WEBAPP",
"version": "11.5.0",
"description": "PAS OpenEdge WebApp",
"name": "ROOT",
"state": "STARTED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/"
}

Pacific Application Server for OpenEdge: Administration Guide

177

Chapter 7: REST API Reference for oemanager.war

],
"oetype": "APPLICATION",
"version": "11.5.0",
"description": "PAS Application",
"name": "pas1",
"type": "OPENEDGE"
}
]
},
"operation": "GET OEABL SERVICE",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

List Web applications deployed to an ABL application

Description
Get information from the OEManager about all the Web applications deployed to an ABL application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/webapps

Media type
application/vnd.progress+json

Request body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v http://localhost:16680/oemanager/applications/pas1/webapps

Response body example

{
"result": {
"WebApp": [
{
"applicationName": "pas1",
"transports": [
{
"status": "INITIALIZED",

178

Pacific Application Server for OpenEdge: Administration Guide

Application management

"descriptors": [
{
"archiveLocation":
"/wrk/pas1/webapps/ROOT/WEB-INF/adapters/soap//ROOT/SimpleTest.wsdl",
"archiveName": "SimpleTest.wsm",
"accessUrl": "urn:nxgas:simpletestsf",
"oetype": "SOAP_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge SOAP Service Artifact",
"name": "SimpleTest",
"state": "DISABLED",
"type": "OPENEDGE"
}
],
"oetype": "SOAP",
"version": "11.4ALPHA",
"description": "PAS OpenEdge SOAP Service.",
"name": "SOAP",
"state": "DISABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/soap"
},
{
"status": "INITIALIZED",
"oetype": "APSV",
"version": "v115.PASOE (11-SEPT-2014)",
"description": "PAS OpenEdge APSV Transport.",
"name": "APSV",
"state": "ENABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/apsv"
},
{
"status": "INITIALIZED",
"contextPath": "/wrk/pas1/webapps/ROOT",
"descriptors": [
{
"archiveLocation":
"WEB-INF/adapters/rest/_oepingService/_oepingService.paar",
"archiveName": "_oepingService.paar",
"accessUrl": "/rest/_oepingService",
"oetype": "REST_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge REST Service Descriptor",
"name": "_oepingService",
"type": "OPENEDGE",
"uri": "localhost:16680/rest/_oepingService"
}
],
"oetype": "REST",
"version": "v11.4.0 (12-Dec-2013)",
"description": "PAS OpenEdge REST Transport.",
"name": "REST",
"state": "ENABLED",
"type": "OPENEDGE",
"uri": "localhost:16680/rest"
}
],
"oetype": "WEBAPP",
"version": "11.5.0",
"description": "PAS OpenEdge WebApp",
"name": "ROOT",
"state": "STARTED",
"type": "OPENEDGE",
"uri": "localhost:16680/"
}
]
},
"operation": "GET OEABL SERVICES",

Pacific Application Server for OpenEdge: Administration Guide

179

Chapter 7: REST API Reference for oemanager.war

"versionStr": "PASOE 11.5.0",

"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Get information about a specific Web application

Description
Get information from the OEManager about a specific Web application deployed to an ABL
application.

HTTP Operation
GET

URI
//host_name:port/oemanager/applications/ABL_app_name/webapps/Web_app_name

Media type
application/vnd.progress+json

Request body
NA

Response codes
200 Success
500 Unexpected Server Error

Command-line example
curl -X GET -v http://localhost:16680/oemanager/applications/pas1/webapps/ROOT

Response body example

{
"result": {
"WebApp": [
{
"applicationName": "pas1",
"transports": [
{
"status": "INITIALIZED",
"descriptors": [
{
"archiveLocation":
"/wrk/pas1/webapps/ROOT/WEB-INF/adapters/soap//ROOT/SimpleTest.wsdl",
"archiveName": "SimpleTest.wsm",
"accessUrl": "urn:nxgas:simpletestsf",
"oetype": "SOAP_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge SOAP Service Artifact",

180

Pacific Application Server for OpenEdge: Administration Guide

Application management

"name": "SimpleTest",
"state": "DISABLED",
"type": "OPENEDGE"
}
],
"oetype": "SOAP",
"version": "11.4ALPHA",
"description": "PAS OpenEdge SOAP Service.",
"name": "SOAP",
"state": "DISABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/soap"
},
{
"status": "INITIALIZED",
"oetype": "APSV",
"version": "v115.PASOE (11-SEPT-2014)",
"description": "PAS OpenEdge APSV Transport.",
"name": "APSV",
"state": "ENABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/apsv"
},
{
"status": "INITIALIZED",
"contextPath": "/wrk/pas1/webapps/ROOT",
"descriptors": [
{
"archiveLocation":
"WEB-INF/adapters/rest/_oepingService/_oepingService.paar",
"archiveName": "_oepingService.paar",
"accessUrl": "/rest/_oepingService",
"oetype": "REST_DESCRIPTOR",
"version": "11.5.0",
"description": "PAS OpenEdge REST Service Descriptor",
"name": "_oepingService",
"type": "OPENEDGE",
"uri": "http://localhost:16680/rest/_oepingService"
}
],
"oetype": "REST",
"version": "v11.4.0 (12-Dec-2013)",
"description": "PAS OpenEdge REST Transport.",
"name": "REST",
"state": "ENABLED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/rest"
}
],
"oetype": "WEBAPP",
"version": "11.5.0",
"description": "PAS OpenEdge WebApp",
"name": "ROOT",
"state": "STARTED",
"type": "OPENEDGE",
"uri": "http://localhost:16680/"
}
]
},
"operation": "GET OEABL SERVICES",
"versionStr": "PASOE 11.5.0",
"versionNo": 1,
"outcome": "SUCCESS",
"errmsg": ""
}

Pacific Application Server for OpenEdge: Administration Guide

181

Chapter 7: REST API Reference for oemanager.war

182

Pacific Application Server for OpenEdge: Administration Guide

Index

Index
A

ABL application information 174, 176, 178, 180

Access control 64
Adding users 62
Administrative utilities 1819
Agent management 140
Agent status 141
Application management 174
apsv-basic.xml 60
Audience 9

help 126
HTTPS 48

C
Cancel a request 138
clean action 117
Clients 131
config action 113
Configuration files 23
Configuration properties 134135, 149150
Connection information 143
Container security configurations 83
CORS support 83
create 110
Creating instances 38

D
delete 112
deploy 101
Deployed services 162
deployREST.sh 44
deploySOAP.sh 45
Development server 52
Development servers 22
Directory structure extensions 33
disable 107

E
enable 106
Enabling Spring Security 59
env 127

I
info 100
instances 117
Instances
3538, 40
creating 38
managing 37
Running as a UNIX daemon 40
Running as a Windows service 40

J
Jacksum 63
JConsole 19
JMX 19
JVM security manager 49

L
LDAP security configurations 75
leaks 106
list 99
List agents 140
List clients 131
List sessions 130
Logging 22

M
Managing instances 37
Managing Web applications 43
MBeans 19
MemoryRealm 50

O
OEPAS 18
OpenEdge Explorer 19
OpenEdge Management 19
Organization 10

feature action 115

Pacific Application Server for OpenEdge: Administration Guide

183

Index

REST API for oemanager.war (continued)

reset runtime metrics 137
reset service runtime metrics 170
reset transport metrics 160161
sessions 130
stop an agent 151
terminate a session 139
update configuration properties 135, 150
update service runtime properties 168
update transport properties 154
REST API Reference 129
REST service deployment (if needed)
44
Nest index terms for sub entries 44
Roles
50
assigning to users 50
Runtime metrics 136

P
Pacific Application Server
17, 19, 33, 47
administrative utilities 19
as a production server 47
directory structure extensions 33
extensions to Apache Tomcat 17
PAS for OpenEdge
52
development server 52
production server 52
PASOE
18
administrative utilities 18
Production server 47, 52
Production servers 22
Properties
24
PAS properties 24
Properties files 23
Purpose 9

S
SAML

R
Realms 50
register 119
reload 103
Remote access filters 52
Request information 133, 145
Reset runtime metrics 137
resources 108
REST API for oemanager.war
130131, 133143, 145, 149152, 154157,
159163, 165172, 174, 176, 178, 180
cancel a request 138
clients 131
deploy a new service 166167
enable or disable a service 171
enable or disable a transport 155156
get ABL application information 174, 176, 180
get agent status 141
get configuration properties 134, 149
get connection information 143
get request information 133, 145
get runtime metrics 136
get service configuration properties 165
get service information 163
get service runtime metrics 169
get session metrics 142
get transport configuration properties 152
get transport metrics 157, 159
list agents 140
list deployed services 162
list Web applications 178
removing a service 172

184

7779
Creating and configuring service provider metadata
77
Registering service provider 78
Security configuration model 79
SAML security configurations 76
Security 47
Service deployment 166167
Service enable or disable 171
Service information 163, 165
Service removal 172
Service runtime metrics 169170
Service runtime properties 168
Session management 130
Session metrics 142
sessions 109
Sessions 130
SOAP service deployment 45
soap-basic-local.xml 61
SPA configuration 68
SPA security configurations 65
Spring Security 49
SSO support 89
start 121
status 104
stop 123
Stop an agent 151

T
tcman 94
TCMAN
18, 93, 96, 99104, 106110, 112113, 115,
117, 119121, 123127

Pacific Application Server for OpenEdge: Administration Guide

Index

TCMAN (continued)
clean 117
config 113
create 110
customizing 96
delete 112
deploy 101
disable 107
enable 106
env 127
extending 96
feature 115
general actions 126
help 126
info 100
instances 117
leaks 106
list 99
manager actions 99
register 119
reload 103
resources 108
server actions 110
sessions 109
start 121
status 104
stop 123
test 125
undeploy 102
unregister 120

TCMAN (continued)
using 93
version 124
Terminate a session 139
test 125
Transport management 152
Transport metrics 157, 159161
Transport properties 152, 154
Transports 155156

U
undeploy 102
UNIX daemon 40
unregister 120

V
version 124

W
Web application deployment 44
Web application security configurations 55
Web applications
43, 45
managing 43
Packaging 45
Windows service 40

Pacific Application Server for OpenEdge: Administration Guide

185

Index

186

Pacific Application Server for OpenEdge: Administration Guide