Update model docs for device components

docs/models/dcim/consoleport.md

@@ -1,5 +1,36 @@
-## Console Ports
+# Console Ports
 
-A console port provides connectivity to the physical console of a device. These are typically used for temporary access by someone who is physically near the device, or for remote out-of-band access provided via a networked console server. Each console port may be assigned a physical type.
+A console port provides connectivity to the physical console of a device. These are typically used for temporary access by someone who is physically near the device, or for remote out-of-band access provided via a networked console server.
 
-Cables can connect console ports to console server ports or pass-through ports.
+!!! tip
+    Like most device components, console ports are instantiated automatically from [console port templates](./consoleporttemplate.md) assigned to the selected device type when a device is created.
+
+## Fields
+
+### Device
+
+The device to which this console port belongs.
+
+### Module
+
+The installed module within the assigned device to which this console port belongs (optional).
+
+### Name
+
+The name of the console port. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the console port.
+
+### Type
+
+The type of console port.
+
+### Speed
+
+Operating speed, in bits per second (bps).
+
+### Mark Connected
+
+If selected, this component will be treated as if a cable has been connected.

docs/models/dcim/consoleporttemplate.md

@@ -1,3 +1,3 @@
-## Console Port Templates
+# Console Port Templates
 
-A template for a console port that will be created on all instantiations of the parent device type. Each console port can be assigned a physical type.
+A template for a console port that will be created on all instantiations of the parent device type. See the [console port](./consoleport.md) documentation for more detail.

docs/models/dcim/consoleserverport.md

@@ -1,5 +1,36 @@
-## Console Server Ports
+# Console Server Ports
 
-A console server is a device which provides remote access to the local consoles of connected devices. They are typically used to provide remote out-of-band access to network devices. Each console server port may be assigned a physical type.
+A console server is a device which provides remote access to the local consoles of connected devices. They are typically used to provide remote out-of-band access to network devices, and generally connect to [console ports](./consoleport.md).
 
-Cables can connect console server ports to console ports or pass-through ports.
+!!! tip
+    Like most device components, console server ports are instantiated automatically from [console server port templates](./consoleserverporttemplate.md) assigned to the selected device type when a device is created.
+
+## Fields
+
+### Device
+
+The device to which this console server port belongs.
+
+### Module
+
+The installed module within the assigned device to which this console server port belongs (optional).
+
+### Name
+
+The name of the console server port. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the console server port.
+
+### Type
+
+The type of console server port.
+
+### Speed
+
+Operating speed, in bits per second (bps).
+
+### Mark Connected
+
+If selected, this component will be treated as if a cable has been connected.

docs/models/dcim/consoleserverporttemplate.md

@@ -1,3 +1,3 @@
-## Console Server Port Templates
+# Console Server Port Templates
 
-A template for a console server port that will be created on all instantiations of the parent device type. Each console server port can be assigned a physical type.
+A template for a console server port that will be created on all instantiations of the parent device type. See the [console server port](./consoleserverport.md) documentation for more detail.

docs/models/dcim/devicebay.md

@@ -1,8 +1,22 @@
-## Device Bays
+# Device Bays
 
 Device bays represent a space or slot within a parent device in which a child device may be installed. For example, a 2U parent chassis might house four individual blade servers. The chassis would appear in the rack elevation as a 2U device with four device bays, and each server within it would be defined as a 0U device installed in one of the device bays. Child devices do not appear within rack elevations or count as consuming rack units.
 
 Child devices are first-class Devices in their own right: That is, they are fully independent managed entities which don't share any control plane with the parent.  Just like normal devices, child devices have their own platform (OS), role, tags, and components.  LAG interfaces may not group interfaces belonging to different child devices.
 
 !!! note
-    Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, these should be modeled as modules installed within module bays.
+    Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, these should be modeled as [modules](./module.md) installed within [module bays](./modulebay.md).
+
+## Fields
+
+### Device
+
+The device to which this device bay belongs.
+
+### Name
+
+The device bay's name. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the device bay.

