zitinexus-router-script/UI/INSTALLATION_GUIDE.md

ZitiNexus Router Enrollment UI - Installation Guide

Quick Start

Prerequisites

• Ubuntu 22.04 or 24.04 LTS
• Root/sudo access
• Internet connectivity

Automated Installation

1. Download and extract the UI files to your server

2. Run the installation script:

   cd UI
   sudo chmod +x install.sh
   sudo ./install.sh
   

3. Follow the prompts to select your web server (Apache or Nginx)

4. Access the interface:

   • URL: http://ziti-enrollment.local
   • Username: admin
   • Password: admin123

Manual Installation

If you prefer manual installation, follow the detailed steps in README.md.

Post-Installation Steps

1. Change Default Password (IMPORTANT)

Edit /var/www/ziti-enrollment/includes/config.php:

// Change this line:
define('ADMIN_PASSWORD_HASH', password_hash('your-new-secure-password', PASSWORD_DEFAULT));

2. Configure for Production

Enable HTTPS

# Install SSL certificate (example with Let's Encrypt)
sudo apt install certbot python3-certbot-apache  # or python3-certbot-nginx
sudo certbot --apache -d your-domain.com        # or --nginx

Secure File Permissions

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

Configure Firewall

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

3. Test the Installation

1. Access the web interface
2. Login with your credentials
3. Check system status on the dashboard
4. Test enrollment with a valid hash key

Troubleshooting

Common Issues

1. Permission Denied Errors

# Fix ownership
sudo chown -R www-data:www-data /var/www/ziti-enrollment

# Fix permissions
sudo chmod -R 755 /var/www/ziti-enrollment
sudo chmod -R 777 /var/www/ziti-enrollment/logs /var/www/ziti-enrollment/temp

2. PHP Functions Disabled

# Check disabled functions
php -r "echo ini_get('disable_functions');"

# Edit PHP configuration
sudo nano /etc/php/8.1/apache2/php.ini  # or /etc/php/8.1/fpm/php.ini

# Remove exec, shell_exec, proc_open from disable_functions line
# Restart web server
sudo systemctl restart apache2  # or nginx and php8.1-fpm

3. Sudo Access Issues

# Test sudo access
sudo -u www-data sudo -l

# If issues, recreate sudoers file
sudo tee /etc/sudoers.d/ziti-enrollment << 'EOF'
www-data ALL=(ALL) NOPASSWD: /usr/bin/apt-get, /usr/bin/systemctl, /usr/bin/mkdir, /usr/bin/chmod, /usr/bin/chown, /usr/bin/curl, /usr/bin/gpg, /usr/bin/ziti, /usr/bin/which, /usr/bin/hostname, /usr/bin/uname, /usr/bin/lsb_release
EOF

# Validate
sudo visudo -c

4. Web Server Not Starting

# Check status
sudo systemctl status apache2  # or nginx

# Check logs
sudo journalctl -u apache2 -f  # or nginx

# Check configuration
sudo apache2ctl configtest  # or nginx -t

Log Files

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

Security Checklist

• Changed default password
• Configured HTTPS
• Set proper file permissions
• Configured firewall
• Restricted network access (if needed)
• Regular security updates scheduled
• Log monitoring configured

Support

For technical support:

1. Check the logs for error messages
2. Verify system requirements are met
3. Test individual components (web server, PHP, sudo access)
4. Review the troubleshooting section
5. Consult the main README.md for detailed information

Uninstallation

To remove the UI:

# Stop and disable web server
sudo systemctl stop apache2  # or nginx php8.1-fpm
sudo systemctl disable apache2  # or nginx php8.1-fpm

# Remove files
sudo rm -rf /var/www/ziti-enrollment
sudo rm -f /etc/apache2/sites-available/ziti-enrollment.conf  # or /etc/nginx/sites-available/ziti-enrollment
sudo rm -f /etc/apache2/sites-enabled/ziti-enrollment.conf   # or /etc/nginx/sites-enabled/ziti-enrollment
sudo rm -f /etc/sudoers.d/ziti-enrollment

# Remove from hosts file
sudo sed -i '/ziti-enrollment.local/d' /etc/hosts

# Optionally remove packages
sudo apt remove apache2 php8.1 libapache2-mod-php8.1  # or nginx php8.1-fpm
sudo apt autoremove

---

Note: This UI complements the original bash script and provides the same functionality through a modern web interface. Both tools can coexist on the same system.