Systems

BaseSystem

class pybsd.systems.base.BaseSystem(name, hostname=None)[source]

Bases: object

Describes a base OS instance such as a computer, a virtualized system or a jail

It provides common functionality for a full system, a jail or a virtualized instance. This allows interaction with both real and modelized instances.

Parameters:
  • name (str) – a name that identifies the system.
  • hostname (Optional[str]) – The system’s hostname.
ExecutorClass

class

the class of the system’s executor. It must be or extend Executor

ExecutorClass

alias of Executor

execute = None

function: a method that proxies binaries invocations

hostname

str: The system’s hostname. If not specified, the system’s name is returned instead.

name

str: a name that identifies the system.

System

class pybsd.systems.base.System(name, ext_if, int_if=None, lo_if=None, hostname=None)[source]

Bases: pybsd.systems.base.BaseSystem

Describes a full OS instance

It provides common functionality for a full system.

Interfaces

Each interface is described by:

tuple (interface_name (str), list [ip_interfaces (str)]).

Each ip interface is composed of an ip and an optional prefixlen, such as:

('re0', ['10.0.2.0/24', '10.0.1.0/24', '1c02:4f8:0f0:14e6::2:0:1/110', '1c02:4f8:0f0:14e6::1:0:1/110'])

if the prefixlen is not specified it will default to /32 (IPv4) or /128 (IPv6)

Example

>>> from pybsd import System
>>> box01 = System(name='box01',
...                hostname='box01.foo.bar',
...                ext_if=('re0', ['148.241.178.106/24', '1c02:4f8:0f0:14e6::/110', '1c02:4f8:000:14e6::/110']),
...                int_if=('eth0', ['192.168.0.0/24', '1c02:4f8:0f0:14e6::0:0:1/110'])
...               )
>>> '148.241.178.106' in box01.ips
True
>>> '148.241.178.101' in box01.ips
False
>>> box01.ips
SortedSet(['127.0.0.1', '148.241.178.106', '192.168.0.0', '1c02:4f8:0:14e6::', '1c02:4f8:f0:14e6::', '1c02:4f8:f0:14e6::1', '::1'], key=None, load=1000)
Parameters:
  • name (str) – a name that identifies the system.
  • ext_if (tuple (str, list [str])) – Interface definition used to initialize self.ext_if
  • int_if (Optional[ tuple (str, list [str]) ]) – Interface definition used to initialize self.int_if
  • lo_if (Optional[ tuple (str, list [str]) ]) – Interface definition used to initialize self.lo_if
  • hostname (Optional[int]) – The system’s hostname.
Raises:

DuplicateIPError – if any ip address in the interface definitions is already in use.
ext_if = None

Interface: the system’s outward-facing interface

int_if

Interface: the system’s internal network-facing interface. If not expressly defined, it defaults to self.ext_if, as in that case the same interface will be used for all networks.

ips

sortedcontainers.SortedSet ([ str ]): a sorted set containing all ips on this system.

lo_if = None

Interface: the system’s loopback interface. If not expressly defined, it defaults to (‘lo0’, [‘127.0.0.1/8’, ‘::1/110’])

make_if(definition)[source]

Returns an Interface based on definition

Parameters:definition (tuple (str, list [str])) –
Returns:a valid interface
Return type:Interface
Raises:DuplicateIPError – raised if one of the ip addresses in definition is already in use
reset_int_if()[source]

Resets the system’s int_if to its default value (its own ext_if)

Master

class pybsd.systems.masters.Master(name, ext_if, int_if=None, lo_if=None, j_if=None, jlo_if=None, hostname=None)[source]

Bases: pybsd.systems.base.System

Describes a system that can host jails

Parameters:
  • name (str) – a name that identifies the system.
  • ext_if (tuple (str, list [str])) – Definition of the system’s outward-facing interface
  • int_if (Optional[ tuple (str, list [str]) ]) – Definition of the system’s internal network-facing interface. If it is not specified it defaults to ext_if, as in that case the same interface will be used for all networks.
  • lo_if (Optional[ tuple (str, list [str]) ]) – Definition of the system’s loopback interface. It defaults to (‘lo0’, [‘127.0.0.1/8’, ‘::1/110’])
  • j_if (Optional[ tuple (str, list [str]) ]) – Definition of the interface the system provides to hosted jails as their external interface. By default, this will be the system’s own ext_if.
  • jlo_if (Optional[ tuple (str, list [str]) ]) – Definition of the interface the system provides to hosted jails as their loopback interface. By default, this will be the system’s own lo_if.
  • hostname (Optional[int]) – The system’s hostname.
JailHandlerClass

class

the class of the system’s jail handler. It must be or extend BaseJailHandler

JailHandlerClass

alias of BaseJailHandler

attach_jail(jail)[source]

Adds a jail to the system’s jails list.

Re-attaching an already-owned jail is transparent.

Parameters:

jail (Jail) – The jail to be added
Returns:

the jail that was added. This allows chaining of commands.
Return type:

Jail
Raises:
clone_jail(jail, name, uid, hostname=None)[source]

Creates and returns the clone of a Jail, using provided parameters as the new value of unique properties.

Parameters:
  • jail (Jail) – The jail to be cloned
  • name (str) – a name that identifies the system.
  • uid (int) – The jail’s id.
  • hostname (Optional[str]) – The jail’s hostname.
Returns:

The cloned jail
Return type:

Jail
Raises:

see exceptions raised by attach_jail()
ezjail_admin_binary[source]