docs/models/dcim/devicebaytemplate.md

@@ -1,3 +1,3 @@
-## Device Bay Templates
+# Device Bay Templates
 
-A template for a device bay that will be created on all instantiations of the parent device type. Device bays hold child devices, such as blade servers.
+A template for a device bay that will be created on all instantiations of the parent device type. See the [device bay](./devicebay.md) documentation for more detail.

docs/models/dcim/frontport.md

@@ -1,3 +1,40 @@
-## Front Ports
+# Front Ports
 
-Front ports are pass-through ports used to represent physical cable connections that comprise part of a longer path. For example, the ports on the front face of a UTP patch panel would be modeled in NetBox as front ports. Each port is assigned a physical type, and must be mapped to a specific rear port on the same device. A single rear port may be mapped to multiple front ports, using numeric positions to annotate the specific alignment of each.
+Front ports are pass-through ports which represent physical cable connections that comprise part of a longer path. For example, the ports on the front face of a UTP patch panel would be modeled in NetBox as front ports. Each port is assigned a physical type, and must be mapped to a specific [rear port](./rearport.md) on the same device. A single rear port may be mapped to multiple front ports, using numeric positions to annotate the specific alignment of each.
+
+## Fields
+
+### Device
+
+The device to which this port belongs.
+
+### Module
+
+The installed module within the assigned device to which this port belongs (optional).
+
+### Name
+
+The port's name. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the port.
+
+### Type
+
+The port's termination type.
+
+### Rear Ports
+
+The rear port and position to which this front port maps.
+
+!!! tip
+    When creating multiple front ports using a patterned name (e.g. `Port [1-12]`), you may select the equivalent number of rear port-position mappings from the list.
+
+### Color
+
+The port's color (optional).
+
+### Mark Connected
+
+If selected, this component will be treated as if a cable has been connected.

docs/models/dcim/frontporttemplate.md

@@ -1,3 +1,3 @@
-## Front Port Templates
+# Front Port Templates
 
-A template for a front-facing pass-through port that will be created on all instantiations of the parent device type. Front ports may have a physical type assigned, and must be associated with a corresponding rear port and position. This association will be automatically replicated when the device type is instantiated.
+A template for a front-facing pass-through port that will be created on all instantiations of the parent device type. See the [front port](./frontport.md) documentation for more detail.

docs/models/dcim/interface.md

@@ -1,34 +1,138 @@
-## Interfaces
+# Interfaces
 
-Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. Each interface must be assigned a type, and may optionally be assigned a MAC address, MTU, and IEEE 802.1Q mode (tagged or access). Each interface can also be enabled or disabled, and optionally designated as management-only (for out-of-band management). Additionally, each interface may optionally be assigned to a VRF.
+Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. IP addresses and VLANs can be assigned to interfaces.
 
 !!! note
-    Although devices and virtual machines both can have interfaces, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa.
+    Although both devices and virtual machines both can have interfaces assigned, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa.
 
-### Interface Types
+## Fields
 
-Interfaces may be physical or virtual in nature, but only physical interfaces may be connected via cables. Cables can connect interfaces to pass-through ports, circuit terminations, or other interfaces. Virtual interfaces, such as 802.1Q-tagged subinterfaces, may be assigned to physical parent interfaces.
+### Device
 
-Physical interfaces may be arranged into a link aggregation group (LAG) and associated with a parent LAG (virtual) interface. LAG interfaces can be recursively nested to model bonding of trunk groups. Like all virtual interfaces, LAG interfaces cannot be connected physically.
+The device to which this interface belongs.
 
-### Power over Ethernet (PoE)
+### Module
+
+The installed module within the assigned device to which this interface belongs (optional).
+
+### Name
+
+The name of the interface, as reported by the device's operating system. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the interface.
+
+### Type
+
+The type of interface. Interfaces may be physical or virtual in nature, but only physical interfaces may be connected via cables.
 
 !!! note
