WebSphere Application Server for z/OS Version 6.0.2
Using SERVAUTH to Protect
TCP Port Usage
The information in this document is also included in the WP100653 white paper,
"WebSphere for z/OS V6 Sample ND Configuration."
This document can be found on the web at:
www.ibm.com/support/techdocs
Search for document number WP100673 under the category of "White Papers"
Version Date: November 29, 2005
See "Document Change History" on page 16 for a description of the changes in this version of the document
IBM Washington Systems Center
Don Bagwell
IBM Washington Systems Center
301-240-3016
[email protected]
Many thanks go to Mike Kearney, Bob Teichman and
Johnny Chi, all of the Washington Systems Center.
WP100673 - Using SERVAUTH to Protect TCP Port Usage
Table of Contents
Executive Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
One-page Summary of Definitions and Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
SYS1.TCPPARM(PROFELXC) update for SYSC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
SYS1.TCPPARM(PROFELXD) update for SYSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
VARY command used to activate updated TCP PROFILE members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Creation of RACF SERVAUTH profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
An Overview of Defining and Activating the SERVAUTH Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Understanding the format and relationship of PORTRANGE and SERVAUTH . . . . . . . . . . . . . . . . . . . . . . . 4
Controlling who can access the port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Activating the changes in the TCP PROFILE member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
PORTRANGE value can't conflict with other PORT or PORTRANGE definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
What's in PROFILE member is not necessarily how TCPIP views things . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Viewing the present PORTLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Using the DELETE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Creating and activating the RACF SERVAUTH profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Activating and RACLISTing the SERVAUTH class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Defining the SERVAUTH class profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Permitting IDs or groups READ access to the SERVAUTH class profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Refreshing the RACLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Deleting a SERVAUTH class profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Testing the changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
A Real Example of Configuring Port-level Protection using SERVAUTH . . . . . . . . . . . . . . . . . . . . . . 10
Inventory of ports used by WebSphere cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Determined PORTRANGE value to be used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Understood the implications of our multi-system cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Coded PORTRANGE statement in each TCP PROFILE member and activated with VARY . . . . . . . . 12
Updated PROFILE members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Varied the PROFILE members active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Verified definitions with NETSTAT PORTLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Created SERVAUTH class profiles and granted config group READ access . . . . . . . . . . . . . . . . . . . . . 14
CLASSACT and RACLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
SERVAUTH for SYSC, config group access and refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
SERVAUTH for SYSD, config group access and refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Tested protection offered by SERVAUTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Test: WPCELL access permitted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Test: non-WPCELL access prohibited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Document Change History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
-1-
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
Executive Overview
As any user of WebSphere Application Server for z/OS knows, WebSphere uses a lot of TCP
ports. The Washington Systems Center has long recommended that a range of ports be set aside
for a given WebSphere cell, and the allocation of the ports across the servers of the cell be made
from the ports in that range. Doing so reduces the chances of TCP port conflicts -- if everyone in
your organization knows that ports 28500 to 28599 are for WebSphere cell WPCELL, they won't
use any of those ports for other things.
That system works, so long as everyone knows about the range used by WebSphere and everyone
honors the reserved port range.
However, if you wish to make certain nobody else uses your WebSphere ports, it calls for
something more. It calls for the RACF SERVAUTH class.
Notes:
! Here and elsewhere the term "RACF" is meant to convey the SAF function of z/OS. RACF is
IBM's product to implement SAF; competitive products exist. In this document we illustrate the
RACF's implementation of port reservation.
! RACF provides protection not just at the port level, but also protection at the TCP stack level as
well. For this paper we're interested only in port and port-range protection.
At a high-level, here is how the SERVAUTH functionality works:
Program
1
2
SYS1.TCPPARMS(PROFILE)
TCP Function
RACF Database
3
High-level picture of SERVAUTH port protection
Notes:
1. A program or process seeks to bind to a port (or ports)
2. TCP looks in the PROFILE member to see if that port (or ports) is defined on a PORT or PORTRANGE
statement, and if so, whether the keyword SAF is seen.
Note: As the name implies, PORTRANGE is a way to define a range of ports. PORT provides a way to
define individual ports. Other than that, the mechanism is the same. WebSphere uses a lot of
ports; therefore, using PORTRANGE is appropriate
3. If keyword SAF is seen, TCP will consult with RACF to see if the ID of the program or process has at least
READ access to the SERVAUTH profile defined in RACF.
This document is divided into three sections:
!
"One-page Summary of Definitions and Commands" -- a simple reference sheet of the WPCELL scenario
described starting on page 10.
!
"An Overview of Defining and Activating the SERVAUTH Protection" -- provides a more complete
explanation of the configuration statements used to provide the protection.
"A Real Example of Configuring Port-level Protection using SERVAUTH" -- an illustration of the
configuration of PORTRANGE and SERVAUTH using an actual WebSphere cell at the Washington Systems
Center.
!
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
-2-
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
One-page Summary of Definitions and Commands
Based on the WPCELL scenario as described starting on page 10.
SYS1.TCPPARM(PROFELXC) update for SYSC
PORTRANGE
28500 100 TCP * SAF WPCELL
;
; SET-ASIDE OF PORTS FOR WPCELL
SYS1.TCPPARM(PROFELXD) update for SYSD
PORTRANGE
28500 100 TCP * SAF WPCELL
;
; SET-ASIDE OF PORTS FOR WPCELL
VARY command used to activate updated TCP PROFILE members
System
VARY command issued
System SYSC
VARY TCPIP,,O,SYS1.TCPPARMS(PROFELXC)
System SYSD
VARY TCPIP,,O,SYS1.TCPPARMS(PROFELXD)
Creation of RACF SERVAUTH profiles
SETROPTS CLASSACT(SERVAUTH)
SETROPTS RACLIST(SERVAUTH) GENERIC(SERVAUTH)
RDEFINE SERVAUTH (EZB.PORTACCESS.SYSC.TCPIPC.WPCELL) UACC(NONE)
PERMIT EZB.PORTACCESS.SYSC.TCPIPC.WPCELL CLASS(SERVAUTH) ID(WPCFG) ACC(READ)
SETROPTS RACLIST(SERVAUTH) GENERIC(SERVAUTH) REFRESH
RDEFINE SERVAUTH (EZB.PORTACCESS.SYSD.TCPIPD.WPCELL) UACC(NONE)
PERMIT EZB.PORTACCESS.SYSD.TCPIPD.WPCELL CLASS(SERVAUTH) ID(WPCFG) ACC(READ)
SETROPTS RACLIST(SERVAUTH) GENERIC(SERVAUTH) REFRESH
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
-3-
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
An Overview of Defining and Activating the SERVAUTH Protection
This section will provide you with a more detailed explanation of the statements and how they're put
into effect.
Understanding the format and relationship of PORTRANGE and SERVAUTH
There are two key definitions that work together to provide the port-level protection:
TCP PROFILE member
1
7
8
PORTRANGE
28500 100 TCP * SAF WPCELL ; reserved for WPCELL
4
3
6
5
; 2
EZB.PORTACCESS.SYSC.TCPIPC.WPCELL
9
10
11
12
RACF SERVAUTH CLASS Profile
The two key definition statement, their content, and the relationship between the two
The TCP Profile member:
1. The keyword PORTRANGE indicates the start of a series of statements that define different port ranges
to be protected. The example above shows only one such range of ports, but multiple ranges can be
coded.
2. The first number is the starting port in the range. In this example, 28500 is the first port in the range
of ports to be protected.
3. The next number is the number of ports -- including the starting port -- to be protected. In this
example the value is 100. That means ports 28500 through 28599 will be protected.
4. The keyword TCP defines the communication protocol. For WebSphere the value to use is TCP.
Other protocols, such as UDP and FTP are permitted, but they don't apply to WebSphere.
5. The next field defines the JOBNAME. An asterisk means "any JOBNAME." In the case of
WebSphere, the range of ports will include many different JOBNAME values. Therefore, for a
WebSphere cell, the use of an asterisk is appropriate.
6. The keyword SAF tells TCP to check with the Security Access Facility of z/OS to determine if the user
attempting access has the authority. The absence of SAF means TCP uses its own mechanism,
which is typically based on JOBNAME rather than user identity.
7. The field that follows the keyword SAF is one that ties the PORTRANGE definition to a particular
SERVAUTH class profile. The value is one you define. It must be between 1 and 8 characters in
length.
Notes: ! As the picture illustrates, this value relates directly to the last field on the SERVAUTH
profile name. Case does not matter -- both TCP and RACF will fold lowercase to
uppercase.
! Since in our example we were blocking off the ports for the WPCELL, we decided that
the cell short name was as good a value as any for this field.
8. An optional comment field to describe the definition. Note the semi-colon delimiting the end of the
statement and the beginning of the comment field.
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
-4-
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
The RACF SERVAUTH class profile:
9. The string EZB.PORTACCESS is a keyword string. It must be coded exactly like that.
10. The third field in the profile name -- note the "dot" separators -- refers to the MVS system name on
which this port request occurred. In this example, that value is SYSC.
Note: What happens if a WebSphere cell spans multiple MVS images? You would need multiple
SERVAUTH class profiles -- one for each MVS image over which the cell spanned.
11. The fourth field in the profile name refers to the JOBNAME for the started TCP communication
system. In this example that value is TCPIPC.
Note: Another reason why a WebSphere cell that spans MVS images will require multiple
SERVAUTH class profiles.
12. The fifth (and last) field of the SERVAUTH class profile name is the "SAF Name," and relates directly to
the value supplied in the TCP profile member after the SAF keyword. It's this value, in combination
with the system name and TCP JOBNAME values, that TCP and RACF use to isolate down to a
particular SERVAUTH profile to use.
Controlling who can access the port
This is simply a matter of granting an ID READ access to the new SERVAUTH profile. Which ID
should you grant READ access? If you wish to allow any ID used by WebSphere for a given
cell, then grant access to that cell's configuration group ID. All controller and servant IDs are
connected to the config group, so if that group ID has READ access, all its connected IDs do as
well.
For example, the WPCELL illustrated in the white paper WP100653 had a config group ID of
WPCFG. See "Creating and activating the RACF SERVAUTH profile" on page 8 for more.
Activating the changes in the TCP PROFILE member
Once the PORTRANGE definition is added to the TCP PROFILE member, it needs to be
activated to take effect. One way to accomplish that is to stop and restart TCPIP. Another way
is to VARY TCP to refresh the PROFILE member:
VARY TCPIP,,O,SYS1.TCPPARMS(PROFILE)
The "obeyfile" (that's what the PROFILE member is called) is read in and processed:
EZZ0060I PROCESSING COMMAND: VARY TCPIP,,O,SYS1.TCPPARMS(PROFILE)
EZZ0300I OPENED OBEYFILE FILE 'SYS1.TCPPARMS(PROFILE)'
EZZ0309I PROFILE PROCESSING BEGINNING FOR 'SYS1.TCPPARMS(PROFILE)'
:
(messages related to statements in PROFILE here)
:
EZZ0316I PROFILE PROCESSING COMPLETE FOR FILE 'SYS1.TCPPARMS(PROFILE)'
At that point the PORTRANGE specification should be active. Of course, until the matching
RACF SERVAUTH class profile is present it won't have any effect. That topic is covered under
"Creating and activating the RACF SERVAUTH profile" on page 8.
Before we move on to that, let's cover a few more things about the TCP PROFILE member.
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
-5-
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
PORTRANGE value can't conflict with other PORT or PORTRANGE definition
TCP will not permit a PORTRANGE definition that conflicts with another port value:
PORT
21 TCP FTPSERVE
23 TCP INTCLIEN
:
9080 TCP * IMWEBSRV
;
Conflict
PORTRANGE
9000 100 TCP * SAF WPCELL
;
; FTP SERVER
; Telnet server
; HTTP Server
; Reservation for WPCELL
Conflicting port values -- PORT and PORTRANGE in this example -- in PROFILE
The error messages you'll get will look something like this:
VARY TCPIP,,O,SYS1.TCPPARMS(PROFILE)
EZZ0060I PROCESSING COMMAND: VARY TCPIP,,O,SYS1.TCPPARMS(PROFILE)
EZZ0300I OPENED OBEYFILE FILE 'SYS1.TCPPARMS(PROFILE)'
EZZ0309I PROFILE PROCESSING BEGINNING FOR 'SYS1.TCPPARMS(PROFILE)'
:
EZZ0600I PORTRANGE 9080-9080 * CONFLICTS WITH PORT RESERVATION
:
EZZ0316I PROFILE PROCESSING COMPLETE FOR FILE 'SYS1.TCPPARMS(PROFILE)'
EZZ0303I OBEYFILE FILE CONTAINS ERRORS
:
EZZ0059I VARY OBEY COMMAND FAILED: SEE PREVIOUS MESSAGES
Notes: ! Notice how the conflict message does not indicate the full range of ports on the original
PORTRANGE statement. It only reflects the point of conflict.
! It doesn't say so in the error message, but testing showed that the whole range of ports
specified on the PORTRANGE was rejected because of the conflict.
! Always read the output from the VARY command carefully. Look for any indication that
the VARY failed due to things like conflicts.
This was the obvious example -- when an explicitly coded conflict exists. But there's a more
subtle type of conflict you should know about.
What's in PROFILE member is not necessarily how TCPIP views things
It is tempting to think that what's defined in the PROFILE member is the same as what's
active in TCPIP, but that's not necessarily true. And in the case of ports, it's more than just
failing to VARY the PROFILE member active after something is changed.
Key Points:
! PORT and PORTRANGE values are not deactivated simply by removing them from
the PROFILE member and issuing the VARY command. They must be explicitly
removed with the DELETE statement.
! You can't necessarily rely on what's defined in the PROFILE member to know what
TCP holds in its memory.
We saw in the previous section how a PORTRANGE definition can be rejected if there's any
conflict at all with the values specified. It's possible there's an active PORT or PORTRANGE in
TCP's memory which is not coded in the PROFILE member. Before your PORTRANGE value
can take effect, the conflict must be resolved.
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
-6-
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
Viewing the present PORTLIST
This is done with the simple command:
NETSTAT PORTLIST
Note: Or, depending on where you're issuing the command, TSO NETSTAT PORTLIST
This will display back the currently held list of ports:
EZZ2350I
EZZ2795I
EZZ2796I
EZZ2797I
EZZ2797I
EZZ2797I
EZZ2797I
:
EZZ2797I
EZZ2797I
EZZ2797I
EZZ2797I
***
MVS TCP/IP
Port# Prot
----- ---00020 TCP
00021 TCP
00023 TCP
00025 TCP
NETSTAT CS V1R7
User
Flags
-------OMVS
D
FTPSERVE DA
TCPIPC
DA
SMTP
DA
05655
09080
00520
01211
*
*
OMPRSYSC
OMVS
TCP
TCP
UDP
UDP
DA
DA
D
DA
TCPIP Name: TCPIPC
Range
IP Address
--------------
" example of port conflict shown earlier
Note: This is also a very handy want to verify that your PORTRANGE definition took effect. The
output from NETSTAT PORTLIST will be all the ports in the range, with the defined
range of ports showing under the "Range" column of the output.
Suppose you have a conflict ... what can be done about it? There are two basic ways to
address a conflict with the port range you wish to set aside for WebSphere:
1. Change the range of ports used by your WebSphere cell -- which can be done through the
Admin Console, but it is a labor intensive process and prone to human error.
Note: If you've just created a new cell and discover that your port range is conflicts with
something else, it may be easiest to delete the cell and rebuild it. Go back into the
ISPF panels and change the ports to a new range, then regenerate the jobs. If your
cell is well established then deleting it may not be an option.
2. Use the DELETE statement to remove the conflicting ports so your PORTRANGE can take
effect.
We explore the second one next.
Using the DELETE statement
The DELETE statement is used to remove from TCP's memory any PORT or PORTRANGE
reservation. Examples of its use would be:
Single Port
DELETE PORT
28800 TCP *
Range of Ports
DELETE PORTRANGE
28800 100 TCP *
Note: This is only necessary if a port or port range is in effect and you wish to remove them
from TCP's consideration. Otherwise, just use the PORTRANGE and VARY and move on
to the creation of the SERVAUTH profile.
Therefore, if you're experiencing conflicts with your desired PORTRANGE definition, do
the following:
!
!
Code a DELETE definition to remove the conflicting port
VARY the PROFILE member active
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
-7-
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
!
!
!
!
Remove or comment out the DELETE definition
Add your PORTRANGE definition
VARY the PROFILE member again to pick up your PORTRANGE value
Use the NETSTAT PORTLIST command to verify your PORTRANGE is in effect
Creating and activating the RACF SERVAUTH profile
This involves four steps:
1.
2.
3.
4.
Activating the SERVAUTH class
"RACLISTing" the class
Defining the SERVAUTH class profile
Permitting the IDs (or groups) READ access to the newly defined class
Note: Steps 1 and 2 may not be necessary, as the class may be active and raclisted already on your
system. But issuing the commands do no harm, so we'll offer them here.
Activating and RACLISTing the SERVAUTH class
Two commands do this:
SETROPTS CLASSACT(SERVAUTH)
SETROPTS RACLIST(SERVAUTH) GENERIC(SERVAUTH)
Defining the SERVAUTH class profile
The command used to do this takes this form:
RDEFINE SERVAUTH (EZB.PORTACCESS.aaa.bbb.ccc) UACC(NONE)
Where:
! aaa is the system name on which the TCP stack resides
! bbb is the MVS JOBNAME for the started TCP stack
! ccc is the "SAF name" provided on the PORTRANGE definition in the PROFILE member
Note: It's critical to code the values for aaa, bbb and ccc correctly. They are not arbitrary values.
Recall that TCPIP will be the one who checks with RACF (or "SAF") to verify access
authority. RACF will understand what SERVAUTH profile to check based on ... well, the MVS
system on which the TCPIP stack resides who called RACF, the MVS JOBNAME of the
TCPIP started task that made the call to RACF, and the string that followed the keyword SAF
on the PORTRANGE definition in the TCPIP PROFILE member. The values matter. Code
carefully.
So to come up with the SERVAUTH class profile name to use, do the following for each MVS
image in the Sysplex that will host a WebSphere node whose ports you wish to reserve and
protect:
!
Capture the true MVS system name for the MVS image
!
Capture the true MVS JOBNAME value that is used for the TCPIP started task on that image
!
Verify the actual string used after the SAF keyword on the PORTRANGE definition
Then construct the RDEFINE SERVAUTH command and submit it.
Permitting IDs or groups READ access to the SERVAUTH class profile
The SERVAUTH profile just created had a UACC(NONE) value. That means by default
nobody has access to it. That means your WebSphere cell will fail to come up because it
will not (yet) have access to the newly-restricted ports.
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
-8-
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
To allow your WebSphere cell to use the ports you must grant WebSphere READ access to
this SERVAUTH profile. This could be done at the userid level, but there might be several
different IDs who will attempt to use the ports. It is far easier to simply grant the
WebSphere Configuration Group READ access. That will provide every ID in your
WebSphere cell access, as all server IDs in a cell are (or should) be connected to this
Config Group.
PERMIT EZB.PORTACCESS.aaa.bbb.ccc CLASS(SERVAUTH) ID(ddd) ACC(READ)
Where:
! aaa is the system name on which the TCP stack resides
! bbb is the MVS JOBNAME for the started TCP stack
! ccc is the "SAF name" provided on the PORTRANGE definition in the PROFILE member
! ddd is the cell's "Configuration Group" ID
Refreshing the RACLIST
So the changes take effect, issue:
SETROPTS RACLIST(SERVAUTH) GENERIC(SERVAUTH) REFRESH
Deleting a SERVAUTH class profile
Issue the following two commands:
RDELETE SERVAUTH (EZB.PORTACCESS.aaa.bbb.ccc)
SETROPTS RACLIST(SERVAUTH) GENERIC(SERVAUTH) REFRESH
Testing the changes
There are really two things to test for:
Test
1 Your WebSphere cell has access to the
ports and can start/operate properly
What's being validated
This is a test to make sure you didn't by accident do
something to "break" your WebSphere cell.
2 Others are prevented from using the ports This is a test to make sure the changes you've code have
set aside for WebSphere
truly taken effect. Your changes may not take effect. For
example, a minor mis-match in the "SAF name" value
between the TCP PROFILE member and the SERVAUTH
class profile name could mean that no protection is in
effect. Or a failure to RACLIST refresh RACF would
mean the created SERVAUTH profiles would not yet be in
effect.
See "Tested protection offered by SERVAUTH" on page 14 for an example of these two tests in
action.
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
-9-
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
A Real Example of Configuring Port-level Protection using SERVAUTH
The following is simply an illustration of a real-world application of the concepts provided earlier.
The WebSphere cell was the WPCELL, which is documented in the WP100653 white paper and is
operational on the WSCPLEX at the IBM Washington Systems Center.
Inventory of ports used by WebSphere cell
The "WPCELL" illustrated in the WP100653 white paper had nine servers and used some 85
ports:
MVS SYSC
MVS SYSD
WPDEMN
WPDMGR
CR
CR
WPDEMN
SR
A
CR
WPAGNTD
WPAGNTC
CR
WPNODEC
CR
WPNODED
WPSR01C
WPSR02D
CR
CR
SR
WPSR03C
CR
Cluster:
WPSR03
SR
SR
WPSR03D
CR
SR
The WPCELL documented in white paper WP100653
The ports allocated scheme used for this cell looked like this:
Daemons
SOAP
Bootstrap/ORB
ORB SSL
Discovery
Multicast
HA Mgr
SIB
SIB SSL
SIB MQ
SIB MQ SSL
JMS Direct
JMS Queued
HTTP
HTTP SSL
28502
28503
DMGR
28510
28511
28512
28513
28515
Node Agents
28520
28521
28522
28523
28524
28525
28518
28519
WPSR01
28530
28531
28532
WPSR02
28550
28551
28552
Cluster:
WPSR03
28570
28571
28572
28533
28540
28541
28542
28543
28544
28545
28538
28539
28553
28560
28561
28562
28563
28564
28565
28558
28559
28573
28580
28581
28582
28583
28584
28585
28578
28579
Notes:
! This allocation method is found in the WebSphere planning spreadsheet, which can be found at:
http://www03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/PRS1331
! A key objective of this allocation method is to have each port "type" (ORB, HTTP, etc.) end with the
same digit. That makes it easier to know what port is used for what when so many ports are used for
the cell.
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
- 10 -
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
! The dark gray boxes in the table above represent ports not used. The allocation method is not 100%
efficient. But it is effective.
! Some ports on the table are only used if you enable that function of WebSphere. For instance, the SIB
and JMS ports only come into play if you configure a "Service Integration Bus," or make use of the
integrated messaging service of WebSphere. If you don't use those functions, those ports aren't bound.
Determined PORTRANGE value to be used
A quick scan of the table above shows that the lowest port number used is 28502 (the Daemon
ORB port), and the highest port number used is 28585 (cluster JMS Queued). That's a range
of about 85 ports (28585 - 28502 = 83 ¡ 85).
Note: In truth, on 51 unique port values were used. As mentioned, the port allocation matrix has some
"holes" in it where ports aren't used. We decided not to allow those unused ports to be used by
others, so we reserved the whole range -- used and unused ports alike -- for WebSphere.
To make things even more simple, we planned to block off a round-number 100 ports on the
PORTRANGE definition:
PORTRANGE
28500 100 TCP * SAF WPCELL
;
; SET-ASIDE OF PORTS FOR WPCELL
The effect was to block off ports 28500 through 28599 for the WPCELL.
Understood the implications of our multi-system cell
The WPCELL spanned both SYSC and SYSD on the WSCPLEX. This had a direct impact on
the TCP PROFILE members to be updated, and the format of the SERVAUTH class profiles to
be added:
MVS SYSC
Daemon
MVS SYSD
DMGR
Node
Daemon
AppServer
Node
AppServer
Node
SYSC TCP/IP
SYSD TCP/IP
SYS1.TCPPARMS(PROFELXC)
SYS1.TCPPARMS(PROFELXD)
PORTRANGE
28500 100 TCP * SAF WPCELL
;
PORTRANGE
28500 100 TCP * SAF WPCELL
;
EZB.PORTACCESS.SYSC.TCPIPC.WPCELL
RACF
EZB.PORTACCESS.SYSD.TCPIPD.WPCELL
Planning for definitions with WPCELL spanning two MVS images
Notes:
! We've already noted that the WPCELL didn't use all the ports in the 28500-28599 range. In addition,
the ports that were used were not used equally on both MVS systems. Some ports were used on both,
but many were not. We made no attempt to define our PORTRANGE definitions different on each MVS
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
- 11 -
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
image. We planned to block off the full 100 port range on both MVS images. This was done for
simplicity. That meant the PORTRANGE definition was in fact identical for both systems.
! Two MVS images meant two TCP stacks, which meant two PROFILE members in SYS1.TCPPARMS.
The naming convention for these systems happened to be PROFELXC and PROFELXD. As just noted,
the PORTRANGE definition in each was identical.
! Because two MVS images were in play, it meant two different RACF SERVAUTH definitions. Both ended
with the WPCELL value, which is what tied it to the PORTRANGE definition in the PROFILE member.
What was different was the "system name" field and the "TCP JOBNAME" field. You can see from the
illustration above how the two SERVAUTH definitions are made unique with different system names
(SYSC and SYSD) and different TCP JOBNAME values (TCPIPC and TCPIPD).
Coded PORTRANGE statement in each TCP PROFILE member and activated with VARY
As just noted, there were two TCP PROFILE members to update:
System
Data set and member
System SYSC
SYS1.TCPPARMS(PROFELXC)
System SYSD
SYS1.TCPPARMS(PROFELXD)
Updated PROFILE members
Each was coded with the exact same definition:
:
ENDAUTOLOG
Definitions added
;
PORTRANGE
28500 100 TCP * SAF WPCELL
; SET-ASIDE OF PORTS FOR WPCELL
;
PORT
; Values from RFC 1010, "Assigned numbers"
Existing
definitions in
20 TCP OMVS NOAUTOLOG
; FTP DEFAULT DATA
PORT
PROFILE member
21 TCP FTPSERVE
; FTP SERVER
:
New PORTRANGE definition coded into both PROFELXC and PROFELXD
Note: Some of the ports were used on one MVS image but not the other. It would have been
possible to code the PORTRANGE for each MVS image to reflect this. But it would have
meant added complexity and the risk of making a mistake. Better, we thought, to block out
the same range on both MVS images.
Varied the PROFILE members active
Then we varied the PROFILE members active:
System
VARY command issued
System SYSC
VARY TCPIP,,O,SYS1.TCPPARMS(PROFELXC)
System SYSD
VARY TCPIP,,O,SYS1.TCPPARMS(PROFELXD)
The system messages in response to the VARY command looked like this (for SYSD, a very
similar response was seen for SYSC):
VARY TCPIP,,O,SYS1.TCPPARMS(PROFELXD)
EZZ0060I PROCESSING COMMAND: VARY TCPIP,,O,SYS1.TCPPARMS(PROFELXD)
EZZ0300I OPENED OBEYFILE FILE 'SYS1.TCPPARMS(PROFELXD)'
EZZ0309I PROFILE PROCESSING BEGINNING FOR 'SYS1.TCPPARMS(PROFELXD)'
EZZ0717I KEEPALIVEOPTIONS STATEMENT ON LINE 1 WILL BE RETIRED IN A FUTURE RELEASE
EZZ0655I PORT
20 TCP OMVS IS ALREADY RESERVED
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
- 12 -
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0655I
EZZ0327I
EZZ0327I
EZZ0327I
EZZ0327I
EZZ0322I
EZZ0322I
EZZ0323I
EZZ0313I
RELEASE
EZZ0781I
EZZ0353I
EZZ0353I
EZZ0316I
Notes:
PORT
21 TCP FTPSERVE IS ALREADY RESERVED
PORT
23 TCP TCPIPD IS ALREADY RESERVED
PORT
25 TCP SMTP IS ALREADY RESERVED
PORT 446 TCP OMVS IS ALREADY RESERVED
PORT 520 UDP OMPRSYSD IS ALREADY RESERVED
PORT 1211 TCP OMVS IS ALREADY RESERVED
PORT 1211 UDP OMVS IS ALREADY RESERVED
PORT 1212 TCP OMVS IS ALREADY RESERVED
PORT 1213 TCP OMVS IS ALREADY RESERVED
PORT 1214 TCP OMVS IS ALREADY RESERVED
PORT 1220 TCP OMVS IS ALREADY RESERVED
PORT 1221 TCP OMVS IS ALREADY RESERVED
PORT 1223 TCP OMVS IS ALREADY RESERVED
PORT 5023 TCP OMVS IS ALREADY RESERVED
DEVICE NAME GIG0C ON LINE 53 IS ALREADY DEFINED
LINK NAME GIG1 ON LINE 54 IS ALREADY DEFINED
DEVICE NAME GIG0E ON LINE 58 IS ALREADY DEFINED
LINK NAME GIG2 ON LINE 59 IS ALREADY DEFINED
VIPABACKUP RANK VALUE 300 NOT VALID ON LINE 64, 1 USED
VIPABACKUP RANK VALUE 300 NOT VALID ON LINE 65, 1 USED
GATEWAY STATEMENT ON LINE 74 HAD NO ENTRIES
VARSUBNETTING OPTION IN IPCONFIG STATEMENT ON LINE 80 IS
NOT SUPPORTED IN THIS
VARIABLE SUBNETTING SUPPORT
DEVICE GIG0C ON LINE 170 IS
DEVICE GIG0E ON LINE 171 IS
PROFILE PROCESSING COMPLETE
IS ALWAYS ENABLED IN TCP/IP
ALREADY STARTED
ALREADY STARTED
FOR FILE 'SYS1.TCPPARMS(PROFELXD)
! Notice there's no positive confirmation of the new PORTRANGE definitions. We verified
they "took" by issuing the NETSTAT PORTLIST command (described next).
! TCP issues a lot of messages indicating definitions are already active. This happens
when a PROFILE member is activated after a new definition is added. All the old
definitions are processed again, and TCP flags the old definitions with "Already
Reserved" statements.
! The WSCPLEX system at the Washington Systems Center is a test system. Our
PROFILE members are not the most clean and orderly. Some of the messages shown
above would go away if we cleaned up the PROFILE members. ☺
Verified definitions with NETSTAT PORTLIST
Next, we verified the PORTRANGE was in effect by issuing the NETSTAT PORTLIST
command on each system. The output (for SYSC this time) looked like this:
EZZ2350I MVS TCP/IP NETSTAT CS V1R7
TCPIP Name: TCPIPC
EZZ2795I Port# Prot User
Flags
Range
IP Address
EZZ2796I ----- ---- --------------------EZZ2797I 00020 TCP OMVS
D
EZZ2797I 00021 TCP FTPSERVE DA
EZZ2797I 00023 TCP TCPIPC
DA
:
: (other ports removed from example to save space in the document)
:
EZZ2797I 05022 TCP OMVS
DA
EZZ2797I 05655 TCP *
DA
EZZ2797I 28500 TCP *
DAR
28500-28599
EZZ2797I 28501 TCP *
DAR
28500-28599
:
: (port range 28502 - 28596 removed from example to save space in document)
:
EZZ2797I 28597 TCP *
DAR
28500-28599
EZZ2797I 28598 TCP *
DAR
28500-28599
EZZ2797I 28599 TCP *
DAR
28500-28599
EZZ2797I 00520 UDP OMPRSYSC D
EZZ2797I 01211 UDP OMVS
DA
***
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
- 13 -
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
Created SERVAUTH class profiles and granted config group READ access
With TCP/IP on both SYSC and SYSD enabled to perform SAF authorization checking for port
access, it was time to code the SERVAUTH definitions into RACF.
CLASSACT and RACLIST
A little preliminary work:
SETROPTS CLASSACT(SERVAUTH)
SETROPTS RACLIST(SERVAUTH) GENERIC(SERVAUTH)
SERVAUTH for SYSC, config group access and refresh
This involved three steps:
1. Created SERVAUTH profile
RDEFINE SERVAUTH (EZB.PORTACCESS.SYSC.TCPIPC.WPCELL) UACC(NONE)
We received the expected response from RACF:
ICH10006I RACLISTED PROFILES FOR SERVAUTH WILL NOT REFLECT THE
ADDITION(S) UNTIL A SETROPTS REFRESH IS ISSUED.
2. Granted WPCFG (the config group) READ access:
PERMIT EZB.PORTACCESS.SYSC.TCPIPC.WPCELL CLASS(SERVAUTH) ID(WPCFG) ACC(READ)
3. Issued refresh
SETROPTS RACLIST(SERVAUTH) GENERIC(SERVAUTH) REFRESH
The profile for SYSC was in place.
SERVAUTH for SYSD, config group access and refresh
The exact same steps were followed as for SYSC, except the profile was slightly different:
RDEFINE SERVAUTH (EZB.PORTACCESS.SYSD.TCPIPD.WPCELL) UACC(NONE)
Tested protection offered by SERVAUTH
Two tests were performed:
1. Tested to insure the WPCELL could start
2. Tested to insure nobody else could use ports
Test: WPCELL access permitted
This simply involved starting every server in the cell -- DMGR, Daemons, Node Agents and
servers. All started properly. All TCP ports for the cell were bound without restriction.
Test: non-WPCELL access prohibited
This involved attempting to start the IBM HTTP Server using a port within the range
reserved for the WPCELL. The user identity of the HTTP Server address space was not
connected to the WPCFG group, so it did not have READ access to the SERVAUTH profile.
In other words, if the SERVAUTH protection was working, the HTTP Server should fail to
start.
??? Why the HTTP Server? Because it's a very simple single-address space server. Anything
would have worked -- the key was that it tried to use a port in the PORTRANGE for the
WPCELL, and it ran under a user identity not connected to the WPCFG group.
We chose port 28500 as the port for the HTTP Server. That was the first port in the
PORTRANGE specified in the TCP PROFILE. It's also a port that wasn't otherwise used by
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
- 14 -
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
the WPCELL. If the HTTP Server was to fail initializing, we wanted it to fail because of
SERVAUTH restrictions, not something more basic like a conflict with a port already bound.
The test was performed on both SYSC and SYSD. Two different SERVAUTH profiles were
created, and it was important to test that both were invoked.
The test succeeded on both SYSC and SYSD -- the HTTP Server failed to start. Here's the
result from SYSC:
S WPWEB
IRR812I PROFILE WPWEB.* (G) IN THE STARTED CLASS WAS USED
TO START WPWEB WITH JOBNAME WPWEB.
$HASP100 WPWEB
ON STCINRDR
IEF695I START WPWEB
WITH JOBNAME WPWEB
IS ASSIGNED TO USER
WEBSERV , GROUP SYS1 1
$HASP373 WPWEB
STARTED
IMW3534I PID: 84083496 SERVER STARTING
ICH408I USER(WEBSERV 2) GROUP(SYS1
) NAME(WEB SERVER
)
EZB.PORTACCESS.SYSC.TCPIPC.WPCELL CL(SERVAUTH) 3
INSUFFICIENT ACCESS AUTHORITY
ACCESS INTENT(READ
) ACCESS ALLOWED(NONE
) 4
$HASP395 WPWEB
ENDED 5
Notes:
1. The identity under which the started HTTP Server ran was WEBSERV, which was connected to
group SYS1 but not connected to WPCFG. Recall that WPCFG was the WPCELL "Config Group,"
and was the ID that was granted READ access to the SERVAUTH profiles.
2. An ICH408I message was issued. This meant that RACF detected an access attempt for which
the ID attempting access did not have permission. In this case the user was WEBSERV, the ID
under which the HTTP Server was running.
3. This indicated that the attempt made by the WEBSERV ID was access to the SERVAUTH profile with
name EZB.PORTACCESS.SYSC.TCPIPC.WPCELL. This was TCP responding to the
PORTRANGE definition with the keyword SAF and checking with RACF.
4. The access intent by the WEBSERV ID was READ, but the access intent that ID had was NONE.
Therefore, the access was rejected.
5. Because the HTTP Server could not bind to its defined port, initialization failed.
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
- 15 -
Section: Main
Version Date: Tuesday, November 29, 2005
WP100673 - Using SERVAUTH to Protect TCP Port Usage
Document Change History
Check the date in the footer of the document for the version of the document.
November 26, 2005
Original document.
November 29, 2005
Added the WP100673 number to the document and re-published.
Document Change History
End of WP100673
© 2005, IBM Americas Advanced Technical Support
Washington Systems Center, Gaithersburg, MD
- 16 -
Section: Main
Version Date: Tuesday, November 29, 2005