diff --git a/README.md b/README.md index cbd2b7b..769be47 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Details of the data flow specifications, displaying all the IP addresses, IP ran ### Application -![All the data flows mapped to one application](docs/media/readme-dataflow-details.png) +![All the data flows mapped to one application](docs/media/tuto-application-details.png) The application allows you to group all the related data flows. ### Device tab views diff --git a/docs/data-model.md b/docs/data-model.md index b7c794b..6c13004 100644 --- a/docs/data-model.md +++ b/docs/data-model.md @@ -42,13 +42,6 @@ It was decided not to use the native **Service** object: To ease maintenance, the IP Addresses, IP Ranges and Prefixes are grouped in Object Aliases. These can be seen as reusable groups of addresses that can be a source or a destination to one or several data flows. -## Plugin limitations - -The plugin cannot modify the native NetBox objects and add ForeignKey relations. However, it requires a Many to Many relationship between the Object Aliases (or the source/destination) and different types of objects (IP Address, IP Range and Prefix) and Generic Many to Many relationships are not supported by Django (nor a good idea in general). - -To circumvent this limitation, the plugin makes use of a proxy object, Object Alias Target, that represents one-to-one a NetBox's native IP Address, IP Range or Prefix. These proxy objects are automatically created when needed and destroyed when the linked object is deleted, and the user should not have to worry about them. However, some usecases (like creating object aliases via the API) may need to be aware of them. - - ## Data Model The following sections explain the different objects created by the plugin. @@ -82,19 +75,20 @@ Examples of roles: Data Flows should have a source, a destination, a protocol, source ports and destination ports. Only the protocol is mandatory. +By convention, if the list of source ports or destination ports is empty, this means "Any" port is accepted (for transport protocols with ports). The interface will display `Any`. API and exports will return an empty list. + **Data Flow Groups** form a forest of groups. They can also be assigned to an Application. Data Flow Groups can be enabled and disabled and inherit the status of their parent. Disabled Data Flow Groups disable all the Data Flows contained within. ### Object Alias **Object Aliases** are a group of references to other NetBox objects. Object Aliases are used as sources and destinations of Data Flows and corresponds to the groups or aliases used in firewall configuration. -Internally, Object Aliases contain **Object Alias Targets**, because Django cannot create ManyToMany relationships to generic objects. Object Alias Targets are not exposed in the interface and should be transparent for the user. - -Object Aliases can contain: +Object Aliases can contain any number of: * IP Addresses (`ipam.ipaddress`) * IP Ranges (`ipam.iprange`) * Prefixes (`ipam.prefix`) -If an IP Address is assigned to a device or virtual machine, that device is -also displayed. +There is no defined meaning for an empty object alias, but it can be used when: +* The aliased object is not documented in NetBox (e.g.: third party public IP addresses) +* The alias is "Any" / "Internet" destination diff --git a/docs/media/data-model.png b/docs/media/data-model.png index b871c39..9656ccf 100644 Binary files a/docs/media/data-model.png and b/docs/media/data-model.png differ diff --git a/docs/media/readme-application-dataflows.png b/docs/media/readme-application-dataflows.png deleted file mode 100644 index 28a2b36..0000000 Binary files a/docs/media/readme-application-dataflows.png and /dev/null differ diff --git a/docs/media/readme-dataflow-details.png b/docs/media/readme-dataflow-details.png index eb16e58..d923090 100644 Binary files a/docs/media/readme-dataflow-details.png and b/docs/media/readme-dataflow-details.png differ diff --git a/docs/media/tuto-application-details.png b/docs/media/tuto-application-details.png index 5e799d5..306fd03 100644 Binary files a/docs/media/tuto-application-details.png and b/docs/media/tuto-application-details.png differ diff --git a/docs/media/tuto-application-roles.png b/docs/media/tuto-application-roles.png index 8087bac..037af5a 100644 Binary files a/docs/media/tuto-application-roles.png and b/docs/media/tuto-application-roles.png differ diff --git a/docs/media/tuto-applications.png b/docs/media/tuto-applications.png index 616b8a6..cb1d50e 100644 Binary files a/docs/media/tuto-applications.png and b/docs/media/tuto-applications.png differ diff --git a/docs/media/tuto-dataflow-db-new.png b/docs/media/tuto-dataflow-db-new.png index 730f46a..21744e2 100644 Binary files a/docs/media/tuto-dataflow-db-new.png and b/docs/media/tuto-dataflow-db-new.png differ diff --git a/docs/media/tuto-dataflow-list-all.png b/docs/media/tuto-dataflow-list-all.png index f722292..6b144d6 100644 Binary files a/docs/media/tuto-dataflow-list-all.png and b/docs/media/tuto-dataflow-list-all.png differ diff --git a/docs/media/tuto-dataflow-new.png b/docs/media/tuto-dataflow-new.png index d764596..6e072fd 100644 Binary files a/docs/media/tuto-dataflow-new.png and b/docs/media/tuto-dataflow-new.png differ diff --git a/docs/media/tuto-dataflow-targets.png b/docs/media/tuto-dataflow-targets.png index 7e28390..403986e 100644 Binary files a/docs/media/tuto-dataflow-targets.png and b/docs/media/tuto-dataflow-targets.png differ diff --git a/docs/media/tuto-dataflowgroups.png b/docs/media/tuto-dataflowgroups.png index 8ac1951..6d46fb9 100644 Binary files a/docs/media/tuto-dataflowgroups.png and b/docs/media/tuto-dataflowgroups.png differ diff --git a/docs/media/tuto-device-tab.png b/docs/media/tuto-device-tab.png index 23bc9ad..546e10f 100644 Binary files a/docs/media/tuto-device-tab.png and b/docs/media/tuto-device-tab.png differ diff --git a/docs/media/tuto-dfg-details.png b/docs/media/tuto-dfg-details.png index 48d3e9c..4785fbd 100644 Binary files a/docs/media/tuto-dfg-details.png and b/docs/media/tuto-dfg-details.png differ diff --git a/docs/media/tuto-menu.png b/docs/media/tuto-menu.png index 55bc80e..f239531 100644 Binary files a/docs/media/tuto-menu.png and b/docs/media/tuto-menu.png differ diff --git a/docs/media/tuto-objectalias-addip.png b/docs/media/tuto-objectalias-addip.png deleted file mode 100644 index b136e0d..0000000 Binary files a/docs/media/tuto-objectalias-addip.png and /dev/null differ diff --git a/docs/media/tuto-objectalias-after.png b/docs/media/tuto-objectalias-after.png deleted file mode 100644 index 9c7a83d..0000000 Binary files a/docs/media/tuto-objectalias-after.png and /dev/null differ diff --git a/docs/media/tuto-objectalias-details.png b/docs/media/tuto-objectalias-details.png new file mode 100644 index 0000000..882eae1 Binary files /dev/null and b/docs/media/tuto-objectalias-details.png differ diff --git a/docs/media/tuto-objectalias-list-all.png b/docs/media/tuto-objectalias-list-all.png index e305a2a..dcf8930 100644 Binary files a/docs/media/tuto-objectalias-list-all.png and b/docs/media/tuto-objectalias-list-all.png differ diff --git a/docs/media/tuto-objectalias-list.png b/docs/media/tuto-objectalias-list.png index e11d952..962b7ea 100644 Binary files a/docs/media/tuto-objectalias-list.png and b/docs/media/tuto-objectalias-list.png differ diff --git a/docs/media/tuto-objectalias-new.png b/docs/media/tuto-objectalias-new.png index 8e0cff0..2150ccf 100644 Binary files a/docs/media/tuto-objectalias-new.png and b/docs/media/tuto-objectalias-new.png differ diff --git a/docs/media/tuto-vm-tab.png b/docs/media/tuto-vm-tab.png index fae0bac..1a76a20 100644 Binary files a/docs/media/tuto-vm-tab.png and b/docs/media/tuto-vm-tab.png differ diff --git a/docs/quick-start.md b/docs/quick-start.md index 16c504f..f0fb482 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -28,7 +28,7 @@ First, go the bottom of the NetBox navigation menu to find the Data Flow plugin, ![Menu of the plugin](media/tuto-menu.png) -Think of an **Object Alias** as a reusable group of IP addresses, ranges or prefixes that we can use as source and/or destination in many data flows. The technical reasons for its existence are detailed in the [data model](data-model.md). +Think of an **Object Alias** as a reusable group of IP addresses, ranges or prefixes that we can use as source and/or destination in many data flows. You can have more information in the [data model](data-model.md). Our Object Aliases can contain any number of the following native NetBox objects: @@ -48,19 +48,13 @@ Let's create three Object Aliases: | acme_backend | Backend servers for Acme | | acme_database | Database servers for Acme | -The creation is a two-step process: first, you create the alias, and then you can link aliased objects to it. +When you create or edit an object alias, you can link any IP Address, IP Range or Prefix. Zou can use the filter functions to search which addresses need to be added. -![A newly created alias](media/tuto-objectalias-new.png) +![Creation of a new alias](media/tuto-objectalias-new.png) -Create `acme_frontend` and open it, then click on "+ Add aliased objects" in the top right. There, you can select any IP Address, IP Range or Prefix to add, and you can use the filter functions to search which addresses need to be added. +Once created, your alias will look like that: -In you case, let's add the IP address of our three servers to the alias. - -![Adding three IP addresses in an alias](media/tuto-objectalias-addip.png) - -The objects contained in the alias are listed on its detail page. - -![Detail page of the object alias](media/tuto-objectalias-after.png) +![Detail page of the object alias](media/tuto-objectalias-details.png) Let's repeat the same process for 'acme_backend' and 'acme_database'. @@ -78,14 +72,14 @@ For the plugin, a data flow is a network connection between some sources and som * The sources are zero, one or more object aliases * The destinations are also zero, one or more (potentially different) object aliases * The protocol can be Any/ICMP/TCP/UDP/TCP+UDP/SCTP -* There can be a list of source and destination ports +* There can be a list of source and destination ports (by default, any port) * The data flow can be marked as enabled or disabled. > [!NOTE] > The data flow can have an optional application and data flow group, which are explained later in the tutorial. > [!TIP] -> By convention, if zero object aliases are specified as source (or as destination), this is interpreted (and displayed) as "Any". +> By convention, if zero object aliases are specified as source (or as destination), this is interpreted (and displayed) as "Any". Similarly, if no source or destination ports are defined, this is interpreted as "Any". > [!TIP] > You can change the list of available protocols in the configuration. Check [the Protocol Choices section](installation-configuration.md#protocol-choices) in the configuration documenation for details. @@ -215,7 +209,7 @@ Let's create the remaining data flows. > Because we have disabled the group "Acme Inc. external access", the data flow it contains is marked as *Disabled (Inherited)*. > The data flow "Internal access to Acme backend API" also appears *Disabled*: its groups are all enabled, but the data flow was disabled directy. -The "Targets" tab in the data flow's detailed view can be used to resolve the object aliases and display the list of all IP address, ranges and prefixes in this data flow. The list displays when possible some context, e.g.: the device to which the IP is assigned or the VLAN a prefix is part of. +The "Targets" tab in the data flow's detailed view can be used to resolve the object aliases and display the list of all IP address, ranges and prefixes in this data flow. ![Targets tab of a data flow showing all its components](media/tuto-dataflow-targets.png)