zitinexus-public
/
zitinexus-router-script
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
zitinexus-router-script/Router-enrollment-script/INSTALLATION.md

8.0 KiB
Raw Blame History

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

# 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

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

Step 3: Configure (Optional)

Edit config.sh to customize settings:

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:

./test-enrollment.sh

Select option 6 to run all tests.

Step 5: Run Enrollment

Execute the main enrollment script:

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:

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

Advanced Configuration

Customize these settings in config.sh:

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

# 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

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

# 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

# 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

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

2. Hash Key Not Found

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

3. API Connection Failed

# 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

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

5. Service Won't Start

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

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

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

# Allow outbound HTTPS
sudo ufw allow out 443/tcp

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

If using iptables:

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

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

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

# 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

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