#2257: massive docs addition for config file
This commit is contained in:
Czar Echavez
@@ -0,0 +1,41 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
``ip_address``
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
The IP address of the |NODE| in the network.
|
||||
|
||||
``subnet_mask``
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Optional. Default value is ``255.255.255.0``.
|
||||
|
||||
The subnet mask for the |NODE| to use.
|
||||
|
||||
``default_gateway``
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The IP address that the |NODE| will use as the default gateway. Typically, this is the IP address of the closest router that the |NODE| is connected to.
|
||||
|
||||
``dns_server``
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Optional. Default value is ``None``
|
||||
|
||||
The IP address of the node which holds an instance of the DNS server. Some applications may use a domain name e.g. the WebBrowser (TODO: WebBrowser page)
|
||||
|
||||
``applications``
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
A list of applications which are not considered system software that need to be installed on the |NODE|.
|
||||
|
||||
See :ref:`Applications <applications_config>`
|
||||
|
||||
``services``
|
||||
^^^^^^^^^^^^
|
||||
|
||||
A list of services which are not considered system software that need to be installed on the |NODE|.
|
||||
|
||||
See :ref:`Services <services_config>`
|
||||
@@ -0,0 +1,49 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
``routes``
|
||||
----------
|
||||
|
||||
A list of routes which tells the |NODE| where to forward the packet to depending on the target IP address.
|
||||
|
||||
e.g.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: node
|
||||
...
|
||||
routes:
|
||||
- address: 192.168.0.10
|
||||
subnet_mask: 255.255.255.0
|
||||
next_hop_ip_address: 192.168.1.1
|
||||
metric: 0
|
||||
|
||||
``address``
|
||||
"""""""""""
|
||||
|
||||
The target IP address for the route. If the packet destination IP address matches this, the router will route the packet according to the ``next_hop_ip_address``.
|
||||
|
||||
This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
|
||||
|
||||
``subnet_mask``
|
||||
"""""""""""""""
|
||||
|
||||
Optional. Default value is ``255.255.255.0``.
|
||||
|
||||
The subnet mask setting for the route.
|
||||
|
||||
``next_hop_ip_address``
|
||||
"""""""""""""""""""""""
|
||||
|
||||
The IP address of the next hop IP address that the packet will follow if the address matches the packet's destination IP address.
|
||||
|
||||
This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
|
||||
|
||||
``metric``
|
||||
""""""""""
|
||||
|
||||
Optional. Default value is ``0``. This value accepts floats.
|
||||
|
||||
The cost or distance of a route. The higher the value, the more cost or distance is attributed to the route.
|
||||
@@ -0,0 +1,13 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
``ref``
|
||||
-------
|
||||
|
||||
Human readable name used as reference for the |NODE|. Not used in code.
|
||||
|
||||
``hostname``
|
||||
------------
|
||||
|
||||
The hostname of the |NODE|. This will be used to reference the |NODE|.
|
||||
@@ -0,0 +1,18 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
``type``
|
||||
--------
|
||||
|
||||
The type of node to add.
|
||||
|
||||
Available options are:
|
||||
|
||||
- ``computer``
|
||||
- ``firewall``
|
||||
- ``router``
|
||||
- ``server``
|
||||
- ``switch``
|
||||
|
||||
To create a |NODE|, type must be |NODE_TYPE|.
|
||||
39
docs/source/configuration/simulation/nodes/computer.rst
Normal file
39
docs/source/configuration/simulation/nodes/computer.rst
Normal file
@@ -0,0 +1,39 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
.. _computer_configuration:
|
||||
|
||||
``computer``
|
||||
============
|
||||
|
||||
A basic representation of a computer within the simulation.
|
||||
|
||||
See :py:mod:`primaite.simulator.network.hardware.nodes.host.computer.Computer`
|
||||
|
||||
example computer
|
||||
----------------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: client_1
|
||||
hostname: client_1
|
||||
type: computer
|
||||
ip_address: 192.168.0.10
|
||||
subnet_mask: 255.255.255.0
|
||||
default_gateway: 192.168.0.1
|
||||
dns_server: 192.168.1.10
|
||||
applications:
|
||||
...
|
||||
services:
|
||||
...
|
||||
|
||||
.. include:: common/common_node_attributes.rst
|
||||
|
||||
.. include:: common/node_type_list.rst
|
||||
|
||||
.. include:: common/common_host_node_attributes.rst
|
||||
|
||||
.. |NODE| replace:: computer
|
||||
.. |NODE_TYPE| replace:: ``computer``
|
||||
258
docs/source/configuration/simulation/nodes/firewall.rst
Normal file
258
docs/source/configuration/simulation/nodes/firewall.rst
Normal file
@@ -0,0 +1,258 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
.. _firewall_configuration:
|
||||
|
||||
``firewall``
|
||||
============
|
||||
|
||||
A basic representation of a network router within the simulation.
|
||||
|
||||
The firewall is similar to how :ref:`Router <router_configuration>` works, with the difference being how firewall has specific ACL rules for inbound and outbound traffic as well as firewall being limited to 3 ports.
|
||||
|
||||
See :py:mod:`primaite.simulator.network.hardware.nodes.network.firewall.Firewall`
|
||||
|
||||
example firewall
|
||||
----------------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: firewall
|
||||
hostname: firewall
|
||||
type: firewall
|
||||
start_up_duration: 0
|
||||
shut_down_duration: 0
|
||||
ports:
|
||||
external_port: # port 1
|
||||
ip_address: 192.168.20.1
|
||||
subnet_mask: 255.255.255.0
|
||||
internal_port: # port 2
|
||||
ip_address: 192.168.1.2
|
||||
subnet_mask: 255.255.255.0
|
||||
dmz_port: # port 3
|
||||
ip_address: 192.168.10.1
|
||||
subnet_mask: 255.255.255.0
|
||||
acl:
|
||||
internal_inbound_acl:
|
||||
...
|
||||
internal_outbound_acl:
|
||||
...
|
||||
dmz_inbound_acl:
|
||||
...
|
||||
dmz_outbound_acl:
|
||||
...
|
||||
external_inbound_acl:
|
||||
...
|
||||
external_outbound_acl:
|
||||
...
|
||||
routes:
|
||||
...
|
||||
|
||||
.. include:: common/common_node_attributes.rst
|
||||
|
||||
.. include:: common/node_type_list.rst
|
||||
|
||||
``ports``
|
||||
---------
|
||||
|
||||
The firewall node only has 3 ports. These specifically are:
|
||||
|
||||
- ``external_port`` (port 1)
|
||||
- ``internal_port`` (port 2)
|
||||
- ``dmz_port`` (port 3) (can be optional)
|
||||
|
||||
The ports should be defined with an ip address and subnet mask e.g.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: firewall
|
||||
...
|
||||
ports:
|
||||
external_port: # port 1
|
||||
ip_address: 192.168.20.1
|
||||
subnet_mask: 255.255.255.0
|
||||
internal_port: # port 2
|
||||
ip_address: 192.168.1.2
|
||||
subnet_mask: 255.255.255.0
|
||||
dmz_port: # port 3
|
||||
ip_address: 192.168.10.1
|
||||
subnet_mask: 255.255.255.0
|
||||
|
||||
``ip_address``
|
||||
""""""""""""""
|
||||
|
||||
The IP address for the given port. This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
|
||||
|
||||
``subnet_mask``
|
||||
"""""""""""""""
|
||||
|
||||
Optional. Default value is ``255.255.255.0``.
|
||||
|
||||
The subnet mask setting for the port.
|
||||
|
||||
``acl``
|
||||
-------
|
||||
|
||||
There are 6 ACLs that can be defined for a firewall
|
||||
|
||||
- ``internal_inbound_acl`` for traffic going towards the internal network
|
||||
- ``internal_outbound_acl`` for traffic coming from the internal network
|
||||
- ``dmz_inbound_acl`` for traffic going towards the dmz network
|
||||
- ``dmz_outbound_acl`` for traffic coming from the dmz network
|
||||
- ``external_inbound_acl`` for traffic coming from the external network
|
||||
- ``external_outbound_acl`` for traffic going towards the external network
|
||||
|
||||
.. image:: ../../../../_static/firewall_acl.png
|
||||
|
||||
By default, ``external_inbound_acl`` and ``external_outbound_acl`` will permit any traffic through.
|
||||
|
||||
See :py:mod:`primaite.simulator.network.hardware.nodes.network.router.AccessControlList`
|
||||
|
||||
See :ref:`List of Ports <List of Ports>` for a list of ports.
|
||||
|
||||
``internal_inbound_acl``
|
||||
""""""""""""""""""""""""
|
||||
|
||||
ACL rules for packets that have a destination IP address in what is considered the internal network.
|
||||
|
||||
example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: firewall
|
||||
...
|
||||
acl:
|
||||
internal_inbound_acl:
|
||||
22: # position 22 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
src_port: ARP # are emitted from the ARP port
|
||||
dst_port: ARP # are going towards an ARP port
|
||||
23: # position 23 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
protocol: ICMP # are ICMP
|
||||
|
||||
``internal_outbound_acl``
|
||||
"""""""""""""""""""""""""
|
||||
|
||||
ACL rules for packets that have a source IP address in what is considered the internal network and is going towards the DMZ network or the external network.
|
||||
|
||||
example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: firewall
|
||||
...
|
||||
acl:
|
||||
internal_outbound_acl:
|
||||
22: # position 22 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
src_port: ARP # are emitted from the ARP port
|
||||
dst_port: ARP # are going towards an ARP port
|
||||
23: # position 23 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
protocol: ICMP # are ICMP
|
||||
|
||||
|
||||
``dmz_inbound_acl``
|
||||
"""""""""""""""""""
|
||||
|
||||
ACL rules for packets that have a destination IP address in what is considered the DMZ network.
|
||||
|
||||
example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: firewall
|
||||
...
|
||||
acl:
|
||||
dmz_inbound_acl:
|
||||
22: # position 22 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
src_port: ARP # are emitted from the ARP port
|
||||
dst_port: ARP # are going towards an ARP port
|
||||
23: # position 23 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
protocol: ICMP # are ICMP
|
||||
|
||||
``dmz_outbound_acl``
|
||||
""""""""""""""""""""
|
||||
|
||||
ACL rules for packets that have a source IP address in what is considered the DMZ network and is going towards the internal network or the external network.
|
||||
|
||||
example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: firewall
|
||||
...
|
||||
acl:
|
||||
dmz_outbound_acl:
|
||||
22: # position 22 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
src_port: ARP # are emitted from the ARP port
|
||||
dst_port: ARP # are going towards an ARP port
|
||||
23: # position 23 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
protocol: ICMP # are ICMP
|
||||
|
||||
|
||||
|
||||
``external_inbound_acl``
|
||||
""""""""""""""""""""""""
|
||||
|
||||
Optional. By default, this will allow any traffic through.
|
||||
|
||||
ACL rules for packets that have a destination IP address in what is considered the external network.
|
||||
|
||||
example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: firewall
|
||||
...
|
||||
acl:
|
||||
external_inbound_acl:
|
||||
22: # position 22 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
src_port: ARP # are emitted from the ARP port
|
||||
dst_port: ARP # are going towards an ARP port
|
||||
23: # position 23 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
protocol: ICMP # are ICMP
|
||||
|
||||
``external_outbound_acl``
|
||||
"""""""""""""""""""""""""
|
||||
|
||||
Optional. By default, this will allow any traffic through.
|
||||
|
||||
ACL rules for packets that have a source IP address in what is considered the external network and is going towards the DMZ network or the internal network.
|
||||
|
||||
example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: firewall
|
||||
...
|
||||
acl:
|
||||
external_outbound_acl:
|
||||
22: # position 22 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
src_port: ARP # are emitted from the ARP port
|
||||
dst_port: ARP # are going towards an ARP port
|
||||
23: # position 23 on ACL list
|
||||
action: PERMIT # allow packets that
|
||||
protocol: ICMP # are ICMP
|
||||
|
||||
.. include:: common/common_network_node_attributes.rst
|
||||
|
||||
.. |NODE| replace:: firewall
|
||||
.. |NODE_TYPE| replace:: ``firewall``
|
||||
125
docs/source/configuration/simulation/nodes/router.rst
Normal file
125
docs/source/configuration/simulation/nodes/router.rst
Normal file
@@ -0,0 +1,125 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
.. _router_configuration:
|
||||
|
||||
``router``
|
||||
==========
|
||||
|
||||
A basic representation of a network router within the simulation.
|
||||
|
||||
See :py:mod:`primaite.simulator.network.hardware.nodes.network.router.Router`
|
||||
|
||||
example router
|
||||
--------------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: router_1
|
||||
hostname: router_1
|
||||
type: router
|
||||
num_ports: 5
|
||||
ports:
|
||||
...
|
||||
acl:
|
||||
...
|
||||
|
||||
.. include:: common/common_node_attributes.rst
|
||||
|
||||
.. include:: common/node_type_list.rst
|
||||
|
||||
``num_ports``
|
||||
-------------
|
||||
|
||||
Optional. Default value is ``5``.
|
||||
|
||||
The number of ports the router will have.
|
||||
|
||||
``ports``
|
||||
---------
|
||||
|
||||
Sets up the router's ports with an IP address and a subnet mask.
|
||||
|
||||
Example of setting ports for a router with 2 ports:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: router_1
|
||||
...
|
||||
ports:
|
||||
1:
|
||||
ip_address: 192.168.1.1
|
||||
subnet_mask: 255.255.255.0
|
||||
2:
|
||||
ip_address: 192.168.10.1
|
||||
subnet_mask: 255.255.255.0
|
||||
|
||||
``ip_address``
|
||||
""""""""""""""
|
||||
|
||||
The IP address for the given port. This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
|
||||
|
||||
``subnet_mask``
|
||||
"""""""""""""""
|
||||
|
||||
Optional. Default value is ``255.255.255.0``.
|
||||
|
||||
The subnet mask setting for the port.
|
||||
|
||||
``acl``
|
||||
-------
|
||||
|
||||
Sets up the ACL rules for the router.
|
||||
|
||||
e.g.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: router_1
|
||||
...
|
||||
acl:
|
||||
1:
|
||||
action: PERMIT
|
||||
src_port: ARP
|
||||
dst_port: ARP
|
||||
2:
|
||||
action: PERMIT
|
||||
protocol: ICMP
|
||||
|
||||
See :py:mod:`primaite.simulator.network.hardware.nodes.network.router.AccessControlList`
|
||||
|
||||
See :ref:`List of Ports <List of Ports>` for a list of ports.
|
||||
|
||||
``action``
|
||||
""""""""""
|
||||
|
||||
Available options are
|
||||
|
||||
- ``PERMIT`` : Allows the specified ``protocol`` or ``src_port`` and ``dst_port`` pairs
|
||||
- ``DENY`` : Blocks the specified ``protocol`` or ``src_port`` and ``dst_port`` pairs
|
||||
|
||||
``src_port``
|
||||
""""""""""""
|
||||
|
||||
Is used alongside ``dst_port``. Specifies the port where a packet originates. Used by the ACL Rule to determine if a packet with a specific source port is allowed to pass through the network node.
|
||||
|
||||
``dst_port``
|
||||
""""""""""""
|
||||
|
||||
Is used alongside ``src_port``. Specifies the port where a packet is destined to arrive. Used by the ACL Rule to determine if a packet with a specific destination port is allowed to pass through the network node.
|
||||
|
||||
``protocol``
|
||||
""""""""""""
|
||||
|
||||
Specifies which protocols are allowed by the ACL Rule to pass through the network node.
|
||||
|
||||
See :ref:`List of IPProtocols <List of IPProtocols>` for a list of protocols.
|
||||
|
||||
.. include:: common/common_network_node_attributes.rst
|
||||
|
||||
.. |NODE| replace:: router
|
||||
.. |NODE_TYPE| replace:: ``router``
|
||||
39
docs/source/configuration/simulation/nodes/server.rst
Normal file
39
docs/source/configuration/simulation/nodes/server.rst
Normal file
@@ -0,0 +1,39 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
.. _server_configuration:
|
||||
|
||||
``server``
|
||||
==========
|
||||
|
||||
A basic representation of a server within the simulation.
|
||||
|
||||
See :py:mod:`primaite.simulator.network.hardware.nodes.host.server.Server`
|
||||
|
||||
example server
|
||||
--------------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: server_1
|
||||
hostname: server_1
|
||||
type: server
|
||||
ip_address: 192.168.10.10
|
||||
subnet_mask: 255.255.255.0
|
||||
default_gateway: 192.168.10.1
|
||||
dns_server: 192.168.1.10
|
||||
applications:
|
||||
...
|
||||
services:
|
||||
...
|
||||
|
||||
.. include:: common/common_node_attributes.rst
|
||||
|
||||
.. include:: common/node_type_list.rst
|
||||
|
||||
.. include:: common/common_host_node_attributes.rst
|
||||
|
||||
.. |NODE| replace:: server
|
||||
.. |NODE_TYPE| replace:: ``server``
|
||||
37
docs/source/configuration/simulation/nodes/switch.rst
Normal file
37
docs/source/configuration/simulation/nodes/switch.rst
Normal file
@@ -0,0 +1,37 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
.. _switch_configuration:
|
||||
|
||||
``switch``
|
||||
==========
|
||||
|
||||
A basic representation of a network switch within the simulation.
|
||||
|
||||
See :py:mod:`primaite.simulator.network.hardware.nodes.network.switch.Switch`
|
||||
|
||||
example switch
|
||||
--------------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodes:
|
||||
- ref: switch_1
|
||||
hostname: switch_1
|
||||
type: switch
|
||||
num_ports: 8
|
||||
|
||||
.. include:: common/common_node_attributes.rst
|
||||
|
||||
.. include:: common/node_type_list.rst
|
||||
|
||||
``num_ports``
|
||||
-------------
|
||||
|
||||
Optional. Default value is ``8``.
|
||||
|
||||
The number of ports the switch will have.
|
||||
|
||||
.. |NODE| replace:: switch
|
||||
.. |NODE_TYPE| replace:: ``switch``
|
||||
@@ -0,0 +1,10 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
.. _applications_config:
|
||||
|
||||
``applications``
|
||||
================
|
||||
|
||||
apps
|
||||
10
docs/source/configuration/simulation/software/services.rst
Normal file
10
docs/source/configuration/simulation/software/services.rst
Normal file
@@ -0,0 +1,10 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
.. _services_config:
|
||||
|
||||
``services``
|
||||
============
|
||||
|
||||
services
|
||||
Reference in New Issue
Block a user