Troubleshooting

A systematic guide to diagnosing and troubleshooting issues in VyOS. This guide covers common problems, a troubleshooting methodology, and practical solutions for all major system components.

Troubleshooting Methodology

Systematic Approach

Step 1: Define the problem

Precise description of the symptoms
Reproducibility of the problem
Time of occurrence (after changes, spontaneously)
Impact on users/services

Step 2: Gather information

System logs
Device configuration
Component status
Network topology

Step 3: Analyze

Event correlation
Hypothesis testing
Problem isolation

Step 4: Resolve

Apply the fix
Verify the result
Document the solution

Step 5: Prevent

Root cause analysis
Prevent recurrence
Update procedures

Diagnostic Tools

# Basic set of commands for initial diagnostics
show version                        # System version
show configuration                  # Current configuration
show interfaces                     # Interface status
show ip route                       # Routing table
show log tail 100                   # Last 100 log lines
show system uptime                  # System uptime
show system resources               # Resource usage

# Advanced diagnostics
monitor log                         # Real-time log monitoring
monitor traffic interface eth0      # Traffic capture
show conntrack table ipv4           # Connection table
show vpn ipsec sa                   # IPsec tunnel status
show dhcp server leases             # DHCP leases

Network Connectivity Issues

Problem: No Connectivity to a Remote Host

Diagnostics

# Step 1: Check the status of the local interface
show interfaces
show interfaces ethernet eth0

# Step 2: Check the IP configuration
show interfaces addresses

# Step 3: Check routing
show ip route
show ip route 8.8.8.8

# Step 4: Check connectivity
ping 8.8.8.8
ping 8.8.8.8 source-address <your-ip>

# Step 5: Trace the route
traceroute 8.8.8.8

# Step 6: Check DNS
nslookup google.com

Common Causes and Solutions

Cause 1: Interface is down

# Check the status
show interfaces ethernet eth0

# If the interface is administratively down
configure
delete interfaces ethernet eth0 disable
commit
save
exit

# Check the physical connection
show interfaces ethernet eth0 physical

Cause 2: Incorrect IP address configuration

# Check the current configuration
show interfaces ethernet eth0 address

# Fix the IP address
configure
set interfaces ethernet eth0 address 192.168.1.1/24
commit
save
exit

# Verify the result
show interfaces addresses
ping 192.168.1.254  # Gateway

Cause 3: Missing route

# Check the route to the target network
show ip route 8.8.8.8

# Add a default route if it is missing
configure
set protocols static route 0.0.0.0/0 next-hop 192.168.1.254
commit
save
exit

# Check routing
show ip route
ping 8.8.8.8

Cause 4: Firewall is blocking traffic

# Check firewall rules
show firewall

# Check rule counters
show firewall statistics

# Temporarily disable the firewall to test
configure
set firewall all-ping enable
set firewall state-policy established action accept
set firewall state-policy related action accept
commit

# Check connectivity
ping 8.8.8.8

# If it helped, configure the firewall correctly
set firewall name WAN_LOCAL default-action drop
set firewall name WAN_LOCAL rule 10 action accept
set firewall name WAN_LOCAL rule 10 state established enable
set firewall name WAN_LOCAL rule 10 state related enable
commit
save

Cause 5: MTU issues

# Check the MTU
show interfaces ethernet eth0

# Test with different packet sizes
ping 8.8.8.8 size 1472 do-not-fragment  # 1472 + 28 = 1500
ping 8.8.8.8 size 1400 do-not-fragment

# If large packets do not pass, reduce the MTU
configure
set interfaces ethernet eth0 mtu 1400
commit
save

# For PPPoE an MTU of 1492 is usually required
set interfaces ethernet eth0 mtu 1492

Problem: Slow Network Performance

Performance Diagnostics

# Check interface load
show interfaces
show interfaces counters

# Check for interface errors
show interfaces ethernet eth0 statistics

# Check duplex and speed
show interfaces ethernet eth0 physical

# Monitor traffic
monitor traffic interface eth0

# Check system resources
show system cpu
show system memory
show system storage

Common Causes and Solutions

Cause 1: Duplex mismatch

# Check the current settings
show interfaces ethernet eth0 physical

