zitinexus-router-script/UI/TROUBLESHOOTING.md

# ZitiNexus Router Enrollment UI - Troubleshooting Guide

This guide helps resolve common issues with the ZitiNexus Router Enrollment UI, particularly the GPG key installation failure on CloudStack instances.

## Quick Fix Steps

### 1. Fix File Permissions and Configuration

On your CloudStack instance, run these commands as root:

```bash
# Navigate to the UI directory
cd /path/to/your/UI/directory

# Make the fix script executable
chmod +x fix-permissions.sh

# Run the fix script
sudo ./fix-permissions.sh
```

### 2. Access the Diagnostic Script

After running the fix script, access the diagnostic tool:

```
http://your-server-ip/debug-command-execution.php
```

This will show you exactly what's failing and provide specific recommendations.

## Common Issues and Solutions

### Issue 1: "File not found" when accessing diagnostic script

**Cause**: The web server document root is not configured correctly, or files are in the wrong location.

**Solution**:
1. Check if the installation was completed properly
2. Ensure files are in `/var/www/ziti-enrollment/public/`
3. Run the fix-permissions script

### Issue 2: "Failed to add OpenZiti GPG key"

**Cause**: PHP execution environment differences between manual execution and web server execution.

**Root Causes**:
- PHP-FPM has restricted execution permissions
- Sudo configuration issues for www-data user
- Environment variables not properly set
- GPG command execution context problems

**Solutions**:

#### Option A: Fix Web Server Execution (Recommended)
```bash
# 1. Fix sudo permissions
sudo visudo -f /etc/sudoers.d/ziti-enrollment

# Add these lines:
www-data ALL=(ALL) NOPASSWD: /usr/bin/curl
www-data ALL=(ALL) NOPASSWD: /usr/bin/gpg
www-data ALL=(ALL) NOPASSWD: /usr/bin/mkdir
www-data ALL=(ALL) NOPASSWD: /usr/bin/chmod
www-data ALL=(ALL) NOPASSWD: /usr/bin/cp
www-data ALL=(ALL) NOPASSWD: /usr/bin/apt-get
www-data ALL=(ALL) NOPASSWD: /usr/bin/systemctl

# 2. Test sudo access
sudo -u www-data sudo -n whoami

# 3. Create keyrings directory
sudo mkdir -p /usr/share/keyrings
sudo chmod 755 /usr/share/keyrings

# 4. Test GPG key download manually
sudo -u www-data curl -sSLf https://get.openziti.io/tun/package-repos.gpg -o /tmp/test-gpg.key
sudo -u www-data sudo gpg --dearmor --output /usr/share/keyrings/test.gpg /tmp/test-gpg.key
```

#### Option B: Use CLI Instead of Web Interface
```bash
# Run the enrollment script directly via SSH
cd /path/to/Router-enrollment-script/
sudo ./enroll-router.sh
```

#### Option C: Manual GPG Key Installation
```bash
# Download and install GPG key manually
curl -sSLf https://get.openziti.io/tun/package-repos.gpg | sudo gpg --dearmor --output /usr/share/keyrings/openziti.gpg
sudo chmod a+r /usr/share/keyrings/openziti.gpg

# Add repository
echo 'deb [signed-by=/usr/share/keyrings/openziti.gpg] https://packages.openziti.org/zitipax-openziti-deb-stable debian main' | sudo tee /etc/apt/sources.list.d/openziti-release.list

# Update and install
sudo apt update
sudo apt install -y openziti-router
```

### Issue 3: PHP-FPM Execution Restrictions

**Symptoms**: Commands work manually but fail through web interface

**Cause**: PHP-FPM runs with restricted permissions and environment

**Solutions**:

1. **Configure PHP-FPM for better command execution**:
```bash
# Edit PHP-FPM pool configuration
sudo nano /etc/php/8.x/fpm/pool.d/www.conf

# Add these lines:
env[PATH] = /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
env[HOME] = /var/www
env[SHELL] = /bin/bash
```

2. **Restart PHP-FPM**:
```bash
sudo systemctl restart php8.x-fpm
```

### Issue 4: Network Connectivity Issues

**Symptoms**: Cannot reach get.openziti.io

