Merge branch '294-add-excluded' into develop

Author: tcaiazzi

docs/kathara-lclean.1.ronn

@@ -4,7 +4,7 @@ kathara-lclean(1) -- Stop a Kathara network scenario
 
 ## SYNOPSIS
 
-`kathara lclean` [`-h`] [`-d` <DIRECTORY>] [<DEVICE_NAME> [<DEVICE_NAME> ...]]  
+`kathara lclean` [`-h`] [`-d` <DIRECTORY>] [`--exclude` <DEVICE_NAME> [<DEVICE_NAME> ...]] [<DEVICE_NAME> [<DEVICE_NAME> ...]]  
 
 ## DESCRIPTION
 
@@ -22,6 +22,9 @@ By default, stops all the devices of the network scenario. If a list of <DEVICE_
 	Cleans the Kathara network scenario that is located inside <DIRECTORY>.  
 	If no `-d` option is provided, assume the network scenario is located in the current directory.
 
+* `--exclude` [<DEVICE_NAME> [<DEVICE_NAME> ...]]
+    A list of device names. You can exclude certain devices of the network scenario from being shut down.
+
 * `DEVICE_NAME`:
     A list of device names. Instead of shutting down the whole network scenario, only specified devices are stopped.
 

docs/kathara-lrestart.1.ronn

@@ -7,7 +7,8 @@ kathara-lrestart(1) -- Restart a Kathara network scenario
 `kathara lrestart` [`-h`] [`-F`] [`-l`]  
 [`--noterminals` | `--terminals` | `--privileged`] [`-d` <DIRECTORY>]  
 [`-o` [<OPTION> [<OPTION> ...]]] [`--xterm` <XTERM>]  
-[`--no-hosthome` \| `--hosthome`] [`--no-shared` \| `--shared`] [<DEVICE_NAME> [<DEVICE_NAME> ...]]
+[`--no-hosthome` \| `--hosthome`] [`--no-shared` \| `--shared`] [`--exclude` <DEVICE_NAME> [<DEVICE_NAME> ...]]  
+[<DEVICE_NAME> [<DEVICE_NAME> ...]]
 
 
 ## DESCRIPTION
