towerops/LIBRENMS_INTEGRATION.md

# LibreNMS Integration

This document explains how to import MIB files and device profiles from a LibreNMS installation into Towerops.

## Quick Start

Import device profiles from LibreNMS (no authentication needed):

```bash
mix upload_librenms --librenms-path ~/dev/librenms
```

Upload everything including MIBs (requires superuser API token):

```bash
mix upload_librenms --librenms-path ~/dev/librenms --token your-api-token
```

This will:
1. Upload all MIB files from `~/dev/librenms/mibs/` to the server (if --token provided)
2. Import all device profiles from `~/dev/librenms/resources/definitions/`

## Options

### Basic Usage

```bash
# Upload to local server (default: http://localhost:4000)
mix upload_librenms --librenms-path ~/dev/librenms

# Upload to production server
mix upload_librenms --librenms-path ~/dev/librenms \
  --url https://towerops.net \
  --token your-api-token-here

# Upload specific profiles only
mix upload_librenms --librenms-path ~/dev/librenms \
  --profiles routeros,ios,iosxe
```

### Command-Line Options

- `--librenms-path` - Path to LibreNMS installation (required)
- `--url` - Server URL (default: http://localhost:4000)
- `--token` - API token for authentication (required for remote servers)
- `--profiles` - Comma-separated list of profiles to import (default: all)

## What Gets Uploaded

### MIB Files

All MIB files from `{librenms-path}/mibs/` are uploaded, organized by vendor:

```
~/dev/librenms/mibs/
  ├── mikrotik/
  │   ├── MIKROTIK-MIB
  │   └── ...
  ├── cisco/
  │   ├── CISCO-SMI
  │   └── ...
  └── ...
```

Each vendor's MIBs are uploaded separately with the vendor name preserved.

### Device Profiles

Device profiles are imported from LibreNMS YAML definitions:

```
~/dev/librenms/resources/definitions/
  ├── os_detection/
  │   ├── routeros.yaml    # Detection patterns
  │   └── ios.yaml
  └── os_discovery/
      ├── routeros.yaml    # Device info & sensors
      └── ios.yaml
```

For each profile, the following is imported:
- **Detection patterns** (sysObjectID, sysDescr regex)
- **Device info OIDs** (serial number, firmware version, hardware)
- **Sensor OIDs** (temperature, voltage, current, power, fanspeed)

**Note**: Only scalar sensors (ending with `.0`) are imported. Table-based sensors with `{{ $index }}` templates are skipped.

## Authentication

### Profile Import Only (No Token Needed)

Profile imports work without authentication since they only write to the local database:

```bash
# Import profiles without uploading MIBs
mix upload_librenms --librenms-path ~/dev/librenms
```

### MIB Upload (Token Required)

MIB uploads require a **superuser API token** for both local and remote servers:

```bash
# Upload MIBs + import profiles (local server)
mix upload_librenms --librenms-path ~/dev/librenms \
  --token your-superuser-token

# Upload to remote server
mix upload_librenms --librenms-path ~/dev/librenms \
  --url https://towerops.net \
  --token your-superuser-token
```

**Creating an API Token:**
1. Log in to Towerops as a superuser
2. Navigate to Settings → API Tokens
3. Create a new token
4. Copy the token value

**Note**: The token MUST be from a superuser account. Regular user tokens will be rejected with a 403 Forbidden error.

## Examples

### Example 1: Import Profiles Only (Quick Start)

Import device profiles without uploading MIBs (no token needed):

```bash
mix upload_librenms --librenms-path ~/dev/librenms
```

Output:
```
Skipping MIB upload: --token is required for MIB uploads (superuser API token needed)
Step 2/2: Importing device profiles from ~/dev/librenms/resources/definitions...
Importing 150 specified profiles
Importing profile: routeros
✓ routeros: created/updated successfully
...
Import complete: 150 succeeded, 0 failed

Upload complete!
```

### Example 2: Upload Everything (MIBs + Profiles)

Upload MIBs and import profiles (requires superuser token):

```bash
mix upload_librenms --librenms-path ~/dev/librenms --token sk_dev_abc123...
```

Output:
```
Step 1/2: Uploading MIB files from ~/dev/librenms/mibs...
Found 500 vendor directories
Uploading MIBs for vendor: mikrotik
  Uploading: MIKROTIK-MIB
  Uploading: ...
MIB upload complete: 5000 succeeded, 0 failed

Step 2/2: Importing device profiles from ~/dev/librenms/resources/definitions...
Importing 150 specified profiles
Importing profile: routeros
✓ routeros: created/updated successfully
...
Import complete: 150 succeeded, 0 failed

Upload complete!
```

### Example 3: Update Specific Profiles

Re-import just the MikroTik and Cisco profiles (no MIB upload):

```bash
mix upload_librenms --librenms-path ~/dev/librenms \
  --profiles routeros,ios,iosxe,nxos
```

### Example 4: Production Deployment

Upload everything to production server:

```bash
mix upload_librenms --librenms-path ~/dev/librenms \
  --url https://towerops.net \
  --token sk_live_abc123...
```

## Manual Tasks

You can also run each step separately if needed:

### Upload MIBs Only

```bash
mix upload_mibs --source-dir ~/dev/librenms/mibs \
  --url https://towerops.net \
  --token your-token
```

### Import Profiles Only

```bash
mix import_profiles --source-path ~/dev/librenms/resources/definitions \
  --profiles routeros,ios
```

## Troubleshooting

### Error: "LibreNMS directory not found"

Make sure the path to your LibreNMS installation is correct:

```bash
ls -la ~/dev/librenms
# Should show mibs/ and resources/ directories
```

### Error: "No vendor directories found"

The mibs directory structure should have vendor subdirectories:

```bash
ls -la ~/dev/librenms/mibs/
# Should show directories like mikrotik/, cisco/, etc.
```

### Error: "Superuser access required"

MIB uploads require a superuser API token. Make sure you're using a token created by a superuser account.

### Warning: "Definitions directory not found"

LibreNMS moved the definitions from `includes/definitions/` to `resources/definitions/` in recent versions. Update your path accordingly.

## What's Imported

### RouterOS (MikroTik) Example

For the `routeros` profile, the following is imported:

**Profile Metadata:**
- Name: routeros
- Vendor: Mikrotik RouterOS
- Detection OID: .1.3.6.1.4.1.14988.1
- Priority: 100

**Device OIDs:**
- Serial number: `MIKROTIK-MIB::mtxrSerialNumber.0`
- Firmware version: `MIKROTIK-MIB::mtxrLicVersion.0`

**Sensor OIDs:**
- None (routeros only has table-based sensors which are skipped)

### Cisco IOS Example

For the `ios` profile:

**Profile Metadata:**
- Name: ios
- Vendor: Cisco IOS
- Detection Pattern: "Cisco Internetwork Operating System Software"
- Detection OID: .1.3.6.1.4.1.9.1.2330
- Priority: 100

**Device OIDs:**
- None (IOS doesn't define them in os_discovery)

**Sensor OIDs:**
- None (IOS only has table-based sensors which are skipped)

## Database Schema

The imported profiles are stored in the database:

- `device_profiles` - Profile metadata (name, vendor, detection patterns)
- `profile_device_oids` - Device identification OIDs (serial, firmware, etc.)
- `profile_sensor_oids` - Sensor discovery OIDs (temperature, voltage, etc.)

You can query them:

```elixir
# Get all profiles
Towerops.Profiles.list_profiles()

# Get specific profile with associations
Towerops.Profiles.get_profile("routeros")

# Match a device to a profile
system_info = %{
  sys_descr: "RouterOS 7.16.1",
  sys_object_id: ".1.3.6.1.4.1.14988.1"
}
Towerops.Profiles.match_profile(system_info)
```

## Next Steps

After importing profiles:

1. **Test device discovery** - Discover a MikroTik or Cisco device to verify profile matching works
2. **Check MIB translation** - Verify that MIB names are being translated to numeric OIDs correctly
3. **Add more profiles** - Import additional vendor profiles as needed
4. **Build Web UI** - Create LiveView pages for managing profiles in the browser

## Related Documentation

- `PROFILES_README.md` - Database-driven profile system documentation
- `lib/mix/tasks/upload_librenms.ex` - Task implementation
- `lib/mix/tasks/import_profiles.ex` - Profile import implementation
- `lib/mix/tasks/upload_mibs.ex` - MIB upload implementation