# If auto-negotiation is not working, set it manually
configure
set interfaces ethernet eth0 duplex full
set interfaces ethernet eth0 speed 1000
commit
save

# Restart the interface
sudo ip link set eth0 down
sudo ip link set eth0 up

Cause 2: High CPU load

# Check the CPU load
show system cpu
show system processes

# Identify the top consuming processes
top

# If the load comes from conntrack
show conntrack table ipv4 | wc -l

# Increase the conntrack table size
configure
set system conntrack table-size 262144
commit
save

# Optimize timeouts
set system conntrack timeout tcp established 432000
set system conntrack timeout tcp close 10

Cause 3: QoS limitations

# Check QoS policies
show qos

# Check policy application
show qos interface eth0

# Temporarily disable QoS to test
configure
delete traffic-policy
delete interfaces ethernet eth0 traffic-policy
commit

# If it helped, review the QoS configuration

Cause 4: DNS issues

# Check DNS resolution
nslookup google.com
dig google.com

# Check the DNS response time
time nslookup google.com

# If it is slow, change the DNS servers
configure
set system name-server 8.8.8.8
set system name-server 8.8.4.4
commit
save

# For DNS forwarding, check the cache
show dns forwarding statistics
reset dns forwarding cache

VPN Issues

Problem: IPsec Tunnel Does Not Come Up

IPsec Diagnostics

# Check IPsec status
show vpn ipsec sa
show vpn ipsec status

# Detailed tunnel information
show vpn ipsec sa detail

# Check the configuration
show configuration vpn ipsec

# IPsec logs
show log vpn ipsec
monitor log | match ipsec

Common Causes and Solutions

Cause 1: IKE/ESP parameter mismatch

# Check the parameters on both sides
show configuration vpn ipsec ike-group
show configuration vpn ipsec esp-group

# A typical working configuration
configure
set vpn ipsec ike-group IKE-SITE proposal 1 encryption aes256
set vpn ipsec ike-group IKE-SITE proposal 1 hash sha256
set vpn ipsec ike-group IKE-SITE proposal 1 dh-group 14
set vpn ipsec ike-group IKE-SITE lifetime 28800

set vpn ipsec esp-group ESP-SITE proposal 1 encryption aes256
set vpn ipsec esp-group ESP-SITE proposal 1 hash sha256
set vpn ipsec esp-group ESP-SITE lifetime 3600
set vpn ipsec esp-group ESP-SITE pfs dh-group14

commit
save

# Restart IPsec
sudo ipsec restart

Cause 2: Incorrect Pre-Shared Key

# Check the PSK configuration (the password is not shown)
show configuration vpn ipsec site-to-site peer <peer-ip> authentication

# Update the PSK
configure
set vpn ipsec site-to-site peer <peer-ip> authentication pre-shared-secret 'new-secret'
commit
save

# Restart the tunnel
reset vpn ipsec-peer <peer-ip>

Cause 3: Firewall is blocking IPsec traffic

# IPsec requires UDP 500 (IKE) and UDP 4500 (NAT-T)
# Also ESP (protocol 50)

configure
# Allow IKE
set firewall name WAN_LOCAL rule 100 action accept
set firewall name WAN_LOCAL rule 100 protocol udp
set firewall name WAN_LOCAL rule 100 destination port 500

# Allow NAT-T
set firewall name WAN_LOCAL rule 101 action accept
set firewall name WAN_LOCAL rule 101 protocol udp
set firewall name WAN_LOCAL rule 101 destination port 4500

# Allow ESP
set firewall name WAN_LOCAL rule 102 action accept
set firewall name WAN_LOCAL rule 102 protocol esp

commit
save

Cause 4: NAT conflict

# Check NAT rules
show nat source

# IPsec traffic must not pass through NAT
# Add an exclude rule
configure
set nat source rule 100 outbound-interface eth0
set nat source rule 100 source address 192.168.1.0/24
set nat source rule 100 destination address 192.168.2.0/24  # Remote network
set nat source rule 100 exclude

commit
save

Cause 5: Incorrect subnet configuration

# Check the local and remote prefixes
show configuration vpn ipsec site-to-site peer <peer-ip> tunnel

