charmhelpers.core.host¶

`ChecksumError`	A class derived from Value error to indicate the checksum failed.
`add_group`	Add a group to the system
`add_new_group`
`add_to_updatedb_prunepath`
`add_user_to_group`	Add a user to a group
`adduser`	Add a user to the system.
`chdir`	Change the current working directory to a different directory for a code block and return the previous directory after the block exits.
`check_hash`	Validate a file using a cryptographic checksum.
`chownr`	Recursively change user and group ownership of files and directories in given path.
`cmp_pkgrevno`	Compare supplied revno with the revno of the installed package.
`file_hash`	Generate a hash checksum of the contents of ‘path’ or None if not found.
`fstab_add`	Adds the given device entry to the /etc/fstab file
`fstab_mount`	Mount filesystem using fstab
`fstab_remove`	Remove the given mountpoint entry from /etc/fstab
`get_bond_master`	Returns bond master if interface is bond slave otherwise None.
`get_nic_hwaddr`	Return the Media Access Control (MAC) for a network interface.
`get_nic_mtu`	Return the Maximum Transmission Unit (MTU) for a network interface.
`get_total_ram`	The total amount of system RAM in bytes.
`gid_exists`	Check if a gid exists
`group_exists`	Check if a group exists
`init_is_systemd`	Return True if the host system uses systemd, False otherwise.
`is_container`	Determine whether unit is running in a container
`is_phy_iface`	Returns True if interface is not virtual, otherwise False.
`lchownr`	Recursively change user and group ownership of files and directories in a given path, not following symbolic links.
`list_nics`	Return a list of nics of given type(s)
`lsb_release`	Return /etc/lsb-release in a dict
`mkdir`	Create a directory
`mount`	Mount a filesystem at a particular mountpoint
`mounts`	Get a list of all mounted volumes as [[mountpoint,device],[...]]
`path_hash`	Generate a hash checksum of all files matching ‘path’.
`pwgen`	Generate a random pasword.
`restart_on_change`	Restart services based on configuration files changing
`restart_on_change_helper`	Helper function to perform the restart_on_change function.
`rsync`	Replicate the contents of a path
`service`	Control a system service
`service_available`	Determine whether a system service is available
`service_pause`	Pause a system service.
`service_reload`	Reload a system service, optionally falling back to restart if
`service_restart`	Restart a system service
`service_resume`	Resume a system service.
`service_running`	Determine whether a system service is running
`service_start`	Start a system service
`service_stop`	Stop a system service
`set_nic_mtu`	Set the Maximum Transmission Unit (MTU) on a network interface.
`symlink`	Create a symbolic link
`uid_exists`	Check if a uid exists
`umount`	Unmount a filesystem
`updatedb`
`user_exists`	Check if a user exists
`write_file`	Create or overwrite a file with the contents of a byte string.

Tools for working with the host system

exception charmhelpers.core.host.ChecksumError¶

Bases: exceptions.ValueError

A class derived from Value error to indicate the checksum failed.

charmhelpers.core.host.add_group(group_name, system_group=False, gid=None)¶

Add a group to the system

Will log but otherwise succeed if the group already exists.

Parameters:	group_name (str) – group to create system_group (bool) – Create system group gid (int) – GID for user being created
Returns:	The password database entry struct, as returned by grp.getgrnam

charmhelpers.core.host.add_to_updatedb_prunepath(path, updatedb_path='/etc/updatedb.conf')¶

charmhelpers.core.host.add_user_to_group(username, group)¶: Add a user to a group

charmhelpers.core.host.adduser(username, password=None, shell='/bin/bash', system_user=False, primary_group=None, secondary_groups=None, uid=None, home_dir=None)¶

Add a user to the system.

Will log but otherwise succeed if the user already exists.

Parameters:

username (str) – Username to create
password (str) – Password for user; if None, create a system user
shell (str) – The default shell for the user
system_user (bool) – Whether to create a login or system user
primary_group (str) – Primary group for user; defaults to username
secondary_groups (list) – Optional list of additional groups
uid (int) – UID for user being created
home_dir (str) – Home directory for user

Returns:

The password database entry struct, as returned by pwd.getpwnam

charmhelpers.core.host.chdir(*args, **kwds)¶

Change the current working directory to a different directory for a code block and return the previous directory after the block exits. Useful to run commands from a specificed directory.

Parameters:	directory (str) – The directory path to change to for this context.

charmhelpers.core.host.check_hash(path, checksum, hash_type='md5')¶

Validate a file using a cryptographic checksum.

Parameters:	checksum (str) – Value of the checksum used to validate the file. hash_type (str) – Hash algorithm used to generate checksum. Can be any hash alrgorithm supported by `hashlib`, such as md5, sha1, sha256, sha512, etc.
Raises:	ChecksumError – If the file fails the checksum

charmhelpers.core.host.chownr(path, owner, group, follow_links=True, chowntopdir=False)¶

Recursively change user and group ownership of files and directories in given path. Doesn’t chown path itself by default, only its children.

Parameters:	path (str) – The string path to start changing ownership. owner (str) – The owner string to use when looking up the uid. group (str) – The group string to use when looking up the gid. follow_links (bool) – Also follow and chown links if True chowntopdir (bool) – Also chown path itself if True

charmhelpers.core.host.file_hash(path, hash_type='md5')¶

Generate a hash checksum of the contents of ‘path’ or None if not found.

Parameters:	hash_type (str) – Any hash alrgorithm supported by `hashlib`, such as md5, sha1, sha256, sha512, etc.

charmhelpers.core.host.fstab_add(dev, mp, fs, options=None)¶: Adds the given device entry to the /etc/fstab file

