A fix is available
APAR status
Closed as new function.
Error description
Currently a problem exist when using FTP behind a firewall. The Firewall does not allow incoming data connections. If the client establishes a listening socket and passes it to the SERVER, the FTP server cannot establish the connection through the Fire- wall. When using NAT firewalls with encryption, the IP address for the data connection will be lost because the firewall can not translate the encrypted IP address. EPSV support is needed to avoid this problem. With EPSV the FTP server will only return the PORT number. The IP address is agreed upon by the client and the server and does not need to be transferred.
Local fix
Problem summary
**************************************************************** * USERS AFFECTED: IBM Communications Server for z/OS Version 1 * * Release 4 IP: FTP * **************************************************************** * PROBLEM DESCRIPTION: FTP data transfer fails when FTP is * * behind a firewall because: * * 1) The firewall does not allow the * * connection from the server back through * * the firewall. * * 2) Even when PASV is used, the firewall * * may allow the control connection via * * port 21 but does not allow a data * * connection using one of the ephemeral * * ports. * * 3) When PASV is used, the IP address, * * which is passed back from the FTP * * server, may be lost because the NAT * * firewall can not translate an * * encrypted IP address. * **************************************************************** * RECOMMENDATION: * **************************************************************** FTP cannot establish the data connection if the server, client or both are behind a firewall. Some of the problems are: After the FTP client has established the listening socket, the firewall will not allow the server back through the clients firewall. The firewall may allow a connection to the 'well known port' 21, which is the control connection, but does not allow the data connection via a ephemeral port. The NAT firewall needs to translate the IP address but cannot if the address is encrypted. PQ89200 extends this function to support Distributed VIPA in SYSPLEX. +-------------------------------------------------------------+ + Please check our Communications Server for OS/390 homepages + + for common networking tips and fixes. The URL for these + + homepages can be found in Informational APAR II11334. + +-------------------------------------------------------------+
Problem conclusion
Temporary fix
Comments
The FTP client has been changed to allow the EPSV command for IPv4. By setting EPSV4 to TRUE, the client will request that the server initiate the data connections and pass the port number back to the client. The IP address is agreed upon so it is not necessary for an IP address to flow across the network. This resolves the firewall problem where the IP address is encrypted and can not be translated from public to private. The FTP server has been changed to support a range of ephemeral PORT numbers. If PASSIVEDATAPORTS option has been defined in FTPDATA and PASV or EPSV is issued, the server will attempt to get a port in the specified range. Now the firewall can be configured to only allow the data connection in the same range of ports. If the server can not get a port within the requested range, then the FTP client will attempt to open a data connection in the normal way. The following documentation changes are required: z/OS Communications Server IP Messages Volume 3 (EZY) Document Number SC31-8785-02 Add the following message: EZYFT78I lowport value lowport cannot exceed highport value highport Explanation: FTP encountered an error while processing a PASSIVEDATAPORTS statement in the FTP.DATA file. The value specified for the lowest allowed port number is greater than the value specified for the highest allowed port number. This is not allowed. lowport is the value specified for the lowest allowed port number. highport is the value specified for the highest allowed port number. System Action: The current statement is ignored. FTP continues processing. User or Operator Response: Correct the erroneous statement in the FTP.DATA file, and restart FTP. Refer to the z/OS Communications Server: IP Configuration Reference for information about statements in the FTP.DATA file. System Programmer Response: None. Source Data Set: EZAFTPEP Procedure Name: read_ftpdata() --------------------------------------------------- z/OS Communications Server IP Messages Volume 1 (EZA) Document Number SC31-8783-03 Add the following message: EZA2916I local site variable statement_name is set to value Explanation: This message is displayed as part of the locstat subcommand output. statement_name is the name of the statement coded in the client FTP.DATA file. value is the current setting of statement_name. It is the default value assigned by FTP, or what you specified in the FTP.DATA file, or the most recent value you assigned with a locsite subcommand. You can use the locsite subcommand to change value. Refer to the z/OS Communications Server: IP User's Guide and Commands and the z/OS Communications Server: IP Configuration Reference for information about the statement_name statement in the client FTP.DATA file. System Action: Processing continues. User or Operator Response: If you want to change the setting of statement_name temporarily, use the locsite subcommand. Refer to the z/OS Communications Server: IP User's Guide and Commands for information about the locsite subcommand. If you want to make a permanent change to statement_name, refer to the z/OS Communications Server: IP Configuration Reference for information about coding the statement_name statement. System Programmer Response: None. Source Data Set: ezaftpcl Procedure Name: locstat() ========================================================== z/OS Communications Server IP Configuration Reference Document Number SC31-8776-03 After chapter FTP.DATA data set statements add entries for the PASSIVEDATAPORTS and EPSV4 statements. PASSIVEDATAPORTS Use the PASSIVEDATAPORTS statement to assign a range of port numbers for the FTP server to use as listening data socket ports. Syntax >>__PASSIVEDATAPORTS (low_port, high_port)___>< Parameters low_port The lowest port number the FTP server is allowed to use when creating a listening data socket. The lowest number allowed for low_port is 1024. high_port The highest port number the FTP server is allowed to use when creating a listening data socket. The highest number allowed for high_port is 65535. By default, the FTP server allows the stack to select a port number from its entire range of ephemeral ports for listening data sockets. PASSIVEDATAPORTS affects ports selected for the data connection only; the control connection ports are not affected. PASSIVEDATAPORTS is useful in conjunction with fire walls which restrict the range of port numbers allowed to FTP. Restriction: If you have PORTRANGE statements in PROFILE.TCPIP that reserve ports for a different application, and those reserved ports intersect with the PASSIVEDATAPORTS ports, the FTP server will never be able to obtain those ports. Examples To restrict the server's choice of ports for listening data sockets to ports from 50000 to 50099, code this statement in FTP.DATA. PASSIVEDATAPORTS (50000,50099) ============================================================= EPSV4 Statement Use the EPSV4 statement to direct the FTP client to use EPSV and EPRT commands on IPv4 sessions. The locsite subcommand is also available to set this parameter. Syntax _EPSV4 FALSE__________ >>____|_______________________|__________>< |_EPSV4_ _ _FALSE___| |_TRUE_| Parameters FALSE Prevents the client from using EPRT and EPSV commands on IPv4 sessions. This is the default. TRUE Directs the client to use EPRT and EPSV commands on IPv4 sessions. EPRT and EPSV commands are described in RFC 2428. See RFC 2428 for more information about these commands. If the server rejects and EPRT or EPSV command during the session, the client stops sending EPRT and EPSV to that server regardless of how you have set EPSV4. Recommendation: If your client has trouble establishing a data connection on an IPv4 security protected, encrypted session through an NAT firewall, coding EPSV4 TRUE in the client's FTP.DATA can help. Restrictions: The FTP server ignores this statement. Socksified sessions use PASV or PORT commands to establish data connections, as specified by the FWFRIENDLY setting. When EPSV4 is TRUE, the client attempts EPSV but never EPRT to establish a socksified data connection. Some FTP servers support EPRT and EPSV commands, but do not reply as described in RFC 2428. If the FTP server reply to EPSV or EPRT does not conform to RFC 2428, the client reacts as if the server had rejected the Command. RFC 2428 stipulates EPSV is the preferred command to establish data connections. Therefore, when EPSV4 is TRUE, the client will try EPSV regardless of how you have set FWFRIENDLY. The client uses EPRT only to set up a data connection for proxy transfer. Examples Direct the client to use EPSV and EPRT commands on IPv4 FTP sessions. EPSV4 TRUE ============================================================= z/OS Communications Server IP Diagnosis Guide Document Number GC31-8782-03 Chapter 8, Diagnosing FTP Problems In the Client section, under Common Problems, Add a new common problems: Secure IPv4 FTP session can't transfer data through an NAT fire wall. If you are using an encrypted FTP control connection, as is the case when using TLS security, and your client sends PASV or PORT to establish a data connection for file transfer, you may find that you can log into a server successfully through a NAT (network address translation) fire wall, but you can't transfer data because the client can't start a data connection. NAT firewalls monitor the FTP control connection as well as the IP headers, changing the IP addresses as needed. If the control connection is encrypted, the NAT can't monitor it to change the IP addresses the FTP client and server exchange with PASV and PORT commands. Use the locsite subcommand with the EPSV4 parameter, or code EPSV4 TRUE in FTP.DATA, to direct the client to use EPSV instead of PORT or PASV on IPv4 sessions to establish the data connection. The EPSV command exchanges only port numbers between FTP client and server, so the NAT fire wall does not need to translate IP addresses. Note that the server must support EPSV on IPv4 sessions for this solution to be Effective. For more information about the EPSV command, see RFC 2428. For more information about the locsite subcommand, see IP User's Guide and Commands. For more information about the EPSV4 statement in FTP.DATA, see IP Configuration Reference. Fire wall won't permit FTP client to establish a data Connection If you log into an FTP server through a fire wall, you may find you can log in successfully to the server, but the fire wall won't let FTP establish a passive data connection because the ephemeral ports chosen for the data connection are outside the range of ports the fire wall will permit. If the client sends EPSV or PASV to the server to start the data connection, the client is said to be establishing a passive data connection, or is said to be operating in passive mode. In passive mode, the server chooses the ephemeral port for the data connection. Ephemeral port numbers are part of EPSV and PASV replies the server sends to the client. You can configure the z/OS FTP server to use only a specific range of ephemeral ports or the data connection compatible with what you have configured for your fire wall by coding the PASSIVEDATAPORTS statement in FTP.DATA. See the IP Configuration Reference for information about the PASSIVEDATAPORTS statement. If the client sends PORT or EPRT to the server to start the data connection, the client is said to be establishing an active data connection, or operating in active mode. Active mode FTP is not recommended for sessions through fire walls. Use the locsite subcommand with the FWFRIENDLY parameter, or code FWFRIENDLY TRUE in FTP.DATA, to direct the client to operate in passive mode. ========================================================== z/OS Communications Server V1R4.0 IP User's Guide and Commands Document Number SC31-8780-02 Chapter: Changing Local Site Defaults Using FTP.DATA Add new entry to the table: FTP.DATA Data Set Statements for the FTP Client statement value description EPSV4 true On an IPv4 session, allow client to use EPSV to establish a data connection. If the server rejects the EPSV command, the client will refer to the FWFRIENDLY setting to determine how to establish the data connection, unless it is setting up a data connection for proxy transfer. In that case, the client will use PASV to set up the data connection. Once the server rejects either the EPSV command or the EPRT command, the client won't send either command again, even when EPSV4 is TRUE. FALSE On an IPv4 session, do not use EPSV to establish a data connection. The client will refer to the FWFRIENDLY setting to determine how to establish the data connection. This is the default. ------------------------------------------------------------- Chapter: Sample FTP.DATA Data Set (FTPDATA) In the section LOCSITE Subcommand--Specify Site Information to the Local Host, add these parameters: EPSV4 Specifies the client is to attempt to use the EPSV command to establish a data connection on an IPv4 session instead of referring to the FWFRIENDLY setting. See RFC 2428 for information about the EPSV command. If the server rejects the EPSV command, the client refers to the FWFRIENDLY setting to determine how to establish the data connection. When the client is setting up proxy transfer data connections, it will try the EPSV command on IPv4 sessions; if the server rejects the EPSV command, the client will try the PASV command. If the server rejects either the EPSV or the EPRT command during the session, the client won't send EPSV to the server again, even when EPSV4 is specified. NOEPSV4 Prevents the client from using the EPSV command to establish a data connection on an IPv4 session. See RPC 2428 for information about the EPSV command. When NOEPSV4 is set, the client refers to the FWFRIENDLY
APAR Information
APAR number
PQ80281
Reported component name
TCP/IP V3 MVS
Reported component ID
5655HAL00
Reported release
140
Status
CLOSED UR1
PE
NoPE
HIPER
NoHIPER
Special Attention
NoSpecatt / Xsystem
Submitted date
2003-10-31
Closed date
2003-11-20
Last modified date
2005-01-14
APAR is sysrouted FROM one or more of the following:
APAR is sysrouted TO one or more of the following:
UQ82394 UQ82395
Modules/Macros
EZAFTPAC EZAFTPAS EZAFTPCK EZAFTPCL EZAFTPCP EZAFTPCX EZAFTPDM EZAFTPEP EZAFTPGM EZAFTPGU EZAFTPLD EZAFTPLS EZAFTPRX EZAFTPSC EZAFTPSD EZAFTPSM EZAFTPSR
| SC31877603 | SC31878002 | SC31878502 | GC31878203 | SC31878303 |
Fix information
Fixed component name
TCP/IP V3 MVS
Fixed component ID
5655HAL00
Applicable component levels
Fix is available
Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.
[{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SG19M","label":"APARs - z\/OS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"140","Edition":"","Line of Business":{"code":"","label":""}},{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SSCY4DZ","label":"DO NOT USE"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"140","Edition":"","Line of Business":{"code":"","label":""}}]
Document Information
Modified date:
14 January 2005