Merge pull request #269 from digitalocean/develop

Release v1.2.0

README.md

@@ -15,62 +15,14 @@ Questions? Comments? Please join us on IRC in **#netbox** on **irc.freenode.net*
 
 ## Screenshots
 
-![Screenshot of main page](docs/screenshot1.png "Main page")
+![Screenshot of main page](docs/media/screenshot1.png "Main page")
 
-![Screenshot of rack elevation](docs/screenshot2.png "Rack elevation")
+![Screenshot of rack elevation](docs/media/screenshot2.png "Rack elevation")
 
-![Screenshot of prefix hierarchy](docs/screenshot3.png "Prefix hierarchy")
+![Screenshot of prefix hierarchy](docs/media/screenshot3.png "Prefix hierarchy")
 
 # Installation
 
 Please see docs/getting-started.md for instructions on installing NetBox.
 
 To upgrade NetBox, please download the [latest release](https://github.com/digitalocean/netbox/releases) and run `upgrade.sh`.
-
-# Components
-
-NetBox understands all of the physical and logical building blocks that comprise network infrastructure, and the manners in which they are all related.
-
-## DCIM
-
-DCIM comprises all the physical installations and connections which comprise a network. NetBox tracks where devices are installed, as well as their individual power, console, and network connections.
-
-**Site:** A physical location (typically a building) where network devices are installed. Devices in different sites cannot be directly connected to one another.
-
-**Rack:** An equipment rack into which devices are installed. Each rack belongs to a site.
-
-**Device:** Any type of rack-mounted device. For example, routers, switches, servers, console servers, PDUs, etc. 0U (non-rack-mounted) devices are supported.
-
-## IPAM
-
-IPAM deals with the IP addressing and VLANs in use on a network. NetBox makes a distinction between IP prefixes (networks) and individual IP addresses.
-
-Because NetBox is a combined DCIM/IPAM system, IP addresses can be assigned to device interfaces in the application just as they are in the real world.
-
-**Aggregate:** A top-level aggregate of IP address space; for example, 10.0.0.0/8 or 2001:db8::/32. Each aggregate belongs to a regional Internet registry (RIR) like ARIN or RIPE, or to an authoritative standard such as RFC 1918.
-
-**VRF:** A virtual routing table. VRF support is currently still under development.
-
-**Prefix:** An IPv4 or IPv6 network. A prefix can be assigned to a VRF; if not, it is considered to belong to the global table. Prefixes are grouped by aggregates automatically and can optionally be assigned to sites.
-
-**IP Address:** An individual IPv4 or IPv6 address (with CIDR mask). IP address can be assigned to device interfaces.
-
-**VLAN:** VLANs are assigned to sites, and can optionally have one or more IP prefixes assigned to them. VLAN IDs are unique only within the scope of a site.
-
-## Circuits
-
-Long-distance data connections are typically referred to as _circuits_. NetBox provides a method for managing circuits and their providers. Individual circuits can be terminated to device interfaces.
-
-**Provider:** An entity to which a network connects to. This can be a transit provider, peer, or some other organization.
-
-**Circuit:** A data circuit which connects to a provider. The local end of a circuit can be assigned to a device interface.
-
-## Secrets
-
-NetBox provides encrypted storage of sensitive data it calls _secrets_. Each user may be issued an encryption key with which stored secrets can be retrieved.
-
-Note that NetBox does not merely hash secrets, a function which is only useful for validation. It employs fully reversible AES-256 encryption so that secret data can be retrieved and consumed by other services.
-
-**Secrets** Any piece of confidential data which must be retrievable. For example: passwords, SNMP communities, RADIUS shared secrets, etc.
-
-**User Key:** An individual user's encrypted copy of the master key, which can be used to retrieve secret data.

docker-compose.yml

@@ -9,6 +9,7 @@ services:
             POSTGRES_PASSWORD: J5brHrAXFLQSif0K
             POSTGRES_DB: netbox
     netbox:
+        build: .
         image: digitalocean/netbox
         links:
         - postgres

docs/api-integration.md

@@ -0,0 +1,19 @@
+# API Integration
+
+NetBox features a read-only REST API which can be used to integrate it with
+other applications.
+
+In the future, both read and write actions will be available via the API.
+
+## Clients
+
+The easiest way to start integrating your applications with NetBox is to make
+use of an API client.  If you build or discover an API client that is not part
+of this list, please send a pull request!
+
+- **Go**: [github.com/digitalocean/go-netbox](https://github.com/digitalocean/go-netbox)
+
+## Documentation
+
+If you wish to build a new API client or simply explore the NetBox API,
+Swagger documentation can be found at the URL `/api/docs/` on a NetBox server.

docs/configuration/mandatory-settings.md

@@ -0,0 +1,45 @@
+NetBox's local configuration is held in `netbox/netbox/configuration.py`. An example configuration is provided at `netbox/netbox/configuration.example.py`. You may copy or rename the example configuration and make changes as appropriate. NetBox will not run without a configuration file.
+
+## ALLOWED_HOSTS
+
+This is a list of valid fully-qualified domain names (FQDNs) for the NetBox server. NetBox will not permit write access to the server via any other hostnames. The first FQDN in the list will be treated as the preferred name.
+
+Example:
+
+```
+ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123']
+```
+
+---
+
+## DATABASE
+
+NetBox requires access to a PostgreSQL database service to store data. This service can run locally or on a remote system. The following parameters must be defined within the `DATABASE` dictionary:
+
+* NAME - Database name
+* USER - PostgreSQL username
+* PASSWORD - PostgreSQL password
+* HOST - Name or IP address of the database server (use `localhost` if running locally)
+* PORT - TCP port of the PostgreSQL service; leave blank for default port (5432)
+
+Example:
+
+```
+DATABASE = {
+    'NAME': 'netbox',               # Database name
+    'USER': 'netbox',               # PostgreSQL username
+    'PASSWORD': 'J5brHrAXFLQSif0K', # PostgreSQL password
+    'HOST': 'localhost',            # Database server
+    'PORT': '',                     # Database port (leave blank for default)
+}
+```
+
+---
+
+## SECRET_KEY
+
+This is a secret cryptographic key is used to improve the security of cookies and password resets. The key defined here should not be shared outside of the configuration file. `SECRET_KEY` can be changed at any time, however be aware that doing so will invalidate all existing sessions.
+
+Please note that this key is **not** used for hashing user passwords or for the encrypted storage of secret data in NetBox.
+
+`SECRET_KEY` should be at least 50 characters in length and contain a random mix of letters, digits, and symbols. The script located at `netbox/generate_secret_key.py` may be used to generate a suitable key.

docs/configuration.md → docs/configuration/optional-settings.md

@@ -1,62 +1,6 @@
-<h1>Configuration</h1>
+The following are optional settings which may be declared in `netbox/netbox/configuration.py`.
 
-NetBox's local configuration is held in `netbox/netbox/configuration.py`. An example configuration is provided at `netbox/netbox/configuration.example.py`. You may copy or rename the example configuration and make changes as appropriate. NetBox will not run without a configuration file.
-
-[TOC]
-
-# Mandatory Settings
-
----
-
-#### ALLOWED_HOSTS
-
-This is a list of valid fully-qualified domain names (FQDNs) for the NetBox server. NetBox will not permit write access to the server via any other hostnames. The first FQDN in the list will be treated as the preferred name.
-
-Example:
-
-```
-ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123']
-```
-
----
-
-#### DATABASE
-
-NetBox requires access to a PostgreSQL database service to store data. This service can run locally or on a remote system. The following parameters must be defined within the `DATABASE` dictionary:
-
-* NAME - Database name
-* USER - PostgreSQL username
-* PASSWORD - PostgreSQL password
-* HOST - Name or IP address of the database server (use `localhost` if running locally)
-* PORT - TCP port of the PostgreSQL service; leave blank for default port (5432)
-
-Example:
-
-```
-DATABASE = {
-    'NAME': 'netbox',               # Database name
-    'USER': 'netbox',               # PostgreSQL username
-    'PASSWORD': 'J5brHrAXFLQSif0K', # PostgreSQL password
-    'HOST': 'localhost',            # Database server
-    'PORT': '',                     # Database port (leave blank for default)
-}
-```
-
----
-
-#### SECRET_KEY
-
-This is a secret cryptographic key is used to improve the security of cookies and password resets. The key defined here should not be shared outside of the configuration file. `SECRET_KEY` can be changed at any time, however be aware that doing so will invalidate all existing sessions.
-
-Please note that this key is **not** used for hashing user passwords or for the encrypted storage of secret data in NetBox.
-
-`SECRET_KEY` should be at least 50 characters in length and contain a random mix of letters, digits, and symbols. The script located at `netbox/generate_secret_key.py` may be used to generate a suitable key.
-
-# Optional Settings
-
----
-
-#### ADMINS
+## ADMINS
 
 NetBox will email details about critical errors to the administrators listed here. This should be a list of (name, email) tuples. For example:
 
@@ -69,15 +13,15 @@ ADMINS = [
 
 ---
 
-#### DEBUG
+## DEBUG
 
 Default: False
 
 This setting enables debugging. This should be done only during development or troubleshooting. Never enable debugging on a production system, as it can expose sensitive data to unauthenticated users. 
 
 ---
 
-#### EMAIL
+## EMAIL
 
 In order to send email, NetBox needs an email server configured. The following items can be defined within the `EMAIL` setting:
 
@@ -90,47 +34,47 @@ In order to send email, NetBox needs an email server configured. The following i
 
 ---
 
-#### LOGIN_REQUIRED
+## LOGIN_REQUIRED
 
 Default: False,
 
 Setting this to True will permit only authenticated users to access any part of NetBox. By default, anonymous users are permitted to access most data in NetBox (excluding secrets) but not make any changes.
 
 ---
 
-#### MAINTENANCE_MODE
+## MAINTENANCE_MODE
 
 Default: False
 
 Setting this to True will display a "maintenance mode" banner at the top of every page.
 
 ---
 
-#### NETBOX_USERNAME
+## NETBOX_USERNAME
 
-#### NETBOX_PASSWORD
+## NETBOX_PASSWORD
 
 If provided, NetBox will use these credentials to authenticate against devices when collecting data.
 
 ---
 
-#### PAGINATE_COUNT
+## PAGINATE_COUNT
 
 Default: 50
 
 Determine how many objects to display per page within each list of objects.
 
 ---
 
-#### TIME_ZONE
+## TIME_ZONE
 
 Default: UTC
 
 The time zone NetBox will use when dealing with dates and times. It is recommended to use UTC time unless you have a specific need to use a local time zone. [List of available time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
 
 ---
 
-#### Date and Time Formatting
+## Date and Time Formatting
 
 You may define custom formatting for date and times. For detailed instructions on writing format strings, please see [the Django documentation](https://docs.djangoproject.com/en/dev/ref/templates/builtins/#date).
 

docs/circuits.md → docs/data-model/circuits.md

@@ -1,9 +1,5 @@
-<h1>Circuits</h1>
-
 The circuits component of NetBox deals with the management of long-haul Internet and private transit links and providers.
 
-[TOC]
-
 # Providers
 
 A provider is any entity which provides some form of connectivity. This obviously includes carriers which offer Internet and private transit service. However, it might also include Internet exchange (IX) points and even organizations with whom you peer directly.

docs/dcim.md → docs/data-model/dcim.md

@@ -1,9 +1,5 @@
-<h1>DCIM</h1>
-
 Data center infrastructure management (DCIM) entails all physical assets: sites, racks, devices, cabling, etc.
 
-[TOC]
-
 # Sites
 
 How you define sites will depend on the nature of your organization, but typically a site will equate a building or campus. For example, a chain of banks might create a site to represent each of its branches, a site for its corporate headquarters, and two additional sites for its presence in two colocation facilities.

docs/extras.md → docs/data-model/extras.md

@@ -1,9 +1,5 @@
-<h1>Extras</h1>
-
 This section entails features of NetBox which are not crucial to its primary functions, but that provide additional value.
 
-[TOC]
-
 # Export Templates
 
 NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Extras > Export Templates under the admin interface.

docs/ipam.md → docs/data-model/ipam.md

@@ -1,9 +1,5 @@
-<h1>IPAM</h1>
-
 IP address management (IPAM) entails the allocation of IP networks, addresses, and related numeric resources.
 
-[TOC]
-
 # VRFs
 
 A VRF object in NetBox represents a virtual routing and forwarding (VRF) domain within a network. Each VRF is essentially a separate routing table: the same IP prefix or address can exist in multiple VRFs. VRFs are commonly used to isolate customers or organizations from one another within a network.

docs/secrets.md → docs/data-model/secrets.md

@@ -1,9 +1,5 @@
-<h1>Secrets</h1>
-
 "Secrets" are small amounts of data that must be kept confidential; for example, passwords and SNMP community strings. NetBox provides encrypted storage of secret data.
 
-[TOC]
-
 # Secrets
 
 A secret represents a single credential or other string which must be stored securely. Each secret is assigned to a device within NetBox. The plaintext value of a secret is encrypted to a ciphertext immediately prior to storage within the database using a 256-bit AES master key. A SHA256 hash of the plaintext is also stored along with each ciphertext to validate the decrypted plaintext.