Base Classes

A module that implements core functionality for library or standalone use.

exception munet.base.MunetError

A generic munet error.

exception munet.base.CalledProcessError(returncode, cmd, output=None, stderr=None)

Improved logging subclass of subprocess.CalledProcessError.

class munet.base.Timeout(delta)

An object to passively monitor for timeouts.

munet.base.shell_quote(command)

Return command wrapped in single quotes.

munet.base.convert_number(value)

Convert a number value with a possible suffix to an integer.

>>> convert_number("100k") == 100 * 1024
True
>>> convert_number("100M") == 100 * 1000 * 1000
True
>>> convert_number("100Gi") == 100 * 1024 * 1024 * 1024
True
>>> convert_number("55") == 55
True
Return type:

int

class munet.base.Commander(name, logger=None, unet=None, **kwargs)

An object that can execute commands.

async async_get_exec_path(binary)

Return the full path to the binary executable.

binary :: binary name or list of binary names

get_exec_path(binary)

Return the full path to the binary executable.

binary :: binary name or list of binary names

get_exec_path_host(binary)

Return the full path to the binary executable.

If the object is actually a derived class (e.g., a container) this method will return the exec path for the native namespace rather than the container. The path is the one which the other xxx_host methods will use.

binary :: binary name or list of binary names

test(flags, arg)

Run test binary, with flags and arg.

test_nsonly(flags, arg)

Run test binary, with flags and arg.

path_exists(path)

Check if path exists.

async cleanup_pid(pid, kill_pid=None)

Signal a pid to exit with escalating forcefulness.

spawn(cmd, spawned_re, expects=(), sends=(), use_pty=False, logfile=None, logfile_read=None, logfile_send=None, trace=None, **kwargs)

Create a spawned send/expect process.

Parameters:

  • cmd – list of args to exec/popen with, or an already open socket

  • spawned_re – what to look for to know when done, spawn returns when seen

  • expects – a list of regex other than spawned_re to look for. Commonly, “ogin:” or “[Pp]assword:”r.

  • sends – what to send when an element of expects matches. So e.g., the username or password if thats what corresponding expect matched. Can be the empty string to send nothing.

  • use_pty – true for pty based expect, otherwise uses popen (pipes/files)

  • trace – if true then log send/expects

  • _spawn. (**kwargs - kwargs passed on the)

Returns:

A pexpect process.

Raises:

  • pexpect.TIMEOUT, pexpect.EOF as documented in pexpect –

  • CalledProcessError if EOF is seen and cmd exited then – raises a CalledProcessError to indicate the failure.

async async_spawn(cmd, spawned_re, expects=(), sends=(), use_pty=False, logfile=None, logfile_read=None, logfile_send=None, trace=None, **kwargs)

Create an async spawned send/expect process.

Parameters:

  • cmd – list of args to exec/popen with, or an already open socket

  • spawned_re – what to look for to know when done, spawn returns when seen

  • expects – a list of regex other than spawned_re to look for. Commonly, “ogin:” or “[Pp]assword:”r.

  • sends – what to send when an element of expects matches. So e.g., the username or password if thats what corresponding expect matched. Can be the empty string to send nothing.

  • use_pty – true for pty based expect, otherwise uses popen (pipes/files)

  • trace – if true then log send/expects

  • _spawn. (**kwargs - kwargs passed on the)

Returns:

A pexpect process.

Raises:

  • pexpect.TIMEOUT, pexpect.EOF as documented in pexpect –

  • CalledProcessError if EOF is seen and cmd exited then – raises a CalledProcessError to indicate the failure.

async shell_spawn(cmd, prompt, expects=(), sends=(), use_pty=False, will_echo=False, is_bourne=True, **kwargs)

Create a shell REPL (read-eval-print-loop).

Parameters:

  • cmd – shell and list of args to popen with, or an already open socket

  • prompt – the REPL prompt to look for, the function returns when seen

  • expects – a list of regex other than spawned_re to look for. Commonly, “ogin:” or “[Pp]assword:”r.

  • sends – what to send when an element of expects matches. So e.g., the username or password if thats what corresponding expect matched. Can be the empty string to send nothing.

  • is_bourne – if False then do not modify shell prompt for internal parser friently format, and do not expect continuation prompts.

  • use_pty – true for pty based expect, otherwise uses popen (pipes/files)

  • will_echo – bash is buggy in that it echo’s to non-tty unlike any other sh/ksh, set this value to true if running back

  • _spawn. (**kwargs - kwargs passed on the)

popen(cmd, **kwargs)

Creates a pipe with the given command.

Parameters:

  • cmd – str or list of command to open a pipe with.

  • **kwargs – kwargs is eventually passed on to Popen. If command is a string then will be invoked with bash -c, otherwise command is a list and will be invoked without a shell.

Returns:

a subprocess.Popen object.

popen_nsonly(cmd, **kwargs)