Returns the path of this environment’s ezjail-admin binary.

Returns:
Return type:str
hostnames

set: returns a set containing the hostnames attached to a Master. These will be its own hostname and that of jails attached to it.

j_if

Interface: the interface the system provides to hosted jails as their external interface. By default, this will be the system’s own ext_if.

jlo_if

Interface: the interface the system provides to hosted jails as their loopback interface. By default, this will be the system’s own lo_if.

names

set: returns a set containing the names attached to a Master. These will be its own name and that of jails attached to it.

reset_j_if()[source]

Resets the system’s j_if to its default value (its own ext_if)

reset_jlo_if()[source]

Resets the system’s jlo_if to its default value (its own lo_if)

uids

set: returns a set containing the uids attached to a Master. These will be the uids of jails attached to it.

Jail

class pybsd.systems.jails.Jail(name, uid, hostname=None, master=None, auto_start=False, jail_class=u'service')[source]

Bases: pybsd.systems.base.BaseSystem

Describes a jailed system

When attached to an instance of Master a jail can be created, deleted and controlled through said master’s ezjail-admin interface.

Example

>>> from pybsd import Jail, Master
>>> master01 = Master(name='master01',
...                   hostname='master01.foo.bar',
...                   ext_if=('re0', ['148.241.178.106/24', '1c02:4f8:0f0:14e6::/110']),
...                   int_if=('eth0', ['192.168.0.0/24', '1c02:4f8:0f0:14e6::0:0:1/110']),
...                   j_if=('re0', ['10.0.1.0/24', '1c02:4f8:0f0:14e6::1:0:1/110']),
...                   jlo_if=('lo1', ['127.0.1.0/24', '::0:1:0:0/110']))
>>> jail01 = Jail(name='system',
...               uid=12,
...               hostname='system.foo.bar',
...               master=None,
...               auto_start=True,
...               jail_class='web')
Parameters:
  • name (str) – a name that identifies the jail.
  • uid (int) – The jail’s id, unique over a user’s or an organization’s domain.
  • hostname (Optional[str]) – The jail’s hostname. It not specified the jail’s name is used instead. #: Optional[Master]:
  • master (Optional[Master]) – The jail’s master i.e. host system. By default a Jail is created detached and the value of master is None.
  • jail_type (Optional[str]) –

    The jail’s type, according to its storage solution. If the jail is not attached it is set to None by default. If attached the default is Z, for ZFS filesystem-based jail.

    Possible types are:
    • D –> Directory tree based jail.
    • I –> File-based jail.
    • E –> Geli encrypted file-based jail.
    • B –> Bde encrypted file-based jail.
    • Z –> ZFS filesystem-based jail.
  • auto_start (Optional[bool]) – Whether the jail should be started automatically at host system’s boot time.
  • jail_class (Optional[str]) – Allows differentiating jails by class. This will be worked out of base jails to depend on the jail handler. The base handler will probably not have the notion of classes
Raises:
  • AttachNonMasterError – if master is specified and is not an instance of Master
  • DuplicateJailNameError – if master is specified and the jail’s name is already attached to it
  • DuplicateJailHostnameError – if master is specified and the jail’s hostname is already attached to it
  • DuplicateJailUidError – if master is specified and the jail’s uid is already attached to it
  • JailAlreadyAttachedError – if master is specified and the jail is already attached to another master
auto_start = None

Optional[bool]: Whether the jail should be started automatically at host system’s boot time.

base_hostname

str or NoneType: The system’s hostname.

ext_if

Interface: the jail’s outward-facing interface. It is evaluated dynamically by the master’s jail handler, so that the same base jail cloned on different host systems can return different values.

handler

bool: Whether the jail is currently attached to a master.

hostname

str or NoneType: The jail’s hostname. If not attached, it. is equal to None

is_attached

bool: Whether the jail is currently attached to a master.

jail_class = None

Optional[str]: Allows differentiating jails by class.

jail_class_id

int: Returns this jail’s class id.

This is an integer value which is given by its jail_handler according to its class.

jail_type

str or NoneType: The jail’s type, according to its storage solution. If not attached, it. is equal to None

Possible types are:
  • D –> Directory tree based jail.
  • I –> File-based jail.
  • E –> Geli encrypted file-based jail.
  • B –> Bde encrypted file-based jail.
  • Z –> ZFS filesystem-based jail.
jid

int: Returns this jail’s jid as per ezjail_admin

The 1 value returned when attached is a stub for now. It must come from parsing master’s ezjail-admin.list()’s output

lo_if

Interface: the jail’s loopback interface. It is evaluated dynamically by the master’s jail handler, so that the same base jail cloned on different host systems can return different values.

master = None

Optional[Master]: The jail’s master i.e. host system. By default a Jail is created detached.

name

str: a name that identifies the system.

path

unipath.Path: the absolute path of the jail’s filesystem, relative to the host’s filesystem. It is evaluated dynamically by the master’s jail handler, so that the same base jail cloned on different host systems can return different values. By default it resolves to a directory called after jail.name, inside the host system’s jail_path: foo.path = unipath.Path(‘/usr/jails/foo’).

status

str: Returns this jail’s status as per ezjail_admin

Possible status
  • D The jail is detached (not attached to any master)
  • S The jail is stopped.
  • A The image of the jail is mounted, but the jail is not running.
  • R The jail is running.

The S value is a stub for now. It must come from parsing master’s ezjail-admin.list()’s output

uid

int: The jail’s uid.