diff --git a/docs/features/vpn-tunnels.md b/docs/features/vpn-tunnels.md new file mode 100644 index 000000000..a89265ec2 --- /dev/null +++ b/docs/features/vpn-tunnels.md @@ -0,0 +1,49 @@ +# Tunnels + +NetBox can model private tunnels formed among virtual termination points across your network. Typical tunnel implementations include GRE, IP-in-IP, or IPSec. A tunnel may be terminated to two or more device or virtual machine interfaces. + +```mermaid +flowchart TD + Termination1[TunnelTermination] + Termination2[TunnelTermination] + Interface1[Interface] + Interface2[Interface] + Tunnel --> Termination1 & Termination2 + Termination1 --> Interface1 + Termination2 --> Interface2 + Interface1 --> Device + Interface2 --> VirtualMachine + +click Tunnel "../../models/vpn/tunnel/" +click TunnelTermination1 "../../models/vpn/tunneltermination/" +click TunnelTermination2 "../../models/vpn/tunneltermination/" +``` + +# IPSec & IKE + +NetBox includes robust support for modeling IPSec & IKE policies. These are used to define encryption and authentication parameters for IPSec tunnels. + +```mermaid +flowchart TD + subgraph IKEProposals[Proposals] + IKEProposal1[IKEProposal] + IKEProposal2[IKEProposal] + end + subgraph IPSecProposals[Proposals] + IPSecProposal1[IPSecProposal] + IPSecProposal2[IPSecProposal] + end + IKEProposals --> IKEPolicy + IPSecProposals --> IPSecPolicy + IKEPolicy & IPSecPolicy--> IPSecProfile + IPSecProfile --> Tunnel + +click IKEProposal1 "../../models/vpn/ikeproposal/" +click IKEProposal2 "../../models/vpn/ikeproposal/" +click IKEPolicy "../../models/vpn/ikepolicy/" +click IPSecProposal1 "../../models/vpn/ipsecproposal/" +click IPSecProposal2 "../../models/vpn/ipsecproposal/" +click IPSecPolicy "../../models/vpn/ipsecpolicy/" +click IPSecProfile "../../models/vpn/ipsecprofile/" +click Tunnel "../../models/vpn/tunnel/" +``` diff --git a/docs/models/vpn/ikepolicy.md b/docs/models/vpn/ikepolicy.md new file mode 100644 index 000000000..7b739072b --- /dev/null +++ b/docs/models/vpn/ikepolicy.md @@ -0,0 +1,25 @@ +# IKE Policies + +An [Internet Key Exhcnage (IKE)](https://en.wikipedia.org/wiki/Internet_Key_Exchange) policy defines an IKE version, mode, and set of [proposals](./ikeproposal.md) to be used in IKE negotiation. These policies are referenced by [IPSec profiles](./ipsecprofile.md). + +## Fields + +### Name + +The unique user-assigned name for the policy. + +### Version + +The IKE version employed (v1 or v2). + +### Mode + +The IKE mode employed (main or aggressive). + +### Proposals + +One or more [IKE proposals](./ikeproposal.md) supported for use by this policy. + +### Pre-shared Key + +A pre-shared secret key associated with this policy (optional). diff --git a/docs/models/vpn/ikeproposal.md b/docs/models/vpn/ikeproposal.md new file mode 100644 index 000000000..dd8d75330 --- /dev/null +++ b/docs/models/vpn/ikeproposal.md @@ -0,0 +1,39 @@ +# IKE Proposals + +An [Internet Key Exhcnage (IKE)](https://en.wikipedia.org/wiki/Internet_Key_Exchange) proposal defines a set of parameters used to establish a secure bidirectional connection across an untrusted medium, such as the Internet. IKE proposals defined in NetBox can be referenced by [IKE policies](./ikepolicy.md), which are in turn employed by [IPSec profiles](./ipsecprofile.md). + +!!! note + Some platforms refer to IKE proposals as [ISAKMP](https://en.wikipedia.org/wiki/Internet_Security_Association_and_Key_Management_Protocol), which is a framework for authentication and key exchange which employs IKE. + +## Fields + +### Name + +The unique user-assigned name for the proposal. + +### Authentication Method + +The strategy employed for authenticating the IKE peer. Available options are listed below. + +| Name | +|----------------| +| Pre-shared key | +| Certificate | +| RSA signature | +| DSA signature | + +### Encryption Algorithm + +The protocol employed for data encryption. Options include DES, 3DES, and various flavors of AES. + +### Authentication Algorithm + +The mechanism employed to ensure data integrity. Options include MD5 and SHA HMAC implementations. + +### Group + +The [Diffie-Hellman group](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) supported by the proposal. Group IDs are [managed by IANA](https://www.iana.org/assignments/ikev2-parameters/ikev2-parameters.xhtml#ikev2-parameters-8). + +### SA Lifetime + +The maximum lifetime for the IKE security association (SA), in seconds. diff --git a/docs/models/vpn/ipsecpolicy.md b/docs/models/vpn/ipsecpolicy.md new file mode 100644 index 000000000..3283d3b23 --- /dev/null +++ b/docs/models/vpn/ipsecpolicy.md @@ -0,0 +1,17 @@ +# IPSec Policy + +An [IPSec](https://en.wikipedia.org/wiki/IPsec) policy defines a set of [proposals](./ikeproposal.md) to be used in the formation of IPSec tunnels. A perfect forward secrecy (PFS) group may optionally also be defined. These policies are referenced by [IPSec profiles](./ipsecprofile.md). + +## Fields + +### Name + +The unique user-assigned name for the policy. + +### Proposals + +One or more [IPSec proposals](./ipsecproposal.md) supported for use by this policy. + +### PFS Group + +The [perfect forward secrecy (PFS)](https://en.wikipedia.org/wiki/Forward_secrecy) group supported by this policy (optional). diff --git a/docs/models/vpn/ipsecprofile.md b/docs/models/vpn/ipsecprofile.md new file mode 100644 index 000000000..1ad1ce7d5 --- /dev/null +++ b/docs/models/vpn/ipsecprofile.md @@ -0,0 +1,21 @@ +# IPSec Profile + +An [IPSec](https://en.wikipedia.org/wiki/IPsec) profile defines an [IKE policy](./ikepolicy.md), [IPSec policy](./ipsecpolicy.md), and IPSec mode used for establishing an IPSec tunnel. + +## Fields + +### Name + +The unique user-assigned name for the profile. + +### Mode + +The IPSec mode employed by the profile: Encapsulating Security Payload (ESP) or Authentication Header (AH). + +### IKE Policy + +The [IKE policy](./ikepolicy.md) associated with the profile. + +### IPSec Policy + +The [IPSec policy](./ipsecpolicy.md) associated with the profile. diff --git a/docs/models/vpn/ipsecproposal.md b/docs/models/vpn/ipsecproposal.md new file mode 100644 index 000000000..d061b1535 --- /dev/null +++ b/docs/models/vpn/ipsecproposal.md @@ -0,0 +1,25 @@ +# IPSec Proposal + +An [IPSec](https://en.wikipedia.org/wiki/IPsec) proposal defines a set of parameters used in negotiating security associations for IPSec tunnels. IPSec proposals defined in NetBox can be referenced by [IPSec policies](./ipsecpolicy.md), which are in turn employed by [IPSec profiles](./ipsecprofile.md). + +## Fields + +### Name + +The unique user-assigned name for the proposal. + +### Encryption Algorithm + +The protocol employed for data encryption. Options include DES, 3DES, and various flavors of AES. + +### Authentication Algorithm + +The mechanism employed to ensure data integrity. Options include MD5 and SHA HMAC implementations. + +### SA Lifetime (Seconds) + +The maximum amount of time for which the security association (SA) may be active, in seconds. + +### SA Lifetime (Data) + +The maximum amount of data which can be transferred within the security association (SA) before it must be rebuilt, in kilobytes. diff --git a/docs/models/vpn/tunnel.md b/docs/models/vpn/tunnel.md new file mode 100644 index 000000000..ebe004da1 --- /dev/null +++ b/docs/models/vpn/tunnel.md @@ -0,0 +1,36 @@ +# Tunnels + +A tunnel represents a private virtual connection established among two or more endpoints across a shared infrastructure by employing protocol encapsulation. Common encapsulation techniques include [Generic Routing Encapsulation (GRE)](https://en.wikipedia.org/wiki/Generic_Routing_Encapsulation), [IP-in-IP](https://en.wikipedia.org/wiki/IP_in_IP), and [IPSec](https://en.wikipedia.org/wiki/IPsec). NetBox supports modeling both peer-to-peer and hub-and-spoke tunnel topologies. + +Device and virtual machine interfaces are associated to tunnels by creating [tunnel terminations](./tunneltermination.md). + +## Fields + +### Name + +A unique name assigned to the tunnel for identification. + +### Status + +The operational status of the tunnel. By default, the following statuses are available: + +| Name | +|----------------| +| Planned | +| Active | +| Disabled | + +!!! tip "Custom tunnel statuses" + Additional tunnel statuses may be defined by setting `Tunnel.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter. + +### Encapsulation + +The encapsulation protocol or technique employed to effect the tunnel. NetBox supports GRE, IP-in-IP, and IPSec encapsulations. + +### Tunnel ID + +An optional numeric identifier for the tunnel. + +### IPSec Profile + +For IPSec tunnels, this is the [IPSec Profile](./ipsecprofile.md) employed to negotiate security associations. diff --git a/docs/models/vpn/tunneltermination.md b/docs/models/vpn/tunneltermination.md new file mode 100644 index 000000000..8bcfd11c4 --- /dev/null +++ b/docs/models/vpn/tunneltermination.md @@ -0,0 +1,30 @@ +# Tunnel Terminations + +A tunnel termination connects a device or virtual machine interface to a [tunnel](./tunnel.md). The tunnel must be created before any terminations may be added. + +## Fields + +### Tunnel + +The [tunnel](./tunnel.md) to which this termination is made. + +### Role + +The functional role of the attached interface. The following options are available: + +| Name | Description | +|-------|--------------------------------------------------| +| Peer | An endpoint in a point-to-point or mesh topology | +| Hub | A central point in a hub-and-spoke topology | +| Spoke | An edge point in a hub-and-spoke topology | + +!!! note + Multiple hub terminations may be attached to a tunnel. + +### Interface + +The device or virtual machine interface terminated to the tunnel. + +### Outside IP + +The public or underlay IP address with which this termination is associated. This is the IP to which peers will route tunneled traffic. diff --git a/mkdocs.yml b/mkdocs.yml index 3e61f922a..f927bf386 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -74,6 +74,7 @@ nav: - Circuits: 'features/circuits.md' - Wireless: 'features/wireless.md' - Virtualization: 'features/virtualization.md' + - VPN Tunnels: 'features/vpn-tunnels.md' - Tenancy: 'features/tenancy.md' - Contacts: 'features/contacts.md' - Search: 'features/search.md' @@ -252,6 +253,14 @@ nav: - ClusterType: 'models/virtualization/clustertype.md' - VMInterface: 'models/virtualization/vminterface.md' - VirtualMachine: 'models/virtualization/virtualmachine.md' + - VPN: + - IKEPolicy: 'models/vpn/ikepolicy.md' + - IKEProposal: 'models/vpn/ikeproposal.md' + - IPSecPolicy: 'models/vpn/ipsecpolicy.md' + - IPSecProfile: 'models/vpn/ipsecprofile.md' + - IPSecProposal: 'models/vpn/ipsecproposal.md' + - Tunnel: 'models/vpn/tunnel.md' + - TunnelTermination: 'models/vpn/tunneltermination.md' - Wireless: - WirelessLAN: 'models/wireless/wirelesslan.md' - WirelessLANGroup: 'models/wireless/wirelesslangroup.md'