396 lines
8.0 KiB
Markdown
396 lines
8.0 KiB
Markdown
# 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
|