zitinexus-router-script/UI

ZitiNexus Router Enrollment UI

A modern PHP-based web interface for enrolling OpenZiti routers using the ZitiNexus Portal. This UI provides a user-friendly alternative to the command-line enrollment script.

Features

• Modern Web Interface: Clean, responsive design with real-time progress tracking
• Authentication System: Secure login with session management
• System Status Monitoring: Real-time display of Ziti CLI, service, and configuration status
• Interactive Enrollment: Step-by-step enrollment process with live progress updates
• Input Validation: Client-side and server-side validation for hash keys and API endpoints
• Comprehensive Logging: Detailed logs with different severity levels
• Mobile Responsive: Works on desktop, tablet, and mobile devices

System Requirements

• Operating System: Ubuntu 22.04 or 24.04 LTS
• Web Server: Apache 2.4+ or Nginx 1.18+
• PHP: 8.0 or higher with extensions:
  • curl
  • json
  • posix
  • proc_open/exec functions enabled
• Root Access: Required for system operations (router installation, service management)
• Internet Connectivity: For downloading packages and API communication

Installation

1. Install Web Server and PHP

For Apache:

sudo apt update
sudo apt install apache2 php8.1 php8.1-curl php8.1-json libapache2-mod-php8.1
sudo systemctl enable apache2
sudo systemctl start apache2

For Nginx:

sudo apt update
sudo apt install nginx php8.1-fpm php8.1-curl php8.1-json
sudo systemctl enable nginx php8.1-fpm
sudo systemctl start nginx php8.1-fpm

2. Deploy the UI

# Create web directory
sudo mkdir -p /var/www/ziti-enrollment

