zitinexus-router-script/UI/README.md

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

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

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

```bash
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:

```bash
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`:

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

```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**
   ```php
   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**
   ```bash
   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**
   ```bash
   # 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**
   ```bash
   # 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**
   ```bash
   # 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**
   ```bash
   # 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`:

```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](https://docs.openziti.io/)

## License

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