zitinexus-router-script/Router-enrollment-script

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

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

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

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

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

# 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

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

# 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

Version History

• v1.0.0: Initial release with full enrollment automation