# Fix if incorrect
configure
set vpn ipsec site-to-site peer <peer-ip> tunnel 1 local prefix 192.168.1.0/24
set vpn ipsec site-to-site peer <peer-ip> tunnel 1 remote prefix 192.168.2.0/24
commit
save

# Restart the tunnel
reset vpn ipsec-peer <peer-ip>

# Check the status
show vpn ipsec sa

Problem: WireGuard Is Not Working

WireGuard Diagnostics

# Check the interface status
show interfaces wireguard wg0

# Check peers
show interfaces wireguard wg0 summary

# Check the handshake
show interfaces wireguard wg0 detail

# Check the configuration
show configuration interfaces wireguard wg0

Solutions for WireGuard

Cause 1: Incorrect public keys

# Generate new keys
generate wireguard default-keypair

# Get the public key to share with the peer
show wireguard keypairs pubkey default

# Set the peer's public key
configure
set interfaces wireguard wg0 peer <peer-name> public-key '<peer-public-key>'
commit
save

Cause 2: Firewall is blocking WireGuard

# WireGuard uses UDP (usually 51820)
configure
set firewall name WAN_LOCAL rule 200 action accept
set firewall name WAN_LOCAL rule 200 protocol udp
set firewall name WAN_LOCAL rule 200 destination port 51820
commit
save

Cause 3: No handshake with the peer

# Check the peer endpoint
show configuration interfaces wireguard wg0 peer <peer-name>

# Check persistent-keepalive
configure
set interfaces wireguard wg0 peer <peer-name> persistent-keepalive 25
commit
save

# Force the connection to initiate
ping <peer-wg-ip>

Routing Issues

Problem: BGP Neighbor Does Not Establish

BGP Diagnostics

# Check BGP neighbors
show ip bgp summary
show ip bgp neighbors
show ip bgp neighbors <neighbor-ip> advertised-routes
show ip bgp neighbors <neighbor-ip> received-routes

# Check the BGP configuration
show configuration protocols bgp

# BGP logs
show log | match bgp

Solutions for BGP

Cause 1: No TCP connectivity

# BGP uses TCP 179
# Check connectivity
telnet <neighbor-ip> 179

# Check the firewall
configure
set firewall name WAN_LOCAL rule 300 action accept
set firewall name WAN_LOCAL rule 300 protocol tcp
set firewall name WAN_LOCAL rule 300 destination port 179
commit
save

# Check the route to the neighbor
show ip route <neighbor-ip>

Cause 2: Incorrect BGP parameters

# Check the ASN on both sides
show configuration protocols bgp

# Check remote-as
show configuration protocols bgp <local-asn> neighbor <neighbor-ip>

# Fix if incorrect
configure
set protocols bgp <local-asn> neighbor <neighbor-ip> remote-as <correct-remote-asn>
commit
save

# Reset the BGP session
reset ip bgp <neighbor-ip>

Cause 3: MD5 authentication mismatch

# Check the MD5 password
show configuration protocols bgp <asn> neighbor <neighbor-ip> password

# Update the password (it must match the peer)
configure
set protocols bgp <asn> neighbor <neighbor-ip> password 'correct-password'
commit
save

# Reset the session
reset ip bgp <neighbor-ip>

Cause 4: TTL security

# For eBGP multihop
configure
set protocols bgp <asn> neighbor <neighbor-ip> ebgp-multihop 2
commit
save

# For TTL security
set protocols bgp <asn> neighbor <neighbor-ip> ttl-security hops 1

Problem: OSPF Adjacency Does Not Form

OSPF Diagnostics

# Check OSPF neighbors
show ip ospf neighbor
show ip ospf neighbor detail

# Check OSPF interfaces
show ip ospf interface

# Check the OSPF database
show ip ospf database

# OSPF configuration
show configuration protocols ospf

Solutions for OSPF

Cause 1: Area mismatch

# Check the area on both sides
show configuration protocols ospf area

# Fix the area
configure
set protocols ospf area 0 network 192.168.1.0/24
commit
save

Cause 2: Hello/Dead intervals do not match

# Check the intervals
show ip ospf interface eth1

# Set the intervals (they must match on both sides)
configure
set protocols ospf interface eth1 hello-interval 10
set protocols ospf interface eth1 dead-interval 40
commit
save

Cause 3: Authentication mismatch

