# Router Enrollment Script Installation Guide

This guide provides step-by-step instructions for installing and using the OpenZiti Router Enrollment Script on Ubuntu Linux systems.

## Quick Installation

```bash
# 1. Download the script package
wget https://your-portal.com/downloads/router-enrollment-script.tar.gz

# 2. Extract the package
tar -xzf router-enrollment-script.tar.gz
cd Router-enrollment-script

# 3. Make scripts executable
chmod +x *.sh

# 4. Run the enrollment script
sudo ./enroll-router.sh
```

## Manual Installation

### Step 1: Download Files

Copy these files to your Ubuntu router machine:
- `enroll-router.sh` - Main enrollment script
- `test-enrollment.sh` - Testing script
- `config.sh` - Configuration file
- `README.md` - Documentation

### Step 2: Set Permissions

```bash
chmod +x enroll-router.sh
chmod +x test-enrollment.sh
chmod +x config.sh
```

### Step 3: Configure (Optional)

Edit `config.sh` to customize settings:

```bash
nano config.sh
```

Key settings to modify:
- `DEFAULT_API_ENDPOINT` - Your ZitiNexus Portal API URL
- `CONFIG_DIR` - Router configuration directory
- `LOG_FILE` - Log file location

### Step 4: Test Prerequisites

Run the test script to verify system readiness:

```bash
./test-enrollment.sh
```

Select option 6 to run all tests.

### Step 5: Run Enrollment

Execute the main enrollment script:

```bash
sudo ./enroll-router.sh
```

## Prerequisites

### System Requirements

- **Operating System**: Ubuntu 22.04, 24.04, or compatible Linux distribution
- **Architecture**: x86_64 (amd64) or ARM64
- **Memory**: Minimum 512MB RAM
- **Disk Space**: Minimum 100MB free space
- **Network**: Internet connectivity for downloads and API calls

### Required Permissions

- **Root Access**: Script must be run with `sudo`
- **Network Access**: Outbound HTTPS (port 443) to:
  - ZitiNexus Portal API
  - OpenZiti controller
  - Package repositories
  - OpenZiti installation sources

### Dependencies

The script will automatically install these if missing:
- `curl` - For API calls and downloads
- `jq` - For JSON processing
- `systemctl` - For service management (usually pre-installed)

## Configuration Options

### Basic Configuration

Edit the `DEFAULT_API_ENDPOINT` in `config.sh`:

```bash
DEFAULT_API_ENDPOINT="https://your-portal.example.com/api"
```

### Advanced Configuration

Customize these settings in `config.sh`:

```bash
# Directory locations
CONFIG_DIR="/etc/zitirouter"
LOG_FILE="/var/log/ziti-router-enrollment.log"

# API settings
API_CONNECT_TIMEOUT=30
MAX_API_RETRIES=3

# Service settings
SERVICE_NAME="ziti-router"
SERVICE_RESTART_DELAY=5
```

### Environment-Specific Configuration

Create local configuration files:

```bash
# System-wide configuration
sudo mkdir -p /etc/zitirouter
sudo nano /etc/zitirouter/local.conf

# User-specific configuration
nano ~/.ziti-router-enrollment.conf
```

## Usage Examples

### Basic Enrollment

```bash
sudo ./enroll-router.sh
```

Follow the prompts:
1. Enter API endpoint (or press Enter for default)
2. Enter hash key from ZitiNexus Portal

### Testing Before Enrollment

```bash
# Test system requirements
./test-enrollment.sh

# Select option 4: Test System Requirements
# Select option 1: Test API Connectivity
# Select option 3: Test API Registration Call (with real hash key)
```

### Checking Installation

```bash
# Check router service status
systemctl status ziti-router

# View router logs
journalctl -u ziti-router -f

# Check configuration
cat /etc/zitirouter/router.yaml

# View enrollment log
tail -f /var/log/ziti-router-enrollment.log
```

## Troubleshooting

### Common Issues

#### 1. Permission Denied

```bash
# Error: Permission denied
sudo ./enroll-router.sh
```

#### 2. Hash Key Not Found

```bash
# Error: Hash key not found
# Solution: Verify hash key from portal, check if expired (24h limit)
```

#### 3. API Connection Failed

```bash
# Error: API request failed with HTTP 000
# Check network connectivity
ping google.com

# Check API endpoint
curl -I https://your-portal.com/api/router/health
```

