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:

# 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)

# 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

# Run the enrollment script directly via SSH
cd /path/to/Router-enrollment-script/
sudo ./enroll-router.sh

Option C: Manual GPG Key Installation

# 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:

# 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:

sudo systemctl restart php8.x-fpm

Issue 4: Network Connectivity Issues

Symptoms: Cannot reach get.openziti.io

Solutions:

# 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:

sudo apt update
sudo apt install -y curl gnupg jq

Diagnostic Commands

Run these commands to diagnose issues:

# 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:

# 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

# 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

# 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

# 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:

# 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.