Metadata-Version: 2.4
Name: netbox-device-importer
Version: 0.1.0
Summary: NetBox plugin: SSH-scrape network gear and import devices/interfaces/VLANs/IPs into NetBox.
Author: Dries Velle
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paramiko>=3.0
Dynamic: license-file

# NetBox Device Importer — User Guide

Import network devices into NetBox by SSH-scraping them (switches / firewalls) or
from a CSV of manual devices. Runs from the **Device Import & Sync** menu and writes
Devices, Interfaces, VLANs, IPs and Prefixes for you.

> Deploying, upgrading or maintaining the plugin? See the deployment guide in
> the project documentation. This page is for using it.

---

## Before you import — set these up in NetBox first

The importer **matches on existing NetBox objects** and will **not** create the
following. Create them before importing, and match names **exactly** (case-sensitive):

- **Tenant**, **Site**, **Device Role**, **Device Type** must already exist.
- **Device Type interfaces must be pre-created with the exact names the importer uses:**
  - Switches (`hios`, `hcos`, `ios`, `smbos`): interfaces named **`1/1`, `1/2`, `1/3`, …**
  - Static single-interface devices: interface named **`1/1`**
    (except the UPS model **`5PX 3000i RT3U G2`**, which uses **`External-NIC`**).
  - If an interface name on the device has no matching interface on the Device Type,
    that interface is **skipped** (logged as a warning) — the rest still import.
- **Device Type "Model" must equal the model the device reports.** For FortiGate the
  reported model is normalised (e.g. `FortiGate-100F` → `FG100F`); the Device Type
  model in NetBox must match the normalised value.

The importer **does** create automatically: **Locations**, **Racks** (default height
42U), **VLANs** (named `AutoCreatedFromImportScript` unless the device supplies a
name), **Prefixes**, and **IP addresses**.

---

## Supported platforms

| Platform value | Devices |
|---|---|
| `hios` | Hirschmann HiOS switches |
| `hcos` | Hirschmann HiSecOS (HCoS) switches |
| `ios` | Cisco IOS switches |
| `smbos` | Cisco SMB OS (C1300) switches |
| `fortios` | Fortinet FortiOS firewalls |

Stacked Cisco switches (`ios`, `smbos`) are detected and **skipped** (not supported).

---

## Using it

Open **Device Import & Sync** in the left nav. Two entry points:

### Single Device (SSH)

Import one SSH-reachable device. You fill in:

- **Device IP, SSH port, username, password**
- **Platform** (dropdown)
- **Placement** via NetBox pickers — **Tenant, Site, Location, Rack, Device Role**.
  These chain: pick a Site and the Location list narrows to it, pick a Location and
  the Rack list narrows again. You can only pick things that already exist, so
  placement can't be mistyped.
- Optional: rack height (only if the rack must be created), position, asset tag.

Name, serial, model, interfaces and VLANs are read from the device — you do **not**
enter them. (The scraped model must already exist as a Device Type, per above.)

### Multi Import (CSV)

Pick the CSV format, upload the file, submit. Two formats:

**SSH devices — `Sources.csv`** (the importer logs in and scrapes each device):

```
DeviceIP,sshPort,username,password,tenant,site,location,rack,rackHeightInU,positionInRack,deviceRole,platform,AssetTag-RDSPP
```

`platform` must be one of `hios`, `hcos`, `ios`, `fortios`, `smbos`.

**Static devices — `Devices.csv`** (no SSH; you provide everything):

```
Device-IP,netmask,VLAN-IDs,MAC-address,Device-Name,Device-Type,Serialnumber,Firmware,tenant,site,location,rack,rackHeightInU,positionInRack,deviceRole,AssetTag-RDSPP
```

- **`VLAN-IDs`** is a `-`-delimited **list** (not a range), e.g. `0-99-105`. The
  **first** entry is the **untagged** VLAN (`0` = none); the rest are **tagged**.
- Interface for a static device is the single Device-Type interface (`1/1`, or
  `External-NIC` for the `5PX 3000i RT3U G2` UPS).

**CSV rules (both formats):**

- A **header row is required** and must match the columns above.
- **No trailing blank lines.**
- All names are **case-sensitive** and must match existing NetBox objects.

---

## Dry run — always test first

Every form has a **Commit to NetBox** checkbox. **Leave it unchecked** for a dry run:
the device is scraped, parsed, and every intended change is written to the job log,
then **rolled back** — nothing is saved. Check it only when the dry-run log looks
correct.

---

## Watching the result

Submitting queues a background job and takes you to its page. There you see live
progress and a log line for each step (prerequisites OK, VLAN OK, Mgmt IP OK,
interfaces completed, and any warnings/errors). Re-open the job any time from
**Jobs** in NetBox.

---

## Credentials

SSH credentials you provide (in the CSV or the single-device form) are used **only for
that run** and are **never stored** in NetBox — they do not appear on the job record.

---

## Common messages

| Message | Meaning / fix |
|---|---|
| `Site does not exist: X` | Create the Site in NetBox (exact, case-sensitive name), or fix the CSV value. |
| `Tenant does not exist` / `Device-Role does not exist` | Same — create it first or correct the name. |
| `Device-Type does not exist: <model>` | Create a Device Type whose Model matches the device's reported model (FortiGate uses the normalised name). |
| `Interface not found on device (skipped): 1/x` | The Device Type is missing that interface name — add it to the Device Type, then re-import. |
| `SSH connection failed` | Check reachability/credentials/port; the NetBox worker must be able to reach the device. |
| `Stacked switch - not processed` | Stacked Cisco switches are intentionally skipped. |
| `Firewall interface config incomplete` | The FortiGate scrape returned too few interfaces (transient SSH/parse issue) — retry. |