-    This feature was added in NetBox v3.3.
+    The interface type refers to the physical termination or port on the device. Interfaces which employ a removable optic or similar transceiver should be defined to represent the type of transceiver in use, irrespective of the physical termination to that transceiver.
 
-Physical interfaces can be assigned a PoE mode to indicate PoE capability: power supplying equipment (PSE) or powered device (PD). Additionally, a PoE mode may be specified. This can be one of the listed IEEE 802.3 standards, or a passive setting (24 or 48 volts across two or four pairs).
+### Speed
 
-### Wireless Interfaces
+The operating speed, in kilobits per second (kbps).
 
-Wireless interfaces may additionally track the following attributes:
+### Duplex
 
-* **Role** - AP or station
-* **Channel** - One of several standard wireless channels
-* **Channel Frequency** - The transmit frequency
-* **Channel Width** - Channel bandwidth
+The operation duplex (full, half, or auto).
 
-If a predefined channel is selected, the frequency and width attributes will be assigned automatically. If no channel is selected, these attributes may be defined manually.
+### VRF
 
-### IP Address Assignment
+The [virtual routing and forwarding](../ipam/vrf.md) instance to which this interface is assigned.
 
-IP addresses can be assigned to interfaces. VLANs can also be assigned to each interface as either tagged or untagged. (An interface may have only one untagged VLAN.)
+### MAC Address
+
+The 48-bit MAC address (for Ethernet interfaces).
+
+### WWN
+
+The 64-bit world-wide name (for Fibre Channel interfaces).
+
+### MTU
+
+The interface's configured maximum transmissible unit (MTU).
+
+### Transmit Power
+
+The interface's configured output power, in dBm (for optical interfaces).
+
+### Enabled
+
+If not selected, this interface will be treated as disabled/inoperative.
+
+### Management Only
+
+Designates the interface as handling management traffic only (e.g. for out-of-band management connections).
+
+### Mark Connected
+
+If selected, this component will be treated as if a cable has been connected.
+
+### Parent Interface
+
+Virtual interfaces can be bound to a physical parent interface. This is helpful for modeling virtual interfaces which employ encapsulation on a physical interface, such as an 802.1Q VLAN-tagged subinterface.
+
+### Bridged Interface
+
+Interfaces can be bridged to other interfaces on a device in two manners: symmetric or grouped.
+
+* **Symmetric:** For example, eth0 is bridged to eth1, and eth1 is bridged to eth0. This effects a point-to-point bridge between the two interfaces, which NetBox will follow when tracing cable paths.
+* **Grouped:** Multiple interfaces are each bridged to a common virtual bridge interface, effecting a multiaccess bridged segment. NetBox cannot follow these relationships when tracing cable paths, because no forwarding information is available.
+
+### LAG Interface
+
+Physical interfaces may be arranged into link aggregation groups (LAGs, also known as "trunks") and associated with a parent LAG (virtual) interface. LAG interfaces can be recursively nested to model bonding of trunk groups. Like all virtual interfaces, LAG interfaces cannot be connected physically.
+
+### PoE Mode
+
+The power over Ethernet (PoE) mode for this interface. (This field must be left empty for interfaces which do not support PoE.) Choices include:
+
+* Powered device (PD)
+* Power-supplying equipment (PSE)
+
+### PoE Type
+
+The classification of PoE transmission supported, for PoE-enabled interfaces. This can be one of the listed IEEE 802.3 standards, or a passive setting (24 or 48 volts across two or four pairs).
+
+### 802.1Q Mode
+
+For switched Ethernet interfaces, this identifies the 802.1Q encapsulation strategy in effect. Options include:
+
+* **Access:** All traffic is assigned to a single VLAN, with no tagging.
+* **Tagged:** One untagged "native" VLAN is allowed, as well as any number of tagged VLANs.
+* **Tagged (all):** Implies that all VLANs are carried by the interface. One untagged VLAN may be designated.
+
+This field must be left blank for routed interfaces which do employ 802.1Q encapsulation.
+
+### Untagged VLAN
+
+The "native" (untagged) VLAN for the interface. Valid only when one of the above 802.1Q mode is selected.
+
+### Tagged VLANs
+
+The tagged VLANs which are configured to be carried by this interface. Valid only for the "tagged" 802.1Q mode above.
+
+### Wireless Role
+
+Indicates the configured role for wireless interfaces (access point or station).
+
+### Wireless Channel
+
+The configured channel for wireless interfaces.
+
+!!! tip
+    Selecting one of the pre-defined wireless channels will automatically populate the channel frequency and width upon saving the interface.
+
+### Channel Frequency
+
+The configured operation frequency of a wireless interface, in MHz. This is typically inferred by the configured channel above, but may be set manually e.g. to identify a licensed channel not available for general use.
+
+### Channel Width
+
+The configured channel width of a wireless interface, in MHz. This is typically inferred by the configured channel above, but may be set manually e.g. to identify a licensed channel not available for general use.
+
+### Wireless LANs
+
+The [wireless LANs](../wireless/wirelesslan.md) for which this interface carries traffic. (Valid for wireless interfaces only.)