charmhelpers.core.host.fstab_mount(mountpoint)¶: Mount filesystem using fstab

charmhelpers.core.host.fstab_remove(mp)¶: Remove the given mountpoint entry from /etc/fstab

charmhelpers.core.host.get_bond_master(interface)¶

Returns bond master if interface is bond slave otherwise None.

NOTE: the provided interface is expected to be physical

charmhelpers.core.host.get_nic_hwaddr(nic)¶: Return the Media Access Control (MAC) for a network interface.

charmhelpers.core.host.get_nic_mtu(nic)¶: Return the Maximum Transmission Unit (MTU) for a network interface.

charmhelpers.core.host.get_total_ram()¶

The total amount of system RAM in bytes.

This is what is reported by the OS, and may be overcommitted when there are multiple containers hosted on the same machine.

charmhelpers.core.host.gid_exists(gid)¶: Check if a gid exists

charmhelpers.core.host.group_exists(groupname)¶: Check if a group exists

charmhelpers.core.host.init_is_systemd()¶: Return True if the host system uses systemd, False otherwise.

charmhelpers.core.host.is_container()¶

Determine whether unit is running in a container

@return: boolean indicating if unit is in a container

charmhelpers.core.host.is_phy_iface(interface)¶: Returns True if interface is not virtual, otherwise False.

charmhelpers.core.host.lchownr(path, owner, group)¶

Recursively change user and group ownership of files and directories in a given path, not following symbolic links. See the documentation for ‘os.lchown’ for more information.

Parameters:	path (str) – The string path to start changing ownership. owner (str) – The owner string to use when looking up the uid. group (str) – The group string to use when looking up the gid.

charmhelpers.core.host.list_nics(nic_type=None)¶: Return a list of nics of given type(s)

charmhelpers.core.host.mkdir(path, owner='root', group='root', perms=365, force=False)¶: Create a directory

charmhelpers.core.host.mount(device, mountpoint, options=None, persist=False, filesystem='ext3')¶: Mount a filesystem at a particular mountpoint

charmhelpers.core.host.mounts()¶: Get a list of all mounted volumes as [[mountpoint,device],[...]]

charmhelpers.core.host.path_hash(path)¶

Generate a hash checksum of all files matching ‘path’. Standard wildcards like ‘*’ and ‘?’ are supported, see documentation for the ‘glob’ module for more information.

Returns:	dict: A { filename: hash } dictionary for all matched files. Empty if none found.

charmhelpers.core.host.pwgen(length=None)¶: Generate a random pasword.

charmhelpers.core.host.restart_on_change(restart_map, stopstart=False, restart_functions=None)¶

Restart services based on configuration files changing

This function is used a decorator, for example:

@restart_on_change({
    '/etc/ceph/ceph.conf': [ 'cinder-api', 'cinder-volume' ]
    '/etc/apache/sites-enabled/*': [ 'apache2' ]
    })
def config_changed():
    pass  # your code here

In this example, the cinder-api and cinder-volume services would be restarted if /etc/ceph/ceph.conf is changed by the ceph_client_changed function. The apache2 service would be restarted if any file matching the pattern got changed, created or removed. Standard wildcards are supported, see documentation for the ‘glob’ module for more information.

@param restart_map: {path_file_name: [service_name, ...] @param stopstart: DEFAULT false; whether to stop, start OR restart @param restart_functions: nonstandard functions to use to restart services

{svc: func, ...}

@returns result from decorated function

charmhelpers.core.host.restart_on_change_helper(lambda_f, restart_map, stopstart=False, restart_functions=None)¶

Helper function to perform the restart_on_change function.

This is provided for decorators to restart services if files described in the restart_map have changed after an invocation of lambda_f().

@param lambda_f: function to call. @param restart_map: {file: [service, ...]} @param stopstart: whether to stop, start or restart a service @param restart_functions: nonstandard functions to use to restart services

{svc: func, ...}

@returns result of lambda_f()

charmhelpers.core.host.rsync(from_path, to_path, flags='-r', options=None, timeout=None)¶: Replicate the contents of a path

charmhelpers.core.host.service(action, service_name)¶: Control a system service

charmhelpers.core.host.service_pause(service_name, init_dir='/etc/init', initd_dir='/etc/init.d')¶

Pause a system service.

Stop it, and prevent it from starting again at boot.

charmhelpers.core.host.service_reload(service_name, restart_on_failure=False)¶: Reload a system service, optionally falling back to restart if reload fails

charmhelpers.core.host.service_restart(service_name)¶: Restart a system service

charmhelpers.core.host.service_resume(service_name, init_dir='/etc/init', initd_dir='/etc/init.d')¶

Resume a system service.

Reenable starting again at boot. Start the service

charmhelpers.core.host.service_running(service_name)¶: Determine whether a system service is running

charmhelpers.core.host.service_start(service_name)¶: Start a system service

charmhelpers.core.host.service_stop(service_name)¶: Stop a system service

charmhelpers.core.host.set_nic_mtu(nic, mtu)¶: Set the Maximum Transmission Unit (MTU) on a network interface.

charmhelpers.core.host.symlink(source, destination)¶: Create a symbolic link

charmhelpers.core.host.uid_exists(uid)¶: Check if a uid exists

charmhelpers.core.host.umount(mountpoint, persist=False)¶: Unmount a filesystem

charmhelpers.core.host.updatedb(updatedb_text, new_path)¶

charmhelpers.core.host.user_exists(username)¶: Check if a user exists

charmhelpers.core.host.write_file(path, content, owner='root', group='root', perms=292)¶: Create or overwrite a file with the contents of a byte string.