charmhelpers.core.host

ChecksumError A class derived from Value error to indicate the checksum failed.
CompareHostReleases Provide comparisons of Ubuntu releases.
add_group Add a group to the system
add_new_group
add_to_updatedb_prunepath Adds the specified path to the mlocate’s udpatedb.conf PRUNEPATH list.
add_user_to_group Add a user to a group
adduser Add a user to the system.
arch Return the package architecture as a string.
chage Change user password expiry information
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_distrib_codename Return the codename of the distribution :returns: The codename :rtype: str
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_system_env Get data from system environment as represented in /etc/environment.
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.
install_ca_cert Install the given cert as a trusted CA.
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
modulo_distribution Modulo distribution
mount Mount a filesystem at a particular mountpoint
mounts Get a list of all mounted volumes as [[mountpoint,device],[…]]
owner Returns a tuple containing the username & groupname owning the path.
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 reload fails.
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: 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')

Adds the specified path to the mlocate’s udpatedb.conf PRUNEPATH list.

This method has no effect if the path specified by updatedb_path does not exist or is not a file.

@param path: string the path to add to the updatedb.conf PRUNEPATHS value @param updatedb_path: the path the updatedb.conf file

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.chage(username, lastday=None, expiredate=None, inactive=None, mindays=None, maxdays=None, root=None, warndays=None)

Change user password expiry information

Parameters:
  • username (str) – User to update
  • lastday (str) – Set when password was changed in YYYY-MM-DD format
  • expiredate (str) – Set when user’s account will no longer be accessible in YYYY-MM-DD format. -1 will remove an account expiration date.
  • inactive (str) – Set the number of days of inactivity after a password has expired before the account is locked. -1 will remove an account’s inactivity.
  • mindays (str) – Set the minimum number of days between password changes to MIN_DAYS. 0 indicates the password can be changed anytime.
  • maxdays (str) – Set the maximum number of days during which a password is valid. -1 as MAX_DAYS will remove checking maxdays
  • root (str) – Apply changes in the CHROOT_DIR directory
  • warndays (str) – Set the number of days of warning before a password change is required
Raises:

subprocess.CalledProcessError – if call to chage fails

charmhelpers.core.host.chdir(directory)

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_system_env(key, default=None)

Get data from system environment as represented in /etc/environment.

Parameters:
  • key (str) – Key to look up
  • default (any) – Value to return if key is not found
Returns:

Value for key if found or contents of default parameter

Return type:

any

Raises:

subprocess.CalledProcessError

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.install_ca_cert(ca_cert, name=None)

Install the given cert as a trusted CA.

The name is the stem of the filename where the cert is written, and if not provided, it will default to juju-{charm_name}.

If the cert is empty or None, or is unchanged, nothing is done.

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.modulo_distribution(modulo=3, wait=30, non_zero_wait=False)

Modulo distribution

This helper uses the unit number, a modulo value and a constant wait time to produce a calculated wait time distribution. This is useful in large scale deployments to distribute load during an expensive operation such as service restarts.

If you have 1000 nodes that need to restart 100 at a time 1 minute at a time:

time.wait(modulo_distribution(modulo=100, wait=60)) restart()

If you need restarts to happen serially set modulo to the exact number of nodes and set a high constant wait time:

time.wait(modulo_distribution(modulo=10, wait=120)) restart()

@param modulo: int The modulo number creates the group distribution @param wait: int The constant time wait value @param non_zero_wait: boolean Override unit % modulo == 0,

return modulo * wait. Used to avoid collisions with leader nodes which are often given priority.

@return: int Calculated time to wait for unit operation

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.owner(path)

Returns a tuple containing the username & groupname owning the path.

Parameters:path (str) – the string path to retrieve the ownership
Return tuple(str, str):
 A (username, groupname) tuple containing the name of the user and group owning the path.
Raises:OSError – if the specified path does not exist
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.remove_password_expiry(username, lastday=None, *, expiredate='-1', inactive='-1', mindays='0', maxdays='-1', root=None, warndays=None)

Change user password expiry information

Parameters:
  • username (str) – User to update
  • lastday (str) – Set when password was changed in YYYY-MM-DD format
  • expiredate (str) – Set when user’s account will no longer be accessible in YYYY-MM-DD format. -1 will remove an account expiration date.
  • inactive (str) – Set the number of days of inactivity after a password has expired before the account is locked. -1 will remove an account’s inactivity.
  • mindays (str) – Set the minimum number of days between password changes to MIN_DAYS. 0 indicates the password can be changed anytime.
  • maxdays (str) – Set the maximum number of days during which a password is valid. -1 as MAX_DAYS will remove checking maxdays
  • root (str) – Apply changes in the CHROOT_DIR directory
  • warndays (str) – Set the number of days of warning before a password change is required
Raises:

subprocess.CalledProcessError – if call to chage fails

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, **kwargs)

Control a system service.