# Configure MD5 authentication (must be identical on both sides)
configure
set protocols ospf area 0 authentication md5
set protocols ospf interface eth1 authentication md5 key-id 1 md5-key 'password'
commit
save

Cause 4: Passive interface

# Check passive interfaces
show configuration protocols ospf passive-interface

# If the interface is passive, remove it
configure
delete protocols ospf passive-interface eth1
commit
save

DHCP Issues

Problem: DHCP Clients Do Not Get Addresses

DHCP Server Diagnostics

# Check the DHCP server status
show service dhcp-server

# Check active leases
show dhcp server leases

# Check statistics
show dhcp server statistics

# Check the configuration
show configuration service dhcp-server

# DHCP logs
show log dhcp
monitor log | match dhcp

Solutions for DHCP

Cause 1: DHCP service is not running

# Check the service
show service dhcp-server

# Start the service
sudo systemctl restart isc-dhcp-server  # VyOS 1.4
sudo systemctl restart kea-dhcp4-server  # VyOS 1.5

# Check the status
sudo systemctl status isc-dhcp-server  # VyOS 1.4
sudo systemctl status kea-dhcp4-server  # VyOS 1.5

Cause 2: Incorrect subnet configuration

# Check the subnet configuration
show configuration service dhcp-server shared-network-name LAN

# Fix the subnet
configure
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 default-router 192.168.1.1
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 name-server 8.8.8.8
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 start 192.168.1.100
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 stop 192.168.1.200
commit
save

Cause 3: Pool exhausted

# Check the number of leases
show dhcp server leases

# Count active leases
show dhcp server leases | grep "^IP" | wc -l

# Expand the pool
configure
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 stop 192.168.1.250
commit
save

Cause 4: Firewall is blocking DHCP

# DHCP uses UDP 67 (server) and 68 (client)
configure
set firewall name LAN_LOCAL rule 400 action accept
set firewall name LAN_LOCAL rule 400 protocol udp
set firewall name LAN_LOCAL rule 400 destination port 67
set firewall name LAN_LOCAL rule 400 source port 68

commit
save

Cause 5: Static mapping conflict (VyOS 1.5 Kea)

# In VyOS 1.5 Kea requires an IP or hostname in addition to the MAC
configure
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping workstation mac '00:11:22:33:44:55'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping workstation ip-address '192.168.1.50'
commit
save

Problem: DHCP Client Does Not Get an Address on WAN

DHCP Client Diagnostics

# Check the interface status
show interfaces ethernet eth0

# Check the DHCP lease
show dhcp client leases

# Try to renew the lease
release dhcp interface eth0
renew dhcp interface eth0

# Logs
show log | match eth0

Solutions for DHCP Client

Cause 1: Interface is not set to DHCP

configure
set interfaces ethernet eth0 address dhcp
commit
save

Cause 2: DHCP client is not sending requests

# Capture traffic to check
sudo tcpdump -i eth0 port 67 or port 68 -v

# If there is no DHCP Discover, restart the interface
configure
delete interfaces ethernet eth0 disable
set interfaces ethernet eth0 disable
commit
delete interfaces ethernet eth0 disable
commit
save

Performance Issues

Problem: High CPU Load

CPU Diagnostics

# Check the CPU load
show system cpu
show system cpu detailed

# Top processes
show system processes

# Detailed process information
top

Solutions for CPU

Cause 1: Large conntrack table

# Check the conntrack table size
show conntrack table ipv4 | wc -l

# Check the limit
sudo sysctl net.netfilter.nf_conntrack_max

# Increase the limit
configure
set system conntrack table-size 262144
commit
save

# Optimize timeouts
set system conntrack timeout tcp close 10
set system conntrack timeout tcp time-wait 60
commit
save

# Apply immediately
sudo sysctl -w net.netfilter.nf_conntrack_max=262144

Cause 2: Intensive logging

# Check the log size
show log
du -sh /var/log/

# Reduce the logging level
configure
set system syslog global facility all level warning
commit
save

# Remove old logs
sudo find /var/log -name "*.log" -mtime +30 -delete

Cause 3: Many BGP prefixes

# Check the number of BGP prefixes
show ip bgp summary