docs/models/dcim/interfacetemplate.md

@@ -1,3 +1,3 @@
-## Interface Templates
+# Interface Templates
 
-A template for a network interface that will be created on all instantiations of the parent device type. Each interface may be assigned a physical or virtual type, and may be designated as "management-only." Power over Ethernet (PoE) mode and type may also be assigned to interface templates.
+A template for a network interface that will be created on all instantiations of the parent device type. See the [interface](./interface.md) documentation for more detail.

docs/models/dcim/inventoryitem.md

@@ -2,6 +2,42 @@
 
 Inventory items represent hardware components installed within a device, such as a power supply or CPU or line card. They are intended to be used primarily for inventory purposes.
 
-Each inventory item can be assigned a functional role, manufacturer, part ID, serial number, and asset tag (all optional). A boolean toggle is also provided to indicate whether each item was entered manually or discovered automatically (by some process outside NetBox).
-
 Inventory items are hierarchical in nature, such that any individual item may be designated as the parent for other items. For example, an inventory item might be created to represent a line card which houses several SFP optics, each of which exists as a child item within the device. An inventory item may also be associated with a specific component within the same device. For example, you may wish to associate a transceiver with an interface.
+
+## Fields
+
+### Device
+
+The device in which the inventory item is installed.
+
+### Parent
+
+The parent inventory item to which this item is assigned (optional).
+
+### Name
+
+The inventory item's name. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the inventory item.
+
+### Role
+
+The functional [role](./inventoryitemrole.md) assigned to this inventory item.
+
+### Manufacturer
+
+The [manufacturer](./manufacturer.md) that produced the item.
+
+### Part ID
+
+The part identification or model number assigned by the manufacturer.
+
+### Serial Number
+
+The serial number assigned by the manufacturer.
+
+### Asset Tag
+
+A unique, locally-administered label used to identify hardware resources.

docs/models/dcim/inventoryitemtemplate.md

@@ -1,3 +1,3 @@
 # Inventory Item Templates
 
-A template for an inventory item that will be automatically created when instantiating a new device. All attributes of this object will be copied to the new inventory item, including the associations with a parent item and assigned component, if any.
+A template for an inventory item that will be automatically created when instantiating a new device. All attributes of this object will be copied to the new inventory item, including the associations with a parent item and assigned component, if any. See the [inventory item](./inventoryitem.md) documentation for more detail.

docs/models/dcim/modulebay.md

@@ -1,3 +1,24 @@
-## Module Bays
+# Module Bays
 
