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 tojuju-{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.
-
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.