HDISV troubleshooting guide
Overview
This guide helps resolve common issues when using HDISV.
Quick reference
- Connection issues
- Password and login problems
- 3270 terminal issues
- VPN problems
- z/OS not responding
- Storage issues
- Performance problems
- Getting help
Connection issues
Cannot SSH to z/OS
Symptoms:
ssh: connect to host 172.20.x.x port 22: Connection refused
ssh: connect to host 172.20.x.x port 22: No route to host
Solutions:
1. Check VPN connection
- Verify VPN connection
- Try disconnecting and reconnecting
- Verify VPN client shows "Connected" status
2. Verify IP address
- Check ZLPN dashboard for the correct IP
- Verify the z/OS IP is used (not Linux IP in Linux Layer Access mode)
3. Check SSH key
# Use the correct private key
ssh -i ~/.ssh/id_rsa zosadmn@<your-ip>
# Verify key permissions
chmod 600 ~/.ssh/id_rsa
4. Try different SSH options
# Disable strict host key checking
ssh -o StrictHostKeyChecking=no zosadmn@<your-ip>
# Use verbose mode to see what's happening
ssh -v zosadmn@<your-ip>
5. Wait and retry
- If instance was just created, wait 5-10 minutes
- z/OS may still be starting up
"WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED"
Symptoms:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Cause: User previously connected to a different instance with the same IP address.
Solutions:
Option 1: Remove old host key (Recommended)
ssh-keygen -R <your-ip-address>
Option 2: Bypass check (Quick Fix)
ssh -o StrictHostKeyChecking=no zosadmn@<your-ip>
Option 3: Edit known_hosts file
# Open the file
vi ~/.ssh/known_hosts
# Find and delete the line with the IP address
# Save and exit
Connection timeout
Symptoms:
ssh: connect to host 172.20.x.x port 22: Connection timed out
Solutions:
1. Verify VPN
- Disconnect and reconnect to VPN
- Check VPN logs for errors
2. Check firewall
- Ensure workstation firewall allows outbound SSH
- Try from a different network if possible
3. Verify instance status
- Check ZLPN portal - instance should show "Active"
- If "Error" status, contact support
4. Test connectivity
# Try to ping the IP
ping <your-ip>
# If ping works but SSH doesn't, z/OS may not be fully started
Password and login problems
Cannot set password
Symptoms:
password_change.py -u ZOSADMN -p 'MyPassword123'
# Error: Password does not meet requirements
Cause: Password doesn't meet RACF passphrase rules.
Solution:
RACF passphrase requirements:
- Minimum length: 14 characters
- Maximum length: 100 characters
- Must contain:
- At least 2 alphabetic characters (A-Z, a-z)
- At least 2 non-alphabetic characters (numbers, punctuation, special)
- Cannot contain:
- User ID (ZOSADMN) as consecutive characters
- More than 2 consecutive identical characters
Valid examples:
password_change.py -u ZOSADMN -p 'MySecurePass123!'
password_change.py -u ZOSADMN -p 'Development2024#'
password_change.py -u ZOSADMN -p 'zOS-Testing-456'
Invalid examples:
# Too short
password_change.py -u ZOSADMN -p 'Short123'
# Contains ZOSADMN
password_change.py -u ZOSADMN -p 'MyZOSADMNpass123'
# Too many consecutive characters
password_change.py -u ZOSADMN -p 'Passwordddd123!'
Forgot password
Symptoms:
- Cannot login to TSO
- Password expired or forgotten
Solution:
Reset via SSH:
# SSH to z/OS
ssh zosadmn@<your-ip> -i ~/.ssh/id_rsa
# Set new password
password_change.py -u ZOSADMN -p 'NewSecurePass123!'
If SSH also fails:
- For Managed Service mode: Recreate the instance (data is preserved)
- For Linux Layer Access mode: Contact support or terminate and create new instance
"Permission denied (publickey)"
Symptoms:
ssh zosadmn@<your-ip>
Permission denied (publickey).
Cause: SSH key mismatch or not properly uploaded.
Solutions:
1. Verify the SSH key
# Check available keys
ls -la ~/.ssh/
# Try specifying the key explicitly
ssh -i ~/.ssh/id_rsa zosadmn@<your-ip>
ssh -i ~/.ssh/id_ed25519 zosadmn@<your-ip>
2. Check key format
# View public key
cat ~/.ssh/id_rsa.pub
# Should start with "ssh-rsa" or "ssh-ed25519"
3. Verify key was uploaded
- Check ZLPN portal
- Ensure PUBLIC key is uploaded (.pub file), not private key
4. Recreate instance with correct key
- For Managed Service mode: Use recreate operation
- Upload the correct public key during recreation
3270 terminal issues
Cannot connect to 3270 terminal
Symptoms:
- Connection refused on port 2023
- Timeout when connecting
- "Host not found" error
Solutions:
1. Verify VPN connection
- Must be connected to VPN first
- Try disconnecting and reconnecting
2. Check IP and port
- IP: z/OS IP address from ZLPN portal
- Port: 2023 (standard TN3270 port)
3. Test SSH first
# If SSH works, z/OS is running
ssh zosadmn@<your-ip>
4. Wait for z/OS startup
- 3270 service starts after z/OS is fully booted
- Wait 5-10 minutes after instance creation
5. Try different emulator
- IBM Host On-Demand
- x3270 (Linux/Mac)
- wc3270 (Windows)
- Vista TN3270
3270 connection drops
Symptoms:
- Connection established but drops after a few minutes
- "Connection lost" messages
Solutions:
1. Check VPN stability
- VPN may be disconnecting
- Check VPN client logs
2. Adjust emulator timeout
- Increase keep-alive interval
- Enable TCP keep-alive in emulator settings
3. Check network
- Test from different network if possible
- Corporate firewall may be interfering
Cannot login to TSO
Symptoms:
- 3270 connects but TSO login fails
- "Invalid userid or password" message
Solutions:
1. Verify credentials
TSO ZOSADMN
# Then enter password
2. Check password
- Use the password set via SSH
- Password is case-sensitive
3. Reset password
# SSH to z/OS
ssh zosadmn@<your-ip>
# Reset password
password_change.py -u ZOSADMN -p 'NewPassword123!'
VPN problems
VPN won't connect
Symptoms:
- VPN client shows "Connection failed"
- Authentication errors
- Timeout errors
Solutions:
1. Verify credentials
- Check VPN username and password
- Ensure credentials haven't expired
2. Request VPN access
- If user doesn't have VPN access, request it through ZLPN portal
- Navigate to HDISV Overview page
- Click "Request VPN Access"
3. Check VPN client
- Ensure VPN client is installed correctly
- Try reinstalling VPN client
- Check for client updates
4. Contact support
- If credentials are correct but still can't connect
- Submit support ticket through ZLPN portal
VPN disconnects frequently
Symptoms:
- VPN connects but drops after a few minutes
- Must reconnect frequently
Solutions:
1. Check network stability
- Test internet connection
- Try from different network if possible
2. Adjust VPN settings
- Increase timeout values
- Enable keep-alive if available
3. Check firewall
- Corporate firewall may be blocking VPN
- Try from home network to test
z/OS not responding
z/OS appears hung
Symptoms:
- SSH connects but commands don't respond
- 3270 connects but screens don't update
- Long delays for any operation
Solutions:
1. Check instance status
- Log into ZLPN portal
- Verify instance shows "Active" status
2. Wait for operations to complete
- Some operations (like dataset allocation) can take time
- Wait 5-10 minutes before assuming it's hung
3. Try new connection
# Open new SSH session
ssh zosadmn@<your-ip>
# Try simple command
pwd
4. Restart instance (Last Resort)
- For Managed Service mode: Use ZLPN portal to stop/start
- For Linux Layer Access mode: Contact support
Commands return errors
Symptoms:
- z/OS commands fail with errors
- "Command not found" messages
- Unexpected error codes
Solutions:
1. Check command syntax
# USS commands (from SSH)
ls -la
cd /u/zosadmn
# TSO commands (from 3270)
LISTDS
LISTCAT
2. Verify the environment
- SSH accesses USS (Unix System Services)
- 3270 accesses TSO
- Commands are different in each
3. Check permissions
# From SSH
ls -la /u/zosadmn
[↑ Return to Quick reference](#quick-reference)
# Verify file ownership
Storage issues
Out of space errors
Symptoms:
IEC030I B37-04
Space allocation error
Dataset full
Cause: User volumes (USER01 or USMS01) are full.
Solutions:
1. Check space usage
# From TSO/ISPF
# Option 3.4 - DSLIST
# Enter: ZOSADMN.**
# Review space used
2. Delete unnecessary datasets
# From ISPF 3.4
# Type 'D' next to dataset to delete
# Or use IDCAMS DELETE command
3. Request additional storage
- Log into ZLPN portal
- Navigate to the instance
- Click "Order Additional Storage"
- Wait for approval and provisioning
4. Compress datasets
# From TSO
COMPRESS 'ZOSADMN.MY.DATASET'
See Managing Storage for detailed instructions.
Cannot allocate dataset
Symptoms:
Dataset allocation failed
Insufficient space
Volume not found
Solutions:
1. Check volume
# Allocate on USER01 or USMS01
# From ISPF 3.2
Volume: USER01
2. Reduce size
- Try smaller primary/secondary allocation
- Use tracks instead of cylinders
3. Check space
# From TSO
LISTCAT ENTRIES('USER01') ALL
Performance problems
Slow response times
Symptoms:
- Commands take long to execute
- Screen updates are slow
- Jobs run slowly
Solutions:
1. Check instance size
- Small instance: 2 vCPUs, 8 GB RAM
- Medium instance: 4 vCPUs, 16 GB RAM
- Large instance: 8 vCPUs, 32 GB RAM
Consider upgrading if:
- Running multiple concurrent jobs
- Using multiple middleware products
- Experiencing consistent slowness
2. Check network latency
# From user workstation
ping <your-ip>
# Look for high latency (>100ms)
3. Optimize workload
- Close unused 3270 sessions
- Cancel unnecessary jobs
- Reduce concurrent operations
4. Check time of day
- Performance may vary based on overall system load
- Try during off-peak hours
Jobs take too long
Symptoms:
- Batch jobs run much slower than expected
- JCL execution times are excessive
Solutions:
1. Review JCL
- Check for inefficient steps
- Optimize dataset access patterns
- Use appropriate buffer sizes
2. Check job priority
# From SDSF
# Review job class and priority
3. Monitor resources
# From TSO
# Use RMF or similar tools if available
4. Consider instance upgrade
- Larger instance provides more CPU and memory
- Contact support to discuss upgrade options
Getting help
IBM provides support solely for matters related to system operation and availability. IBM does not provide system administration or other support related to customization and use of the system. Users can obtain applicable support by submitting an IBM Support case. Select "Other contracted support services" in the Type of Support field and "IBM Z and LinuxONE Partner Network" in the Service field. To assist with investigation and troubleshooting, please provide the following details in the support ticket:
1. Instance details
- Instance name and size (small/medium/large)
- Deployment mode (Managed Service/Linux Layer Access)
2. Problem description
- What was the user trying to do?
- What happened instead?
- When did it start?
- Is it reproduceable?
3. Error messages
- Exact error text
- Screenshots if helpful
- Any error codes
4. Failed solutions
- List troubleshooting steps already attempted
- Results of each attempt