Skip to content

Design a Homelab with Netbox

Overview

Netbox is presented as a "SoT" (Source of Truth) for network designs — the user is supposed to populate it, then wire any automation to fetch data from it, as an alternative to the usual scattered configuration files.

More concretely, Netbox does DCIM and IPAM.

On the plus side, the UI allows multiple users, possibly with various rights, to collaborate and any change is reflected in a log.

On the downside, Netbox does not enforce a lot of constraints natively, the rationale being to be as flexible as possible for users trying to model an existing network already in production.

Starting to use Netbox for the first time is not straightforward, some parts of the data model are pretty explicit, but a few others are not.

There is documentation, but it's more oriented towards administrators of the service, and to document the API and integrations; except the page on the "order of operations" which is interesting https://netboxlabs.com/docs/netbox/getting-started/planning/#order-of-operations for populating data.

The best resource to begin is certainly the dedicated Youtube serie: https://www.youtube.com/playlist?list=PL7sEPiUbBLo_iTds-NV-9Tu05Gg2Aj8N7

However that serie illustrates a typical multi-site corporate network, and it's difficult to grasp what's necessary or not for a small homelab, which is going to be our goal here.

Our target is a typical small homelab:

  • A rack, containing:
    • A modem, from the ISP
    • A router
    • A switch
    • A wireless access point
    • A server, used as type-1 hypervisor
  • A classic network configuration: for IPv4, IPv6, VLANs, WiFi
  • A couple of VMs

For the hypervisor, I'll arbitrarily choose Proxmox VE as it's a free popular choice in the homelab community, but adapt the naming below if you prefer another implementation.

Design

Organization

Creating a site is the first thing to do, as it's a mandatory dependency of mostly everything else, in the Netbox data model. A site also implies constraints discussed later.

Create a site object, e.g. "Home".

We won't need anything else in the Organization part.

Racks

Create a rack object, e.g. "Rack", within our site, Home.

You'll have to specify its characteristics, including its height in Rack Units, etc. Those specs are important because the DCIM data model allows you to virtually stack devices into the rack and see the space usage and other aspects such as power consumption.

We won't need anything else in the Racks part.

Devices

Manufacturers & Device Types

With the Netbox data model, we first need to populate Device Types, from which we will be able to instantiate the devices themselves.

What's surprising is that modifying a type won't reflect on the instances; for instance if you add an interface to a device type, this won't add that interface it to its instances; so the bottomline is to get the types correct first.

To populate device types, you can use the community library: https://github.com/netbox-community/devicetype-library Hop into the "device-types" sub directory, find the manufacturer then find your model and copy the YAML content.

Back into your Netbox instance:

  • In Devices > Manufacturers, create the Manufacturer objects — as they won't be created automatically and the import below will fail if it's missing
  • In Devices > Device Types, click on Import, then paste your YAML and proceed

Repeat for each device. If you can't find your model in the community library, create it manually.

HEADS UP ! It's very likely your router will have split hardware for the LAN part and the WAN part(s). In particular, for each, if there are multiple ports, you might want to create a new interface of type "bridge" and assign each port to that bridge; this matters because we'll later assign the router primary IPv4, on the LAN part, to that bridge interface.

Device Roles

In Devices > Device Roles, create the following objects:

  • Modem
  • Router
  • Switch — if you have a hierarchy of switches, create Core Switch, Distribution Switch, Access Switch instead
  • AP
  • Proxmox VE Server

Devices

All the dependencies are now ready: site, device type, device role.

Prior to creating actual devices, a few words about device names:

  • It's unique per site (and tenant, if there's any)
  • It's supposed (my sources are LLMs…) to match the hostname of the device primary IP (if any) DNS name — but this is not enforced, it's a convention, e.g. if the device is named myrouter, then the DNS record should be myrouter.rest_of_domain_name
  • A common convention in the industry is to name a device like <site>-<devrole>-<nb>, e.g. home-router-01 BUT, later on, we also have to configure our DNS records and typically those records will look like <hostname>.<site>.<domain_name>. So we might end up with home-router-01.home.example.com — that repetition is not pretty. Instead of a site prefix, and in the case of a homelab and personal equipment in general, I personally prefer to use a person (tenant in Netbox glossary) prefix because in general a device belongs (or at least is managed) by one person, e.g. jdoe-laptop. Given we only have one device per device role, ditching the numbering also simplifies the naming scheme. For the rest of the document, I'm adopting this jdoe- prefix.

