netbox-community · jeremystretch · Dec 10, 2018 · Aug 14, 2018 · Aug 14, 2018 · Aug 14, 2018
diff --git a/.travis.yml b/.travis.yml
@@ -5,7 +5,6 @@ addons:
   postgresql: "9.4"
 language: python
 python:
-  - "2.7"
   - "3.5"
 install:
   - pip install -r requirements.txt

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,82 @@
+v2.5.0 (2018-12-10)
+
+## Notes
+
+### Python 3 Required
+
+As promised, Python 2 support has been completed removed. Python 3.5 or higher is now required to run NetBox. Please see [our Python 3 migration guide](https://netbox.readthedocs.io/en/stable/installation/migrating-to-python3/) for assistance with upgrading.
+
+### Removed Deprecated User Activity Log
+
+The UserAction model, which was deprecated by the new change logging feature in NetBox v2.4, has been removed. If you need to archive legacy user activity, do so prior to upgrading to NetBox v2.5, as the database migration will remove all data associated with this model.
+
+### View Permissions in Django 2.1
+
+Django 2.1 introduces view permissions for object types (not to be confused with object-level permissions). Implementation of [#323](https://github.com/digitalocean/netbox/issues/323) is planned for NetBox v2.6. Users are encourage to begin assigning view permissions as desired in preparation for their eventual enforcement.
+
+### upgrade.sh No Longer Invokes sudo
+
+The `upgrade.sh` script has been tweaked so that it no longer invokes `sudo` internally. This was done to ensure compatibility when running NetBox inside a Python virtual environment. If you need elevated permissions when upgrading NetBox, call the upgrade script with `sudo upgrade.sh`.
+
+## New Features
+
+### Patch Panels and Cables ([#20](https://github.com/digitalocean/netbox/issues/20))
+
+NetBox now supports modeling physical cables for console, power, and interface connections. The new pass-through port component type has also been introduced to model patch panels and similar devices.
+
+## Enhancements
+
+* [#450](https://github.com/digitalocean/netbox/issues/450) - Added `outer_width` and `outer_depth` fields to rack model
+* [#867](https://github.com/digitalocean/netbox/issues/867) - Added `description` field to circuit terminations
+* [#1444](https://github.com/digitalocean/netbox/issues/1444) - Added an `asset_tag` field for racks
+* [#1931](https://github.com/digitalocean/netbox/issues/1931) - Added a count of assigned IP addresses to the interface API serializer
+* [#2000](https://github.com/digitalocean/netbox/issues/2000) - Dropped support for Python 2
+* [#2053](https://github.com/digitalocean/netbox/issues/2053) - Introduced the `LOGIN_TIMEOUT` configuration setting
+* [#2057](https://github.com/digitalocean/netbox/issues/2057) - Added description columns to interface connections list
+* [#2104](https://github.com/digitalocean/netbox/issues/2104) - Added a `status` field for racks
+* [#2165](https://github.com/digitalocean/netbox/issues/2165) - Improved natural ordering of Interfaces
+* [#2292](https://github.com/digitalocean/netbox/issues/2292) - Removed the deprecated UserAction model
+* [#2367](https://github.com/digitalocean/netbox/issues/2367) - Removed deprecated RPCClient functionality
+* [#2426](https://github.com/digitalocean/netbox/issues/2426) - Introduced `SESSION_FILE_PATH` configuration setting for authentication without write access to database
+* [#2594](https://github.com/digitalocean/netbox/issues/2594) - `upgrade.sh` no longer invokes sudo
+
+## Changes From v2.5-beta2
+
+* [#2474](https://github.com/digitalocean/netbox/issues/2474) - Add `cabled` and `connection_status` filters for device components
+* [#2616](https://github.com/digitalocean/netbox/issues/2616) - Convert Rack `outer_unit` and Cable `length_unit` to integer-based choice fields
+* [#2622](https://github.com/digitalocean/netbox/issues/2622) - Enable filtering cables by multiple types/colors
+* [#2624](https://github.com/digitalocean/netbox/issues/2624) - Delete associated content type and permissions when removing InterfaceConnection model
+* [#2626](https://github.com/digitalocean/netbox/issues/2626) - Remove extraneous permissions generated from proxy models
+* [#2632](https://github.com/digitalocean/netbox/issues/2632) - Change representation of null values from `0` to `null`
+* [#2639](https://github.com/digitalocean/netbox/issues/2639) - Fix preservation of length/dimensions unit for racks and cables
+* [#2648](https://github.com/digitalocean/netbox/issues/2648) - Include the `connection_status` field in nested represenations of connectable device components
+* [#2649](https://github.com/digitalocean/netbox/issues/2649) - Add `connected_endpoint_type` to connectable device component API representations
+
+## API Changes
+
+* The `/extras/recent-activity/` endpoint (replaced by change logging in v2.4) has been removed
+* The `rpc_client` field has been removed from dcim.Platform (see #2367)
+* Introduced a new API endpoint for cables at `/dcim/cables/`
+* New endpoints for front and rear pass-through ports (and their templates) in parallel with existing device components
+* The fields `interface_connection` on Interface and `interface` on CircuitTermination have been replaced with `connected_endpoint` and `connection_status`
+* A new `cable` field has been added to console, power, and interface components and to circuit terminations
+* New fields for dcim.Rack: `status`, `asset_tag`, `outer_width`, `outer_depth`, `outer_unit`
+* The following boolean filters on dcim.Device and dcim.DeviceType have been renamed:
+    * `is_console_server`: `console_server_ports`
+    * `is_pdu`: `power_outlets`
+    * `is_network_device`: `interfaces`
+* The following new boolean filters have been introduced for dcim.Device and dcim.DeviceType:
+    * `console_ports`
+    * `power_ports`
+    * `pass_through_ports`
+* The field `interface_ordering` has been removed from the DeviceType serializer
+* Added a `description` field to the CircuitTermination serializer
+* Added `ipaddress_count` to InterfaceSerializer to show the count of assigned IP addresses for each interface
+* The `available-prefixes` and `available-ips` IPAM endpoints now return an HTTP 204 response instead of HTTP 400 when no new objects can be created
+* Filtering on null values now uses the string `null` instead of zero
+
+---
+
 v2.4.9 (2018-12-07)
 
 ## Enhancements

diff --git a/README.md b/README.md
@@ -16,8 +16,6 @@ or join us in the #netbox Slack channel on [NetworkToCode](https://networktocode
 
 ### Build Status
 
-NetBox is built against both Python 2.7 and 3.5. Python 3.5 or higher is strongly recommended.
-
 |             | status |
 |-------------|------------|
 | **master** | [![Build Status](https://travis-ci.org/digitalocean/netbox.svg?branch=master)](https://travis-ci.org/digitalocean/netbox) |

diff --git a/base_requirements.txt b/base_requirements.txt
@@ -1,25 +1,72 @@
-# django-filter-1.1.0 breaks with Django-2.1
-Django>=1.11,<2.1
+# The Python web framework on which NetBox is built
+# https://github.com/django/django
+Django
+
+# Django middleware which permits cross-domain API requests
+# https://github.com/OttoYiu/django-cors-headers
 django-cors-headers
+
+# Runtime UI tool for debugging Django
+# https://github.com/jazzband/django-debug-toolbar
 django-debug-toolbar
-# django-filter-2.0.0 drops Python 2 support (blocked by #2000)
-django-filter==1.1.0
+
+# Library for writing reusable URL query filters
+# https://github.com/carltongibson/django-filter
+django-filter
+
+# Modified Preorder Tree Traversal (recursive nesting of objects)
+# https://github.com/django-mptt/django-mptt
 django-mptt
+
+# Abstraction models for rendering and paginating HTML tables
+# https://github.com/jieter/django-tables2
 django-tables2
+
+# User-defined tags for objects
+# https://github.com/alex/django-taggit
 django-taggit
+
+# A Django REST Framework serializer which represents tags
+# https://github.com/glemmaPaul/django-taggit-serializer
 django-taggit-serializer
+
+# A Django field for representing time zones
+# https://github.com/mfogel/django-timezone-field/
 django-timezone-field
-# https://github.com/encode/django-rest-framework/issues/6053
-djangorestframework==3.8.1
+
+# A REST API framework for Django projects
+# https://github.com/encode/django-rest-framework
+djangorestframework
+
+# Swagger/OpenAPI schema generation for REST APIs
+# https://github.com/axnsan12/drf-yasg
 drf-yasg[validation]
+
+# Python interface to the graphviz graph rendering utility
+# https://github.com/xflr6/graphviz
 graphviz
-Markdown
-natsort
-ncclient
+
+# Simple markup language for rendering HTML
+# https://github.com/Python-Markdown/markdown
+# py-gfm requires Markdown<3.0
+Markdown<3.0
+
+# Library for manipulating IP prefixes and addresses
+# https://github.com/drkjam/netaddr
 netaddr
-paramiko
+
+# Fork of PIL (Python Imaging Library) for image processing
+# https://github.com/python-pillow/Pillow
 Pillow
+
+# PostgreSQL database adapter for Python
+# https://github.com/psycopg/psycopg2
 psycopg2-binary
+
+# GitHub-flavored Markdown extensions
+# https://github.com/zopieux/py-gfm
 py-gfm
+
+# Extensive cryptographic library (fork of pycrypto)
+# https://github.com/Legrandin/pycryptodome
 pycryptodome
-xmltodict
diff --git a/docs/administration/netbox-shell.md b/docs/administration/netbox-shell.md
@@ -9,7 +9,7 @@ This will launch a customized version of [the built-in Django shell](https://doc
 ```
 $ ./manage.py nbshell
 ### NetBox interactive shell (jstretch-laptop)
-### Python 2.7.6 | Django 1.11.3 | NetBox 2.1.0-dev
+### Python 3.5.2 | Django 2.0.8 | NetBox 2.4.3
 ### lsmodels() will show available models. Use help(<model>) for more info.
 ```
 

diff --git a/docs/configuration/optional-settings.md b/docs/configuration/optional-settings.md
@@ -133,6 +133,14 @@ Setting this to True will permit only authenticated users to access any part of
 
 ---
 
+## LOGIN_TIMEOUT
+
+Default: 1209600 seconds (14 days)
+
+The liftetime (in seconds) of the authentication cookie issued to a NetBox user upon login.
+
+---
+
 ## MAINTENANCE_MODE
 
 Default: False
@@ -223,6 +231,14 @@ The file path to the location where custom reports will be kept. By default, thi
 
 ---
 
+## SESSION_FILE_PATH
+
+Default: None
+
+Session data is used to track authenticated users when they access NetBox. By default, NetBox stores session data in the PostgreSQL database. However, this inhibits authentication to a standby instance of NetBox without write access to the database. Alternatively, a local file path may be specified here and NetBox will store session data as files instead of using the database. Note that the user as which NetBox runs must have read and write permissions to this path.
+
+---
+
 ## TIME_ZONE
 
 Default: UTC

diff --git a/docs/core-functionality/circuits.md b/docs/core-functionality/circuits.md
@@ -25,7 +25,7 @@ Circuit types are fully customizable.
 
 A circuit may have one or two terminations, annotated as the "A" and "Z" sides of the circuit. A single-termination circuit can be used when you don't know (or care) about the far end of a circuit (for example, an Internet access circuit which connects to a transit provider). A dual-termination circuit is useful for tracking circuits which connect two sites.
 
-Each circuit termination is tied to a site, and optionally to a specific device and interface within that site. Each termination can be assigned a separate downstream and upstream speed independent from one another. Fields are also available to track cross-connect and patch panel details.
+Each circuit termination is tied to a site, and may optionally be connected via a cable to a specific device interface or pass-through port. Each termination can be assigned a separate downstream and upstream speed independent from one another. Fields are also available to track cross-connect and patch panel details.
 
 !!! note
     A circuit represents a physical link, and cannot have more than two endpoints. When modeling a multi-point topology, each leg of the topology must be defined as a discrete circuit.

diff --git a/docs/core-functionality/devices.md b/docs/core-functionality/devices.md
@@ -4,12 +4,6 @@ A device type represents a particular make and model of hardware that exists in
 
 Device types are instantiated as devices installed within racks. For example, you might define a device type to represent a Juniper EX4300-48T network switch with 48 Ethernet interfaces. You can then create multiple devices of this type named "switch1," "switch2," and so on. Each device will inherit the components (such as interfaces) of its device type at the time of creation. (However, changes made to a device type will **not** apply to instances of that device type retroactively.)
 
-The device type model includes three flags which inform what type of components may be added to it:
-
-* `is_console_server`: This device type has console server ports
-* `is_pdu`: This device type has power outlets
-* `is_network_device`: This device type has network interfaces
-
 Some devices house child devices which share physical resources, like space and power, but which functional independently from one another. A common example of this is blade server chassis. Each device type is designated as one of the following:
 
 * A parent device (which has device bays)
@@ -32,6 +26,8 @@ Each device type is assigned a number of component templates which define the ph
 * Power ports
 * Power outlets
 * Network interfaces
+* Front ports
+* Rear ports
 * Device bays (which house child devices)
 
 Whenever a new device is created, its components are automatically created per the templates assigned to its device type. For example, a Juniper EX4300-48T device type might have the following component templates defined:
@@ -56,32 +52,28 @@ When assigning a multi-U device to a rack, it is considered to be mounted in the
 
 A device is said to be full depth if its installation on one rack face prevents the installation of any other device on the opposite face within the same rack unit(s). This could be either because the device is physically too deep to allow a device behind it, or because the installation of an opposing device would impede airflow.
 
-## Device Roles
-
-Devices can be organized by functional roles. These roles are fully customizable. For example, you might create roles for core switches, distribution switches, and access switches.
-
----
-
-# Device Components
+## Device Components
 
-There are six types of device components which comprise all of the interconnection logic with NetBox:
+There are eight types of device components which comprise all of the interconnection logic with NetBox:
 
 * Console ports
 * Console server ports
 * Power ports
 * Power outlets
 * Network interfaces
+* Front ports
+* Rear ports
 * Device bays
 
-## Console
+### Console
 
 Console ports connect only to console server ports. Console connections can be marked as either *planned* or *connected*.
 
-## Power
+### Power
 
 Power ports connect only to power outlets. Power connections can be marked as either *planned* or *connected*.
 
-## Interfaces
+### Interfaces
 
 Interfaces connect to one another in a symmetric manner: If interface A connects to interface B, interface B therefore connects to interface A. Each type of connection can be classified as either *planned* or *connected*.
 
@@ -91,10 +83,20 @@ Each interface can also be enabled or disabled, and optionally designated as man
 
 VLANs can be assigned to each interface as either tagged or untagged. (An interface may have only one untagged VLAN.)
 
-## Device Bays
+### Pass-through Ports
+
+Pass-through ports are used to model physical terminations which comprise part of a longer path, such as a cable terminated to a patch panel. Each front port maps to a position on a rear port. A 24-port UTP patch panel, for instance, would have 24 front ports and 24 rear ports. Although this relationship is typically one-to-one, a rear port may have multiple front ports mapped to it. This can be useful for modeling instances where multiple paths share a common cable (for example, six different fiber connections sharing a 12-strand MPO cable).
+
+Pass-through ports can also be used to model "bump in the wire" devices, such as a media convertor or passive tap.
+
+### Device Bays
 
 Device bays represent the ability of a device to house child devices. For example, you might install four blade servers into a 2U chassis. The chassis would appear in the rack elevation as a 2U device with four device bays. 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, but they are included in the "Non-Racked Devices" list within the rack view.
 
+## Device Roles
+
+Devices can be organized by functional roles. These roles are fully customizable. For example, you might create roles for core switches, distribution switches, and access switches.
+
 ---
 
 # Platforms
@@ -118,3 +120,25 @@ Inventory items represent hardware components installed within a device, such as
 A virtual chassis represents a set of devices which share a single control plane: a stack of switches which are managed as a single device, for example. Each device in the virtual chassis is assigned a position and (optionally) a priority. Exactly one device is designated the virtual chassis master: This device will typically be assigned a name, secrets, services, and other attributes related to its management.
 
 It's important to recognize the distinction between a virtual chassis and a chassis-based device. For instance, a virtual chassis is not used to model a chassis switch with removable line cards such as the Juniper EX9208, as its line cards are _not_ physically separate devices capable of operating independently.
+
+---
+
+# Cables
+
+A cable represents a physical connection between two termination points, such as between a console port and a patch panel port, or between two network interfaces. Cables can be traced through pass-through ports to form a complete path between two endpoints. In the example below, three individual cables comprise a path between the two connected endpoints.
+
+```
+|<------------------------------------------ Cable Path ------------------------------------------->|
+
+  Device A                   Patch Panel A                 Patch Panel B                  Device B
++-----------+               +-------------+               +-------------+               +-----------+
+| Interface | --- Cable --- | Front Port  |               | Front Port  | --- Cable --- | Interface |
++-----------+               +-------------+               +-------------+               +-----------+
+                            +-------------+               +-------------+
+                            |  Rear Port  | --- Cable --- |  Rear Port  |
+                            +-------------+               +-------------+
+```
+
+All connections between device components in NetBox are represented using cables. However, defining the actual cable plant is optional: Components can be be directly connected using cables with no type or other attributes assigned.
+
+Cables are also used to associated ports and interfaces with circuit terminations. To do this, first create the circuit termination, then navigate the desired component and connect a cable between the two.