-Module bays represent a space or slot within a device in which a field-replaceable module may be installed. A common example is that of a chassis-based switch such as the Cisco Nexus 9000 or Juniper EX9200. Modules in turn hold additional components that become available to the parent device.
+Module bays represent a space or slot within a device in which a field-replaceable [module](./module.md) may be installed. A common example is that of a chassis-based switch such as the Cisco Nexus 9000 or Juniper EX9200. Modules in turn hold additional components that become available to the parent device.
+
+!!! note
+    If you need to model child devices rather than modules, use a [device bay](./devicebay.md) instead.
+
+## Fields
+
+### Device
+
+The device to which this module bay belongs.
+
+### Name
+
+The module bay's name. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the module bay.
+
+### Position
+
+The numeric position in which this module bay is situated. For example, this would be the number assigned to a slot within a chassis-based switch.

docs/models/dcim/modulebaytemplate.md

@@ -1,3 +1,3 @@
-## Module Bay Templates
+# Module Bay Templates
 
-A template for a module bay that will be created on all instantiations of the parent device type. Module bays hold installed modules that do not have an independent management plane, such as line cards.
+A template for a module bay that will be created on all instantiations of the parent device type. See the [module bay](./modulebay.md) documentation for more detail.

docs/models/dcim/poweroutlet.md

@@ -1,7 +1,39 @@
-## Power Outlets
+# Power Outlets
 
-Power outlets represent the outlets on a power distribution unit (PDU) or other device that supply power to dependent devices. Each power port may be assigned a physical type, and may be associated with a specific feed leg (where three-phase power is used) and/or a specific upstream power port. This association can be used to model the distribution of power within a device.
+Power outlets represent the outlets on a power distribution unit (PDU) or other device that supplies power to dependent devices. Each power port may be assigned a physical type, and may be associated with a specific feed leg (where three-phase power is used) and/or a specific upstream power port. This association can be used to model the distribution of power within a device.
 
 For example, imagine a PDU with one power port which draws from a three-phase feed and 48 power outlets arranged into three banks of 16 outlets each. Outlets 1-16 would be associated with leg A on the port, and outlets 17-32 and 33-48 would be associated with legs B and C, respectively.
 
-Cables can connect power outlets only to downstream power ports. (Pass-through ports cannot be used to model power distribution.)
+## Fields
+
+### Device
+
+The device to which this power outlet belongs.
+
+### Module
+
+The installed module within the assigned device to which this power outlet belongs (optional).
+
+### Name
+
+The name of the power outlet. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the power outlet.
+
+### Type
+
+The type of power outlet.
+
+### Power Port
+
+When modeling a device which redistributes power from an upstream supply, such as a power distribution unit (PDU), each power outlet should be mapped to the respective [power port](./powerport.md) on the device which supplies power. For example, a 24-outlet PDU may two power ports, each distributing power to 12 of its outlets.
+
+### Feed Leg
+
+This field is used to indicate to which leg of three-phase power circuit the outlet is bound. (This should be left blank for single-phase applications.)
+
+### Mark Connected
+
+If selected, this component will be treated as if a cable has been connected.

docs/models/dcim/poweroutlettemplate.md

@@ -1,3 +1,3 @@
-## Power Outlet Templates
+# Power Outlet Templates
 
-A template for a power outlet that will be created on all instantiations of the parent device type. Each power outlet can be assigned a physical type, and its power source may be mapped to a specific feed leg and power port template. This association will be automatically replicated when the device type is instantiated.
+A template for a power outlet that will be created on all instantiations of the parent device type. See the [power outlet](./poweroutlet.md) documentation for more detail.

docs/models/dcim/powerport.md

@@ -1,8 +1,40 @@
-## Power Ports
+# Power Ports
 