In Devices > Devices, create those objects:

  • jdoe-modem
  • jdoe-router
  • jdoe-switch
  • jdoe-pve
  • jdoe-ap

Make sure to tie those devices to rack slots (except the AP probably.)

Connections

Now that all the hardware specified, we can model cabling between interfaces.

An interface model is pretty extensive, including the type/speed (e.g. GBE) but also PoE capabilities, and other features.

That being said, one thing to keep in mind is that you won't get any warning (at least natively without extra plugins) from Netbox if you are wiring 2 interfaces with different capabilities. It could be interesting, for instance, to get some sort of notification if you wire a GE interface with a 2.5GE interface — even if it's obviously possible in reality, it could also be an operator mistake.

In Connections > Cables, create the following objects:

  • modem <-> router
  • router <-> switch
  • switch <-> pve
  • switch <-> ap

You'll have to select the most appropriate interfaces according to your equipment, the speed in particular. If you have equipement powered over Ethernet (PoE PD mode), make sure to connect it to a PoE PSE interface with the correct capacity.

Virtualization

Cluster Types

On creating a VM, Netbox will warn you that "A virtual machine must be assigned to a site and/or cluster." We do have a site so we could skip the clustering part, but a cluster brings two small benefits, first the ability to map devices to a cluster (our type-1 hypervisor(s)) and it will also surface the resource allocation of all the VMs within the cluster (vCPU, RAM, disk.)

A cluster must have a type, so this is the first step in this section. A cluster type — according to the Youtube serie — is mostly a virtualization tech, so Proxmox VE in our case.

In Virtualization > Cluster Types, create an object named "Proxmox VE".

Clusters

In Virtualization > Cluster, create a new object:

  • Name: PVE Cluster
  • Select Proxmox VE as its type.

A homelab typically has a single cluster (or none at all, which is equivalent in this case) so numbering the cluster (e.g. "PVE Cluster 01") is not really useful.

Once created, click on the cluster, and Assign Device, then select the homelab server.

Virtual Machines

In Virtualization > Virtual Machines, create a new object:

  • Name: jdoe-example (following the same naming scheme as devices)

Interfaces

In Virtualization > Interfaces, create a new object:

  • Name: Eth 0 (maybe not the best name once you have multiple VMs)

IPAM

VLANs

A lot of homelabbers are using 4 VLANs: Management, Trusted, IoT, Guests (plus a Cameras VLAN for surveillance gear — we will assume that last one is out of scope here)

The firewall would then be configured with the following access:

  • Management contains the networking gear and can access Internet
  • Trusted (or some device in Trusted at least) would have access to Management, IoT, and Internet
  • IoT would have access to Internet only
  • Guests would have access to Internet only

In order to simplify, we can merge Management and Trusted.

In IPAM > VLANs, create the following objects:

  • Default, with VID 1
  • IoT, with VID 10
  • Guests, with VID 20

RIRs / Aggregates

IPv4

This part is detailed in the Youtube serie linked above.

In IPAM > RIRs, create one object named "RFC 1918" — which specifies IPv4 private networks.

I don't see why this isn't filled in by default in Netbox as all users are probably adding this entry.

In IPAM > Aggregates, create the 3 aggregates mapped to the RIR "RFC 1918":

  • 10.0.0.0/8
  • 172.16.0.0/12
  • 192.168.0.0/16
IPv6

Designing an IPv6 home network is a departure from IPv4. Unlike IPv4, IPv6 is designed to be used end-to-end without NAT. There is, technically, an equivalent to private subnets + NAT on IPv4, which are ULA (Unique-Local Addresses, fc00:​:/7) + NAT66 (IPv6-to-IPv6 translation), but it's generally discouraged in favor of GUA (Global Unicast Addresses), which are the public addresses delegated by your ISP. We stick to GUA here.

In IPAM > RIRs, create one object corresponding to your ISP's Regional Internet Registry, e.g. RIPE NCC for a European ISP.

In IPAM > Aggregates, create the aggregate mapped to that RIR:

  • <isp_prefix> — the block your ISP delegates to you, typically a /48, /56, /60, or /61, e.g. 2a01:e0a:16e:bbe0::/61

Prefixes

IPv4

Use one of the aforementioned aggregates for your homelab addressing plan, in the following I'm using 10/8.

In IPAM > Prefixes, create a prefix and set its VLAN:

  • 10.1.0.0/16 mapped to VLAN 1
  • 10.10.0.0/16 mapped to VLAN 10
  • 10.20.0.0/16 mapped to VLAN 20

