Kathara.manager.docker.DockerMachine

module Kathara.manager.docker.DockerMachine

Global Variables

• BRIDGE_LINK_NAME
• MACHINE_CAPABILITIES
• RP_FILTER_NAMESPACE
• STARTUP_COMMANDS
• SHUTDOWN_COMMANDS

---

class DockerMachine

The class responsible for deploying Kathara devices as Docker container and interact with them.

method DockerMachine.__init__

__init__(
    client: docker.client.DockerClient,
    docker_image: Kathara.manager.docker.DockerImage.DockerImage
) → None

---

method DockerMachine.connect

connect(
    lab_hash: str,
    machine_name: str,
    user: str = None,
    shell: str = None,
    logs: bool = False,
    wait: Union[bool, Tuple[int, float]] = True
) → None

Open a stream to the Docker container specified by machine_name using the specified shell.

Args:

• lab_hash (str): The hash of the network scenario containing the device.
• machine_name (str): The name of the device to connect.
• user (str): The name of a current user on the host.
• shell (str): The path to the desired shell.
• logs (bool): If True, print the logs of the startup command.
• wait (Union[bool, Tuple[int, float]]): If True, wait indefinitely until the end of the startup commands execution before giving control to the user. If a tuple is provided, the first value indicates the number of retries before stopping waiting and the second value indicates the time interval to wait for each retry. Default is True.

Returns: None

Raises:

• MachineNotRunningError: If the specified device is not running.
• ValueError: If the wait values is neither a boolean nor a tuple, or an invalid tuple.

---

method DockerMachine.connect_interface

connect_interface(
    machine: Kathara.model.Machine.Machine,
    interface: Kathara.model.Interface.Interface
) → None

Connect the Docker container representing the machine to a specified collision domain.

Args:

• machine (Kathara.model.Machine.Machine): A Kathara device.
• interface (Kathara.model.Interface.Interface): A Kathara interface object.

Returns: None

Raises:

• DockerPluginError: If Kathara has been left in an inconsistent state.
• APIError: If the Docker APIs return an error.

---

method DockerMachine.copy_files

copy_files(
    machine_api_object: docker.models.containers.Container,
    path: str,
    tar_data: bytes
) → None

Copy the files contained in tar_data in the Docker container path specified by the machine_api_object.

Args:

• machine_api_object (docker.models.containers.Container): A Docker container.
• path (str): The path of the container where copy the tar_data.
• tar_data (bytes): The data to copy in the container.

Returns: None

---

method DockerMachine.create

create(machine: Kathara.model.Machine.Machine) → None

Create a Docker container representing the device and assign it to machine.api_object.

Args:

• machine (Kathara.model.Machine.Machine): A Kathara device.

Returns: None

Raises:

• MachineAlreadyExistsError: If a device with the name specified already exists.
• APIError: If the Docker APIs return an error.

---

method DockerMachine.deploy_machines

deploy_machines(
    lab: Kathara.model.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.

---

method DockerMachine.disconnect_from_link

disconnect_from_link(
    machine: Kathara.model.Machine.Machine,
    link: Kathara.model.Link.Link
) → None

Disconnect the Docker container representing the machine from a specified collision domain.

Args:

• machine (Kathara.model.Machine): A Kathara device.
• link (Kathara.model.Link): A Kathara collision domain object.

Returns: None

---

method DockerMachine.exec

exec(
    lab_hash: str,
    machine_name: str,
    command: Union[str, List],
    user: str = None,
    tty: bool = True,
    wait: Union[bool, Tuple[int, float]] = False,
    stream: bool = True
) → Union[Generator[Tuple[bytes, bytes], NoneType, NoneType], Tuple[bytes, bytes, int]]

Execute the command on the Docker container specified by the lab_hash and the machine_name.

Args:

• lab_hash (str): The hash of the network scenario containing the device.
• machine_name (str): The name of the device.
• user (str): The name of a current user on the host.
• command (Union[str, List]): The command to execute.
• tty (bool): If True, open a new tty.
• wait (Union[bool, Tuple[int, float]]): If True, wait indefinitely until the end of the startup commands execution before executing the command. If a tuple is provided, the first value indicates the number of retries before stopping waiting and the second value indicates the time interval to wait for each retry. Default is False.
• stream (bool): If True, return a generator object containing the stdout and the stderr of the command. If False, returns a tuple containing the complete stdout, the stderr, and the return code of the command.

Returns:

• Union[Generator[Tuple[bytes, bytes]], Tuple[bytes, bytes, int]]: A generator of tuples containing the stdout and stderr in bytes or a tuple containing the stdout, the stderr and the return code of the command.

Raises:

• MachineNotRunningError: If the specified device is not running.
• MachineBinaryError: If the binary of the command is not found.
• ValueError: If the wait values is neither a boolean nor a tuple, or an invalid tuple.

---

method DockerMachine.get_container_name

get_container_name(name: str, lab_hash: str) → str

Return the name of a Docker container.

Args:

• name (str): The name of a Kathara device.
• lab_hash (str): The hash of a running scenario.

Returns:

• str: The name of the Docker container in the format "|dev_prefix||username_prefix||name|_|lab_hash|".

---

method DockerMachine.get_machines_api_objects_by_filters

get_machines_api_objects_by_filters(
    lab_hash: str = None,
    machine_name: str = None,
    user: str = None
) → List[docker.models.containers.Container]

Return the Docker containers objects specified by lab_hash and user.

Args:

• lab_hash (str): The hash of a network scenario. If specified, return all the devices in the scenario.
• machine_name (str): The name of a device. If specified, return the specified container of the scenario.
• user (str): The name of a user on the host. If specified, return only the containers of the user.

Returns:

• List[docker.models.containers.Container]: A list of Docker containers objects.

---

method DockerMachine.get_machines_stats

get_machines_stats(
    lab_hash: str = None,
    machine_name: str = None,
    user: str = None
) → Generator[Dict[str, Kathara.manager.docker.stats.DockerMachineStats.DockerMachineStats], NoneType, NoneType]

Return a generator containing the Docker devices' stats.

Args:

• lab_hash (str): The hash of a network scenario. If specified, return all the stats of the devices in the scenario.
• machine_name (str): The name of a device. If specified, return the specified device stats.
• user (str): The name of a user on the host. If specified, return only the stats of the specified user.

Returns:

• Generator[Dict[str, DockerMachineStats], None, None]: A generator containing device names as keys and DockerMachineStats as values.

Raises:

• PrivilegeError: If user param is None and the user does not have root privileges.

---

method DockerMachine.start

start(machine: Kathara.model.Machine.Machine) → None

Start the Docker container representing the device.

Connect the container to the networks, run the startup commands and open a terminal (if requested).

Args:

• machine (Kathara.model.Machine.Machine): A Kathara device.

Returns: None

Raises:

• MountDeniedError: If the host drive is not shared with Docker.
• DockerPluginError: If Kathara has been left in an inconsistent state.
• APIError: If the Docker APIs return an error.

---

method DockerMachine.undeploy

undeploy(
    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 (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.

---

method DockerMachine.wipe

wipe(user: str = None) → None

Undeploy all the running devices of the specified user. If user is None, it undeploy all the running devices.

Args:

• user (str): The name of a current user on the host.

Returns: None

---

This file was automatically generated via lazydocs.