# Copy UI files
sudo cp -r UI/* /var/www/ziti-enrollment/

# Set proper permissions
sudo chown -R www-data:www-data /var/www/ziti-enrollment
sudo chmod -R 755 /var/www/ziti-enrollment
sudo chmod -R 777 /var/www/ziti-enrollment/logs
sudo chmod -R 777 /var/www/ziti-enrollment/temp

3. Configure Web Server

Apache Virtual Host:

sudo tee /etc/apache2/sites-available/ziti-enrollment.conf << 'EOF'
<VirtualHost *:80>
    ServerName ziti-enrollment.local
    DocumentRoot /var/www/ziti-enrollment/public
    
    <Directory /var/www/ziti-enrollment/public>
        AllowOverride All
        Require all granted
        DirectoryIndex index.php
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/ziti-enrollment_error.log
    CustomLog ${APACHE_LOG_DIR}/ziti-enrollment_access.log combined
</VirtualHost>
EOF

# Enable site and rewrite module
sudo a2ensite ziti-enrollment.conf
sudo a2enmod rewrite
sudo systemctl reload apache2

Nginx Configuration:

sudo tee /etc/nginx/sites-available/ziti-enrollment << 'EOF'
server {
    listen 80;
    server_name ziti-enrollment.local;
    root /var/www/ziti-enrollment/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\. {
        deny all;
    }
}
EOF

# Enable site
sudo ln -s /etc/nginx/sites-available/ziti-enrollment /etc/nginx/sites-enabled/
sudo systemctl reload nginx

4. Configure PHP for System Commands

Edit PHP configuration to allow system command execution:

# Find PHP configuration file
php --ini

# Edit php.ini (example path)
sudo nano /etc/php/8.1/apache2/php.ini

# Ensure these functions are NOT in disable_functions:
# exec, shell_exec, system, proc_open, proc_close, proc_get_status

# Restart web server
sudo systemctl restart apache2  # or nginx

5. Set Up Sudo Access for Web Server

The web server needs to run system commands as root. Create a sudoers file:

sudo tee /etc/sudoers.d/ziti-enrollment << 'EOF'
# Allow www-data to run system commands for Ziti enrollment
www-data ALL=(ALL) NOPASSWD: /usr/bin/apt-get
www-data ALL=(ALL) NOPASSWD: /usr/bin/systemctl
www-data ALL=(ALL) NOPASSWD: /usr/bin/mkdir
www-data ALL=(ALL) NOPASSWD: /usr/bin/chmod
www-data ALL=(ALL) NOPASSWD: /usr/bin/chown
www-data ALL=(ALL) NOPASSWD: /usr/bin/curl
www-data ALL=(ALL) NOPASSWD: /usr/bin/gpg
www-data ALL=(ALL) NOPASSWD: /usr/bin/ziti
www-data ALL=(ALL) NOPASSWD: /usr/bin/which
www-data ALL=(ALL) NOPASSWD: /usr/bin/hostname
www-data ALL=(ALL) NOPASSWD: /usr/bin/uname
www-data ALL=(ALL) NOPASSWD: /usr/bin/lsb_release
EOF

# Validate sudoers file
sudo visudo -c

6. Update Hosts File (Optional)

For local testing, add the domain to your hosts file:

echo "127.0.0.1 ziti-enrollment.local" | sudo tee -a /etc/hosts

Configuration

Default Credentials

• Username: admin
• Password: admin123

⚠️ Important: Change the default password in production by modifying UI/includes/config.php:

define('ADMIN_PASSWORD_HASH', password_hash('your-new-password', PASSWORD_DEFAULT));

API Endpoint

The default API endpoint is set to https://backend.zitinexus.com. You can modify this in UI/includes/config.php:

define('DEFAULT_API_ENDPOINT', 'https://your-api-endpoint.com');

File Paths

All file paths match the original bash script:

• Configuration: /etc/zitirouter/
• Certificates: /etc/zitirouter/certs/
• Logs: /var/log/ziti-router-enrollment.log
• Service: /etc/systemd/system/ziti-router.service

Usage

1. Access the Interface

   • Open your web browser
   • Navigate to http://ziti-enrollment.local (or your configured domain)
   • Login with the default credentials

2. Check System Status

   • The dashboard shows current system status
   • Ziti CLI installation status
   • Router service status
   • Configuration status
   • System hostname

3. Enroll a Router

   • Obtain a hash key from ZitiNexus Portal
   • Enter the API endpoint (pre-filled with default)
   • Paste the 32-character hash key
   • Click "Start Enrollment"
   • Monitor progress and logs in real-time

4. Monitor Progress

   • Progress bar shows overall completion
   • Step indicators show current phase
   • Live log output shows detailed progress
   • System status updates automatically after enrollment

Security Considerations

Production Deployment

1. Change Default Password

   define('ADMIN_PASSWORD_HASH', password_hash('strong-password-here', PASSWORD_DEFAULT));
   

2. Use HTTPS

   • Configure SSL/TLS certificates
   • Redirect HTTP to HTTPS
   • Update virtual host configuration

3. Restrict Access

   • Use firewall rules to limit access
   • Consider VPN or IP whitelisting
   • Implement additional authentication if needed

4. File Permissions

   sudo chmod 600 /var/www/ziti-enrollment/includes/config.php
   sudo chown root:www-data /var/www/ziti-enrollment/includes/config.php
   

5. Regular Updates

   • Keep PHP and web server updated
   • Monitor security advisories
   • Review logs regularly

Troubleshooting

Common Issues

1. Permission Denied Errors

   # Check web server user
   ps aux | grep apache2  # or nginx
   
   # Ensure proper ownership
   sudo chown -R www-data:www-data /var/www/ziti-enrollment
   
   # Check sudoers configuration
   sudo -u www-data sudo -l
   

2. PHP Function Disabled

   # Check disabled functions
   php -r "echo ini_get('disable_functions');"
   
   # Edit php.ini to remove exec, shell_exec, proc_open from disable_functions
   sudo nano /etc/php/8.1/apache2/php.ini
   sudo systemctl restart apache2
   

3. System Command Failures

   # Test sudo access
   sudo -u www-data sudo systemctl status ziti-router
   
   # Check system logs
   sudo tail -f /var/log/syslog
   sudo tail -f /var/log/ziti-router-enrollment.log
   

4. Web Server Issues

   # Check web server status
   sudo systemctl status apache2  # or nginx
   
   # Check error logs
   sudo tail -f /var/log/apache2/error.log
   sudo tail -f /var/log/nginx/error.log
   

Debug Mode

Enable debug logging by modifying UI/includes/config.php:

// Add at the top of config.php
error_reporting(E_ALL);
ini_set('display_errors', 1);
ini_set('log_errors', 1);
ini_set('error_log', '/var/log/php_errors.log');

Log Files

• UI Logs: /var/www/ziti-enrollment/logs/ui-enrollment.log
• System Logs: /var/log/ziti-router-enrollment.log
• Web Server Logs: /var/log/apache2/ or /var/log/nginx/
• PHP Logs: /var/log/php_errors.log

API Compatibility

This UI is fully compatible with the ZitiNexus Portal API and replicates all functionality of the original bash script:

• Router registration with hash key validation
• JWT token and configuration download
• OpenZiti CLI installation and setup
• Router enrollment and certificate generation
• Systemd service creation and management
• Status reporting back to portal

Development

File Structure

UI/
├── public/
│   ├── index.php          # Login page
│   └── dashboard.php      # Main dashboard
├── includes/
│   ├── config.php         # Configuration and utilities
│   ├── auth.php           # Authentication handler
│   ├── api_client.php     # API communication
│   └── enrollment.php     # Core enrollment logic
├── assets/
│   ├── css/style.css      # Styling
│   └── js/app.js          # Frontend JavaScript
├── logs/                  # UI-specific logs
├── temp/                  # Temporary files
└── README.md              # This file

Contributing

1. Follow PSR-12 coding standards for PHP
2. Use modern JavaScript (ES6+)
3. Maintain responsive design principles
4. Add comprehensive error handling
5. Update documentation for any changes

Support

For issues related to:

• UI functionality: Check logs and configuration
• ZitiNexus Portal: Contact your portal administrator
• OpenZiti: Visit OpenZiti Documentation

License

This project follows the same license as the original ZitiNexus Router Script.