It's common to include the VID in the prefix, e.g. 10.10.0.0/16 or 10.0.10.0/24 or 192.168.10.0/24, etc. to "visualize" where a device lands.

IPv6

In IPAM > Prefixes, also create a /64 prefix per VLAN from your delegated IPv6 block:

  • <isp_prefix:lan>/64 mapped to VLAN 1, e.g. 2a01:e0a:16e:bbe1::/64
  • <isp_prefix:iot>/64 mapped to VLAN 10, e.g. 2a01:e0a:16e:bbe2::/64
  • <isp_prefix:guests>/64 mapped to VLAN 20, e.g. 2a01:e0a:16e:bbe3::/64

Note: the first /64 of the delegated block is typically used for the WAN link between modem and router — it is not available for LAN use. LAN assignments start from the second /64.

IPs

In IPAM > IPs, create the following objects:

  • 10.1.0.1/16:
    • Interface: jdoe-router LAN bridge (see discussion at the beginning)
    • Primary IP: yes
    • DNS Name: jdoe-router.<domain>
  • 10.1.0.2/16:
    • Interface: jdoe-pve interface
    • Primary IP: yes
    • DNS Name: jdoe-pve.<domain>
  • 10.1.0.3/16:
    • Interface: jdoe-example interface
    • Primary IP: yes
    • DNS Name: jdoe-example.<domain>
  • <isp_prefix:lan>::1/64, e.g. 2a01:e0a:16e:bbe1::1/64, same as 10.1.0.1 above
  • <isp_prefix:lan>::2/64, e.g. 2a01:e0a:16e:bbe1::2/64, same as 10.1.0.2 above
  • <isp_prefix:lan>::3/64, e.g. 2a01:e0a:16e:bbe1::3/64, same as 10.1.0.3 above

Note: our devices have therefore 2 primary IPs (IPv4, IPv6) — on UI elements able to show only one IP (such as on the dashboard), the IPv6 will be displayed by default.

What's Next?

Having filled all that, we now have a nice interactive documentation of our network.

It's easy to proceed with a manual configuration from here.

However, the next interesting step is to ditch all your automation input configuration files and instead query Netbox, which is another project.

Appendix: Concrete IPv6 Configuration Example

Overview

  • ISP Modem/Router: Freebox Mini 4K
  • Router: UCG-Fiber

ISP prefix delegation

The Freebox delegates 8 × /64 prefixes, equivalent to a /61: - 2a01:e0a:16e:bbe0::/64 through 2a01:e0a:16e:bbe7::/64

The Freebox uses bbe0::/64 for the WAN link between itself and the downstream router — it assigns itself ::1 in that subnet and announces it via RA. This subnet is therefore not available for LAN use. LAN assignments start from bbe1:

  • Default LAN → 2a01:e0a:16e:bbe1::/64
  • IoT → 2a01:e0a:16e:bbe2::/64
  • Guests → 2a01:e0a:16e:bbe3::/64
  • bbe4 through bbe7 are spare.

Freebox configuration

The Freebox does not support DHCPv6-PD (IA_PD) in its default configuration. The workaround is to configure static routes on the Freebox for each LAN prefix, with the UCG-Fiber WAN link-local address (fe80:​:...) as the next hop. The Freebox only accepts link-local addresses as next hops in its UI.

Leave bbe0::/64 without a next hop — it is the WAN link subnet, handled locally by the Freebox.

UCG-Fiber WAN configuration

Use SLAAC on the WAN interface, not DHCPv6. With DHCPv6, the Freebox only assigns a ULA address with no default IPv6 route, so the router cannot reach the internet over IPv6. With SLAAC, the router receives a GUA address in bbe0::/64 and a default route via the Freebox's RA.

UCG-Fiber LAN configuration

Set each LAN to static IPv6 and enter the /64 manually. The "Prefix Delegation" mode in UniFi Network does not expose offset controls, leaving subnet assignment opaque.

Servers

Servers (Proxmox VE, VMs acting as infrastructure) should have their IPv6 configured statically on the device itself, the same way as IPv4. There is no DHCPv6 static mapping equivalent on the UCG-Fiber. Netbox serves as the address plan reference to avoid conflicts.

No DHCPv6 on LAN

End-user clients are addressed via SLAAC only. DHCPv6 is disabled on the Freebox. Servers use static configuration. There is no centralized IPv6 address pinning equivalent to IPv4 DHCP reservations.