ganeti.utils

package documentation

Ganeti utility module.

This module holds functions that can be used in both daemons (all) and the command line scripts.

Module	`algo`	Utility functions with algorithms.
Module	`bitarrays`	Utility functions for managing bitarrays.
Module	`filelock`	Utility functions for file-based locks.
Module	`hash`	Utility functions for hashing.
Module	`io`	Utility functions for I/O.
Module	`livelock`	Lockfiles to prove liveliness
Module	`log`	Utility functions for logging.
Module	`lvm`	Utility functions for LVM.
Module	`mlock`	Wrapper around mlockall(2).
Module	`nodesetup`	Utility functions for manipulating /etc/hosts.
Module	`process`	Utility functions for processes.
Module	`retry`	Utility functions for retrying function calls with a timeout.
Module	`security`	Utility functions for security features of Ganeti.
Module	`storage`	Utility functions for storage.
Module	`tags`	Utility functions for tag related operations
Module	`text`	Utility functions for manipulating or working with text.
Module	`version`	Version utilities.
Module	`wrapper`	Utility functions wrapping other functions.
Module	`x509`	Utility functions for X509.

From __init__.py:

Class	`FdConditionWaiterHelper`	Retry helper for WaitForFdCondition.
Class	`FieldSet`	A simple field set.
Class	`SignalHandler`	Generic signal handler class.
Class	`SignalWakeupFd`	No class docstring; 0/5 instance variable, 4/5 methods documented
Function	`AllDiskOfType`	Checks if the instance has only disks of any of the dev_types.
Function	`AnyDiskOfType`	Checks if the instance has some disks of any types in dev_types.
Function	`BridgeExists`	Check whether the given bridge exists in the system
Function	`EnsureDaemon`	Check for and start daemon if not alive.
Function	`EpochNano`	Return the current timestamp expressed as number of nanoseconds since the unix epoch
Function	`FindMatch`	Tries to find an item in a dictionary matching a name.
Function	`FirstFree`	Returns the first non-existing integer from seq.
Function	`ForceDictType`	Force the values of a dict to have certain types.
Function	`GetDiskTemplate`	Gives a summary disk template from disks.
Function	`GetDiskTemplateString`	Gives a summary disk template from disk devtypes.
Function	`GetHomeDir`	Try to get the homedir of the given user.
Function	`GetMounts`	Returns the list of mounted filesystems.
Function	`ListVolumeGroups`	List volume groups and their size
Function	`MergeTime`	Merges a tuple into time as a floating point number.
Function	`ParseCpuMask`	Parse a CPU mask definition and return the list of CPU IDs.
Function	`ParseMultiCpuMask`	Parse a multiple CPU mask definition and return the list of CPU IDs.
Function	`SendFds`	Sends a set of file descriptors over a socket using sendmsg(2)
Function	`SignalHandled`	Signal Handled decoration.
Function	`SingleWaitForFdCondition`	Waits for a condition to occur on the socket.
Function	`SplitTime`	Splits time as floating point number into a tuple.
Function	`StopDaemon`	Stop daemon
Function	`TimeoutExpired`	Checks whether a timeout has expired.
Function	`TryConvert`	Try to convert a value ignoring errors.
Function	`ValidateDeviceNames`	Validate instance device names.
Function	`ValidateServiceName`	Validate the given service name.
Function	`VerifyDictOptions`	Verify a dict has only keys set which also are in the defaults dict.
Function	`WaitForFdCondition`	Waits for a condition to occur on the socket.
Constant	`UUID_RE`	Undocumented
Function	`_ComputeMissingKeys`	Helper functions to compute which keys a invalid.
Constant	`_VALID_SERVICE_NAME_RE`	Undocumented

_VALID_SERVICE_NAME_RE = ¶

Undocumented

Value

re.compile(r'^[-_\.a-zA-Z0-9]{1,128}$')

UUID_RE = ¶

Undocumented

Value

re.compile(constants.UUID_REGEX)

def ForceDictType(target, key_types, allowed_values=None): ¶

Force the values of a dict to have certain types.

Parameters
target:dict	the dict to update
key_types:dict	dict mapping target dict keys to types in constants.ENFORCEABLE_TYPES
allowed_values:list	list of specially allowed values

def ValidateServiceName(name): ¶

Validate the given service name.

Parameters
name:number or string	Service name or port specification

def _ComputeMissingKeys(key_path, options, defaults): ¶

Helper functions to compute which keys a invalid.

Parameters
key_path	The current key path (if any)
options	The user provided options
defaults	The default dictionary
Returns
A list of invalid keys

def VerifyDictOptions(options, defaults): ¶

Verify a dict has only keys set which also are in the defaults dict.

Parameters
options	The user provided options
defaults	The default dictionary
Raises
`error.OpPrereqError`	If one of the keys is not supported

def ListVolumeGroups(): ¶

List volume groups and their size

Returns
dict	Dictionary with keys volume name and values the size of the volume

def BridgeExists(bridge): ¶

Check whether the given bridge exists in the system

Parameters
bridge:str	the bridge name to check
Returns
boolean	True if it does

def TryConvert(fn, val): ¶

Try to convert a value ignoring errors.

This function tries to apply function fn to val. If no ValueError or TypeError exceptions are raised, it will return the result, else it will return the original value. Any other exceptions are propagated to the caller.

Parameters
fn:callable	function to apply to the value
val	the value to be converted
Returns
The converted value if the conversion was successful, otherwise the original value.

def ParseCpuMask(cpu_mask): ¶

Parse a CPU mask definition and return the list of CPU IDs.

CPU mask format: comma-separated list of CPU IDs or dash-separated ID ranges Example: "0-2,5" -> "0,1,2,5"