@@ -75,6 +76,9 @@ Mainly it has the same options of `lstart` with the lack of some options (e.g. `
 
     Mount the `shared` directory inside the network scenario folder inside all devices on the special directory `/shared`. This is the default specified in `kathara.conf`(5) file.
 
+* `--exclude` [<DEVICE_NAME> [<DEVICE_NAME> ...]]
+    A list of device names. You can exclude certain devices of the network scenario from being restarted.
+
 * `DEVICE_NAME`:
     A list of device names. Instead of restarting the whole network scenario, only specified devices are restarted.
 

docs/kathara-lstart.1.ronn

@@ -6,7 +6,8 @@ kathara-lstart(1) -- Start a Kathara network scenario
 
 `kathara lstart` [`-h`] [`--noterminals` \| `--terminals` \| `--privileged`]  
 [`-d` <DIRECTORY>] [`-F`] [`-l`] [`-o` [<OPTION> [<OPTION> ...]]] [`--xterm` <XTERM>]  
-[`--print`]  [`--no-hosthome` \| `--hosthome`] [`--no-shared` \| `--shared`] [<DEVICE_NAME> [<DEVICE_NAME> ...]]
+[`--print`]  [`--no-hosthome` \| `--hosthome`] [`--no-shared` \| `--shared`] [`--exclude` <DEVICE_NAME> [<DEVICE_NAME> ...]]  
+[<DEVICE_NAME> [<DEVICE_NAME> ...]]
 
 
 ## DESCRIPTION
@@ -86,11 +87,14 @@ The configuration of a Kathara network scenario consists of some files described
 
     Mount the `shared` directory inside the network scenario folder inside all devices on the special directory `/shared`. This is the default specified in `kathara.conf`(5) file.
 
+* `--exclude` [<DEVICE_NAME> [<DEVICE_NAME> ...]]
+    A list of device names. You can exclude certain devices of the network scenario from being started.
+
 * `DEVICE_NAME`:
     A list of device names. Instead of starting the whole network scenario, only specified devices are started.
 
 m4_include(footer.txt)
 
 ## SEE ALSO
 
-`kathara`(1), `kathara-lclean`(1), `kathara-lrestart`(1), `kathara-ltest`(1), `kathara-linfo`(1), `kathara-lab.conf`(5), `kathara-lab.dep`(5), `kathara-lab.ext`(5)
+`kathara`(1), `kathara-lclean`(1), `kathara-lrestart`(1), `kathara-ltest`(1), `kathara-linfo`(1), `kathara-lab.conf`(5), `kathara-lab.dep`(5), `kathara-lab.ext`(5)

src/Kathara/cli/command/LcleanCommand.py

@@ -33,6 +33,14 @@ def __init__(self) -> None:
             required=False,
             help='Specify the folder containing the network scenario.'
         )
+        self.parser.add_argument(
+            '--exclude',
+            dest='excluded_machines',
+            metavar='DEVICE_NAME',
+            nargs='+',
+            default=[],
+            help='Exclude specified devices from clean.'
+        )
         self.parser.add_argument(
             'machine_names',
             metavar='DEVICE_NAME',
@@ -55,5 +63,6 @@ def run(self, current_path: str, argv: List[str]) -> None:
 
         Kathara.get_instance().undeploy_lab(
             lab_hash=lab.hash,
-            selected_machines=set(args['machine_names']) if args['machine_names'] else None
+            selected_machines=set(args['machine_names']) if args['machine_names'] else None,
+            excluded_machines=set(args['excluded_machines']) if args['excluded_machines'] else None,
         )

src/Kathara/cli/command/LrestartCommand.py

@@ -110,6 +110,14 @@ def __init__(self) -> None:
             const=True,
             help='Mount "/shared" directory inside devices.'
         )
+        self.parser.add_argument(
+            '--exclude',
+            dest='excluded_machines',
+            metavar='DEVICE_NAME',
+            nargs='+',
+            default=[],
+            help='Exclude specified devices.'
+        )
         self.parser.add_argument(
             'machine_name',
             metavar='DEVICE_NAME',
@@ -125,6 +133,8 @@ def run(self, current_path: str, argv: List[str]) -> None:
 
         if args['machine_name']:
             lclean_argv.extend(args['machine_name'])
+        if args['excluded_machines']:
+            lclean_argv.extend(['--exclude'] + args['excluded_machines'])
 
         LcleanCommand().run(current_path, lclean_argv)
         LstartCommand().run(current_path, argv)

src/Kathara/cli/command/LstartCommand.py

@@ -129,6 +129,14 @@ def __init__(self) -> None:
             const=True,
             help='Mount "/shared" directory inside devices.'
         )
+        self.parser.add_argument(
+            '--exclude',
+            dest='excluded_machines',
+            metavar='DEVICE_NAME',
+            nargs='+',
+            default=[],
+            help='Exclude specified devices from startup.'
+        )
         self.parser.add_argument(
             'machine_name',
             metavar='DEVICE_NAME',
@@ -216,7 +224,9 @@ def run(self, current_path: str, argv: List[str]) -> Lab:
                 self.console.print("[yellow]\u26a0 Running devices with privileged capabilities, terminals won't open!")
                 Setting.get_instance().open_terminals = False
 
-        Kathara.get_instance().deploy_lab(lab, selected_machines=set(args['machine_name']))
+        Kathara.get_instance().deploy_lab(
+            lab, selected_machines=set(args['machine_name']), excluded_machines=set(args['excluded_machines'])
+        )
 
         if args['list']:
             with self.console.status(

src/Kathara/foundation/manager/IManager.py

@@ -43,12 +43,14 @@ def deploy_link(self, link: Link) -> None:
         raise NotImplementedError("You must implement `deploy_link` method.")
 
     @abstractmethod
-    def deploy_lab(self, lab: Lab, selected_machines: Set[str] = None) -> None:
+    def deploy_lab(self, lab: Lab, selected_machines: Optional[Set[str]] = None,
+                   excluded_machines: Optional[Set[str]] = None) -> None:
         """Deploy a Kathara network scenario.
 
         Args:
             lab (Kathara.model.Lab): A Kathara network scenario.
-            selected_machines (Set[str]): If not None, deploy only the specified devices.
+            selected_machines (Optional[Set[str]]): If not None, deploy only the specified devices.
+            excluded_machines (Optional[Set[str]]): If not None, exclude devices from being deployed.
 
         Returns:
             None
@@ -123,7 +125,8 @@ def undeploy_link(self, link: Link) -> None:
 
     @abstractmethod
     def undeploy_lab(self, lab_hash: Optional[str] = None, lab_name: Optional[str] = None, lab: Optional[Lab] = None,
-                     selected_machines: Optional[Set[str]] = None) -> None:
+                     selected_machines: Optional[Set[str]] = None,
+                     excluded_machines: Optional[Set[str]] = None) -> None:
         """Undeploy a Kathara network scenario.
 
         Args:
@@ -134,6 +137,7 @@ def undeploy_lab(self, lab_hash: Optional[str] = None, lab_name: Optional[str] =
             lab (Optional[Kathara.model.Lab]): The network scenario object.
                 Can be used as an alternative to lab_hash and lab_name. If None, lab_hash or lab_name should be set.
             selected_machines (Optional[Set[str]]): If not None, undeploy only the specified devices.
+            excluded_machines (Optional[Set[str]]): If not None, exclude devices from being undeployed.
 
         Returns:
             None

src/Kathara/manager/Kathara.py

@@ -75,17 +75,19 @@ def deploy_link(self, link: Link) -> None:
         """
         self.manager.deploy_link(link)
 
-    def deploy_lab(self, lab: Lab, selected_machines: Set[str] = None) -> None:
+    def deploy_lab(self, lab: Lab, selected_machines: Optional[Set[str]] = None,
+                   excluded_machines: Optional[Set[str]] = None) -> None:
         """Deploy a Kathara network scenario.
 
         Args:
             lab (Kathara.model.Lab): A Kathara network scenario.
-            selected_machines (Set[str]): If not None, deploy only the specified devices.
+            selected_machines (Optional[Set[str]]): If not None, deploy only the specified devices.
+            excluded_machines (Optional[Set[str]]): If not None, exclude devices from being deployed.
 
         Returns:
             None
         """
-        self.manager.deploy_lab(lab, selected_machines)
+        self.manager.deploy_lab(lab, selected_machines, excluded_machines)
 
     def connect_machine_to_link(self, machine: Machine, link: Link, mac_address: Optional[str] = None) -> None:
         """Connect a Kathara device to a collision domain.
@@ -151,7 +153,8 @@ def undeploy_link(self, link: Link) -> None:
         self.manager.undeploy_link(link)
 
     def undeploy_lab(self, lab_hash: Optional[str] = None, lab_name: Optional[str] = None, lab: Optional[Lab] = None,
-                     selected_machines: Optional[Set[str]] = None) -> None:
+                     selected_machines: Optional[Set[str]] = None,
+                     excluded_machines: Optional[Set[str]] = None) -> None:
         """Undeploy a Kathara network scenario.
 
         Args:
@@ -162,14 +165,15 @@ def undeploy_lab(self, lab_hash: Optional[str] = None, lab_name: Optional[str] =
             lab (Optional[Kathara.model.Lab]): The network scenario object.
                 Can be used as an alternative to lab_hash and lab_name. If None, lab_hash or lab_name should be set.
             selected_machines (Optional[Set[str]]): If not None, undeploy only the specified devices.
+            excluded_machines (Optional[Set[str]]): If not None, exclude devices from being undeployed.
 
         Returns:
             None
 
         Raises:
             InvocationError: If a running network scenario hash or name is not specified.
         """
-        self.manager.undeploy_lab(lab_hash, lab_name, lab, selected_machines)
+        self.manager.undeploy_lab(lab_hash, lab_name, lab, selected_machines, excluded_machines)
 
     def wipe(self, all_users: bool = False) -> None:
         """Undeploy all the running network scenarios.

src/Kathara/manager/docker/DockerLink.py

@@ -13,7 +13,7 @@
 from .stats.DockerLinkStats import DockerLinkStats
 from ... import utils
 from ...event.EventDispatcher import EventDispatcher
-from ...exceptions import PrivilegeError
+from ...exceptions import PrivilegeError, InvocationError
 from ...model.ExternalLink import ExternalLink
 from ...model.Lab import Lab
 from ...model.Link import BRIDGE_LINK_NAME, Link
@@ -30,18 +30,32 @@ def __init__(self, client: DockerClient, docker_plugin: DockerPlugin) -> None:
         self.client: DockerClient = client
         self.docker_plugin: DockerPlugin = docker_plugin
 
-    def deploy_links(self, lab: Lab, selected_links: Set[str] = None) -> None:
+    def deploy_links(self, lab: Lab, selected_links: Set[str] = None, excluded_links: Set[str] = None) -> None:
         """Deploy all the network scenario collision domains as Docker networks.
 
         Args:
             lab (Kathara.model.Lab.Lab): A Kathara network scenario.
             selected_links (Set[str]): A set containing the name of the collision domains to deploy.
+            excluded_links (Set[str]): A set containing the name of the collision domains to exclude.
 
         Returns:
             None
+
+        Raises:
+            InvocationError: If both `selected_links` and `excluded_links` are specified.
         """
-        links = {k: v for (k, v) in lab.links.items() if k in selected_links}.items() if selected_links \
-            else lab.links.items()
+        if selected_links and excluded_links:
+            raise InvocationError(f"You can either specify `selected_links` or `excluded_links`.")
+
+        links = lab.links.items()
+        if selected_links:
+            links = {
+                k: v for k, v in links if k in selected_links
+            }.items()
+        elif excluded_links:
+            links = {
+                k: v for k, v in links if k not in excluded_links
+            }.items()
 
         if len(links) > 0:
             pool_size = utils.get_pool_size()
@@ -148,7 +162,7 @@ def undeploy(self, lab_hash: str, selected_links: Optional[Set[str]] = None) ->
             None
         """
         networks = self.get_links_api_objects_by_filters(lab_hash=lab_hash)
-        if selected_links is not None and len(selected_links) > 0:
+        if selected_links:
             networks = [item for item in networks if item.attrs["Labels"]["name"] in selected_links]
 
         for item in networks:

src/Kathara/manager/docker/DockerMachine.py

@@ -18,7 +18,7 @@
 from ... import utils
 from ...event.EventDispatcher import EventDispatcher
 from ...exceptions import MountDeniedError, MachineAlreadyExistsError, DockerPluginError, \
-    MachineBinaryError, MachineNotRunningError, PrivilegeError
+    MachineBinaryError, MachineNotRunningError, PrivilegeError, InvocationError
 from ...model.Interface import Interface
 from ...model.Lab import Lab
 from ...model.Link import Link, BRIDGE_LINK_NAME
@@ -109,24 +109,36 @@ def __init__(self, client: DockerClient, docker_image: DockerImage) -> None:
         self._engine_version: str = client.version()['Version']
         self.docker_image: DockerImage = docker_image
 
-    def deploy_machines(self, lab: Lab, selected_machines: Set[str] = None) -> None:
+    def deploy_machines(self, lab: Lab, selected_machines: Set[str] = None, excluded_machines: Set[str] = None) -> None:
         """Deploy all the network scenario devices as Docker containers.
 
         Args:
             lab (Kathara.model.Lab.Lab): A Kathara network scenario.
             selected_machines (Set[str]): A set containing the name of the devices to deploy.
+            excluded_machines (Set[str]): A set containing the name of the devices to exclude.
 
         Returns:
             None
 
         Raises:
             PrivilegeError: If the privileged mode is active and the user does not have root privileges.
+            InvocationError: If both `selected_machines` and `excluded_machines` are specified.
         """
         if lab.general_options['privileged_machines'] and not utils.is_admin():
             raise PrivilegeError("You must be root in order to start Kathara devices in privileged mode.")
 
-        machines = {k: v for (k, v) in lab.machines.items() if k in selected_machines}.items() if selected_machines \
-            else lab.machines.items()
+        if selected_machines and excluded_machines:
+            raise InvocationError(f"You can either specify `selected_machines` or `excluded_machines`.")
+
+        machines = lab.machines.items()
+        if selected_machines:
+            machines = {
+                k: v for k, v in machines if k in selected_machines
+            }.items()
+        elif excluded_machines:
+            machines = {
+                k: v for k, v in machines if k not in excluded_machines
+            }.items()
 
         # Check and pulling machine images
         lab_images = set(map(lambda x: x[1].get_image(), machines))
@@ -471,22 +483,30 @@ def start(self, machine: Machine) -> None:
 
         machine.api_object.reload()
 
-    def undeploy(self, lab_hash: str, selected_machines: Set[str] = None) -> None:
+    def undeploy(self, lab_hash: str, selected_machines: Set[str] = None, excluded_machines: Set[str] = None) -> None:
         """Undeploy the devices contained in the network scenario defined by the lab_hash.
 
         If a set of selected_machines is specified, undeploy only the specified devices.
 
         Args:
             lab_hash (str): The hash of the network scenario to undeploy.
-            selected_machines (Optional[Set[str]]): If not None, undeploy only the specified devices.
+            selected_machines (Set[str]): A set containing the name of the devices to undeploy.
+            excluded_machines (Set[str]): A set containing the name of the devices to exclude.
 
         Returns:
             None
+
+        Raises:
+            InvocationError: If both `selected_machines` and `excluded_machines` are specified.
         """
-        containers = self.get_machines_api_objects_by_filters(lab_hash=lab_hash, user=utils.get_current_user_name())
+        if selected_machines and excluded_machines:
+            raise InvocationError(f"You can either specify `selected_machines` or `excluded_machines`.")
 
-        if selected_machines is not None and len(selected_machines) > 0:
+        containers = self.get_machines_api_objects_by_filters(lab_hash=lab_hash, user=utils.get_current_user_name())
+        if selected_machines:
             containers = [item for item in containers if item.labels["name"] in selected_machines]
+        elif excluded_machines:
+            containers = [item for item in containers if item.labels["name"] not in excluded_machines]
 
         if len(containers) > 0:
             pool_size = utils.get_pool_size()