Creates a pipe with the given command.

Parameters:

  • cmd – str or list of command to open a pipe with.

  • **kwargs – kwargs is eventually passed on to Popen. If command is a string then will be invoked with bash -c, otherwise command is a list and will be invoked without a shell.

Returns:

a subprocess.Popen object.

async async_popen(cmd, **kwargs)

Creates a pipe with the given command.

Parameters:

  • cmd – str or list of command to open a pipe with.

  • **kwargs – kwargs is eventually passed on to create_subprocess_exec. If command is a string then will be invoked with bash -c, otherwise command is a list and will be invoked without a shell.

Returns:

a asyncio.subprocess.Process object.

async async_popen_nsonly(cmd, **kwargs)

Creates a pipe with the given command.

Parameters:

  • cmd – str or list of command to open a pipe with.

  • **kwargs – kwargs is eventually passed on to create_subprocess_exec. If command is a string then will be invoked with bash -c, otherwise command is a list and will be invoked without a shell.

Returns:

a asyncio.subprocess.Process object.

async async_cleanup_proc(p, pid=None)

Terminate a process started with a popen call.

Parameters:

  • p – return value from :py:`async_popen`, :py:`popen`, et al.

  • pid – pid to signal instead of p.pid, typically a child of cmd_p == nsenter.

Returns:

None on success, the p if multiple timeouts occur even after a SIGKILL sent.

cmd_nostatus(cmd, **kwargs)

Run given command returning output[s].

Parameters:

  • cmd – str or list of the command to execute. If a string is given it is run using a shell, otherwise the list is executed directly as the binary and arguments.

  • **kwargs – kwargs is eventually passed on to Popen. If command is a string then will be invoked with bash -c, otherwise command is a list and will be invoked without a shell.

Returns:

if “stderr” is in kwargs and not equal to subprocess.STDOUT, then both stdout and stderr are returned, otherwise stderr is combined with stdout and only stdout is returned.

cmd_status(cmd, **kwargs)

Run given command returning status and outputs.

Parameters:

  • cmd – str or list of the command to execute. If a string is given it is run using a shell, otherwise the list is executed directly as the binary and arguments.

  • **kwargs – kwargs is eventually passed on to Popen. If command is a string then will be invoked with bash -c, otherwise command is a list and will be invoked without a shell.

Returns:

(status, output, error) are returned status: the returncode of the command. output: stdout as a string from the command. error: stderr as a string from the command.

cmd_raises(cmd, **kwargs)

Execute a command. Raise an exception on errors.

Parameters:

  • cmd – str or list of the command to execute. If a string is given it is run using a shell, otherwise the list is executed directly as the binary and arguments.

  • **kwargs – kwargs is eventually passed on to Popen. If command is a string then will be invoked with bash -c, otherwise command is a list and will be invoked without a shell.

Returns:

stdout as a string from the command.

Return type:

output

Raises:

CalledProcessError – on non-zero exit status

async async_cmd_status(cmd, **kwargs)

Run given command returning status and outputs.

Parameters:

  • cmd – str or list of the command to execute. If a string is given it is run using a shell, otherwise the list is executed directly as the binary and arguments.

  • **kwargs – kwargs is eventually passed on to create_subprocess_exec. If cmd is a string then will be invoked with bash -c, otherwise cmd is a list and will be invoked without a shell.

Returns:

(status, output, error) are returned status: the returncode of the command. output: stdout as a string from the command. error: stderr as a string from the command.

async async_cmd_nostatus(cmd, **kwargs)

Run given command returning output[s].

Parameters:

  • cmd – str or list of the command to execute. If a string is given it is run using a shell, otherwise the list is executed directly as the binary and arguments.

  • **kwargs – kwargs is eventually passed on to create_subprocess_exec. If cmd is a string then will be invoked with bash -c, otherwise cmd is a list and will be invoked without a shell.

Returns:

if “stderr” is in kwargs and not equal to subprocess.STDOUT, then both stdout and stderr are returned, otherwise stderr is combined with stdout and only stdout is returned.

async async_cmd_raises(cmd, **kwargs)

Execute a command. Raise an exception on errors.

Parameters:

  • cmd – str or list of the command to execute. If a string is given it is run using a shell, otherwise the list is executed directly as the binary and arguments.

  • **kwargs – kwargs is eventually passed on to create_subprocess_exec. If cmd is a string then will be invoked with bash -c, otherwise cmd is a list and will be invoked without a shell.

Returns:

stdout as a string from the command.

Return type:

output

Raises:

CalledProcessError – on non-zero exit status

cmd_legacy(cmd, **kwargs)

Execute a command with stdout and stderr joined, IGNORES ERROR.

run_in_window(cmd, wait_for=False, background=False, name=None, title=None, forcex=False, new_window=False, tmux_target=None, ns_only=False)

Run a command in a new window (TMUX, Screen or XTerm).