**Solutions**:
```bash
# Test connectivity
ping get.openziti.io
curl -I https://get.openziti.io

# Check DNS resolution
nslookup get.openziti.io

# Check firewall rules
sudo ufw status
sudo iptables -L
```

### Issue 5: Missing Dependencies

**Symptoms**: Commands not found (curl, gpg, jq)

**Solution**:
```bash
sudo apt update
sudo apt install -y curl gnupg jq
```

## Diagnostic Commands

Run these commands to diagnose issues:

```bash
# Check web server status
sudo systemctl status apache2  # or nginx
sudo systemctl status php8.x-fpm  # for Nginx

# Check file permissions
ls -la /var/www/ziti-enrollment/
ls -la /var/www/ziti-enrollment/public/

# Check sudo configuration
sudo -u www-data sudo -l

# Test GPG key download
curl -sSLf https://get.openziti.io/tun/package-repos.gpg -o /tmp/test.gpg
file /tmp/test.gpg

# Test GPG dearmor
gpg --dearmor --output /tmp/test.gpg.dearmored /tmp/test.gpg
ls -la /tmp/test.gpg*
```

## Environment-Specific Issues

### CloudStack Instances

CloudStack instances often have:
- Restrictive security policies
- Different network configurations
- Limited sudo access for web server users

**CloudStack-specific fixes**:
1. Ensure the instance has outbound internet access
2. Check security groups allow HTTPS traffic
3. Verify DNS resolution works properly
4. Consider using the CLI enrollment method instead

### Ubuntu 24.04 Specific

Ubuntu 24.04 may have:
- Different PHP-FPM configurations
- Updated security policies
- Different package versions

**Ubuntu 24.04 fixes**:
```bash
# Install specific PHP version
sudo apt install -y php8.3 php8.3-fpm php8.3-curl

# Update sudoers with full paths
which curl gpg apt-get systemctl
# Use the full paths in sudoers configuration
```

## Alternative Solutions

### 1. Use Docker Container
```bash
# Run enrollment in a container with proper permissions
docker run -it --rm -v /etc/zitirouter:/etc/zitirouter ubuntu:24.04 bash
# Then run enrollment commands inside container
```

### 2. Create Wrapper Script
```bash
# Create a wrapper script that runs with proper permissions
sudo tee /usr/local/bin/ziti-enroll-wrapper.sh << 'EOF'
#!/bin/bash
export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
export HOME="/root"
export GNUPGHOME="/root/.gnupg"
exec "$@"
EOF

sudo chmod +x /usr/local/bin/ziti-enroll-wrapper.sh

# Update sudoers to use wrapper
www-data ALL=(ALL) NOPASSWD: /usr/local/bin/ziti-enroll-wrapper.sh
```

### 3. Use systemd Service
```bash
# Create a systemd service for enrollment
sudo tee /etc/systemd/system/ziti-enrollment.service << 'EOF'
[Unit]
Description=Ziti Router Enrollment
After=network.target

[Service]
Type=oneshot
ExecStart=/path/to/enrollment/script
User=root
Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

[Install]
WantedBy=multi-user.target
EOF

# Trigger enrollment via systemd
sudo systemctl start ziti-enrollment
```

## Getting Help

If you continue to experience issues:

1. **Run the diagnostic script** and save the results
2. **Check the log files**:
   - `/var/www/ziti-enrollment/logs/ui-enrollment.log`
   - `/var/log/apache2/error.log` (or nginx equivalent)
   - `/var/log/syslog`

3. **Gather system information**:
```bash
# System info
uname -a
lsb_release -a
php -v
systemctl status apache2  # or nginx

# Network info
ip addr show
cat /etc/resolv.conf

# Permission info
id www-data
sudo -u www-data sudo -l
```

4. **Contact support** with the diagnostic results and system information

## Prevention

To prevent similar issues in the future:

1. **Use the CLI enrollment method** for production deployments
2. **Test the web interface** in a development environment first
3. **Document your specific environment** requirements and configurations
4. **Keep backups** of working configurations
5. **Monitor logs** regularly for early detection of issues

---

**Note**: This troubleshooting guide is specifically designed for the GPG key installation failure issue on CloudStack instances, but the solutions apply to similar environments with restricted execution contexts.