vpn-troubleshooting-guide

name	vpn-troubleshooting-guide
enabled	true
description	Use when performing vpn troubleshooting guide — vPN connectivity troubleshooting decision tree covering common VPN client issues, authentication failures, split tunneling problems, performance degradation, and DNS resolution failures. Guides helpdesk agents through systematic diagnosis of VPN connectivity issues for remote workers.
required_connections	[{"prefix":"itsm","label":"ITSM Tool (ServiceNow, Freshservice, etc.)"}]
config_fields	[{"key":"user_name","label":"Affected User Name","required":true,"placeholder":"e.g., Jane Smith"},{"key":"vpn_client","label":"VPN Client","required":true,"placeholder":"e.g., Cisco AnyConnect, GlobalProtect, OpenVPN"},{"key":"symptom","label":"Primary Symptom","required":true,"placeholder":"e.g., cannot connect, slow speeds, intermittent disconnects"},{"key":"operating_system","label":"Operating System","required":false,"placeholder":"e.g., Windows 11, macOS 14, Ubuntu 22.04"}]
features	["HELPDESK"]

VPN Troubleshooting Guide

Troubleshooting VPN issue for {{ user_name }} Client: {{ vpn_client }} | OS: {{ operating_system }} Symptom: {{ symptom }}

Decision Tree

START: What is the symptom?
│
├─ Cannot Connect at All
│  ├─ Is internet working? (can browse web?)
│  │  ├─ No → Fix internet first (see Network Troubleshooting)
│  │  └─ Yes → Continue
│  ├─ VPN client installed and up to date?
│  │  ├─ No → Install/update VPN client
│  │  └─ Yes → Continue
│  ├─ Correct VPN gateway/profile selected?
│  │  ├─ No → Configure correct gateway
│  │  └─ Yes → Continue
│  ├─ Authentication error?
│  │  ├─ Yes → See Authentication Failures below
│  │  └─ No → Continue
│  └─ Connection times out?
│     ├─ Firewall blocking? (port 443/UDP 4500) → Adjust firewall
│     └─ ISP blocking VPN? → Try different protocol/port
│
├─ Intermittent Disconnects
│  ├─ WiFi signal strength adequate?
│  ├─ Power saving disconnecting adapter?
│  ├─ VPN idle timeout configured?
│  └─ ISP stability issues?
│
├─ Slow Performance
│  ├─ Test speed without VPN vs with VPN
│  ├─ Split tunneling enabled for non-corporate traffic?
│  ├─ VPN gateway overloaded?
│  └─ Geographic distance to VPN gateway?
│
└─ Cannot Access Internal Resources (VPN connected)
   ├─ DNS resolving internal hostnames?
   ├─ Split tunneling routing correct?
   ├─ Firewall rules allowing VPN subnet?
   └─ Resource-specific access permissions?

Step-by-Step Troubleshooting

Cannot Connect — Authentication Failures

1. Verify {{ user_name }}'s AD/IdP account is not locked or disabled
2. Confirm VPN group membership is assigned
3. Check if MFA token/push is being received
4. Test credentials on another system (webmail, SSO portal)
5. If certificate-based: check certificate expiration date
6. Reset VPN-specific credentials if separate from domain credentials

Cannot Connect — Connection Timeout

1. Check if user's ISP or network blocks VPN ports
   • Typical ports: TCP 443, UDP 500, UDP 4500, UDP 1194
2. Try connecting from a different network (mobile hotspot)
3. Verify VPN gateway is operational (check status page / monitoring)
4. Check if {{ vpn_client }} needs a profile/configuration update
5. Clear VPN client cache and reconnect

Intermittent Disconnects

1. Check WiFi signal strength and stability
2. Disable WiFi power saving mode on {{ operating_system }}
3. Check VPN client logs for disconnect reason codes
4. Verify VPN keepalive/DPD settings
5. Test with wired ethernet connection
6. Check for conflicting VPN or firewall software

Slow VPN Performance

1. Run speed test WITHOUT VPN: record results
2. Run speed test WITH VPN: compare results
3. If >50% speed drop:
   • Check if split tunneling is configured (should be for non-work traffic)
   • Try connecting to a closer VPN gateway
   • Check VPN gateway utilization (server-side)
4. If DNS is slow: configure DNS to use VPN DNS servers only for internal domains

Connected but Cannot Access Resources

1. Verify VPN shows connected status with assigned IP
2. Test DNS resolution: nslookup internal-hostname
3. Test connectivity: ping internal-server-ip
4. Check routing table: route print (Windows) or netstat -rn (macOS/Linux)
5. Verify split tunnel routes include the target network
6. Check if resource requires additional authentication

Escalation Criteria

Escalate to network/infrastructure team if:

• VPN gateway is down or overloaded
• Multiple users reporting the same issue simultaneously
• Issue persists after all client-side troubleshooting
• Certificate infrastructure issues
• Firewall rule changes needed

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams

Output Format

Generate a troubleshooting report with:

1. Issue summary (user, symptom, client, OS)
2. Diagnostic steps taken with results
3. Resolution or escalation details
4. Root cause if identified