API Reference

`cli`

The crucible.

crucible.cli.abort_if_false(ctx, _, value)

Exits if a value is false. :type ctx: :param ctx: context to use. :param _: (unused) parameter name. :type value: :param value: parameter value.

Return type:: None

`install`

Module for installing a LIVE OS to disk.

crucible.install.install_to_disk(num_disks, raid_level, ssh_key_path)

Installs the running image to disk.

Parameters:

num_disks (int) – Number of disks to use for the OS array.
raid_level (str) – Stripe or Mirror
ssh_key_path (str) – Path to an SSH key, or a directory of keys to install.

Return type:

None

`network`

Handles network interface configuration files.

exception crucible.network.config.NetworkError(message): An exception for network problems.

crucible.network.config.interface(**kwargs)

Configure the given interface.

Return type:: None

crucible.network.config.resolve_network_manager(**kwargs)

Resolves the running network manager.

Return type:: [<class ‘crucible.network.manager.SystemNetwork’>]

crucible.network.config.system(**kwargs)

Configures the system with the given network options. :type kwargs: :param kwargs: NetworkManager parameters.

Return type:: None

Interface naming module.

class crucible.network.ifname.NIC(name, mac, device_id='', vendor_id='')

Abstraction for a network interface.

property mac: str: Returns the MAC address in uppercase.

property name: str: Returns the name property.

class crucible.network.ifname.PrefixIndexes

Defines allowed network names, and provides an index/counter for naming interfaces.

property hsn: str: Prints an index number for the high-speed network interface(s).

property lan: str: Prints an index number for the local area network interface(s).

property mgmt: str: Prints an index number for the management network interface(s).

property sun: str: Prints an index number for the storage utility network interface(s).

exception crucible.network.ifname.UdevError(message): An exception for udev problems.

crucible.network.ifname.get_new_names(nics)

Given a list of NIC objects, resolve new names using the official prefixes.

Requires ifname.yml.

Parameters:: nics (list[NIC]) – List of ``NIC``s to resolve new classifications for.
Return type:: list[NIC]

crucible.network.ifname.map_nics()

Returns a map of all the network interfaces that the kernel is aware of.

Return type:: list[NIC]

crucible.network.ifname.pcie_redundancy_indexing(nics)

Reindex network interface names to promote PCIe fail-over redundancy where the network is distributed across two switches each connected to their own PCIe device on the host. This means if a PCIe device or a switch fail, the host may maintain connectivity through the other switch and PCIe device.

Note

This does not protect against the edge case where failure on opposite devices occur (e.g. switch0 fails at the same time card1 fails). However, this scenario is very unlikely.

Single PCIe card (no PCIe redundancy):

card0port0 is mgmt0
card1port0 is mgmt1

      ________          __________
      | HOST |          | SWITCH |
      --------          ----------
                        |    _
      ---               |   |_|
      |_                |    _
port0 |_| <-------------|-->|_|
      |_                |    _
port1 |_| <-------------|-->|_|
      |                 |    _
card0 ^                 |   |_|
                        |

Dual PCIe cards (PCIe redundancy):

card0port0 is mgmt0
card1port0 is mgmt1

___________           ________           ___________
| SWITCH 0 |          | HOST |           | SWITCH 1 |
------------          --------           ------------
|  _   _   |                             |   _   _  |
| |_| |_|  |          ---  ---           |  |_| |_| |
|  _   _   |          |_   |_            |   _   _  |
| |_| |_|<-|--port0-->|_|  |_| <--port0--|->|_| |_| |
|  _   _   |          |_   |_            |   _   _  |
| |_| |_|  |          |_|  |_|           |  |_| |_| |
|  _   _   |          |    |             |   _   _  |
| |_| |_|  |     card0^    ^card1        |  |_| |_| |

Parameters:: nics (list[NIC]) – List of NIC devices to check for PCIe redundancy.
Return type:: list[NIC]

crucible.network.ifname.run(skip_rename, skip_udev, merge, overwrite, install_location='/etc/udev/rules.d/')

Renames interfaces on the machine and creates udev rules for them.

Parameters:

skip_rename (bool) – When true, interfaces will not be renamed but only previewed.
skip_udev (bool) – When true, udev rules will not be saved but only previewed.
merge (bool) – When true, new udev rules will merge with any existing ones (uniquely).
overwrite (bool) – When true, new udev rules will overwrite the old udev rules without prompting.
install_location (str) – Where to install udev rules to.

Raises:

UdevError – When udev rules can not be resolved.

Return type:

None

crucible.network.ifname.write_udev_rules(rules, install_location, merge=False, overwrite=False)

Writes the udev rule file.

Parameters:

rules (str) – udev rules to write
install_location (str) – String
merge (bool) – String
overwrite (bool) – String

Return type:

None

Base object for network managers, their configuration, and an interface.

class crucible.network.manager.IPAddr(interface='', cidr='', **kwargs)

Object for IP information.

property ipaddr: IPNetwork: An IP address in CIDR notation.

