PORT statement
Use the PORT statement to reserve a port for one or more specified job names or to control application access to unreserved ports.
Syntax
Parameters
- num
- The number of the port to be reserved. The same port number can
appear in more than one PORT statement with different users or more
than once in the same PORT statement. This port cannot appear in a
range specified by the PORTRANGE statement. If a PORTRANGE statement
including this port number is specified prior to this statement, this
port is ignored. If the PORTRANGE statement follows this statement,
the PORTRANGE statement is ignored. An error message is generated
in either case. num is a value in the range
1 - 65535.
Requirement: For z/OS UNIX applications that are invoked by INETD, ensure that the port number defined for the application in the /etc/services file is the same as the port number reserved for the application on the PORT statement.
- UNRSV
- This value indicates any unreserved port (any port number that
is in the range 1 - 65535 that has not been reserved by a PORT or
PORTRANGE statement).
Use PORT UNRSV statements to indicate which applications or users are permitted to access application-specified unreserved ports. PORT UNRSV statements control access to all unreserved ports in the range 1 - 65535 unless RESTRICTLOWPORTS is configured; however, when RESTRICTLOWPORTS is configured, PORT UNRSV statements control access to unreserved ports only above port 1023. For UDP, access control is applied when an application issues a bind to a particular port number to establish a local port. For TCP, access control is applied depending on the value of the WHENBIND or WHENLISTEN parameter.
If neither DENY nor the SAF keyword is specified, an application that matches the protocol and specified job name [the job name can be an asterisk (* )] on a PORT UNRSV statement can access unreserved ports. If DENY is specified, all applications are denied access to unreserved ports for the specified protocol. If the SAF keyword is specified, applications that match the PORT UNRSV statement must also have user access to the SAF SERVAUTH resource which is indicated by the SAF keyword, to be permitted to access an unreserved port.
Results:- When no PORT UNRSV statements are configured for the socket protocol that is being used, all applications are allowed access to the unreserved ports unless prevented by TCPCONFIG or UDPCONFIG RESTRICTLOWPORTS or by GLOBALCONFIG EXPLICITBINDPORTRANGE. This is the default.
- When TCPCONFIG or UDPCONFIG RESTRICTLOWPORTS is configured for the access protocol that is being used, PORT UNRSV access control applies only to unreserved ports above port 1023.
- If any PORT UNRSV statements are configured for a protocol, access is determined by the PORT UNRSV statement whose specified job name most closely matches the application's job name. If the application's jobname does not match any of the PORT UNRSV statements, the application's access to unreserved ports is denied for that protocol.
- PORT UNRSV statements control access to nonzero, unreserved ports that are specified on explicit binds. Access to unreserved ports that are assigned by the stack is not affected.
Guideline: In a Common INET (CINET) environment with multiple stacks and no established stack affinity, an explicit bind to port 0 is converted to a bind to a specific port in the CINET range. If you have not reserved the ports in your CINET range for jobname OMVS, the explicit bind to port 0 is treated as an explicit bind to an unreserved port.
- RESERVED
- Indicates the port is not available for use by any user. Use RESERVED to lock certain ports. This is optional and valid for TCP or UDP protocols.
- jobname
- Specifies the MVS™ job
name that can use the specified port or
any unreserved port in the case of a PORT UNRSV
statement. You can specify the jobname value
as one of the following values:
- The 1 - 8 character name of the job that is required to use the port.
- A 1 - 8 character value including wildcard characters. The following wildcard
characters are supported:
- An asterisk (*) can be used in any position in the value to indicate zero or more unspecified characters.
- A question mark (?) can be used in any position in the value to indicate a single unspecified character.
- An asterisk (*) wildcard character. Specify an asterisk as the jobname value to reserve a port without specifying a particular job name. You can use an asterisk if you do not know the exact job name or if you want to allow different applications to serially bind to the port.
- A 1 - 7 character prefix that is followed by an asterisk wildcard value. This specification enables all job names that match the prefix to access the port.
For multiple TCP reservations for the same port, or for multiple PORT UNRSV statements for the same protocol, the TCP/IP stack searches these PORT statements for the closest match (if any) to the application's job name. If you specified the job name using a wildcard on more than one of these statements, the TCP/IP stack matches the application job name to a PORT statement jobname value using the most specific value first and the least specific value (or value *, if it was specified) last.
Restriction: To reserve a port that is to be monitored by AUTOLOG, the jobname name must exactly match (no wildcards) the jobname name on the AUTOLOG statement.
The environment in which the application is run determines the job name to be associated with a particular client or server application.
The following list explains how to determine the jobname value given the environment in which the application is run:
- Applications run from batch use the batch job name.
- Applications started from the MVS operator console use the started procedure name as the job name.
- Applications run from a TSO user ID use the TSO user ID as the job name.
- Applications run from the z/OS shell normally have a job name that is the logged on user ID plus a one-character suffix.
- Authorized users can run applications from the z/OS shell and use the _BPX_JOBNAME environment variable to set the job name. In this case, the value specified for the environment variable is the job name.
- Use the name of the started JCL procedure for the UNIX System Services kernel address space to enable applications (except for applications using the Pascal API) to bind to the port. This name is typically OMVS unless a different name is explicitly specified in the STARTUP_PROC parameter of the BPXPRMxx parmlib member.
- z/OS UNIX applications started by INETD use the jobname of the INETD server.
- Use the name of the VTAM® started task for the UDP ports
that are to be used for Enterprise Extender (EE) network connections.Restriction: The VTAM job name cannot include a wildcard character when it reserves EE UDP ports.
Reserved Port Options:
- NOAUTOLOG
- Tells the TCP/IP address space not to restart the server if it was stopped previously. Otherwise, the default is to restart the server if it was stopped previously. If the application associated with the job name is an AUTOLOG started procedure, and the port is inactive (for TCP connections, the procedure must have a socket open to that port in the LISTEN state; for UDP connections, the procedure must have a socket open to that port), then AUTOLOG assumes that the procedure is hung; it cancels and restarts it every five minutes. Use NOAUTOLOG to prevent this from occurring. See AUTOLOG statement for more information.
- DELAYACKS | NODELAYACKS
-
- DELAYACKS
- Delays transmission of acknowledgments when a packet is received
with the PUSH bit on in the TCP header. The DELAYACKS parameter on
the PORT statement affects only connections that use this port. This
is the default, but the behavior can be overridden by specifying
the NODELAYACKS parameter on the TCP/IP stack TCPCONFIG profile statement,
or on any of the following statements used to configure the route
used by the TCP connection:
- The TCP/IP stack BEGINROUTES profile statement
- The Policy Agent RouteTable statement
- The OMPROUTE configuration statements
- NODELAYACKS
- Specifies that an acknowledgment is returned immediately when
a packet is received with the PUSH bit on in the TCP header. The
NODELAYACKS parameter on the PORT statement affects only connections
that use this port. Specifying NODELAYACKS on the PORT statement
overrides the specification of the DELAYACKS parameter on the TCP/IP
stack TCPCONFIG profile statement or on any of the following statements
used to configure the route used by the TCP connection:
- The TCP/IP stack BEGINROUTES profile statement
- The Policy Agent RouteTable statement
- The OMPROUTE configuration statements
- Required when reserving a port to be shared across multiple listeners on the same interface.
When SHAREPORT is specified, TCP/IP allows multiple listeners to listen on the same combination of
port and IP address.
As incoming client connections arrive for this port and IP address, TCP/IP distributes them across the listeners. Specification of this keyword causes incoming connection requests for the port to be distributed among the listeners using a weighted round-robin distribution method based on the servers' accept Efficiency Fractions (SEFs) of the listeners sharing the port. The SEF is a measure, calculated at intervals of approximately one minute, of the efficiency of the server application in accepting new connection requests and managing its backlog queue. Alternatively, SHAREPORTWLM can be coded instead; SHAREPORTWLM changes the connection distribution algorithm.
If the same port is reserved for multiple job names, SHAREPORT or SHAREPORTWLM needs to be specified on only one instance of the port reservation. SHAREPORT and SHAREPORTWLM are valid only for TCP ports. The last setting of either SHAREPORT or SHAREPORTWLM is used for all TCP/IP servers that use that port.
- SHAREPORTWLM
- Required when reserving a port to be shared across multiple listeners
on the same interface. When SHAREPORTWLM is specified, TCP/IP allows
multiple listeners to listen on the same combination of port and IP
address.
The SHAREPORTWLM option can be used instead of SHAREPORT. Like SHAREPORT, SHAREPORTWLM causes incoming connections to be distributed among a set of TCP listeners; however, unlike SHAREPORT, the listener selection is based on WLM server-specific recommendations, modified by the SEF values for each listener. WLM server-specific recommendations are acquired at intervals of approximately 1 minute from the Work Load Manager and reflect the listener's capacity to handle additional work.
If the same port is reserved for multiple job names, SHAREPORT or SHAREPORTWLM needs to be specified on only one instance of the port reservation. SHAREPORT and SHAREPORTWLM are valid only for TCP ports. The last setting of either SHAREPORT or SHAREPORTWLM is used for all TCP/IP servers that use that port.
Result: zAAP and zIIP processor capacity is automatically included when the SHAREPORTWLM parameter is specified and all systems in the sysplex are V1R9 or later.
- BIND ipaddr
- Associates a job name
with the IP address, ipaddr. When a job
with the designated name binds to the IPv4 INADDR_ANY address, or
to the IPv6 unspecified address (in6addr_any), the bind is intercepted
and converted to a bind to the IP address specified by ipaddr.
Subsequent bind processing occurs as though the server instance had
originally issued the bind to the IP address ipaddr.
You can specify either an IPv4 address (in dotted decimal notation) or an IPv6 address (in hexadecimal notation). IPv4-mapped IPv6 addresses and IPv6 addresses with the reserved prefix ::/96 are not supported.
Rule: The BIND ipaddr parameter does not apply to the PORTRANGE statement.
Guidelines:- When you are using the BIND parameter with IPv6 addresses, you should use only manually configured addresses, because autoconfigured addresses might change when the stack is recycled.
- If the IP address specified on the BIND parameter is also specified in a VIPARANGE statement subnet, then VIPARANGE security verification might occur to determine whether an application can create the dynamic VIPA (DVIPA). For information about security profiles for binding to DVIPAs in the VIPARANGE statement, see z/OS Communications Server: IP Configuration Guide.
- SAF resname
- Indicates that the port is reserved for users that have READ access
to the RACF® resource
whereEZB.PORTACCESS.sysname.tcpname.resname
- EZB.PORTACCESS is constant
- sysname is the value of the MVS &SYSNAME. system symbol
- tcpname is the name of the procedure used to start the TCP stack
- resname is the 1-8 character value following the SAF keyword
Restriction: You can not specify a 1-character value of 0 (zero) for resname.If the SAF keyword is specified and a user tries to bind to the port and is not allowed access to the resource, the BIND socket call fails.
Tip: The SAF keyword is ignored when VTAM opens a UDP port for Enterprise Extender (EE) network connections. However, it can still be used to prevent other address spaces that are using the same name as the VTAM started task from opening the port.
This is optional and valid for TCP or UDP protocols.
If the jobname parameter is specified as an asterisk (*), any user ID that is RACF-permitted to the resource specified by the resname value is allowed to bind to the port specified by the value; APF or superuser authority is not required.
This permits multiple users access to the protected port. However, the stack allows only one user to actually BIND to the port at a time. Use SHAREPORT or SHAREPORTWLM to override this behavior for TCP ports.
Guideline: If an application binds to an IP address that is also specified in a VIPARANGE statement subnet, then additional security verification might occur to determine whether the application can create the dynamic VIPA (DVIPA). This additional verification might occur whether the application explicitly binds to the DVIPA address or whether the application binds to the unspecified address and is converted to the DVIPA address using the BIND parameter. For information about security profiles for binding to DVIPAs in the VIPARANGE statement, see z/OS Communications Server: IP Configuration Guide.
- SMC | NOSMC
- Configuration of these parameters overrides configuration of the
AUTOSMC monitoring function for the servers that are associated with
the reserved port. The AUTOSMC monitoring function is
the default option for the GLOBALCONFIG SMCGLOBAL parameter. However,
the default AUTOSMC monitoring is activated only when you enable or
disable SMC support
on the GLOBALCONFIG profile statement.
- To enable or disable Shared Memory Communications over Remote Direct Memory Access (SMC-R) support, specify the SMCR or NOSMCR parameters on the GLOBALCONFIG profile statement.
- To enable or disable Shared Memory Communications - Direct Memory Access (SMC-D) support, specify the SMCD or NOSMCD parameters on the GLOBALCONFIG profile statement.
- NOSMC
- Indicates that Shared Memory Communications (SMC) is not permitted for inbound TCP connections that use this port. This setting overrides the SMCGLOBAL AUTOSMC parameter on the GLOBALCONFIG profile statement and ensures that inbound TCP connections to this port do not use SMC. NOSMC is valid only for TCP ports.
- SMC
- Indicates that the stack attempts to use SMC for inbound TCP connections that use this port. This parameter is required only when you use the SMCGLOBAL AUTOSMC parameter on the GLOBALCONFIG profile statement and you want to ensure that the stack attempts to use SMC for inbound TCP connections. SMC is valid only for TCP ports.
Unreserved Port Options:
- SAF resname
- Indicates that binding to, or listening on, any unreserved port is restricted to users that are permitted to the specified SAF SERVAUTH resource. See the description of the SAF parameter for more information.
- DENY
- DENY indicates that port access should be denied. DENY can be
specified only for unreserved ports (on the PORT UNRSV statement)
and only when the specified jobname is an asterisk (*).
A PORT UNRSV protocol * DENY statement is needed only if no other PORT UNRSV statements are configured for the specified protocol and you want to prevent all access to unreserved ports using that protocol.
- WHENLISTEN
- WHENLISTEN indicates that port access control is targeted to TCP
applications that are acting as servers (that is, applications able
to accept incoming client TCP connections) that issue an explicit
bind to a user-specified unreserved port. Permission to use the unreserved
port is determined when a TCP listen is issued. If a listen is not
issued, no access control check is made. The WHENLISTEN parameter
is not available for the UDP protocol, and it is the default for the
TCP protocol.
Rule: Every PORT UNRSV statement for the TCP protocol must use the same access control option. You cannot specify , or default to, the WHENLISTEN parameter on some statements and specify the WHENBIND parameter on other statements.
- WHENBIND
- WHENBIND indicates that permission to use an unreserved port is
determined when an explicit bind to a specific local port is issued.
This is the default, and only option, for the UDP protocol, and it
can affect UDP applications that bind to a specific local port. If
the WHENBIND parameter is specified for the TCP protocol, it can
affect TCP client applications that bind to a specific local port
for outbound connections.
Rule: Every PORT UNRSV statement for the TCP protocol must specify, or default to, the same access control option. You cannot specify the WHENLISTEN parameter on some statements and specify the WHENBIND parameter on other statements.
Steps for modifying
To change a parameter value, you must delete the existing PORT statement by using the DELETE PORT statement, then redefine with the new PORT statement.
Examples
The following example was used for test configuration and is provided here for illustration only. The sample profile, SEZAINST(SAMPPROF), contains the most current assignments.
PORT
7 UDP MISCSERV ; Miscellaneous Server - echo
7 TCP MISCSERV ; Miscellaneous Server - echo
9 UDP MISCSERV ; Miscellaneous Server - discard
9 TCP MISCSERV ; Miscellaneous Server - discard
19 UDP MISCSERV ; Miscellaneous Server - chargen
19 TCP MISCSERV ; Miscellaneous Server - chargen
20 TCP * NOAUTOLOG ; FTP Server
; 20 TCP * NOAUTOLOG SAF FTPDATA ; FTP Server
21 TCP FTPD1 ; FTP Server
23 TCP TN3270 ; Telnet 3270 Server
; 23 TCP INETD1 BIND 9.67.113.3 ; z/OS UNIX Telnet server
111 TCP PORTMAP ; Portmap Server (SUN 3.9)
111 UDP PORTMAP ; Portmap Server (SUN 3.9)
; 111 TCP PORTMAP1 ; Unix Portmap Server (SUN 4.0)
; 111 UDP PORTMAP1 ; Unix Portmap Server (SUN 4.0)
123 UDP SNTPD ; Simple Network Time Protocol Server
135 UDP LLBD ; NCS Location Broker
161 UDP OSNMPD ; SNMP Agent
389 TCP LDAPSRV ; LDAP Server
443 TCP HTTPS ; http protocol over TLS/SSL
443 UDP HTTPS ; http protocol over TLS/SSL
; 500 UDP IKED ; CS IKE daemon
512 TCP RXSERVE ; Remote Execution Server
514 TCP RXSERVE ; Remote Execution Server
; 512 TCP * SAF OREXECD ; z/OS UNIX Remote Execution Server
; 514 TCP * SAF ORSHELLD ; z/OS UNIX Remote Shell Server
; 515 TCP LPSERVE ; LPD Server
; 515 TCP AOPLPD ; Infoprint LPD Server
520 UDP OMPROUTE ; OMPROUTE Server (IPv4 RIP)
521 UDP OMPROUTE ; OMPROUTE Server (IPv6 RIP)
750 TCP MVSKERB ; Kerberos
750 UDP MVSKERB ; Kerberos
751 TCP ADM@SRV ; Kerberos Admin Server
751 UDP ADM@SRV ; Kerberos Admin Server
; 1700 TCP PAGENT NOAUTOLOG ; Policy Agent pagentQosListener port
; 1701 TCP PAGENT NOAUTOLOG ; Policy Agent pagentQosCollector port
3000 TCP CICSTCP ; CICS Socket
3389 TCP MSYSLDAP ; LDAP Server for Msys
; 4159 TCP NSSD ; CS NSS daemon
; 4500 UDP IKED ; CS IKE daemon
;16310 TCP PAGENT NOAUTOLOG ; Policy Agent server listener port
;
The following examples control application access to unreserved ports:
- To deny all TCP explicit binds to an unreserved port, add the
following statement to your profile:
PORT UNRSV TCP * DENY WHENBIND
- To allow TCP explicit binds to an unreserved port but deny all
TCP listens on an unreserved port, add the following
statement to your profile:
PORT UNRSV TCP * DENY WHENLISTEN
- To deny all TCP listens on an unreserved port, except for applications
that match jobname value
ABC*, add the following statement to your profile:
PORT UNRSV TCP ABC* WHENLISTEN
Guideline: If the ports that applications ABC* are accessing are predictable, you should use PORT reservation statements for those specific ports instead of using the PORT UNRSV statement.
- To deny all TCP listens on an unreserved port, except for application
MYAPP1 and all users permitted to
EZB.PORTACCESS.sysname.tcpname.GENERIC,
add the following statements to your profile:
PORT UNRSV TCP MYAPP1 PORT UNRSV TCP * SAF GENERIC
- To deny all UDP explicit binds to an unreserved port, except for
users permitted to EZB.PORTACCESS.sysname.tcpname.GENERIC,
add the following statement to your profile:
PORT UNRSV UDP * SAF GENERIC
Usage notes
- If there are no PORT UNRSV statements configured for this stack, any user can use a port that is not reserved in this list or that is not reserved with the PORTRANGE statement. If you have TCP/IP hosts in your network that use ports in the range 1 - 1023 for privileged applications, you should reserve them with this statement, the PORTRANGE statement, or the RESTRICTLOWPORTS parameter on the TCPCONFIG or UDPCONFIG statements.
- If an application attempts to access a specific port by explicitly
binding for UDP, by explicitly binding, or listening for TCP, and
no PORT or PORTRANGE statement is found that matches that port and
protocol (that is, the port is unreserved for that protocol), then
a check is made for PORT UNRSV statements. The following list shows
the possible results:
- If there are no PORT UNRSV statements for that protocol, the access is allowed.
- If there are any PORT UNRSV statements for the protocol, a search
is made for the most specific match to the application's job name.
- If a match is found, the access is allowed unless the closest matching PORT UNRSV statement contains the DENY keyword, or if it contains the SAF keyword and the user is not permitted to the specified SAF resource.
- If no matching PORT UNRSV statement is found, the access is denied.
- For z/OS UNIX applications, you can reserve a port by specifying the job name of the application or you can use the name of the started JCL procedure for the z/OS UNIX kernel address space to enable any application (except applications using the Pascal API) to bind to the port. This name is typically OMVS unless a different name is explicitly specified in the STARTUP_PROC parameter in the BPXPRMxx parmlib member. See z/OS MVS Initialization and Tuning Reference for more details about the STARTUP_PROC parameter.
- For syslogd, you must include the following PORT statement:
This port is required for syslogd to accept log data from remote syslogd servers.PORT 514 UDP OMVS ; syslogd Server
Guideline: Instead of OMVS, you can also use the job name of the syslog daemon on this port reservation statement. If your syslog daemon's job name is SYSLOGD1, you can specify:PORT 514 UDP SYSLOGD1
- If you want SNMP OSA Management support, see z/OS Communications Server: IP Configuration Guide for more information about the PORT statement.
- The NOSMC option is enforced during TCP bind() processing. To
allow servers that bind to a port that is configured with the NOSMC
option to use SMC communications, you need to perform the following
steps:
- Delete the existing port reservation by using the VARY TCPIP,,OBEYFILE command with a data set that contains a DELETE PORT statement.
- Create a reservation for the port by using the VARY TCPIP,,OBEYFILE command with a data set that contains a PORT statement without the NOSMC parameter.
- Stop and restart the servers that use the port.