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.

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- through 8-character name of the job that is required to use the port.
• An asterisk (*) wildcard value. 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- through 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 UDP, only one job name can be associated with a particular port. For TCP, the same port can be reserved multiple times for different job names. This can be useful if you have different servers with different job names that need access to the same port. For PORT UNRSV statements, both TCP and UDP can have multiple statements with different job names.

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

SHAREPORT

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

EZB.PORTACCESS.sysname.tcpname.resname

where

• 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 SMC. For more information about enabling SMC, see the description of the GLOBALCONFIG SMCR and SMCD parameters. For more information about AUTOSMC monitoring function, see Use the AUTOSMC monitoring function in z/OS Communications Server: IP Configuration Guide.

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.

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:

  PORT
      514 UDP OMVS         ; syslogd Server

  This port is required for syslogd to accept log data from remote syslogd servers.
  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:
  1. Delete the existing port reservation by using the VARY TCPIP,,OBEYFILE command with a data set that contains a DELETE PORT statement.
  2. 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.
  3. Stop and restart the servers that use the port.

Related topics

• AUTOLOG statement
• DELETE statement
• GLOBALCONFIG statement
• PORTRANGE statement
• TELNETPARMS statements