is_bond()

Whether this is a bond or not.

Return type:: bool

is_bridge()

Whether this is a bridge or not.

Return type:: bool

class crucible.network.manager.Interface(**kwargs)

Object for a system network interface.

property vlan_id: int: The currently assigned VLAN ID.

exception crucible.network.manager.InterfaceError(message): An exception for interface problems.

class crucible.network.manager.SystemNetwork(**kwargs)

Base class for a network manager object.

property dns: list: Prints this objects DNS servers

reload_interface()

Reloads/loads an interface.

Return type:: None

remove_config()

Removes an interface configuration.

Return type:: None

property search: list: Prints this objects search domains.

update_dns()

Updates the system’s static DNS list.

Return type:: None

update_search()

Updates the system’s static DNS list.

Return type:: None

write_config()

Writes a configuration to a file.

Return type:: None

Module for handling sysconfig based network managers.

class crucible.network.sysconfig.Sysconfig(**kwargs)

Main object for all sysconfig derived network managers.

update_dns()

Updates the DNS of the running system.

Return type:: None

update_search()

Updates the search domains of the running system.

Return type:: None

class crucible.network.sysconfig.Wicked(**kwargs)

Abstraction of the SUSE Wicked network manager.

reload_interface(force=False)

Loads new network interface configuration. :type force: bool :param force: Whether to also reload wickedd-nanny.

Return type:: None

remove_config()

Removes a network interface configuration.

Return type:: None

write_config()

Write a string to file, prompting the user to overwrite if the file already exists.

Return type:: None

`storage`

Module for managing bootable devices.

crucible.storage.disk.create_bootable(device, iso, cow)

Runs the bootable media flow.

Parameters:

device (str) – Path of device to make into bootable media.
iso (str) – ISO to make bootable media from.
cow (int) – Size (in MiB) of the copy-on-write partition (default: 50,000 MiB).

Return type:

None

crucible.storage.disk.purge()

Runs the wipe flow.

Return type:: None

`logger`

Logging module.

class crucible.logger.Logger(module_name, log_level=20): Inherits from logging.Logger, configuring custom settings on initialization.

`os`

Module for handling command line calls.

Note

The _CLI object is private, the intended usage is to use run_command.

class crucible.os._CLI(args, shell=False, verbose=False)

An object to abstract the return result from run_command.

_run()

Invoke the loaded command with Popen.

Run the arguments and set the object’s class variables with the results.

Return type:: None

decode(charset)

Decode self.stdout and self.stderr.

Decodes self._stdout and self._stderr with the given charset. :type charset: str :param charset: The character set to decode with.

Return type:: None

property duration: float: The duration of the running command.

property return_code: int: Return code from the command.

property stderr: [<class 'str'>, <class 'bytes'>]: stderr from the command.

property stdout: [<class 'str'>, <class 'bytes'>]: stdout from the command.

crucible.os.chdir(directory, create=False)

Change directories and run a command.

Change into a given directory and returns to the original directory on exit.

Note

This does not wrap the yield in a ‘try’, everything done within the else is the user’s responsibility.

from libcsm.os import chdir

print('doing things in /dir/foo')
with chdir('/some/other/dir'):
    # doing things in /some/other/dir
print('doing more things in /dir/foo')

Parameters:

directory (str) – Where you want to go.
create (bool) – Whether you want the entire tree created or not.

Return type:

None

crucible.os.run_command(args, in_shell=False, silence=False, verbose=False, charset=None)

Run a given command or list of commands by instantiating a CLI object.

from libcsm.os import run_command

result = run_command(['my', 'args'])
print(vars(result))

Parameters:

args ([<class ‘list’>, <class ‘str’>]) – List of arguments to run, can also be a string. If a string,
in_shell (bool) – Whether to use a shell when invoking the command.
silence (bool) – Tells this not to output the command to the log.
verbose (bool) – Tells this to output stdout to the console.
charset (Optional[str]) – Returns the command stdout and stderr as a string instead of bytes, and decoded with the given charset.

Return type:

_CLI

crucible.os.supported_platforms()

Returns whether the running platform is officially supported. This does not cause the program to exit, on the contrary it serves as a helper for other functions to handle behavior.

Return type:: (bool, str)

`vms`

Module for launching VMs.

crucible.vms.reset()

Resets, purges the management VM.

Return type:: None

crucible.vms.start(system_name=None, **kwargs)

Starts the management VM.

Parameters:

system_name (Optional[str]) – The name of the system, a more recognizable handle.
capacity – Capacity (in Gigabytes) for the management VM storage (default 100).
interface – The interface for external networking (default lan0)
ssh_key_path – The path to the SSH key for the VM’s root user (default: /root/.ssh/)
ip_address – The CIDR to assign to the external interface in the management VM
gateway
dns – A comma delimited list of DNS servers to assign to the management VM

Return type:

None

API Reference

cli

install

network

storage

logger

os

vms

`cli`

`install`

`network`

`storage`

`logger`

`os`

`vms`