Quick Start Guide – Getting Started with μNet

Goal: Get μNet running and managing your first network devices in 10 minutes

Installation

Build from Source

Note: μNet is currently in active development. Pre-built releases are not yet available. You must build from source.

git clone https://github.com/bedecarroll/unet.git
cd unet
cargo build --release
cp target/release/unet-cli ./unet
cp target/release/unet-server ./unet-server

Quick Setup

1. Initialize Database

μNet will automatically create a SQLite database on first use:

./unet nodes list
# Creates unet.db in current directory

Managing Vendors

Common vendors are seeded automatically. Manage them using the CLI:

# List vendors
unet vendors list

# Add a vendor
unet vendors add CustomVendor

# Remove a vendor
unet vendors delete CustomVendor

2. Create Sample Data

Note: Pre-built example files are not yet available. You can create sample data manually:

# Create a location
./unet locations create --name "Datacenter" --type "datacenter" --description "Main datacenter"

# Create a node
./unet nodes create --name "core-01" --type "Router" --vendor "Cisco" --model "ISR4321" --location "Datacenter"

# List your data
./unet nodes list
./unet locations list

Basic Operations

Managing Nodes

# Add a new device
./unet nodes add \
  --name core-sw-01 \
  --domain corp.example.com \
  --vendor cisco \
  --model catalyst9300 \
  --role access \
  --lifecycle production \
  --management-ip 192.168.1.10

# List all devices
./unet nodes list

# Show device details
./unet nodes show core-sw-01

# Update device
./unet nodes update core-sw-01 --lifecycle production

# Delete device
./unet nodes delete core-sw-01

Managing Locations

# Add a location
./unet locations add \
  --name "Building A" \
  --location-type building \
  --address "123 Main Street"

# List locations
./unet locations list

# Show location details
./unet locations show "Building A"

Managing Links

# Create a point-to-point link
./unet links add \
  --node-a core-sw-01 \
  --interface-a GigE0/0/1 \
  --node-z dist-sw-01 \
  --interface-z GigE1/0/24 \
  --bandwidth 1000000000

# Create an internet circuit
./unet links add \
  --node-a edge-rtr-01 \
  --interface-a GigE0/0/0 \
  --circuit-id "ISP-CIRCUIT-12345"

# List links
./unet links list

Working with Policies

1. Create Your First Policy

Create a file called network-standards.rules:

# Ensure all production devices are monitored
WHEN node.lifecycle == "Production" 
THEN SET custom_data.monitoring_enabled TO true

# Cisco devices should use SNMPv3
WHEN node.vendor == "Cisco"
THEN SET custom_data.snmp_version TO "v3"

# Core devices need redundancy
WHEN node.role == "Core"
THEN ASSERT custom_data.redundancy_configured IS true

2. Validate and Run Policies

# Check syntax
./unet policy validate network-standards.rules

# Evaluate against all nodes
./unet policy eval network-standards.rules

# Show only failures
./unet policy eval network-standards.rules --failures-only

Using the HTTP Server

1. Start the Server

# Start server on default port (8080)
./unet-server

# Or specify custom settings
./unet-server --host 0.0.0.0 --port 8080 --database-url sqlite://network.db

2. Use CLI with Remote Server

# Set server URL
export UNET_SERVER=http://localhost:8080

# Now CLI commands use the server
./unet nodes list
./unet policy eval network-standards.rules

3. Use the API Directly

# List nodes via API
curl http://localhost:8080/api/v1/nodes

# Create a node via API
curl -X POST http://localhost:8080/api/v1/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-device",
    "vendor": "Cisco",
    "model": "ISR4331",
    "role": "Edge",
    "lifecycle": "Staging"
  }'

# Evaluate policies via API
curl -X POST http://localhost:8080/api/v1/policies/evaluate

Output Formats

μNet supports multiple output formats for different use cases:

# Human-readable table (default for terminal)
./unet nodes list

# JSON for automation
./unet nodes list --output json

# YAML for readability
./unet nodes list --output yaml

# Pipe to other tools
./unet nodes list --output json | jq '.data.data[].name'

Common Workflows

Network Discovery Documentation

# 1. Document your physical sites
./unet locations add --name "HQ Campus" --location-type campus
./unet locations add --name "Main Building" --location-type building --parent-id <campus-id>

# 2. Add your network devices
./unet nodes add --name core-01 --vendor cisco --model asr9000 --role core
./unet nodes add --name dist-01 --vendor cisco --model catalyst9400 --role distribution

# 3. Document connections
./unet links add --node-a core-01 --interface-a TenGigE0/0/0/1 \
                 --node-z dist-01 --interface-z TenGigE1/0/1

# 4. Export for backup
./unet export --output-dir backup/

Compliance Monitoring

# 1. Create compliance policies
cat > compliance.rules << 'EOF'
WHEN node.lifecycle == "Production" THEN ASSERT custom_data.backup_configured IS true
WHEN node.role == "Core" THEN ASSERT custom_data.redundancy_level >= 2
WHEN node.vendor == "Cisco" THEN ASSERT custom_data.snmp_version == "v3"
EOF

# 2. Run compliance check
./unet policy eval compliance.rules --failures-only

# 3. Generate compliance report
./unet policy eval compliance.rules --output json > compliance-report.json

Data Migration

# Export from existing system
./unet export --output-dir migration/

# Edit exported files as needed
# ...

# Import to new environment
./unet import migration/ --dry-run  # Test first
./unet import migration/              # Actually import

Configuration

Environment Variables

# Database location
export UNET_DATABASE_URL="sqlite:///path/to/unet.db"

# Server URL for remote operations
export UNET_SERVER="http://unet-server:8080"

# Default output format
export UNET_OUTPUT_FORMAT="json"

Configuration File

Create ~/.config/unet/config.toml:

[defaults]
database_url = "sqlite:///home/user/network/unet.db"
server_url = "http://unet-server:8080"
output_format = "table"

[logging]
level = "info"

Next Steps

Now that you have μNet running:

Read the CLI Reference for complete command documentation
Study the Policy Guide for advanced policy authoring
Explore the API Reference for automation integration
Review the Architecture Overview to understand the system design

Common Next Actions

Scale Up: Import your real network topology
Automate: Integrate with your CI/CD pipeline
Monitor: Set up continuous policy evaluation
Extend: Use the API to build custom integrations

Getting Help

Troubleshooting: See Troubleshooting Guide
CLI Reference: See complete command documentation
Issues: Report bugs at https://github.com/bedecarroll/unet/issues

Welcome to μNet! 🎉

Keyboard shortcuts

μNet Documentation