Parameters:
  • action – the action to take on the service
  • service_name – the name of the service to perform th action on
  • **kwargs

    additional params to be passed to the service command in the form of key=value.

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

Pause a system service.

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

Parameters:
  • service_name – the name of the service to pause
  • init_dir – path to the upstart init directory
  • initd_dir – path to the sysv init directory
  • **kwargs

    additional parameters to pass to the init system when managing services. These will be passed as key=value parameters to the init system’s commandline. kwargs are ignored for init systems which do not support key=value arguments via the commandline.

charmhelpers.core.host.service_reload(service_name, restart_on_failure=False, **kwargs)

Reload a system service, optionally falling back to restart if reload fails.

The specified service name is managed via the system level init system. Some init systems (e.g. upstart) require that additional arguments be provided in order to directly control service instances whereas other init systems allow for addressing instances of a service directly by name (e.g. systemd).

The kwargs allow for the additional parameters to be passed to underlying init systems for those systems which require/allow for them. For example, the ceph-osd upstart script requires the id parameter to be passed along in order to identify which running daemon should be reloaded. The follow- ing example restarts the ceph-osd service for instance id=4:

service_reload(‘ceph-osd’, id=4)

Parameters:
  • service_name – the name of the service to reload
  • restart_on_failure – boolean indicating whether to fallback to a restart if the reload fails.
  • **kwargs

    additional parameters to pass to the init system when managing services. These will be passed as key=value parameters to the init system’s commandline. kwargs are ignored for init systems not allowing additional parameters via the commandline (systemd).

charmhelpers.core.host.service_restart(service_name, **kwargs)

Restart a system service.

The specified service name is managed via the system level init system. Some init systems (e.g. upstart) require that additional arguments be provided in order to directly control service instances whereas other init systems allow for addressing instances of a service directly by name (e.g. systemd).

The kwargs allow for the additional parameters to be passed to underlying init systems for those systems which require/allow for them. For example, the ceph-osd upstart script requires the id parameter to be passed along in order to identify which running daemon should be restarted. The follow- ing example restarts the ceph-osd service for instance id=4:

service_restart(‘ceph-osd’, id=4)

Parameters:
  • service_name – the name of the service to restart
  • **kwargs

    additional parameters to pass to the init system when managing services. These will be passed as key=value parameters to the init system’s commandline. kwargs are ignored for init systems not allowing additional parameters via the commandline (systemd).

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

Resume a system service.

Reenable starting again at boot. Start the service.

Parameters:
  • service_name – the name of the service to resume
  • init_dir – the path to the init dir
  • dir (initd) – the path to the initd dir
  • **kwargs

    additional parameters to pass to the init system when managing services. These will be passed as key=value parameters to the init system’s commandline. kwargs are ignored for systemd enabled systems.

charmhelpers.core.host.service_running(service_name, **kwargs)

Determine whether a system service is running.

Parameters:
  • service_name – the name of the service
  • **kwargs

    additional args to pass to the service command. This is used to pass additional key=value arguments to the service command line for managing specific instance units (e.g. service ceph-osd status id=2). The kwargs are ignored in systemd services.

charmhelpers.core.host.service_start(service_name, **kwargs)

Start a system service.

The specified service name is managed via the system level init system. Some init systems (e.g. upstart) require that additional arguments be provided in order to directly control service instances whereas other init systems allow for addressing instances of a service directly by name (e.g. systemd).

The kwargs allow for the additional parameters to be passed to underlying init systems for those systems which require/allow for them. For example, the ceph-osd upstart script requires the id parameter to be passed along in order to identify which running daemon should be reloaded. The follow- ing example stops the ceph-osd service for instance id=4:

service_stop(‘ceph-osd’, id=4)

Parameters:
  • service_name – the name of the service to stop
  • **kwargs

    additional parameters to pass to the init system when managing services. These will be passed as key=value parameters to the init system’s commandline. kwargs are ignored for systemd enabled systems.

charmhelpers.core.host.service_stop(service_name, **kwargs)

Stop a system service.

The specified service name is managed via the system level init system. Some init systems (e.g. upstart) require that additional arguments be provided in order to directly control service instances whereas other init systems allow for addressing instances of a service directly by name (e.g. systemd).

The kwargs allow for the additional parameters to be passed to underlying init systems for those systems which require/allow for them. For example, the ceph-osd upstart script requires the id parameter to be passed along in order to identify which running daemon should be reloaded. The follow- ing example stops the ceph-osd service for instance id=4:

service_stop(‘ceph-osd’, id=4)

Parameters:
  • service_name – the name of the service to stop
  • **kwargs

    additional parameters to pass to the init system when managing services. These will be passed as key=value parameters to the init system’s commandline. kwargs are ignored for systemd enabled systems.

charmhelpers.core.host.set_nic_mtu(nic, mtu)

Set the Maximum Transmission Unit (MTU) on a network interface.

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.