#2064: documentation EVERYWHERE

CHANGELOG.md

@@ -35,6 +35,7 @@ SessionManager.
 - DNS Services: `DNSClient` and `DNSServer`
 - FTP Services: `FTPClient` and `FTPServer`
 - HTTP Services: `WebBrowser` to simulate a web client and `WebServer`
+- Fixed an issue where the services were still able to run even though the node the service is installed on is turned off
 
 ### Removed
 - Removed legacy simulation modules: `acl`, `common`, `environment`, `links`, `nodes`, `pol`

docs/source/simulation_components/network/base_hardware.rst

@@ -109,6 +109,67 @@ e.g.
     instant_start_node = Node(hostname="client", start_up_duration=0, shut_down_duration=0)
     instant_start_node.power_on() # node will still need to be powered on
 
+.. _Node Start up and Shut down:
+
+---------------------------
+Node Start up and Shut down
+---------------------------
+
+Nodes are powered on and off over multiple timesteps. By default, the node ``start_up_duration`` and ``shut_down_duration`` is 3 timesteps.
+
+Example code where a node is turned on:
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+
+    node = Node(hostname="pc_a")
+
+    assert node.operating_state is NodeOperatingState.OFF # By default, node is instantiated in an OFF state
+
+    node.power_on() # power on the node
+
+    assert node.operating_state is NodeOperatingState.BOOTING # node is booting up
+
+    for i in range(node.start_up_duration + 1):
+        # apply timestep until the node start up duration
+        node.apply_timestep(timestep=i)
+
+    assert node.operating_state is NodeOperatingState.ON # node is in ON state
+
+
+If the node needs to be instantiated in an on state:
+
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+
+    node = Node(hostname="pc_a", operating_state=NodeOperatingState.ON)
+
+    assert node.operating_state is NodeOperatingState.ON  # node is in ON state
+
+Setting ``start_up_duration`` and/or ``shut_down_duration`` to ``0`` will allow for the ``power_on`` and ``power_off`` methods to be completed instantly without applying timesteps:
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+
+    node = Node(hostname="pc_a", start_up_duration=0, shut_down_duration=0)
+
+    assert node.operating_state is NodeOperatingState.OFF  # node is in OFF state
+
+    node.power_on()
+
+    assert node.operating_state is NodeOperatingState.ON  # node is in ON state
+
+    node.power_off()
+
+    assert node.operating_state is NodeOperatingState.OFF  # node is in OFF state
+
 ------------------
 Network Interfaces
 ------------------
@@ -357,7 +418,6 @@ Creating the four nodes results in:
 
     2023-08-08 15:50:08,359 INFO: Connected NIC 84:20:7c:ec:a5:c6/192.168.0.13
 
-
 ---------------
 Create Switches
 ---------------

docs/source/simulation_components/system/data_manipulation_bot.rst

@@ -35,9 +35,12 @@ Example
 .. code-block:: python
 
     client_1 = Computer(
-        hostname="client_1", ip_address="192.168.10.21", subnet_mask="255.255.255.0", default_gateway="192.168.10.1"
+        hostname="client_1",
+        ip_address="192.168.10.21",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.10.1"
+        operating_state=NodeOperatingState.ON # initialise the computer in an ON state
     )
-    client_1.power_on()
     network.connect(endpoint_b=client_1.ethernet_port[1], endpoint_a=switch_2.switch_ports[1])
     client_1.software_manager.install(DataManipulationBot)
     data_manipulation_bot: DataManipulationBot = client_1.software_manager.software["DataManipulationBot"]

docs/source/simulation_components/system/ftp_client_server.rst

@@ -77,6 +77,7 @@ Dependencies
     from primaite.simulator.network.hardware.nodes.server import Server
     from primaite.simulator.system.services.ftp.ftp_server import FTPServer
     from primaite.simulator.system.services.ftp.ftp_client import FTPClient
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
 
 Example peer to peer network
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -85,10 +86,18 @@ Example peer to peer network
 
     net = Network()
 
-    pc1 = Computer(hostname="pc1", ip_address="120.10.10.10", subnet_mask="255.255.255.0")
-    srv = Server(hostname="srv", ip_address="120.10.10.20", subnet_mask="255.255.255.0")
-    pc1.power_on()
-    srv.power_on()
+    pc1 = Computer(
+        hostname="pc1",
+        ip_address="120.10.10.10",
+        subnet_mask="255.255.255.0",
+        operating_state=NodeOperatingState.ON # initialise the computer in an ON state
+    )
+    srv = Server(
+        hostname="srv",
+        ip_address="120.10.10.20",
+        subnet_mask="255.255.255.0",
+        operating_state=NodeOperatingState.ON # initialise the server in an ON state
+    )
     net.connect(pc1.ethernet_port[1], srv.ethernet_port[1])
 
 Install the FTP Server

