Skip to content

Kathara.model.Machine

Jump to bottom
tcaiazzi edited this page Jul 29, 2025 · 15 revisions

module Kathara.model.Machine

Global Variables

  • MACHINE_CAPABILITIES
  • ALLOWED_VOLUME_MODES

class Machine

A Kathara device.

Contains information about the device and the API object to interact with the Manager.

Attributes:

  • lab (Kathara.model.Lab): The Kathara network Scenario of the device.
  • name (str): The name of the device.
  • interfaces (collection.OrderedDict[int, Kathara.model.Link]): A list of the collision domains of the device.
  • meta (Dict[str, Any]): Keys are meta properties name, values are meta properties values.
  • api_object (Any): To interact with the current Kathara Manager.
  • fs (fs.FS): The filesystem of the device. Contains files and configurations associated to it.

method Machine.__init__ 

__init__(lab: 'LabPackage.Lab', name: str, **kwargs) → None

Create a new instance of a Kathara device.

Args:

  • lab (Kathara.model.Lab): The Kathara network scenario of the new device.
  • name (str): The name of the device.
  • **kwargs: Specifies the optional parameters of the device.

Returns: None

method Machine.add_interface 

add_interface(
    link: 'LinkPackage.Link',
    number: int = None,
    mac_address: str = None
) → InterfacePackage.Interface

Add an interface to the device attached to the specified collision domain.

Args:

  • link (Kathara.model.Link): The Kathara collision domain to attach.
  • number (int): The number of the new interface. If it is None, the first free number is selected.
  • mac_address (str): The MAC address of the interface. If None, a generated MAC address is associated when the Machine is started.

Returns:

  • Interface: The object associated to this interface.

Raises:

  • MachineCollisionDomainConflictError: If the interface number specified is already used on the device.
  • MachineCollisionDomainConflictError: If the device is already connected to the collision domain.

method Machine.add_meta 

add_meta(name: str, value: Any) → None

Add a meta property to the device.

Args:

  • name (str): The name of the property.
  • value (Any): The value of the property.

Returns:

  • Optional[Any]: Previous value if meta was already assigned, None otherwise.

Raises:

  • MachineOptionError: If the specified value is not valid for the specified property.

method Machine.check 

check() → None

Sort interfaces and check if there are missing interface numbers.

Returns: None

Raises:

  • NonSequentialMachineInterfaceError: If there is a missing interface number.

method Machine.copy_directory_from_path 

copy_directory_from_path(src_path: str, dst_path: str) → None

Copy a directory from a src_path in the host filesystem into a dst_path in the fs of the device.

Args:

  • src_path (str): The source path of the directory to copy.
  • dst_path (str): The destination path on the device where to copy the directory.

Returns: None

method Machine.create_file_from_list 

create_file_from_list(lines: List[str], dst_path: str) → None

Create a file from a list of strings in the device fs. If fs is None, create it in the network scenario.

Args:

  • lines (List[str]): The list of strings representing the content of the file to create.
  • dst_path (str): The absolute path of the fs where create the file.

Returns: None

Raises:

  • fs.errors.ResourceNotFound: If the path is not found.

method Machine.create_file_from_path 

create_file_from_path(src_path: str, dst_path: str) → None

Create a file in the device fs from an existing file on the host filesystem. If the fs is None, create it.

Args:

  • src_path (str): The path of the file on the host filesystem to copy in the fs object.
  • dst_path (str): The absolute path of the fs where create the file.

Returns: None

Raises:

  • fs.errors.ResourceNotFound: If the path is not found.

method Machine.create_file_from_stream 

create_file_from_stream(stream: Union[BinaryIO, TextIO], dst_path: str) → None

Create a file in the device fs from a stream. If fs is None, create it in the network scenario.

Args:

  • stream (Union[BinaryIO, TextIO]): The stream representing the content of the file to create.
  • dst_path (str): The absolute path of the fs where create the file.

Returns: None

Raises:

  • UnsupportedOperation: If the stream is opened without read permissions.
  • fs.errors.ResourceNotFound: If the path is not found.

method Machine.create_file_from_string 

create_file_from_string(content: str, dst_path: str) → None

Create a file from a string in the device fs. If fs is None, create it in the network scenario.

Args:

  • content (str): The string representing the content of the file to create.
  • dst_path (str): The absolute path of the fs where create the file.

Returns: None

Raises:

  • fs.errors.ResourceNotFound: If the path is not found.

method Machine.delete_line 

delete_line(
    file_path: str,
    line_to_delete: str,
    first_occurrence: bool = False
) → int

Delete a specified line in a file.

Args:

  • file_path (str): The path of the file to delete the line.
  • line_to_delete (str): A string or a regex representing the line to delete.
  • first_occurrence (bool): Deletes only first occurrence. Default is False.

Returns:

  • int: Number of times the line has been deleted.

Raises:

  • fs.errors.FileExpected: If the path is not a file.
  • fs.errors.ResourceNotFound: If the path does not exist.
  • LineNotFoundError: If the searched line is not found in the file.

method Machine.get_cpu 

get_cpu(multiplier: int = 1) → Optional[int]

Get the CPU limit, multiplied by a specific multiplier.

User should pass a float value ranging from 0 to max user CPUs. Try to take it from options, or device meta. Otherwise, return None.

Args:

  • multiplier (int): A numeric multiplier for the CPU limit value.

Returns:

  • Optional[int]: The CPU limit of the device.

Raises:

  • MachineOptionError: If the CPU value specified is not valid.

method Machine.get_envs 

get_envs() → Dict[str, Union[int, str]]

Get the environment variables specified for the device.

Returns:

  • Dict[str, Union[int, str]]: Keys are environment variables to set, values are the values to apply.

