Add TCP/IP Port Restriction (ADDTCPPORT)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Add TCP/IP Port Restriction (ADDTCPPORT) command is used to restrict a port or range of ports in the TCP/IP configuration to a particular user profile. A port can be restricted for use by multiple user profiles. The addition of the user profile takes effect immediately. Any user profiles currently using a port that will not have access to that port after the use of this command are allowed to finish processing.

The default authorization for TCP/IP ports is to allow any user profile access to any port. If it is unnecessary to restrict a port to a user profile or a group of user profiles, the system administrator does not need to use this command.

Once an application running under a user profile has obtained the use of a restricted port, TCP/IP does not prohibit that application from passing its rights to another job that may be running under another user profile. The new user profile for the port is not checked against the list of user profiles having exclusive rights to that port. That is because the allocation of the port occurred under the user profile that had exclusive rights to that port.

The check for restricted use of the port occurs only on the BIND operation to the port. If other user profiles are currently using a port and an administrator wants to restrict a port or range of ports, the administrator may need to end all current TCP connections or user datagram protocol (UDP) sockets using that port. To do this, enter NETSTAT, select option 3, then select all of the connections or listening sockets that are using the port that you want to restrict. Enter an option 4 (ENDTCPCNN) for each.

There are two independent sets of ports. One set is for TCP processing and the other is for UDP processing. They are completely independent sets of ports and have no relationship to one another.

Restrictions:

You must have input/output system configuration (*IOSYSCFG) special authority to run this command.

Top

Parameters

Keyword	Description	Choices	Notes
PORT	Range of port values	Element list	Required, Positional 1
	Element 1: Lower value	1-65535
	Element 2: Upper value	1-65535, *ONLY
PROTOCOL	Protocol	UDP, TCP	Required, Positional 2
USRPRF	User profile	Character value	Required, Positional 3

Top

Range of port values (PORT)

Specifies the port number or range of port numbers identifying the port or ports that are being restricted. Valid values range from 1 through 65535. However, some of the ports in the range 1 through 1023 are used by system-supplied TCP/IP applications. If the user specifies one of these ports, it can affect the operation of those applications. See the assigned numbers RFC for the definition of port numbers currently used by TCP/IP applications.

This is a required parameter.

Element 1: Lower value

1-65535: Specify the port value or the lower port value in a range that you want restricted.

Element 2: Upper value

*ONLY: The port value specified in the lower port value is the only port value that is restricted.
1-65535: Specify the upper port value in a range that you want restricted.

Top

Protocol (PROTOCOL)

Specifies the transport protocol associated with the port or range of ports being restricted. Each transport protocol has its own distinct set of ports in the range of 1 to 65535.

This is a required parameter.

*UDP: The port is a User Datagram Protocol (UDP) transport protocol port.
*TCP: The port is a Transmission Control Protocol (TCP) transport protocol port.

Top

User profile (USRPRF)

Specifies the user profile to which the port or range of ports is being restricted. Only jobs running under this profile or group profile may use the port or range of ports specified.

A user profile that is used as a group profile may be specified in the user profile field of this command. If users have a group profile specified in their user profile and that group profile was specified for a particular port or range of ports, then these users are given access to the specified port or range of ports. However, adopted authorities are not used when deciding whether this port is restricted or not. Each user profile or group profile that wants to use a port or range of ports must be explicitly added.

When a socket application issues the bind() system call, the user profile that the job is running under is checked against the list of user profiles that are associated with the specified port. If there is not a match on that user profile, then a check is made to determine if this user profile is part of a group and that the group profile is in the list of user profiles that are associated with the specified port.

For example, there are two user profiles, USER_1 and USER_2. USER_2 is specified as a member of a group associated with USER_1. If the TCP port 1015 has a user profile list consisting of USER_1, then a bind() by USER_2 will work because USER_2 is a part of the group profile USER_1.

This is a required parameter.

name: Specify the name of the user profile that the port or range of ports is restricted to.

Top

Examples

Example 1: Adding a Single User Profile

ADDTCPPORT   PORT(7059)  PROTOCOL(*UDP)  USRPRF(TCPUSER)

This command adds the user profile TCPUSER to the set of user profiles that are allowed to bind UDP port 7059. User profiles that have not been added to this set or are not in a group profile that has been added will not be allowed to use UDP port 7059.

Example 2: Adding Multiple User Profiles

ADDTCPPORT   PORT(1590)  PROTOCOL(*TCP)  USRPRF(USER1)
ADDTCPPORT   PORT(1590)  PROTOCOL(*TCP)  USRPRF(USER2)

These commands show that a port can be restricted for use by multiple user profiles. User profiles USER1 and USER2 are the only users that are allowed to bind to TCP port 1590.

Example 3: Adding a Single User Profile to a Range of Ports

ADDTCPPORT   PORT(1591 1600)  PROTOCOL(*TCP)  USRPRF(USER3)

This command adds the user profile USER3 to the set of user profiles that are allowed to bind TCP ports 1591 through 1600.

Top

Error messages

*ESCAPE Messages

TCP1D03: &1 member record length not correct.
TCP1D04: Error occurred processing member &1 of &2/&3.
TCP26E2: User profile &1 damaged.
TCP26E4: Port restriction action successful, but TCP/IP errors occurred.
TCP26FC: Upper port value must be *ONLY.
TCP26F1: Range of ports not valid.
TCP2677: Port restriction not added.
TCP2679: port entry was added successfully but errors occurred.
TCP2680: Duplicate port restriction found.
TCP8050: *IOSYSCFG authority required to use &1.
TCP9503: File &3 in library &2 not available.
TCP9509: Line &1 not found.
TCP9517: Duplicate port entry found.
TCP9526: User profile &1 not found.
TCP9999: Internal system error in program &1.

Top