docs/source/simulation_components/system/software.rst

@@ -6,14 +6,45 @@
 Software
 ========
 
+-------------
+Base Software
+-------------
+
+All software which inherits ``IOSoftware`` installed on a node will not work unless the node has been turned on.
+
+See :ref:`Node Start up and Shut down`
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+    from primaite.simulator.system.services.service import ServiceOperatingState
+    from primaite.simulator.system.services.web_server.web_server import WebServer
+
+    node = Node(hostname="pc_a", start_up_duration=0, shut_down_duration=0)
+
+    node.power_on()
+    assert node.operating_state is NodeOperatingState.ON
+
+    node.software_manager.install(WebServer)
+
+    web_server: WebServer = node.software_manager.software["WebServer"]
+    assert web_server.operating_state is ServiceOperatingState.RUNNING # service is immediately ran after install
+
+    node.power_off()
+    assert node.operating_state is NodeOperatingState.OFF
+    assert web_server.operating_state is ServiceOperatingState.STOPPED # service stops when node is powered off
+
+    node.power_on()
+    assert node.operating_state is NodeOperatingState.ON
+    assert web_server.operating_state is ServiceOperatingState.RUNNING # service turned back on when node is powered on
 
 
-
-Contents
-########
+Services, Processes and Applications:
+#####################################
 
 .. toctree::
-   :maxdepth: 8
+   :maxdepth: 2
 
    database_client_server
    data_manipulation_bot

src/primaite/simulator/network/hardware/base.py

@@ -1187,6 +1187,7 @@ class Node(SimComponent):
             self.start_up_countdown = self.start_up_duration
 
         if self.start_up_duration <= 0:
+            self._start_up_actions()
             self.operating_state = NodeOperatingState.ON
             self.sys_log.info("Turned on")
             for nic in self.nics.values():
@@ -1202,6 +1203,7 @@ class Node(SimComponent):
             self.shut_down_countdown = self.shut_down_duration
 
         if self.shut_down_duration <= 0:
+            self._shut_down_actions()
             self.operating_state = NodeOperatingState.OFF
             self.sys_log.info("Turned off")
 

src/primaite/simulator/system/services/dns/dns_client.py

@@ -1,5 +1,5 @@
 from ipaddress import IPv4Address
-from typing import Dict, Optional, Union
+from typing import Dict, Optional
 
 from primaite import getLogger
 from primaite.simulator.network.protocols.dns import DNSPacket, DNSRequest
@@ -51,7 +51,7 @@ class DNSClient(Service):
         """
         pass
 
-    def add_domain_to_cache(self, domain_name: str, ip_address: IPv4Address) -> Union[bool, None]:
+    def add_domain_to_cache(self, domain_name: str, ip_address: IPv4Address) -> bool:
         """
         Adds a domain name to the DNS Client cache.
 

tests/integration_tests/system/test_application_on_node.py

@@ -108,3 +108,14 @@ def test_server_turns_on_service(populated_node):
 
     assert computer.operating_state is NodeOperatingState.ON
     assert app.operating_state is ApplicationOperatingState.RUNNING
+
+    computer.start_up_duration = 0
+    computer.shut_down_duration = 0
+
+    computer.power_off()
+    assert computer.operating_state is NodeOperatingState.OFF
+    assert app.operating_state is ApplicationOperatingState.CLOSED
+
+    computer.power_on()
+    assert computer.operating_state is NodeOperatingState.ON
+    assert app.operating_state is ApplicationOperatingState.RUNNING

tests/integration_tests/system/test_service_on_node.py

@@ -116,3 +116,14 @@ def test_server_turns_on_service(populated_node):
 
     assert server.operating_state is NodeOperatingState.ON
     assert service.operating_state is ServiceOperatingState.RUNNING
+
+    server.start_up_duration = 0
+    server.shut_down_duration = 0
+
+    server.power_off()
+    assert server.operating_state is NodeOperatingState.OFF
+    assert service.operating_state is ServiceOperatingState.STOPPED
+
+    server.power_on()
+    assert server.operating_state is NodeOperatingState.ON
+    assert service.operating_state is ServiceOperatingState.RUNNING