zitinexus-router-script/Router-enrollment-script/README.md

# OpenZiti Router Enrollment Script

This script automates the enrollment of OpenZiti routers using hash keys from the ZitiNexus Portal. It's designed for Ubuntu 22.04, 24.04, and other Linux distributions.

## Overview

The script performs the complete router enrollment process:
1. Validates hash key with ZitiNexus Portal
2. Downloads router configuration and JWT
3. Installs OpenZiti CLI if needed
4. Enrolls router with OpenZiti controller
5. Creates systemd service for automatic startup
6. Reports enrollment status back to portal

## Prerequisites

- Ubuntu 22.04, 24.04, or compatible Linux distribution
- Root access (script must be run with sudo)
- Internet connectivity
- Hash key from ZitiNexus Portal

## Quick Start

1. **Get Hash Key**: Create a router enrollment in ZitiNexus Portal and copy the hash key
2. **Download Script**: Copy `enroll-router.sh` to your router machine
3. **Make Executable**: `chmod +x enroll-router.sh`
4. **Run Script**: `sudo ./enroll-router.sh`
5. **Follow Prompts**: Enter your portal API endpoint and hash key

## Usage

```bash
# Make script executable
chmod +x enroll-router.sh

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

### Interactive Prompts

The script will prompt for:

1. **ZitiNexus Portal API Endpoint**
   - Default: `https://your-zitinexus-portal.com/api`
   - Example: `https://portal.example.com/api`

2. **Router Enrollment Hash Key**
   - 32-character hexadecimal string from ZitiNexus Portal
   - Example: `a1b2c3d4e5f6789012345678901234567890abcd`

## What the Script Does

### 1. System Requirements Check
- Installs `curl` and `jq` if not present
- Verifies `systemctl` availability
- Checks for root privileges

### 2. OpenZiti CLI Installation
- Downloads and installs OpenZiti CLI from official source
- Adds to system PATH
- Verifies installation

### 3. Directory Setup
- Creates `/etc/zitirouter/` configuration directory
- Creates `/etc/zitirouter/certs/` for certificates
- Sets appropriate permissions

### 4. Router Registration
- Calls ZitiNexus Portal API with hash key
- Downloads JWT token and router configuration
- Implements retry logic for network issues
- Handles rate limiting

### 5. Router Enrollment
- Saves JWT and configuration files
- Runs `ziti edge enroll` command
- Generates router certificates
- Verifies successful enrollment

### 6. Service Setup
- Creates systemd service file
- Enables automatic startup
- Starts router service
- Verifies service is running

### 7. Status Reporting
- Reports successful enrollment to portal
- Includes system information (hostname, architecture, OS)
- Updates portal with router status

## File Locations

After successful enrollment:

```
/etc/zitirouter/
├── router.yaml              # Router configuration
├── enrollment.jwt           # JWT token (removed after enrollment)
└── certs/                   # Router certificates
    ├── <router-name>.cert
    ├── <router-name>.key
    ├── <router-name>.server.chain.cert
    └── <router-name>.cas

/etc/systemd/system/
└── ziti-router.service      # Systemd service file

/var/log/
└── ziti-router-enrollment.log  # Installation log
```

## Service Management

After enrollment, manage the router service with:

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

# View logs
journalctl -u ziti-router -f

# Stop router
systemctl stop ziti-router

# Start router
systemctl start ziti-router

# Restart router
systemctl restart ziti-router

# Disable auto-start
systemctl disable ziti-router

# Enable auto-start
systemctl enable ziti-router
```

## Troubleshooting

### Common Issues

1. **Hash Key Not Found**
   ```
   ERROR: Hash key not found
   ```
   - Verify hash key was copied correctly
   - Check if hash key has expired (24-hour window)
   - Ensure enrollment exists in portal

2. **API Connection Failed**
   ```
   ERROR: API request failed with HTTP 000
   ```
   - Check internet connectivity
   - Verify API endpoint URL
   - Check firewall rules for outbound HTTPS

3. **Hash Key Expired**
   ```
   ERROR: Hash key has expired
   ```
   - Create new router enrollment in portal
   - Use new hash key within 24 hours

4. **OpenZiti Installation Failed**
   ```
   ERROR: Failed to install OpenZiti CLI
   ```
   - Check internet connectivity
   - Verify system has sufficient disk space
   - Try manual installation: `curl -sSLf https://get.openziti.io/install.bash | bash`

5. **Router Enrollment Failed**
   ```
   ERROR: Router enrollment failed
   ```
   - Check controller connectivity
   - Verify JWT token is valid
   - Check system time synchronization

6. **Service Won't Start**
   ```
   WARNING: Router service may not be running properly
   ```
   - Check service logs: `journalctl -u ziti-router -f`
   - Verify configuration file: `cat /etc/zitirouter/router.yaml`
   - Check certificate files exist

### Debug Information

View detailed logs:
```bash
# Script execution log
tail -f /var/log/ziti-router-enrollment.log

# Router service logs
journalctl -u ziti-router -f

# System logs
dmesg | tail
```

Check configuration:
```bash
# Verify router config
cat /etc/zitirouter/router.yaml

# Check certificates
ls -la /etc/zitirouter/certs/

# Test OpenZiti CLI
ziti version
```

### Manual Cleanup

If enrollment fails and you need to start over:

```bash
# Stop service
systemctl stop ziti-router 2>/dev/null || true

# Remove service
systemctl disable ziti-router 2>/dev/null || true
rm -f /etc/systemd/system/ziti-router.service

# Remove configuration
rm -rf /etc/zitirouter/

# Reload systemd
systemctl daemon-reload
```

## Security Considerations

- Script must run as root for system configuration
- Hash keys expire after 24 hours
- Certificates are stored with restricted permissions
- Service runs as root (required for router operations)

## Network Requirements

### Outbound Connections Required

- **ZitiNexus Portal API**: HTTPS (443) to your portal domain
- **OpenZiti Controller**: HTTPS (443) to controller cluster
- **Package Repositories**: HTTP/HTTPS (80/443) for apt packages

### Firewall Rules

```bash
# Allow outbound HTTPS (if using restrictive firewall)
iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 80 -j ACCEPT
```

## Advanced Usage

### Non-Interactive Mode

For automated deployments, you can modify the script to accept parameters:

```bash
# Example modification (not included in base script)
API_ENDPOINT="https://portal.example.com/api"
HASH_KEY="your-hash-key-here"
```

### Custom Configuration

The script uses these default paths:
- Config directory: `/etc/zitirouter/`
- Log file: `/var/log/ziti-router-enrollment.log`
- Service name: `ziti-router.service`

These can be modified by editing the script variables at the top.

## Support

For issues with:
- **Script functionality**: Check this README and logs
- **ZitiNexus Portal**: Contact your portal administrator
- **OpenZiti**: Visit [OpenZiti Documentation](https://docs.openziti.io/)

## Version History

- **v1.0.0**: Initial release with full enrollment automation