# Apply prefix filtering
configure
set policy prefix-list BGP-IN rule 10 action permit
set policy prefix-list BGP-IN rule 10 prefix 0.0.0.0/0
set policy prefix-list BGP-IN rule 10 le 24

set policy route-map BGP-FILTER rule 10 action permit
set policy route-map BGP-FILTER rule 10 match ip address prefix-list BGP-IN

set protocols bgp <asn> neighbor <neighbor-ip> address-family ipv4-unicast route-map import BGP-FILTER

commit
save

Problem: High Memory Usage

Memory Diagnostics

# Check memory usage
show system memory

# Detailed information
free -h
cat /proc/meminfo

# Processes by memory usage
ps aux --sort=-%mem | head -20

Solutions for Memory

Cause 1: Large cache

# Check the cache
free -h

# Clear the page cache (safe)
sudo sync
sudo sysctl -w vm.drop_caches=1

# Clear dentries and inodes
sudo sysctl -w vm.drop_caches=2

# Clear everything
sudo sysctl -w vm.drop_caches=3

Cause 2: DNS forwarding cache is too large

# Check the DNS cache size
show dns forwarding statistics

# Reduce the cache size
configure
set service dns forwarding cache-size 1000
commit
save

# Clear the DNS cache
reset dns forwarding cache

Cause 3: Memory leak

# Identify the leaking process
ps aux --sort=-%mem | head -10

# If the problem is in a VyOS process, restart it
sudo systemctl restart frr  # For routing daemons
sudo systemctl restart vyos-configd  # For the config daemon

# As a last resort, reboot
reboot now

Problem: High Latency

Latency Diagnostics

# Check ping latency
ping 8.8.8.8
ping <local-gateway>

# Check for buffer bloat
show qos interface eth0

# Monitor latency
mtr 8.8.8.8

Solutions for Latency

Cause 1: Buffer bloat

# Apply fq_codel QoS
configure
set traffic-policy shaper WAN bandwidth 100mbit
set traffic-policy shaper WAN default bandwidth 100%
set traffic-policy shaper WAN default queue-type fq-codel

set interfaces ethernet eth0 traffic-policy out WAN

commit
save

Cause 2: High link utilization

# Check interface load
show interfaces

# Apply QoS prioritization
configure
set traffic-policy shaper WAN class 10 bandwidth 30%
set traffic-policy shaper WAN class 10 priority 1
set traffic-policy shaper WAN class 10 match VOIP ip dscp ef

set traffic-policy shaper WAN class 20 bandwidth 40%
set traffic-policy shaper WAN class 20 priority 2
set traffic-policy shaper WAN class 20 match INTERACTIVE ip dscp af21

commit
save

System Issues

Problem: Configuration Is Not Saved

Diagnostics

# Check the current configuration
show configuration

# Check the saved configuration
show configuration saved

# Compare
compare saved

Solutions

Cause 1: Forgot to run save

# Always after commit
commit
save

Cause 2: No space on disk

# Check disk space
show system storage

# If there is no space, clean up
sudo apt-get clean
sudo apt-get autoclean
delete system image <old-version>

# Remove old logs
sudo find /var/log -name "*.gz" -delete

Cause 3: Filesystem problems

# Check the filesystem (only in maintenance mode)
# Reboot into single user mode
sudo fsck /dev/sda1

Problem: System Does Not Boot After Changes

Solution: Boot With a Backup Configuration

# At boot, in the GRUB menu
# Select: VyOS (config file: /config/config.boot.backup)

# After booting, restore the configuration
configure
load /config/config.boot.backup
commit
save

Solution: Reset the Configuration

# In operational mode
load /opt/vyatta/etc/config.boot.default
commit
save
reboot

Problem: High Temperature / Hardware Issues

Hardware Diagnostics

# Temperature (if sensors are available)
show hardware cpu
show hardware temperature

# Check system logs for hardware errors
show log | match error
show log | match hardware

# Additional tools
sudo sensors
sudo dmesg | grep -i error

Solutions

Cause 1: High CPU temperature

# Check the fans (physical)
# Check the CPU load
show system cpu

# Reduce the load if possible
# Check the cooling system physically

Cause 2: Disk errors

# Check S.M.A.R.T.
sudo smartctl -a /dev/sda