-A power port represents the inlet of a device where it draws its power, i.e. the connection port(s) on a device's power supply. Each power port may be assigned a physical type, as well as allocated and maximum draw values (in watts). These values can be used to calculate the overall utilization of an upstream power feed.
+A power port is a device component which draws power from some external source (e.g. an upstream [power outlet](./poweroutlet.md)), and generally represents a power supply internal to a device.
+
+## Fields
+
+### Device
+
+The device to which this power port belongs.
+
+### Module
+
+The installed module within the assigned device to which this power port belongs (optional).
+
+### Name
+
+The name of the power port. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the power port.
+
+### Type
+
+The type of power port.
+
+### Maximum Draw
+
+The maximum amount of power this port consumes (in watts).
 
 !!! info
-    When creating a power port on a device which supplies power to downstream devices, the allocated and maximum draw numbers should be left blank. Utilization will be calculated by taking the sum of all power ports of devices connected downstream.
+    When creating a power port on a device which is mapped to outlets and supplies power to downstream devices, the maximum and allocated draw numbers should be left blank. Utilization will be calculated by taking the sum of all power ports of devices connected downstream.
 
-Cables can connect power ports only to power outlets or power feeds. (Pass-through ports cannot be used to model power distribution.)
+### Allocated Draw
+
+The budgeted amount of power this port consumes (in watts).
+
+### Mark Connected
+
+If selected, this component will be treated as if a cable has been connected.

docs/models/dcim/powerporttemplate.md

@@ -1,3 +1,3 @@
-## Power Port Templates
+# Power Port Templates
 
-A template for a power port that will be created on all instantiations of the parent device type. Each power port can be assigned a physical type, as well as a maximum and allocated draw in watts.
+A template for a power port that will be created on all instantiations of the parent device type. See the [power port](./powerport.md) documentation for more detail.

docs/models/dcim/rearport.md

@@ -1,6 +1,40 @@
-## Rear Ports
+# Rear Ports
 
-Like front ports, rear ports are pass-through ports which represent the continuation of a path from one cable to the next. Each rear port is defined with its physical type and a number of positions: Rear ports with more than one position can be mapped to multiple front ports. This can be useful for modeling instances where multiple paths share a common cable (for example, six discrete two-strand fiber connections sharing a 12-strand MPO cable).
+Like [front ports](./frontport.md), rear ports are pass-through ports which represent the continuation of a path from one cable to the next. Each rear port is defined with its physical type and a number of positions: Rear ports with more than one position can be mapped to multiple front ports. This can be useful for modeling instances where multiple paths share a common cable (for example, six discrete two-strand fiber connections sharing a 12-strand MPO cable).
 
 !!! note
     Front and rear ports need not necessarily reside on the actual front or rear device face. This terminology is used primarily to distinguish between the two components in a pass-through port pairing.
+
+## Fields
+
+### Device
+
+The device to which this port belongs.
+
+### Module
+
+The installed module within the assigned device to which this port belongs (optional).
+
+### Name
+
+The port's name. Must be unique to the parent device.
+
+### Label
+
+An alternative physical label identifying the port.
+
+### Type
+
+The port's termination type.
+
+### Color
+
+The port's color (optional).
+
+### Positions
+
+The number of [front ports](./frontport.md) to which this rear port can be mapped. For example, an MPO fiber termination cassette might have a single 12-strand rear port mapped to 12 discrete front ports, each terminating a single fiber strand. (For rear ports which map directly to a single front port, set this to `1`.)
+
+### Mark Connected
+
+If selected, this component will be treated as if a cable has been connected.

docs/models/dcim/rearporttemplate.md

@@ -1,3 +1,3 @@
-## Rear Port Templates
+# Rear Port Templates
 
-A template for a rear-facing pass-through port that will be created on all instantiations of the parent device type. Each rear port may have a physical type and one or more front port templates assigned to it. The number of positions associated with a rear port determines how many front ports can be assigned to it (the maximum is 1024).
+A template for a rear-facing pass-through port that will be created on all instantiations of the parent device type. See the [rear port](./rearport.md) documentation for more detail.