Parameters
cpu_mask:str	CPU mask definition
Returns
list of int	list of CPU IDs

def ParseMultiCpuMask(cpu_mask): ¶

Parse a multiple CPU mask definition and return the list of CPU IDs.

CPU mask format: colon-separated list of comma-separated list of CPU IDs or dash-separated ID ranges, with optional "all" as CPU value Example: "0-2,5:all:1,5,6:2" -> [ [ 0,1,2,5 ], [ -1 ], [ 1, 5, 6 ], [ 2 ] ]

Parameters
cpu_mask:str	multiple CPU mask definition
Returns
list of lists of int	list of lists of CPU IDs

def GetHomeDir(user, default=None): ¶

Try to get the homedir of the given user.

The user can be passed either as a string (denoting the name) or as an integer (denoting the user id). If the user is not found, the default argument is returned, which defaults to None.

def FirstFree(seq, base=0): ¶

Returns the first non-existing integer from seq.

The seq argument should be a sorted list of positive integers. The first time the index of an element is smaller than the element value, the index will be returned.

The base argument is used to start at a different offset, i.e. [3, 4, 6] with offset=3 will return 5.

Example: [0, 1, 3] will return 2.

Parameters
seq:sequence	the sequence to be analyzed.
base:int	use this value as the base index of the sequence
Returns
int	the first non-used index in the sequence

def SingleWaitForFdCondition(fdobj, event, timeout): ¶

Waits for a condition to occur on the socket.

Immediately returns at the first interruption.

Parameters
fdobj:integer or object supporting a fileno() method	entity to wait for events on
event:integer	ORed condition (see select module)
timeout:float or None	Timeout in seconds
Returns
int or None	None for timeout, otherwise occured conditions

def WaitForFdCondition(fdobj, event, timeout): ¶

Waits for a condition to occur on the socket.

Retries until the timeout is expired, even if interrupted.

Parameters
fdobj:integer or object supporting a fileno() method	entity to wait for events on
event:integer	ORed condition (see select module)
timeout:float or None	Timeout in seconds
Returns
int or None	None for timeout, otherwise occured conditions

def EnsureDaemon(name): ¶

Check for and start daemon if not alive.

Parameters
name:string	daemon name
Returns
bool	'True' if daemon successfully started, 'False' otherwise

def StopDaemon(name): ¶

Stop daemon

Parameters
name:string	daemon name
Returns
bool	'True' if daemon successfully stopped, 'False' otherwise

def SplitTime(value): ¶

Splits time as floating point number into a tuple.

Parameters
value:int or float	Time in seconds
Returns
Tuple containing (seconds, microseconds)

def MergeTime(timetuple): ¶

Merges a tuple into time as a floating point number.

Parameters
timetuple:tuple	Time as tuple, (seconds, microseconds)
Returns
Time as a floating point number expressed in seconds

def EpochNano(): ¶

Return the current timestamp expressed as number of nanoseconds since the unix epoch

Returns
nanoseconds since the Unix epoch

def FindMatch(data, name): ¶

Tries to find an item in a dictionary matching a name.

Callers have to ensure the data names aren't contradictory (e.g. a regexp that matches a string). If the name isn't a direct key, all regular expression objects in the dictionary are matched against it.

Parameters
data:dict	Dictionary containing data
name:string	Name to look for
Returns
tuple; (value in dictionary, matched groups as list)	Undocumented

def GetMounts(filename=constants.PROC_MOUNTS): ¶

Returns the list of mounted filesystems.

This function is Linux-specific.

Parameters
filename	path of mounts file (/proc/mounts by default)
Returns
list of tuples	list of mount entries (device, mountpoint, fstype, options)

def SignalHandled(signums): ¶

Signal Handled decoration.

This special decorator installs a signal handler and then calls the target function. The function must accept a 'signal_handlers' keyword argument, which will contain a dict indexed by signal number, with SignalHandler objects as values.

The decorator can be safely stacked with iself, to handle multiple signals with different handlers.

Parameters
signums:list	signals to intercept

def TimeoutExpired(epoch, timeout, _time_fn=time.time): ¶

Checks whether a timeout has expired.

def ValidateDeviceNames(kind, container): ¶

Validate instance device names.

Check that a device container contains only unique and valid names.

Parameters
kind:string	One-word item description
container:list	Container containing the devices

def AllDiskOfType(disks_info, dev_types): ¶

Checks if the instance has only disks of any of the dev_types.

Parameters
disks_info:list of `Disk`	all the disks of the instance.
dev_types:list of disk templates	the disk type required.
Returns
bool	True iff the instance only has disks of type dev_type.

def AnyDiskOfType(disks_info, dev_types): ¶

Checks if the instance has some disks of any types in dev_types.

Parameters
disks_info:list of `Disk`	all the disks of the instance.
dev_types:list of disk template	the disk type required.
Returns
bool	True if the instance has disks of type dev_types or the instance has no disks and the dev_types allow DT_DISKLESS.

def GetDiskTemplateString(disk_types): ¶

Gives a summary disk template from disk devtypes.

Parameters
disk_types:list of string	all the dev_types of the instance. @rtype disk template @returns the summarized disk template of the disk types.

def GetDiskTemplate(disks_info): ¶

Gives a summary disk template from disks.

Parameters
disks_info:list of `Disk`	all the disks of the instance. @rtype disk template @returns the summarized disk template of the disk types.

def SendFds(sock, data, fds): ¶

Sends a set of file descriptors over a socket using sendmsg(2)

Parameters
sock:socket.socket	the socket over which the fds will be sent
data:bytes	actual data for the sendmsg(2) call
fds:list of file descriptors or file-like objects with fileno() methods	the file descriptors to send