#### 4. OpenZiti Installation Failed

```bash
# Manual installation
curl -sSLf https://get.openziti.io/install.bash | sudo bash
```

#### 5. Service Won't Start

```bash
# Check service logs
journalctl -u ziti-router -n 50

# Check configuration syntax
sudo ziti router run /etc/zitirouter/router.yaml --dry-run
```

### Debug Mode

Enable debug mode for verbose output:

```bash
# Edit config.sh
DEBUG_MODE=true

# Or set environment variable
export DEBUG_MODE=true
sudo -E ./enroll-router.sh
```

### Manual Cleanup

If enrollment fails and you need to start over:

```bash
# Stop and remove service
sudo systemctl stop ziti-router
sudo systemctl disable ziti-router
sudo rm -f /etc/systemd/system/ziti-router.service

# Remove configuration
sudo rm -rf /etc/zitirouter/

# Reload systemd
sudo systemctl daemon-reload
```

## Network Configuration

### Firewall Rules

If using UFW (Ubuntu Firewall):

```bash
# Allow outbound HTTPS
sudo ufw allow out 443/tcp

# Allow outbound HTTP (for package downloads)
sudo ufw allow out 80/tcp
```

If using iptables:

```bash
# Allow outbound HTTPS
sudo iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 80 -j ACCEPT
```

### Proxy Configuration

If behind a corporate proxy:

```bash
# Set proxy environment variables
export http_proxy=http://proxy.company.com:8080
export https_proxy=http://proxy.company.com:8080
export no_proxy=localhost,127.0.0.1

# Run with proxy settings
sudo -E ./enroll-router.sh
```

## Security Considerations

### File Permissions

The script sets these permissions:
- `/etc/zitirouter/`: 755 (readable by all, writable by root)
- `/etc/zitirouter/certs/`: 700 (accessible only by root)
- `/etc/zitirouter/router.yaml`: 644 (readable by all)
- `/etc/zitirouter/enrollment.jwt`: 600 (readable only by root)

### Service Security

The router service runs as root because:
- Requires access to system certificates
- Needs to bind to privileged network interfaces
- Must manage system-level network routing

### Hash Key Security

- Hash keys expire after 24 hours
- Each hash key can only be used once
- Hash keys are validated server-side
- Failed attempts are rate-limited

## Automation

### Non-Interactive Installation

For automated deployments, modify the script to accept parameters:

```bash
#!/bin/bash
# Custom wrapper script

API_ENDPOINT="${1:-https://portal.example.com/api}"
HASH_KEY="${2}"

if [[ -z "$HASH_KEY" ]]; then
    echo "Usage: $0 [api_endpoint] <hash_key>"
    exit 1
fi

# Set environment variables
export API_ENDPOINT
export HASH_KEY

# Run enrollment script
./enroll-router.sh
```

### Configuration Management

Use configuration management tools:

```yaml
# Ansible example
- name: Deploy router enrollment script
  copy:
    src: enroll-router.sh
    dest: /tmp/enroll-router.sh
    mode: '0755'

- name: Configure API endpoint
  lineinfile:
    path: /tmp/config.sh
    regexp: '^DEFAULT_API_ENDPOINT='
    line: 'DEFAULT_API_ENDPOINT="https://{{ portal_url }}/api"'

- name: Run enrollment
  command: /tmp/enroll-router.sh
  become: yes
```

## Support

### Log Files

Check these log files for troubleshooting:
- `/var/log/ziti-router-enrollment.log` - Enrollment process
- `journalctl -u ziti-router` - Router service logs
- `/var/log/syslog` - System logs

### Getting Help

1. **Check Documentation**: Review README.md and this guide
2. **Test Prerequisites**: Run `./test-enrollment.sh`
3. **Check Logs**: Review log files for error details
4. **Portal Support**: Contact your ZitiNexus Portal administrator
5. **OpenZiti Community**: Visit [OpenZiti Documentation](https://docs.openziti.io/)

### Reporting Issues

When reporting issues, include:
- Ubuntu version: `lsb_release -a`
- Script version: Check script header
- Error messages: From logs and console output
- Network configuration: Proxy, firewall settings
- Hash key status: From portal (without revealing the key)

## Version History

- **v1.0.0**: Initial release with full automation
  - Hash key validation
  - OpenZiti CLI installation
  - Router configuration generation
  - Systemd service creation
  - Status reporting to portal