# Check for filesystem errors
dmesg | grep -i "I/O error"

# Back up the configuration immediately
show configuration commands | sudo tee /tmp/config-backup.txt

# Plan the disk replacement

Service Issues

Problem: SSH Is Not Available

SSH Diagnostics

# Check the SSH service (from the console)
show service ssh

# Check the configuration
show configuration service ssh

# Check the process
sudo systemctl status ssh

# Check the port
sudo netstat -tlnp | grep ssh

Solutions for SSH

Cause 1: SSH service is disabled

configure
delete service ssh disable
commit
save

# Verify
show service ssh

Cause 2: Firewall is blocking SSH

configure
set firewall name WAN_LOCAL rule 500 action accept
set firewall name WAN_LOCAL rule 500 protocol tcp
set firewall name WAN_LOCAL rule 500 destination port 22
commit
save

Cause 3: Incorrect listen address

# SSH must listen on the correct interface
configure
set service ssh listen-address 0.0.0.0
commit
save

# Restart SSH
sudo systemctl restart ssh

Problem: NTP Does Not Synchronize

NTP Diagnostics

# Check the NTP status
show ntp

# Check the NTP servers
show configuration service ntp

# Detailed information
sudo ntpq -p

Solutions for NTP

Cause 1: No connectivity to the NTP servers

# Check reachability of the NTP servers
ping 0.pool.ntp.org
ping 1.pool.ntp.org

# Check UDP 123
sudo tcpdump -i eth0 udp port 123 -v

Cause 2: Firewall is blocking NTP

configure
set firewall name WAN_LOCAL rule 600 action accept
set firewall name WAN_LOCAL rule 600 protocol udp
set firewall name WAN_LOCAL rule 600 destination port 123

# Also allow outbound
set firewall name WAN_OUT rule 600 action accept
set firewall name WAN_OUT rule 600 protocol udp
set firewall name WAN_OUT rule 600 destination port 123

commit
save

Cause 3: Incorrect timezone

# Set the correct timezone
configure
set system time-zone Europe/Moscow
commit
save

# Restart NTP
sudo systemctl restart ntp

Collecting Diagnostic Information

Full Diagnostic Set for a Support Ticket

#!/bin/vbash
# Diagnostic information collection script

TIMESTAMP=$(date +%Y%m%d-%H%M%S)
OUTPUT_DIR="/tmp/vyos-diag-${TIMESTAMP}"
mkdir -p "${OUTPUT_DIR}"

echo "Collecting diagnostic information..."

# System information
show version > "${OUTPUT_DIR}/version.txt"
show system uptime > "${OUTPUT_DIR}/uptime.txt"
show system storage > "${OUTPUT_DIR}/storage.txt"
show system memory > "${OUTPUT_DIR}/memory.txt"
show system cpu > "${OUTPUT_DIR}/cpu.txt"

# Configuration
show configuration > "${OUTPUT_DIR}/configuration.txt"
show configuration commands > "${OUTPUT_DIR}/configuration-commands.txt"

# Interfaces
show interfaces > "${OUTPUT_DIR}/interfaces.txt"
show interfaces addresses > "${OUTPUT_DIR}/interfaces-addresses.txt"

# Routing
show ip route > "${OUTPUT_DIR}/ip-route.txt"
show ipv6 route > "${OUTPUT_DIR}/ipv6-route.txt"

# BGP (if used)
show ip bgp summary > "${OUTPUT_DIR}/bgp-summary.txt" 2>/dev/null
show ip bgp neighbors > "${OUTPUT_DIR}/bgp-neighbors.txt" 2>/dev/null

# OSPF (if used)
show ip ospf neighbor > "${OUTPUT_DIR}/ospf-neighbors.txt" 2>/dev/null

# VPN
show vpn ipsec sa > "${OUTPUT_DIR}/ipsec-sa.txt" 2>/dev/null
show interfaces wireguard > "${OUTPUT_DIR}/wireguard.txt" 2>/dev/null

# Firewall
show firewall > "${OUTPUT_DIR}/firewall.txt"
show firewall statistics > "${OUTPUT_DIR}/firewall-stats.txt"

# NAT
show nat source statistics > "${OUTPUT_DIR}/nat-stats.txt"