Parameters:

  • cmd – string to execute.

  • wait_for – True to wait for exit from command or str as channel name to signal on exit, otherwise False

  • background – Do not change focus to new window.

  • title – Title for new pane (tmux) or window (xterm).

  • name – Name of the new window (tmux)

  • forcex – Force use of X11.

  • new_window – Open new window (instead of pane) in TMUX

  • tmux_target – Target for tmux pane.

Returns:

the pane/window identifier from TMUX (depends on new_window)

delete()

Calls self.async_delete within an exec loop.

async async_delete()

Delete the Commander (or derived object).

The actual implementation for any class should be in _async_delete new derived classes should look at the documentation for that function.

class munet.base.InterfaceMixin(*args, **kwargs)

A mixin class to support interface functionality.

get_ns_ifname(ifname)

Return a namespace unique interface name.

This function is primarily overriden by L3QemuVM, IOW by any class that doesn’t create it’s own network namespace and will share that with the root (unet) namespace.

Parameters:

ifname – the interface name.

Returns:

A name unique to the namespace of this object. By defualt the assumption is the ifname is namespace unique.

get_linux_tc_args(ifname, config)

Get interface constraints (jitter, delay, rate) for linux TC.

The keys and their values are as follows:

delay (int): number of microseconds jitter (int): number of microseconds jitter-correlation (float): % correlation to previous (default 10%) loss (float): % of loss loss-correlation (float): % correlation to previous (default 0%) rate (int or str): bits per second, string allows for use of

{KMGTKiMiGiTi} prefixes “i” means K == 1024 otherwise K == 1000

set_intf_constraints(ifname, **constraints)

Set interface outbound constraints.

Set outbound constraints (jitter, delay, rate) for an interface. All arguments may also be passed as a string and will be converted to numerical format. All arguments are also optional. If not specified then that existing constraint will be cleared.

Parameters:

  • ifname – the name of the interface

  • delay (int) – number of microseconds.

  • jitter (int) – number of microseconds.

  • jitter-correlation (float) – Percent correlation to previous (default 10%).

  • loss (float) – Percent of loss.

  • loss-correlation (float) – Percent correlation to previous (default 25%).

  • rate (int) – bits per second, string allows for use of {KMGTKiMiGiTi} prefixes “i” means K == 1024 otherwise K == 1000.

class munet.base.LinuxNamespace(name, net=True, mount=True, uts=True, cgroup=False, ipc=False, pid=False, time=False, user=False, unshare_inline=False, set_hostname=True, private_mounts=None, **kwargs)

A linux Namespace.

An object that creates and executes commands in a linux namespace

intf_ip_cmd(intf, cmd)

Run an ip command, considering an interface’s possible namespace.

intf_tc_cmd(intf, cmd)

Run a tc command, considering an interface’s possible namespace.

set_ns_cwd(cwd)

Common code for changing pre_cmd and pre_nscmd.

Parameters:

cwd (str | Path)

class munet.base.SharedNamespace(name, pid=None, nsflags=None, **kwargs)

Share another namespace.

An object that executes commands in an existing pid’s linux namespace

set_ns_cwd(cwd)

Common code for changing pre_cmd and pre_nscmd.

Parameters:

cwd (str | Path)

class munet.base.Bridge(name=None, mtu=None, unet=None, **kwargs)

A linux bridge.

class munet.base.BaseMunet(name='munet', isolated=True, pid=True, rundir=None, pytestconfig=None, **kwargs)

Munet.

add_host(name, cls=<class 'munet.base.LinuxNamespace'>, **kwargs)

Add a host to munet.

add_dummy(node1, if1, mtu=None, **intf_constraints)

Add a dummy for an interface with no link.

Add a link between switch and node or 2 nodes.

If constraints are given they are applied to each endpoint. See InterfaceMixin::set_intf_constraints() for more info.

add_switch(name, cls=<class 'munet.base.Bridge'>, **kwargs)

Add a switch to munet.

class munet.base.ShellWrapper(spawn, prompt, continuation_prompt=None, extra_init_cmd=None, will_echo=False, escape_ansi=False)

A Read-Execute-Print-Loop (REPL) interface.

A newline or prompt changing command should be sent to the spawned child prior to creation as the prompt will be `expect`ed

run_command(command, timeout=-1)

Pexpect REPLWrapper compatible run_command.

This will split command into lines and feed each one to the shell.

Parameters:

  • command – string of commands separated by newlines, a trailing newline will cause and empty line to be sent.

  • timeout – pexpect timeout value.

cmd_nostatus(cmd, timeout=-1)

Execute a shell command.

Returns:

(strip/cleaned r) output

cmd_status(cmd, timeout=-1)

Execute a shell command.

Returns:

status and (strip/cleaned r) output

cmd_raises(cmd, timeout=-1)

Execute a shell command.

Returns:

(strip/cleaned r) ouptut

Raises:

CalledProcessError – on non-zero exit status