cheat sheet
z/OS TCP/IP
Drive the z/OS Communications Server TCP/IP stack — NETSTAT variants, PING, TRACERTE, RESOLVE, PROFILE.TCPIP configuration, OMPROUTE, and SSH from z/OS UNIX, with end-to-end troubleshooting recipes.
z/OS TCP/IP — NETSTAT, PING, Profile, and Diagnostics
What it is
TCP/IP on z/OS is IBM's implementation of the Internet protocol suite running as a system address space (typically named TCPIP) inside z/OS Communications Server. It exposes the standard sockets API to applications — FTP, FTPS, Telnet/TN3270, SSH (via z/OS UNIX sshd), HTTP via the z/OS HTTP Server, and any user program calling the IBM EZA/EZB sockets bridge — while keeping mainframe-specific concepts like dataset-mounted configuration (PROFILE.TCPIP), SMF type 119 accounting records, and policy-based AT-TLS. Reach for the z/OS TCP/IP toolset (NETSTAT, PING, TRACERTE, RESOLVE, OMPROUTE) whenever a mainframe-side network problem needs diagnosis — they parallel the Linux ss/ip/ping/traceroute/dig family but speak in z/OS terms (jobnames, addresss spaces, RACF resources) rather than process IDs.
Install
The TCP/IP stack is part of base z/OS — there is no install step. What you do verify is which procname the stack runs under (TCPIP is the default, sites with multi-stack may use TCPIPA, TCPIPB, …), and whether your userid can issue diagnostic commands.
(* From TSO — show the active stack name *)
NETSTAT HOME
(* From z/OS console — show the started task *)
D A,TCPIP
D TCPIP,,NET,ID=*
Output:
MVS TCP/IP NETSTAT CS V2R5 TCPIP NAME: TCPIP 10:33:21
HOME ADDRESS LIST:
LINKNAME: OSALINK1 ADDRESS: 10.20.30.5
LINKNAME: LOOPBACK ADDRESS: 127.0.0.1
LINKNAME: IPAQENET6 ADDRESS: 2001:DB8:42::5
3 OF 3 RECORDS DISPLAYED
END OF THE REPORT
TCPIP NAME: TCPIP in the header is the running stack's procname; use that name when targeting the D TCPIP,procname,... console syntax.
Syntax
The umbrella TSO command is NETSTAT [OPTION] [FILTER] — every NETSTAT variant follows this shape. PING and TRACERTE are separate TSO commands but share the same -r style modifier options. Console syntax wraps the equivalents in D TCPIP,procname,....
NETSTAT option [filter] [(MODIFIERS)] (* TSO *)
PING hostname [LENGTH(n)] [COUNT(n)] [TIMEOUT(n)] [TCP] [SRCIP(...)]
TRACERTE hostname [MAXTTL(n)] [DEBUG]
RESOLVE hostname
D TCPIP,TCPIP,NETSTAT,option,filter (* z/OS console *)
D TCPIP,TCPIP,SYSPLEX,VIPADYN
Output: (none — exits 0 on success)
NETSTAT options take a comma-separated filter list at the end with parentheses for keyword filters. Examples appear in each section below.
Essential NETSTAT variants
NETSTAT has the broadest surface area of any z/OS TCP/IP command — there are ~25 options, but six cover the daily-driver use cases.
| Option | What it shows | Linux/Unix analogue |
|---|---|---|
NETSTAT CONN | Established TCP connections | ss -ant state established |
NETSTAT ALLCONN | All connections including listening | ss -ant |
NETSTAT TELNET | TN3270 telnet sessions only | (none) |
NETSTAT HOME | Local interfaces and addresses | ip addr |
NETSTAT ROUTE | Routing table | ip route |
NETSTAT DEVLINKS | Devices, links, and their state | ip link |
NETSTAT PORTLIST | Reserved ports and their owners | /etc/services + ss |
NETSTAT BYTEINFO | Per-connection byte counters | ss -ti |
NETSTAT DROP | (admin) drop a connection by ID | ss -K |
NETSTAT RESCACHE | Resolver cache contents | dig +trace |
NETSTAT STATS | Cumulative protocol counters | nstat / netstat -s |
NETSTAT CONFIG | Active TCP/IP configuration | sysctl -a net.* |
The command name on z/OS UNIX (USS) is onetstat — same functionality, BSD-style flags (-c, -a, -r, -h).
NETSTAT CONN — established TCP connections
NETSTAT CONN lists every active TCP connection with the local and foreign socket, the owning jobname, and the TCP state. Add (IPADDR ...) or (IPPORT ...) to filter; add (APPLD ...) to scope to one jobname.
NETSTAT CONN
NETSTAT CONN (IPADDR 10.20.30.99)
NETSTAT CONN (APPLD CICSPRD1)
NETSTAT CONN (PORT 21) (* anything on TCP port 21 — FTP *)
NETSTAT CONN (CONNTYPE TCP)
Output:
MVS TCP/IP NETSTAT CS V2R5 TCPIP NAME: TCPIP 10:35:12
USER ID CONN LOCAL SOCKET FOREIGN SOCKET STATE
FTPD 00001245 10.20.30.5..21 10.50.60.7..52341 ESTBLSH
TN3270 0000124A 10.20.30.5..23 10.50.60.8..52342 ESTBLSH
ALICE 000012AB 10.20.30.5..22 10.50.60.9..58102 ESTBLSH
3 OF 3 RECORDS DISPLAYED
END OF THE REPORT
The USER ID column is the jobname that owns the socket; on z/OS UNIX-spawned processes (sshd children, inetd children) this is typically the parent procname. To drill into a single connection's byte/queue stats:
NETSTAT BYTEINFO (CONNECTION 000012AB)
NETSTAT ALL (CONNECTION 000012AB)
Output:
CLIENT NAME: ALICE CLIENT ID: 000012AB
LOCAL SOCKET: 10.20.30.5..22 FOREIGN SOCKET: 10.50.60.9..58102
BYTESIN: 00000045128
BYTESOUT: 00000123456
SEGMENTSIN: 00000312
SEGMENTSOUT:00000418
1 OF 1 RECORDS DISPLAYED
END OF THE REPORT
NETSTAT ALLCONN — listeners + established + closing
ALLCONN is the superset — it shows every socket in any TCP state plus open UDP sockets. This is the diagnostic "what is bound to this port" answer.
NETSTAT ALLCONN
NETSTAT ALLCONN (PORT 8080)
NETSTAT ALLCONN (CONNTYPE TCP)
NETSTAT ALLCONN APPLDATA (* include applicaton data field if set *)
Output:
MVS TCP/IP NETSTAT CS V2R5 TCPIP NAME: TCPIP 10:36:40
USER ID CONN LOCAL SOCKET FOREIGN SOCKET STATE
FTPD 00001000 0.0.0.0..21 0.0.0.0..0 LISTEN
SSHD 00001001 0.0.0.0..22 0.0.0.0..0 LISTEN
TN3270 00001002 0.0.0.0..23 0.0.0.0..0 LISTEN
FTPD 00001245 10.20.30.5..21 10.50.60.7..52341 ESTBLSH
WEB1 00001500 10.20.30.5..8080 0.0.0.0..0 LISTEN
WEB1 00001501 10.20.30.5..8080 10.50.60.7..52401 TIMEWAT
6 OF 6 RECORDS DISPLAYED
END OF THE REPORT
TCP states are standard RFC 793 — LISTEN, ESTBLSH, FIN-WT1, FIN-WT2, CLSWT, TIMEWAT, LASTACK, CLOSING. A large TIMEWAT count is healthy after a busy period; piles of CLOSING or FIN-WT2 suggest the partner is not sending the final ACK.
NETSTAT HOME — local addresses
NETSTAT HOME lists the IP addresses bound to the stack, mapped to LINK names. This is the source-side answer to "what is the mainframe's IP" and the place to confirm dynamic VIPA assignments.
NETSTAT HOME
NETSTAT HOME (DETAIL)
Output:
MVS TCP/IP NETSTAT CS V2R5 TCPIP NAME: TCPIP 10:37:55
HOME ADDRESS LIST:
LINKNAME: OSALINK1 ADDRESS: 10.20.30.5 FLAGS: PRIMARY
LINKNAME: OSALINK2 ADDRESS: 10.20.30.6
LINKNAME: VIPALINK1 ADDRESS: 10.20.30.100 FLAGS: STATIC VIPA
LINKNAME: VIPALINK2 ADDRESS: 10.20.30.101 FLAGS: DYNAMIC VIPA
LINKNAME: LOOPBACK ADDRESS: 127.0.0.1
LINKNAME: IPAQENET6 ADDRESS: 2001:DB8:42::5
6 OF 6 RECORDS DISPLAYED
END OF THE REPORT
STATIC VIPA is the always-on Virtual IP defined in PROFILE.TCPIP; DYNAMIC VIPA is movable — automated by sysplex distributor or by VARY TCPIP,,OBEYFILE rules. The PRIMARY flag identifies the source IP used for outbound traffic when no SRCIP is specified.
NETSTAT ROUTE — routing table
NETSTAT ROUTE shows static and dynamically-learned routes. Static routes come from BEGINROUTES/GATEWAY in PROFILE.TCPIP; dynamic routes come from OMPROUTE (OSPF/RIP).
NETSTAT ROUTE
NETSTAT ROUTE (DETAIL)
NETSTAT ROUTE ADDRTYPE IPV4
NETSTAT ROUTE RADV
Output:
MVS TCP/IP NETSTAT CS V2R5 TCPIP NAME: TCPIP 10:39:10
IPV4 DESTINATIONS:
DESTINATION GATEWAY FLAGS REFCNT INTERFACE
DEFAULT 10.20.30.1 UGS 00000004 OSALINK1
10.20.30.0/24 0.0.0.0 US 00000020 OSALINK1
10.50.60.0/24 10.20.30.1 UGS 00000002 OSALINK1
127.0.0.0/8 0.0.0.0 UH 00000000 LOOPBACK
4 OF 4 RECORDS DISPLAYED
END OF THE REPORT
Route flag letters:
| Flag | Meaning |
|---|---|
U | Up |
G | Gateway (next-hop is not directly attached) |
S | Static |
H | Host route (/32) |
D | Dynamic (OMPROUTE-learned) |
M | Modified by ICMP redirect |
R | Replaceable (replaceable by dynamic update) |
S (lowercase context) | Multipath |
NETSTAT DEVLINKS — devices and links
NETSTAT DEVLINKS shows the physical/virtual devices behind each LINK — OSA-Express, HiperSockets, XCF, IUTSAMEH, loopback — with their up/down state and current packet/byte counters.
NETSTAT DEVLINKS
NETSTAT DEVLINKS (DETAIL)
NETSTAT DEVLINKS LINKNAME OSALINK1
Output:
MVS TCP/IP NETSTAT CS V2R5 TCPIP NAME: TCPIP 10:40:25
DEVNAME: OSAQDIO01 DEVTYPE: MPCIPA DEVSTATUS: READY
LNKNAME: OSALINK1 LNKTYPE: IPAQENET LNKSTATUS: READY
NETNUM: 0 QUESIZE: 0 ROUTING PARMS: PRI
BYTESIN: 00000123456789 PACKETSIN: 0000123456
BYTESOUT: 00000098765432 PACKETSOUT: 0000098765
DEVNAME: VIPL01 DEVTYPE: VIPA DEVSTATUS: READY
LNKNAME: VIPALINK1 LNKTYPE: VIPA LNKSTATUS: READY
DEVNAME: LOOPBACK DEVTYPE: LOOPBACK DEVSTATUS: READY
LNKNAME: LOOPBACK LNKTYPE: LOOPBACK LNKSTATUS: READY
3 OF 3 RECORDS DISPLAYED
END OF THE REPORT
If a LINKSTATUS is anything but READY (e.g. NOT ACTIVE, INACTIVE) the link is the cause of any address routed through it being unreachable.
NETSTAT PORTLIST — reserved ports
NETSTAT PORTLIST reports which ports have a PORT reservation in PROFILE.TCPIP. A reserved port is bound only by the jobname listed; binds from other jobs return EACCES.
NETSTAT PORTLIST
Output:
MVS TCP/IP NETSTAT CS V2R5 TCPIP NAME: TCPIP 10:41:18
PORT# PROT USER FLAGS RANGE
00021 TCP FTPD 0-0
00023 TCP TN3270 0-0
00080 TCP WEB1 SAF=BIND 0-0
08080 TCP WEB1 SAF=BIND 0-0
00022 TCP * 0-0
00161 UDP SNMPD 0-0
6 OF 6 RECORDS DISPLAYED
END OF THE REPORT
USER * means "any job" can bind; SAF=BIND adds an extra RACF check (SERVAUTH class) before bind succeeds.
NETSTAT STATS — cumulative counters
NETSTAT STATS dumps the cumulative IP/ICMP/UDP/TCP counters. Useful to spot retransmits or fragmented IP that indicate path issues.
NETSTAT STATS PROTOCOL TCP
NETSTAT STATS PROTOCOL IP
NETSTAT STATS PROTOCOL ICMP
Output: (TCP excerpt)
TCP STATISTICS:
PACKETS SENT = 00012345678
PACKETS RCVD = 00010234567
RETRANSMITS = 00000004210
ACTIVE OPENS = 00000456789
PASSIVE OPENS = 00000234567
ATTEMPT FAILS = 00000000125
RESETS SENT = 00000003421
END OF THE REPORT
A RETRANSMITS / PACKETS SENT ratio above ~1% is the first warning sign of a flaky path or a saturated link.
PING — ICMP echo
PING sends ICMP echo requests from the stack's primary outbound address. Standard one-line invocation suffices for connectivity checks; LENGTH/COUNT/TIMEOUT and TCP variants extend to MTU and TCP-handshake checks.
PING myhost.example.com
PING myhost.example.com (COUNT 4)
PING myhost.example.com (LENGTH 1472 COUNT 1) (* MTU probe — don't-fragment *)
PING myhost.example.com (TIMEOUT 2)
PING myhost.example.com (SRCIP 10.20.30.100) (* test from a VIPA *)
Output:
CS V2R5: Pinging host myhost.example.com (10.50.60.7)
Ping #1 response took 0.012 seconds.
1 packet sent, 1 received, 0% packet loss
Round-trip time: min/avg/max = 0.012/0.012/0.012 seconds
For TCP-level reachability (does the partner accept a SYN on port n?):
PING myhost.example.com (TCP PORT 8080)
Output:
CS V2R5: Pinging host myhost.example.com (10.50.60.7) port 8080
TCP probe #1 took 0.018 seconds.
TCP probe succeeded.
TCP mode replaces the ICMP echo with a SYN/RST handshake — useful when ICMP is firewalled but the application port is open.
TRACERTE — path discovery
TRACERTE reveals each hop between the stack and a target. The default is UDP probes; ICMP switches to echo-request probes (better through firewalls that pass ICMP but drop high-UDP).
TRACERTE myhost.example.com
TRACERTE myhost.example.com (MAXTTL 12)
TRACERTE myhost.example.com (ICMP)
TRACERTE myhost.example.com (SRCIP 10.20.30.100)
TRACERTE 10.50.60.7 (DEBUG)
Output:
CS V2R5: Traceroute to myhost.example.com (10.50.60.7), 30 hops max, 12 byte packets
1 10.20.30.1 0.5 ms 0.4 ms 0.4 ms
2 10.10.0.1 1.1 ms 1.2 ms 1.1 ms
3 192.168.99.1 3.5 ms 3.4 ms 3.4 ms
4 * * * (* hop filters ICMP — UDP probes time out *)
5 10.50.60.7 12.4 ms 12.3 ms 12.4 ms
trace complete
* * * rows are common at firewall hops; they do not necessarily mean the path is broken — only that the device returns no TTL-exceeded response. If the final row reaches the target with timing, the path is up.
RESOLVE — DNS resolution sanity check
RESOLVE performs the same name lookup that any sockets call would, using the resolver order configured in the resolver address space (typically RESOLVER).
RESOLVE myhost.example.com
RESOLVE myhost.example.com (TYPE A)
RESOLVE myhost.example.com (TYPE MX)
RESOLVE 10.50.60.7 (* reverse *)
Output:
HOST NAME: myhost.example.com
HOST ALIASES: m.example.com
HOST ADDRESSES:
10.50.60.7
2001:DB8:99::7
When DNS is the suspect, follow RESOLVE with NETSTAT RESCACHE to confirm the cache state and D TCPIP,RESOLVER,SYSINFO to inspect the resolver's configuration. Hosts that work for some users but not others are nearly always a HOSTS.LOCAL//etc/hosts collision or a stale RESCACHE entry.
PROFILE.TCPIP — stack configuration
PROFILE.TCPIP is the dataset (typically SYS1.TCPPARMS(PROFILE) or TCPIP.PROFILE.TCPIP) read by the stack at startup. It defines devices, links, IP addresses, routes, port reservations, AT-TLS policy hooks, and global TCP behaviours. Changes to it can be applied at runtime with VARY TCPIP,,OBEYFILE,'dsn', which lets you add a route, reserve a port, or define a dynamic VIPA without bouncing the stack.
;; Excerpt — DEVICE/LINK/HOME/ROUTES
;
DEVICE OSAQDIO01 MPCIPA NONROUTER
LINK OSALINK1 IPAQENET OSAQDIO01
DEVICE VIPL01 VIRTUAL 0
LINK VIPALINK1 VIRTUAL 0 VIPL01
HOME
10.20.30.5 OSALINK1
10.20.30.100 VIPALINK1
127.0.0.1 LOOPBACK
;
;; Port reservations
;
PORT
20 TCP OMVS NOAUTOLOG ; FTP data
21 TCP FTPD
22 TCP * ; SSHD via z/OS UNIX
23 TCP TN3270
80 TCP WEB1 SAF BIND
8080 TCP WEB1 SAF BIND
;
;; Static routes
;
BEGINROUTES
ROUTE DEFAULT 10.20.30.1 OSALINK1 MTU 1500
ROUTE 10.50.60.0/24 10.20.30.1 OSALINK1 MTU 1500
ENDROUTES
;
;; Global TCP knobs
;
TCPCONFIG
TCPSENDBFRSIZE 65535
TCPRCVBUFRSIZE 65535
SENDGARBAGE NO
SOMAXCONN 1024
FINWAIT2TIME 60
Apply a delta at runtime:
(* From z/OS console *)
V TCPIP,,OBEYFILE,DSN='ALICE.TCPIP.OBEY.NEWPORT'
Output:
EZZ0060I PROCESSING COMMAND: VARY TCPIP,,OBEYFILE
EZZ0309I PROFILE PROCESSING BEGINNING FOR DSN=ALICE.TCPIP.OBEY.NEWPORT
EZZ0316I PROFILE PROCESSING COMPLETE FOR FILE
Where the OBEYFILE is a partial profile — only the new statements need to appear. To wipe an existing port reservation, include PORT n TCP * NOAUTOLOG DELETE (or the equivalent block syntax).
OMPROUTE — OSPF and RIP daemon
OMPROUTE is the dynamic-routing daemon (a separate address space) that speaks OSPFv2/OSPFv3 and RIPv1/RIPv2 with neighbouring routers and feeds learned routes into the stack's routing table.
;; OMPROUTE config snippet
AREA AREA_ID=0.0.0.0 STUB_AREA=NO
OSPF_INTERFACE
IP_ADDRESS=10.20.30.5
NAME=OSALINK1
SUBNET_MASK=255.255.255.0
AREA=0.0.0.0
COST=1
GLOBAL_OPTIONS
IGNORE_UNDEFINED_INTERFACES=YES
Inspect OMPROUTE state from the console:
F OMPROUTE,DISPLAY,OSPF,IFS
F OMPROUTE,DISPLAY,OSPF,NEIGHBORS
F OMPROUTE,DISPLAY,RT6 ALL
F OMPROUTE,DISPLAY,RT ALL
F OMPROUTE,RECONFIG (* re-read config without restart *)
Output:
EZZ7831I IFS OSPF INTERFACES
INTERFACE AREA COST STATE NEIGHBOR COUNT
10.20.30.5 0.0.0.0 1 DR 2
10.20.30.6 0.0.0.0 1 BDR 1
EZZ7847I OSPF NEIGHBOR LIST
NEIGHBOR ID NEIGHBOR IP STATE PRIORITY INTERFACE
192.0.2.10 10.20.30.1 FULL 1 10.20.30.5
192.0.2.11 10.20.30.2 FULL 1 10.20.30.5
STATE=FULL means the OSPF adjacency is up; transient EXSTART/EXCHANGE/LOADING states resolve in seconds. Stuck INIT/2WAY indicates a router misconfig on the neighbour.
SSH from z/OS UNIX
The OpenSSH client and server live in z/OS UNIX (USS); sshd is configured in /etc/ssh/sshd_config and started either as an inetd child or as a started task that runs BPXBATCH against the daemon binary. From a USS shell prompt:
# Outbound SSH from z/OS UNIX
ssh alicedev@myhost.example.com
# Outbound with a specific key
ssh -i /u/alice/.ssh/id_ed25519 alicedev@myhost.example.com
# scp / sftp
scp /u/alice/release.tar.gz alicedev@myhost.example.com:/tmp/
sftp alicedev@myhost.example.com
# Generate a key (algorithm pinned for IBM-1047 EBCDIC interop)
ssh-keygen -t ed25519 -f /u/alice/.ssh/id_ed25519
Output:
Welcome to myhost (Ubuntu 24.04 LTS)
Last login: Sun May 24 18:42:03 2026 from 10.20.30.5
alicedev@myhost:~$
The z/OS UNIX side cares about file tagging — a key file with the wrong tag will be misread as EBCDIC and rejected by ssh. Tag command:
chtag -tc IBM-1047 /u/alice/.ssh/id_ed25519
chtag -p /u/alice/.ssh/id_ed25519
Output:
t IBM-1047 T=on /u/alice/.ssh/id_ed25519
See the uss page for the full file-tagging story.
FTP vs SFTP vs co:Z SFTP
z/OS Communications Server FTP, OpenSSH SFTP, and the third-party co:Z SFTP all transfer files but differ on encryption, dataset awareness, and operational integration.
| Feature | z/OS FTP (Communications Server) | OpenSSH SFTP (z/OS UNIX) | co:Z SFTP |
|---|---|---|---|
| Protocol | FTP / FTPS (FTP over TLS) | SFTP (SSH subsystem) | SFTP (SSH subsystem) |
| Encryption | None (FTP) or TLS (FTPS) — typically AT-TLS | Always — SSH transport | Always — SSH transport |
| MVS dataset access | Native — SITE RECFM/LRECL/... | Indirect — USS files only | Native — dataset addressing built-in |
| JES integration | SITE FILETYPE=JES | None | Optional |
| Conversion (EBCDIC/ASCII) | TYPE A / SBT translation | Manual iconv | Automatic |
| Audit / SMF | Type 119 records | Via OpenSSH log files | Type 119 add-on |
| Footprint | Bundled with z/OS | Bundled with z/OS UNIX | Site-licensed product |
| Use when | Compliance with FTP/FTPS partners, dataset PUT/GET | Generic UNIX file moves, key-based automation | Heavy dataset/MFT volume with audit needs |
Practical decision tree:
1. Partner only speaks FTP? → z/OS FTP (+TLS if possible)
2. Need encrypted dataset → USS file? → co:Z SFTP (preferred)
3. USS file → USS file, automation? → OpenSSH SFTP
4. Existing PI shop with co:Z licence? → co:Z SFTP for everything
5. Need MQ/MFT-level audit? → Sterling Connect:Direct (out of scope here)
See the ftp page for full FTP usage, and uss for the USS SSH-client setup.
Console diagnostics — D TCPIP and VARY TCPIP
z/OS console commands operate on the running stack. The most useful are listed below; all assume the procname is TCPIP.
D TCPIP (* list active stacks *)
D TCPIP,,STOR (* storage usage of the stack *)
D TCPIP,,NETSTAT,CONN (* equivalent to TSO NETSTAT CONN *)
D TCPIP,,NETSTAT,ALL,IPADDR=10.50.60.7
D TCPIP,,SYSPLEX,VIPADYN (* dynamic VIPA across the sysplex *)
D TCPIP,,SYSPLEX,GROUP (* sysplex group membership *)
D TCPIP,,OSAINFO,INTFN=OSALINK1 (* OSA-Express detail *)
D TCPIP,,HELP (* full command list *)
V TCPIP,,OBEYFILE,DSN='ALICE.TCPIP.OBEY.NEWPORT'
V TCPIP,,SYSPLEX,QUIESCE,TARGET=TCPIPA (* quiesce a member from sysplex distribution *)
V TCPIP,,SYSPLEX,RESUME
V TCPIP,,DROP,CONNECTION=00001245 (* drop a stuck TCP connection *)
V TCPIP,,STOP (* stop a device *)
V TCPIP,,START (* re-start a device *)
P TCPIP (* terminate the stack — last resort *)
Output:
EZZ8453I TCPIP STATUS REPORT
STACK NAME: TCPIP JOBNAME: TCPIP STATUS: ACTIVE
HOST NAME: MYHOST
EZZ8460I STACK INITIALIZATION DATE/TIME: 2026/05/01 03:00:42
EZZ0250I THE TCPIP COMMAND COMPLETED
AT-TLS, TLS 1.3, and zERT — what changed in z/OS 3.1 / 3.2
z/OS 3.1 Communications Server adds AT-TLS support for TLS 1.3 including cached handshakes — a TLS 1.3 reconnect from a known client reuses cached parameters and skips the full handshake, cutting reconnect cost dramatically. On 3.1 the AT-TLS + FIPS 140-2 + TLS 1.3 combination is unsupported (FIPS 140-2 does not define TLS 1.3 cipher suites); z/OS 3.2 (GA 30 September 2025) adds FIPS 140-3 which does permit TLS 1.3, controlled by FIPSMODE(140-3,INDICATE,FAIL(...)) in the TTLSGroupAction. ChaCha20 ciphers remain FIPS-disallowed regardless of release; use AES-GCM or AES-CCM cipher suites only.
;; pagent rule — TLS 1.3 with cached handshakes
TTLSEnvironmentAction TLS_ENV_CLIENT
HandshakeRole Client
TTLSKeyringParms
Keyring TCPIP/TCPIP-KEYRING
TTLSCipherParms
V3CipherSuites4Char 1302 1303 ;; TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256
TTLSEnvironmentAdvancedParms
TLSv1.3 On
HandshakeCacheCapacity 2048 ;; cache up to 2048 client tickets
HandshakeCacheTimeout 600 ;; seconds
FIPSMODE 140-3 INDICATE FAIL OFF ;; z/OS 3.2 only
Apply APAR PH59425 on z/OS 3.1 to ensure the LE HEAPPOOLS64 option is always enabled for AT-TLS — without it, TLS 1.3 connection setup can be measurably slower under load.
zERT — encryption-readiness telemetry
z/OS Encryption Readiness Technology (zERT) is the discovery side: the stack observes every TCP/IP connection's cryptographic posture (protocol, cipher, key length, certificate fingerprint, jobname, peer address) and emits SMF type 119 subtypes 11 and 12. zERT Policy-based Enforcement (z/OS 2.5+, hardened in 3.1) lets you turn detection into action — write a Policy Agent rule that blocks connections that fall below a minimum protection level. On 3.1 the rules can match on Db2 authentication mode, and the user-interface around IBM zERT Network Analyzer has been simplified for security-team self-service.
;; pagent fragment — refuse plaintext or TLS <= 1.1 to FTPS port
zERTPolicyRule REFUSE_WEAK_TLS
LocalAddrRef ADDR_LOCAL
LocalPortRange 21 990
zERTPolicyActionRef zERT_ENFORCE_TLS12_MIN
zERTPolicyAction zERT_ENFORCE_TLS12_MIN
Action Reset ;; or Log
Protocol TLS
MinimumVersion TLSv1.2
Display live zERT enforcement counters:
D TCPIP,,NETSTAT,STATS,PROTOCOL=ZERT
Output:
ZERT STATISTICS:
CONNECTIONS OBSERVED = 00012345
CONNECTIONS RESET = 00000017 (* blocked by enforcement *)
CONNECTIONS LOGGED = 00000235
END OF THE REPORT
SMF and audit records
The TCP/IP stack writes SMF type 119 records for nearly every event of interest — connection initiations, connection terminations, FTP transfers, AT-TLS handshakes, profile changes, port reservations.
| Subtype | Records |
|---|---|
1 | TCP connection initiated |
2 | TCP connection terminated (with byte counters) |
4 | UDP socket close |
5 | TN3270 client connection |
7 | FTP client transfer |
11 | zERT connection-level cryptographic-posture record |
12 | zERT summary record (per jobname / per peer) |
70–75 | FTPS / TLS-related records |
94 | Statistics record |
100 | AT-TLS policy event |
z/OS 3.2 also activates SMF record type 1154, used to log FTP server JES access decisions (SITE FILETYPE=JES) for compliance-evidence collection alongside the syslogd-over-TCP secure logging path.
Extract a day's SMF 119s and summarise with DFSORT:
//SMF119 JOB (ACCT),'SMF 119 DUMP',CLASS=A,MSGCLASS=X,USER=ALICE
//STEP1 EXEC PGM=IFASMFDP
//SYSPRINT DD SYSOUT=*
//DUMPIN DD DSN=SYS1.MAN1,DISP=SHR
//DUMPOUT DD DSN=ALICE.SMF119.DAY,DISP=(,CATLG,DELETE),
// SPACE=(CYL,(50,10)),DCB=(RECFM=VB,LRECL=32756,BLKSIZE=32760)
//SYSIN DD *
INDD(DUMPIN,OPTIONS(DUMP))
OUTDD(DUMPOUT,TYPE(119))
/*
Output: (SYSPRINT)
IFA010I SMF DUMP PARAMETERS
IFA020I RECORDS WRITTEN = 0001023456
IFA021I ELAPSED TIME (SEC.) = 042.16
A second step then runs DFSORT against ALICE.SMF119.DAY to count connections per remote IP, average byte volume, etc.
Common pitfalls
- NETSTAT shows the wrong stack — sites with multiple TCP/IP stacks need
NETSTAT (TCP TCPIPA)to scope to a specific stack name. Without it, NETSTAT defaults to the first stack on the resolver search list. PORT n TCP *vsPORT n TCP jobname— using*(any job) is convenient during dev but defeats RACF SERVAUTH. Always pin production ports to a specific jobname plusSAFkeyword.PINGworks butTRACERTEfails on UDP — many firewalls drop high-UDP. UseTRACERTE (ICMP)if ICMP echo is allowed end-to-end, orPING (TCP PORT n)for an application-level reachability test.- AT-TLS misconfigured silently downgrades to plaintext — if
TLSMECHANISM TLSis not inPROFILE.TCPIPand the policy is loose, FTPS will fall back. Always checkpasearch -p TTLS(USS) and inspect SMF 119 subtype 100. OBEYFILEdeletes more than you meant —BEGINROUTES/ENDROUTESis replace-all in some releases; useADDRTandDELRTkeywords for incremental changes if your release supports them. Otherwise capture the full route table first.RESOLVEreturns ASCII names with mainframe-side EBCDIC quirks — TSO panel display may show?for high-bit characters. The lookup itself worked; only the rendering is broken.- OMPROUTE neighbours stuck
2WAY— typically the neighbour does not match priority/area, or HELLO interval mismatched. CompareF OMPROUTE,DISPLAY,OSPF,IFSoutput to the partner router's config. NETSTAT DROPrequires special authority — withoutREADtoMVS.VARY.TCPIP.DROPinOPERCMDS, you will seeEZZ0500Iaccess denied. Don't confuse the failure for a missing connection.- Wrong source IP on outbound traffic — when the stack has multiple HOME addresses, outbound from a batch job uses the PRIMARY by default. To pick a different source, use
SRCIPinPROFILE.TCPIP(per destination) orBINDon the socket in the program; for ping usePING ... (SRCIP ...). *inHOSTS.LOCALmatches nothing —HOSTS.LOCAL/HOSTS.ADDRINFOlookups are literal; wildcards belong only in DNS or the resolver search list.
Real-world recipes
Troubleshoot "my batch FTP can't reach the partner"
Symptom: an overnight FTP batch job fails with EZA1735I "Std return code = 26530". Walk down the layers.
;; 1. Is DNS working?
RESOLVE remote.partner.example.com
Output:
HOST NAME: remote.partner.example.com
HOST ADDRESSES:
203.0.113.42
;; 2. Is the route up?
NETSTAT ROUTE
Output:
DEFAULT 10.20.30.1 UGS 00000004 OSALINK1
203.0.113.0/24 10.20.30.1 UGSD 00000001 OSALINK1
;; 3. Is the partner reachable at all?
PING 203.0.113.42 (COUNT 3)
Output:
Ping #1 response took 0.045 seconds.
Ping #2 response took 0.044 seconds.
Ping #3 response took 0.044 seconds.
3 packets sent, 3 received, 0% packet loss
;; 4. Is the FTP port (21) open?
PING 203.0.113.42 (TCP PORT 21)
Output:
TCP probe succeeded.
;; 5. Try the connection from the same source IP the FTP job uses
PING 203.0.113.42 (TCP PORT 21 SRCIP 10.20.30.100)
Output:
TCP probe failed.
Step 5 is the smoking gun — the VIPA 10.20.30.100 is firewalled on egress; the primary 10.20.30.5 is not. Fix is either a firewall request for the VIPA or a SRCIP DESTINATION 203.0.113.0/24 10.20.30.5 rule in PROFILE.TCPIP.
Track down a port collision
A new server job fails to start with EZB0006I PORT 8080 IS NOT AVAILABLE. Identify who has the port.
NETSTAT ALLCONN (PORT 8080)
Output:
USER ID CONN LOCAL SOCKET FOREIGN SOCKET STATE
WEB1 00001500 10.20.30.5..8080 0.0.0.0..0 LISTEN
;; Confirm the reservation matches expectations
NETSTAT PORTLIST
Output:
08080 TCP WEB1 SAF=BIND 0-0
WEB1 already owns the port via both reservation and an active LISTEN. Options: kill WEB1 (P WEB1 from the console), or change the new job to a different port.
Drop a stuck TCP connection
A TN3270 user reports their session is frozen and there are 17 lingering connections to the same client IP.
NETSTAT CONN (IPADDR 10.50.60.99)
Output:
USER ID CONN LOCAL SOCKET FOREIGN SOCKET STATE
TN3270 00001501 10.20.30.5..23 10.50.60.99..58102 FIN-WT2
TN3270 00001502 10.20.30.5..23 10.50.60.99..58103 FIN-WT2
... (17 entries)
Drop them from the console:
V TCPIP,,DROP,CONNECTION=00001501
V TCPIP,,DROP,CONNECTION=00001502
Output:
EZZ0060I PROCESSING COMMAND: VARY TCPIP,,DROP
EZZ2500I CONNECTION 00001501 DROPPED
EZZ0060I PROCESSING COMMAND: VARY TCPIP,,DROP
EZZ2500I CONNECTION 00001502 DROPPED
For repeated incidents from a single partner, set FINWAIT2TIME lower in PROFILE.TCPIP so the stack reclaims half-closed sockets automatically.
Add a new static route without recycling the stack
A new partner segment was added at 10.99.0.0/24. The next-hop is the existing default gateway. Add the route at runtime using OBEYFILE.
;; Edit ALICE.TCPIP.OBEY(NEWNET)
BEGINROUTES
ROUTE 10.99.0.0/24 10.20.30.1 OSALINK1 MTU 1500
ENDROUTES
From the console:
V TCPIP,,OBEYFILE,DSN='ALICE.TCPIP.OBEY(NEWNET)'
Output:
EZZ0309I PROFILE PROCESSING BEGINNING FOR DSN=ALICE.TCPIP.OBEY(NEWNET)
EZZ0316I PROFILE PROCESSING COMPLETE FOR FILE
EZZ4202I TCP/IP ROUTING TABLE HAS BEEN UPDATED
Verify with NETSTAT ROUTE:
10.99.0.0/24 10.20.30.1 UGS 00000000 OSALINK1
After verifying, copy the same BEGINROUTES block into the main PROFILE.TCPIP so the route persists across stack recycles.
Reserve a new port for an application
A batch-spawned listener (MYSRV1) needs to bind to port 9100. Add a reservation by OBEYFILE.
;; ALICE.TCPIP.OBEY(MYSRV1PT)
PORT
9100 TCP MYSRV1 SAF BIND
V TCPIP,,OBEYFILE,DSN='ALICE.TCPIP.OBEY(MYSRV1PT)'
NETSTAT PORTLIST
Output:
EZZ0316I PROFILE PROCESSING COMPLETE FOR FILE
PORT# PROT USER FLAGS
09100 TCP MYSRV1 SAF=BIND
A second OBEY removes it on demand:
;; ALICE.TCPIP.OBEY(MYSRV1RM)
PORT
9100 TCP MYSRV1 DELETE
Confirm AT-TLS is encrypting an FTP transfer
A compliance check needs evidence that an existing FTP partner runs over TLS via AT-TLS.
# From z/OS UNIX
pasearch -p TTLS # list active TTLS rules
Output:
TTLS Rule: FTPS_CLIENT
Address: 10.50.60.0/24
PortRange: 21
Direction: Outbound
Status: Active
TTLS Action: TTLS_TLS12
Version: TLS 1.2
KeyringName: TCPIP/TCPIP-KEYRING
;; From TSO — see the connection state including TLS
NETSTAT ALL (CONNECTION 00001245)
Output:
CLIENT NAME: FTPD CLIENT ID: 00001245
LOCAL SOCKET: 10.20.30.5..21 FOREIGN SOCKET: 10.50.60.7..52341
TTLS POLICY: TTLS_TLS12
TTLS STATUS: TTLSCONNECTED, OUTBOUND
TLS PROTOCOL: TLSV12
TLS CIPHER: TLS_AES_256_GCM_SHA384
Capture both outputs in the SMF 119 subtype 100 record extract for the audit trail.
Compare stack performance before/after a change
A network team adjusts MTU on an OSA. To measure impact, snapshot stats before and after.
;; Before
NETSTAT STATS PROTOCOL TCP OUTDATASET(ALICE.NS.BEFORE)
;; ... apply change, wait 30 minutes ...
NETSTAT STATS PROTOCOL TCP OUTDATASET(ALICE.NS.AFTER)
Output:
NETSTAT REPORT WRITTEN TO ALICE.NS.BEFORE
NETSTAT REPORT WRITTEN TO ALICE.NS.AFTER
Then use DFSORT/ICETOOL to diff the RETRANSMITS counter and the OUT-OF-ORDER PACKETS RECEIVED figure between the two reports. A drop in retransmits with the new MTU validates the change; an increase means roll back.
Quick connectivity matrix from one command
Sometimes a partner team asks "can you reach all five of our endpoints right now?" A short REXX driver iterates the list.
/* ALICE.UTIL.REXX(NETCHECK) — REXX */
HOSTS = 'host-a.partner.example.com host-b.partner.example.com host-c.partner.example.com'
DO I = 1 TO WORDS(HOSTS)
H = WORD(HOSTS, I)
ADDRESS TSO "PING" H "(COUNT 2 TIMEOUT 2)"
END
EXIT 0
Run from TSO:
EX 'ALICE.UTIL.REXX(NETCHECK)'
Output:
CS V2R5: Pinging host host-a.partner.example.com (203.0.113.10)
2 packets sent, 2 received, 0% packet loss
CS V2R5: Pinging host host-b.partner.example.com (203.0.113.11)
2 packets sent, 2 received, 0% packet loss
CS V2R5: Pinging host host-c.partner.example.com (203.0.113.12)
2 packets sent, 0 received, 100% packet loss
Host-c is unreachable — escalate immediately rather than waiting for the batch window to fail.
Quick reference card
NETSTAT options (TSO) ; USS equivalent
CONN ALLCONN TELNET ; onetstat -c / -a
HOME ROUTE DEVLINKS ; onetstat -h / -r / -d
PORTLIST CONFIG STATS ; onetstat -o / -f / -s
BYTEINFO RESCACHE DROP ; onetstat -b / (no eq.) / (no eq.)
Filters
(IPADDR a.b.c.d) (IPPORT a.b.c.d..port)
(PORT n) (CONNTYPE TCP|UDP)
(APPLD jobname) (CLIENT clientid)
Diagnostic commands
PING host [(LENGTH n COUNT n TIMEOUT n TCP PORT n SRCIP a.b.c.d)]
TRACERTE host [(MAXTTL n ICMP SRCIP a.b.c.d)]
RESOLVE host [(TYPE A|AAAA|MX|PTR)]
Configuration (PROFILE.TCPIP)
DEVICE / LINK / HOME / BEGINROUTES / PORT / TCPCONFIG / IPCONFIG
Apply runtime delta: V TCPIP,,OBEYFILE,DSN='dsn'
Drop a connection: V TCPIP,,DROP,CONNECTION=connid
OMPROUTE
F OMPROUTE,DISPLAY,OSPF,IFS | NEIGHBORS | RT[6] ALL
F OMPROUTE,RECONFIG
z/OS UNIX
ssh / scp / sftp (file tags must be IBM-1047 + chtag -p)
onetstat / netstat (BSD-style flags)
pasearch -p TTLS (AT-TLS policy)
SMF type 119 subtypes
1 TCP open 2 TCP close 7 FTP transfer
5 TN3270 94 statistics 100 AT-TLS event
11 zERT conn 12 zERT summary (z/OS 3.x)