Update documentation

Alef-Burzmali · Nov 2, 2024 · f4d12e8 · f4d12e8
1 parent 9b0c6d7
commit f4d12e8
Show file tree

Hide file tree

Showing 24 changed files with 15 additions and 27 deletions.
diff --git 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
@@ -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
diff --git a/docs/media/readme-application-dataflows.png b/docs/media/readme-application-dataflows.png
diff --git a/docs/media/readme-dataflow-details.png b/docs/media/readme-dataflow-details.png
diff --git a/docs/media/tuto-application-details.png b/docs/media/tuto-application-details.png
diff --git a/docs/media/tuto-application-roles.png b/docs/media/tuto-application-roles.png
diff --git a/docs/media/tuto-applications.png b/docs/media/tuto-applications.png
diff --git a/docs/media/tuto-dataflow-db-new.png b/docs/media/tuto-dataflow-db-new.png
diff --git a/docs/media/tuto-dataflow-list-all.png b/docs/media/tuto-dataflow-list-all.png
diff --git a/docs/media/tuto-dataflow-new.png b/docs/media/tuto-dataflow-new.png
diff --git a/docs/media/tuto-dataflow-targets.png b/docs/media/tuto-dataflow-targets.png
diff --git a/docs/media/tuto-dataflowgroups.png b/docs/media/tuto-dataflowgroups.png
diff --git a/docs/media/tuto-device-tab.png b/docs/media/tuto-device-tab.png
diff --git a/docs/media/tuto-dfg-details.png b/docs/media/tuto-dfg-details.png
diff --git a/docs/media/tuto-menu.png b/docs/media/tuto-menu.png
diff --git a/docs/media/tuto-objectalias-addip.png b/docs/media/tuto-objectalias-addip.png
diff --git a/docs/media/tuto-objectalias-after.png b/docs/media/tuto-objectalias-after.png
diff --git a/docs/media/tuto-objectalias-details.png b/docs/media/tuto-objectalias-details.png
diff --git a/docs/media/tuto-objectalias-list-all.png b/docs/media/tuto-objectalias-list-all.png
diff --git a/docs/media/tuto-objectalias-list.png b/docs/media/tuto-objectalias-list.png
diff --git a/docs/media/tuto-objectalias-new.png b/docs/media/tuto-objectalias-new.png
diff --git a/docs/media/tuto-vm-tab.png b/docs/media/tuto-vm-tab.png
diff --git 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)