# Services
show dhcp server leases > "${OUTPUT_DIR}/dhcp-leases.txt" 2>/dev/null
show dns forwarding statistics > "${OUTPUT_DIR}/dns-stats.txt" 2>/dev/null

# Logs (last 500 lines)
show log tail 500 > "${OUTPUT_DIR}/system-log.txt"

# Conntrack
show conntrack table ipv4 | head -100 > "${OUTPUT_DIR}/conntrack-sample.txt"

# Archive
cd /tmp
tar czf "vyos-diag-${TIMESTAMP}.tar.gz" "vyos-diag-${TIMESTAMP}/"

echo "Diagnostic information collected:"
echo "/tmp/vyos-diag-${TIMESTAMP}.tar.gz"
ls -lh "/tmp/vyos-diag-${TIMESTAMP}.tar.gz"

echo ""
echo "You can download this file with SCP:"
echo "scp vyos@router-ip:/tmp/vyos-diag-${TIMESTAMP}.tar.gz ."

Save the Script and Use It

# Save the script
sudo vi /config/scripts/collect-diag.sh
# Paste the code above
sudo chmod +x /config/scripts/collect-diag.sh

# Run it
sudo /config/scripts/collect-diag.sh

Troubleshooting Best Practices

General Recommendations

Always create a backup before making changes

save /config/config.boot.backup-$(date +%Y%m%d)

Use commit-confirm for critical changes

commit-confirm 5  # Auto-rollback after 5 minutes if not confirmed
# Test the changes
confirm  # If everything is OK
# Or just wait 5 minutes for auto-rollback

Document your changes

commit comment "Added firewall rule for SSH access from office"

Use compare to review changes

compare  # Compare with the running config
compare saved  # Compare with the saved config

Monitor logs during troubleshooting

monitor log  # In a separate SSH session

Test changes incrementally

# Apply changes one at a time
set ...
commit
# Verify
# Next change

Save the working configuration regularly

save
save /config/config.boot.working

Use rollback when needed

rollback 1  # Roll back 1 commit
rollback 2  # Roll back 2 commits

Keep a change log

# Create a CHANGELOG file
sudo vi /config/CHANGELOG
# Record all significant changes

Automate diagnostic collection

# Create a cron task for a daily configuration backup
set system task-scheduler task daily-backup executable path /config/scripts/daily-backup.sh
set system task-scheduler task daily-backup interval 1d

Checklist for Critical Problems

On connectivity loss:

Check the physical link
Check the IP addressing
Check routing
Check firewall rules
Check NAT rules (if applicable)
Check the MTU
Check the ARP table

On VPN problems:

Check connectivity to the peer
Check the firewall (UDP 500, 4500, ESP)
Check IKE/ESP parameters
Check PSK/certificates
Check NAT exclude rules
Check routing through the VPN

On routing protocol problems:

Check adjacency/peering
Check authentication
Check timers/intervals
Check ACLs/prefix-lists
Check route-maps
Check redistribution

On performance problems:

Check CPU usage
Check memory usage
Check disk space
Check interface statistics (errors, drops)
Check the conntrack table size
Check QoS policies
Check hardware (temperature, fans)

Useful Resources

Official Documentation

VyOS Documentation: https://docs.vyos.io/
VyOS Wiki: https://wiki.vyos.net/
VyOS Forum: https://forum.vyos.io/

Community

VyOS Slack: https://vyos.slack.com/
VyOS Reddit: https://www.reddit.com/r/vyos/
GitHub Issues: https://github.com/vyos/vyos-1x/issues

Useful Reference Commands

# Search for commands
find /configure/

# Help for a command
help <command>

# Autocompletion
<Tab>

# Command history
history

# Clear the screen
clear

Conclusion

Effective troubleshooting in VyOS requires:

A systematic approach: Following the methodology from symptoms to solution
Knowledge of the tools: Using the right diagnostic commands
Experience: Understanding common problems and their solutions
Documentation: Keeping a log of changes and solutions
Prevention: Monitoring and preventing problems

Use this guide as a reference when problems arise, but also develop your analysis and diagnostic skills to resolve non-standard situations.

Reviewed by OpenNix LLC · Last updated on 29 July 2026

VyOS Operation Mode VyOS - Configuration Blueprints and Architecture