method Machine.get_exec_commands 

get_exec_commands() → List[str]

Get the device exec commands.

Returns:

  • List[str]: The list containing the additional commands.

method Machine.get_image 

get_image() → str

Get the image of the device, if defined in options or device meta. If not, use default one.

Returns:

  • str: The name of the device image.

method Machine.get_mem 

get_mem() → str

Get memory limit, if defined in options. If not, use the value from device meta. Otherwise, return None.

Returns:

  • str: The memory limit of the device.

Raises:

  • MachineOptionError: If the memory value specified is not valid.

method Machine.get_num_terms 

get_num_terms() → int

Get the number of terminals to be opened for the device.

Returns:

  • int: The number of terminals to be opened.

Raises:

  • MachineOptionError: If the terminals number value specified is not valid.

method Machine.get_ports 

get_ports() → Dict[Tuple[int, str], int]

Get the port mapping of the device.

Returns:

  • Dict[(int, str), int]: Keys are pairs (host port, protocol), values specifies the guest port.

method Machine.get_shell 

get_shell() → str

Get the custom shell specified for the device.

Returns:

  • str: The path of the custom shell specified for connecting to the device.

method Machine.get_sysctls 

get_sysctls() → Dict[str, Union[int, str]]

Get the sysctls specified for the device.

Returns:

  • Dict[str, Union[int, str]]: Keys contain the sysctls to set, values are the values to apply.

method Machine.get_ulimits 

get_ulimits() → Dict[str, Dict[str, int]]

Get the ulimits of the device.

Returns:

  • Dict[str, Dict[str, int]]: A dictionary containing ulimits of the device.

method Machine.get_volumes 

get_volumes() → dict[str, str]

Get the paths of the additional volumes mounted on the device.

Returns:

  • dict[str, str]: The paths of the additional volumes mounted on the device. Keys represent the paths on the host, while values represent the paths on the device.

method Machine.is_bridged 

is_bridged() → bool

Return True if the device is bridged, else return False.

Returns:

  • bool: True if the device is bridged, else False.

method Machine.is_ipv6_enabled 

is_ipv6_enabled() → bool

Check if IPv6 is enabled on the device.

Returns:

  • bool: True if it is enabled, else False.

Raises:

  • MachineOptionError: If the IPv6 value specified is not valid.

method Machine.is_privileged 

is_privileged() → bool

Return True if the device is privileged, else return False.

Returns:

  • bool: True if the device is privileged, else False.

method Machine.pack_data 

pack_data() → Optional[bytes]

Pack machine data into a .tar.gz file and returns the tar content as a byte array.

While packing files, it also applies the win2linux patch in order to remove UTF-8 BOM.

Returns:

  • bytes: the tar content.

method Machine.remove_interface 

remove_interface(link: 'LinkPackage.Link') → None

Disconnect the device from the specified collision domain.

Args:

  • link (Kathara.model.Link): The Kathara collision domain to disconnect.

Returns: None

Raises:

  • MachineCollisionDomainConflictError: If the device is not connected to the collision domain.

method Machine.update_file_from_list 

update_file_from_list(lines: List[str], dst_path: str) → None

Update a file in the fs object from a list of strings.

Args:

  • lines (List[str]): The list of strings representing the content for updating the file.
  • dst_path (str): The absolute path on the fs of the file to upload.

Returns: None

Raises:

  • InvocationError: If the fs is None.
  • fs.errors.ResourceNotFound: If the path is not found in the fs.

method Machine.update_file_from_string 

update_file_from_string(content: str, dst_path: str) → None

Update a file in the fs object from a string.

Args:

  • content (str): The string representing the content for updating the file.
  • dst_path (str): The absolute path on the fs of the file to update.

Returns: None

Raises:

  • InvocationError: If the fs is None.
  • fs.errors.ResourceNotFound: If the path is not found in the fs.

method Machine.update_meta 

update_meta(args: Dict[str, Any]) → None

Update the device metas from a dict.

Args:

  • args (Dict[str, Any]): Keys are the meta properties names, values are the updated meta properties values.

Returns: None

method Machine.write_line_after 

write_line_after(
    file_path: str,
    line_to_add: str,
    searched_line: str,
    first_occurrence: bool = False
) → int

Write a new line after a specific line in a file.

Args:

  • file_path (str): The path of the file to add the new line.
  • line_to_add (str): The new line to add after the searched line.
  • searched_line (str): A string or a regex representing the searched line.
  • first_occurrence (bool): Inserts line only after the first occurrence. Default is False.

Returns:

  • int: Number of times the line has been added.

Raises:

  • fs.errors.FileExpected: If the path is not a file.
  • fs.errors.ResourceNotFound: If the path does not exist.
  • LineNotFoundError: If the searched line is not found in the file.

method Machine.write_line_before 

write_line_before(
    file_path: str,
    line_to_add: str,
    searched_line: str,
    first_occurrence: bool = False
) → int

Write a new line before a specific line in a file.

Args:

  • file_path (str): The path of the file to add the new line.
  • line_to_add (str): The new line to add before the searched line.
  • searched_line (str): A string or a regex representing the searched line.
  • first_occurrence (bool): Inserts line only before the first occurrence. Default is False.

Returns:

  • int: Number of times the line has been added.

Raises:

  • fs.errors.FileExpected: If the path is not a file.
  • fs.errors.ResourceNotFound: If the path does not exist.
  • LineNotFoundError: If the searched line is not found in the file.

This file was automatically generated via lazydocs.

Website: kathara.org

Contact us: [email protected]

Wiki Home

Manual

Official Labs

Old Netkit Labs

Docker Images

Kathará Python API

Installation Guide

How to Update

Clone this wiki locally