Usage Guide

Basic Usage

Debian Doctor can be run in several ways depending on your needs and permissions.

Quick Start

# Basic system check (limited functionality)
./debian_doctor.sh

# Full system diagnostic (recommended)
sudo ./debian_doctor.sh

Command Options

Running Modes

Automatic Mode

By default, Debian Doctor runs in automatic mode, performing all system checks sequentially:

1. System Information Collection
2. Disk Space Analysis
3. Memory Status Check
4. Service Health Verification
5. Network Connectivity Test
6. Filesystem Integrity Check
7. System Log Analysis
8. Package System Verification

Interactive Diagnosis Mode

After automatic checks, you'll be prompted to enter interactive mode for targeted troubleshooting:

Selecting 'y' opens the interactive menu with specific diagnostic options.

System Checks Explained

Disk Space Check

Monitors filesystem usage with configurable thresholds:

• OK: Usage below 85%
• Warning: Usage between 85-95%
• Critical: Usage above 95%

Memory Status

Analyzes RAM and swap usage:

• Total and available memory
• Memory usage percentage
• Swap utilization
• Memory pressure indicators

Service Health

Checks critical system services:

• systemd-resolved (DNS)
• NetworkManager or networking
• systemd-timesyncd (Time sync)
• SSH daemon (if installed)

Network Connectivity

Verifies network configuration:

• Active network interfaces
• Default gateway presence
• DNS resolution capability
• Internet connectivity

System Logs

Analyzes recent system logs for:

• Critical errors
• Service failures
• Hardware issues
• Security events

Interactive Diagnosis Mode

The interactive menu provides targeted troubleshooting options:

Diagnostic Options

1. Boot Issues

• Checks boot loader configuration
• Analyzes failed services at startup
• Reviews kernel parameters
• Suggests fixes for common boot problems

2. Network Problems

• Tests DNS resolution
• Verifies network interfaces
• Checks firewall rules
• Offers network reset options

3. Package/APT Issues

• Checks for broken packages
• Verifies repository configuration
• Cleans package cache
• Fixes dependency problems

4. Disk Issues

• Identifies large files and directories
• Checks filesystem errors
• Analyzes disk I/O performance
• Suggests cleanup operations

5. Service Failures

• Lists failed services
• Provides service logs
• Offers service restart options
• Suggests configuration fixes

6. Performance Issues

• Identifies high CPU processes
• Checks memory usage patterns
• Analyzes system load
• Suggests optimization steps

Understanding Output

Color Coding

Log Files

Debian Doctor creates log files for detailed analysis:

# Log file location (user-specific)
/tmp/debian_doctor_$(id -u).log

# View the log file
cat /tmp/debian_doctor_$(id -u).log

# Follow log in real-time during execution
tail -f /tmp/debian_doctor_$(id -u).log

Summary Report

At the end of execution, a summary is provided:

Fixing Common Issues

Disk Space Problems

# Clean package cache
sudo apt-get clean
sudo apt-get autoclean

# Remove old kernels
sudo apt-get autoremove --purge

# Find large files
find / -type f -size +100M 2>/dev/null

Package System Issues

# Fix broken packages
sudo apt-get update --fix-missing
sudo apt-get install -f

# Reconfigure packages
sudo dpkg --configure -a

# Clean and update
sudo apt-get clean
sudo apt-get update

Service Failures

# Check service status
systemctl status service-name

# Restart service
sudo systemctl restart service-name

# View service logs
journalctl -u service-name -n 50

Network Problems

# Restart network manager
sudo systemctl restart NetworkManager

# Reset network configuration
sudo netplan apply  # For Ubuntu 18.04+

# Flush DNS cache
sudo systemd-resolve --flush-caches

Best Practices

Regular Maintenance

• Run Debian Doctor weekly for proactive monitoring
• Address warnings before they become critical
• Keep system packages updated
• Monitor disk space trends
• Review log files for recurring issues

Before System Updates

1. Run Debian Doctor to check system health
2. Fix any critical issues found
3. Ensure adequate disk space (at least 2GB free)
4. Verify all services are running properly
5. Create system backup if needed

Troubleshooting Workflow

1. Run automatic checks first
2. Note all warnings and errors
3. Use interactive mode for specific issues
4. Apply suggested fixes one at a time
5. Re-run checks to verify fixes
6. Check log file for detailed information

Security Considerations

• Run with sudo only when necessary
• Review fix commands before confirming
• Keep Debian Doctor updated
• Don't share log files containing sensitive data
• Verify script integrity after updates