ganeti.uidpool

module documentation

User-id pool related functions.

The user-id pool is cluster-wide configuration option. It is stored as a list of user-id ranges. This module contains functions used for manipulating the user-id pool parameter and for requesting/returning user-ids from the pool.

Class	`LockedUid`	Class representing a locked user-id in the uid-pool.
Function	`AddToUidPool`	Add a list of user-ids/user-id ranges to a user-id pool.
Function	`CheckUidPool`	Sanity check user-id pool range definition values.
Function	`ExecWithUnusedUid`	Execute a callable and provide an unused user-id in its kwargs.
Function	`ExpandUidPool`	Expands a uid-pool definition to a list of uids.
Function	`FormatUidPool`	Convert the internal representation of the user-id pool into a string.
Function	`ParseUidPool`	Parse a user-id pool definition.
Function	`ReleaseUid`	This should be called when the given user-id is no longer in use.
Function	`RemoveFromUidPool`	Remove a list of user-ids/user-id ranges from a user-id pool.
Function	`RequestUnusedUid`	Tries to find an unused uid from the uid-pool, locks it and returns it.
Function	`_FormatUidRange`	Convert a user-id range definition into a string.
Function	`_IsUidUsed`	Check if there is any process in the system running with the given user-id

def AddToUidPool(uid_pool, add_uids): ¶

Add a list of user-ids/user-id ranges to a user-id pool.

Parameters
uid_pool	a user-id pool (list of integer tuples)
add_uids	user-id ranges to be added to the pool (list of integer tuples)

def CheckUidPool(uid_pool): ¶

Sanity check user-id pool range definition values.

Parameters
uid_pool	a list of integer pairs (lower, higher range boundaries)

def ExecWithUnusedUid(fn, all_uids, *args, **kwargs): ¶

Execute a callable and provide an unused user-id in its kwargs.

This wrapper function provides a simple way to handle the requesting, unlocking and releasing a user-id. "fn" is called by passing a "uid" keyword argument that contains an unused user-id (as an integer) selected from the set of user-ids passed in all_uids. If there is an error while executing "fn", the user-id is returned to the pool.

Parameters
fn	a callable that accepts a keyword argument called "uid"
all_uids:a set of integers	a set containing all user-ids in the user-id pool
*args	Undocumented
**kwargs	Undocumented

def ExpandUidPool(uid_pool): ¶

Expands a uid-pool definition to a list of uids.

Parameters
uid_pool	a list of integer pairs (lower, higher range boundaries)
Returns
a list of integers

def FormatUidPool(uid_pool, separator=None): ¶

Convert the internal representation of the user-id pool into a string.

The output format is also accepted by ParseUidPool()

Parameters
uid_pool	a list of integer pairs representing UID ranges
separator	the separator character between the uids/uid-ranges. Defaults to ", ".
Returns
a string with the formatted results

def ParseUidPool(value, separator=None): ¶

Parse a user-id pool definition.

Parameters
value	string representation of the user-id pool. The accepted input format is a list of integer ranges. The boundaries are inclusive. Example: '1000-5000,8000,9000-9010'.
separator	the separator character between the uids/uid-ranges. Defaults to a comma.
Returns
a list of integer pairs (lower, higher range boundaries)

def ReleaseUid(uid): ¶

This should be called when the given user-id is no longer in use.

Parameters
uid:LockedUid or integer	the uid to release back to the pool

def RemoveFromUidPool(uid_pool, remove_uids): ¶

Remove a list of user-ids/user-id ranges from a user-id pool.

Parameters
uid_pool	a user-id pool (list of integer tuples)
remove_uids	user-id ranges to be removed from the pool (list of integer tuples)

def RequestUnusedUid(all_uids): ¶

Tries to find an unused uid from the uid-pool, locks it and returns it.

Usage pattern

When starting a process:

    from ganeti import ssconf
    from ganeti import uidpool

    # Get list of all user-ids in the uid-pool from ssconf
    ss = ssconf.SimpleStore()
    uid_pool = uidpool.ParseUidPool(ss.GetUidPool(), separator="\n")
    all_uids = set(uidpool.ExpandUidPool(uid_pool))

    uid = uidpool.RequestUnusedUid(all_uids)
    try:
      <start a process with the UID>
      # Once the process is started, we can release the file lock
      uid.Unlock()
    except ... as err:
      # Return the UID to the pool
      uidpool.ReleaseUid(uid)

Stopping a process:

    from ganeti import uidpool

    uid = <get the UID the process is running under>
    <stop the process>
    uidpool.ReleaseUid(uid)

Parameters
all_uids:set of integers	a set containing all the user-ids in the user-id pool
Returns
a LockedUid object representing the unused uid. It's the caller's responsibility to unlock the uid once an instance is started with this uid.

def _FormatUidRange(lower, higher): ¶

Convert a user-id range definition into a string.

def _IsUidUsed(uid): ¶

Check if there is any process in the system running with the given user-id

Parameters
uid:integer	the user-id to be checked.