Package ganeti :: Module uidpool

Module uidpool

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.

Classes

[hide private]

LockedUid
Class representing a locked user-id in the uid-pool.

Functions

[hide private]

ParseUidPool(value, separator=None)
Parse a user-id pool definition.

source code

AddToUidPool(uid_pool, add_uids)
Add a list of user-ids/user-id ranges to a user-id pool.

source code

RemoveFromUidPool(uid_pool, remove_uids)
Remove a list of user-ids/user-id ranges from a user-id pool.

source code

_FormatUidRange(lower, higher, roman=False)
Convert a user-id range definition into a string.

source code

FormatUidPool(uid_pool, separator=None, roman=False)
Convert the internal representation of the user-id pool into a string.

source code

CheckUidPool(uid_pool)
Sanity check user-id pool range definition values.

source code

ExpandUidPool(uid_pool)
Expands a uid-pool definition to a list of uids.

source code

_IsUidUsed(uid)
Check if there is any process in the system running with the given user-id

source code

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

source code

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

source code

ExecWithUnusedUid(fn, all_uids, *args, **kwargs)
Execute a callable and provide an unused user-id in its kwargs.

source code

Imports: errno, logging, os, random, errors, constants, compat, utils

Function Details

[hide private]

ParseUidPool(value, separator=None)

source code

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)

AddToUidPool(uid_pool, add_uids)

source code

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)

RemoveFromUidPool(uid_pool, remove_uids)

source code

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)

FormatUidPool(uid_pool, separator=None, roman=False)

source code

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

CheckUidPool(uid_pool)

source code

Sanity check user-id pool range definition values.

Parameters:

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

ExpandUidPool(uid_pool)

source code

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

_IsUidUsed(uid)

source code

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

Parameters:

uid (integer) - the user-id to be checked.

RequestUnusedUid(all_uids)

source code

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 ..., 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.

ReleaseUid(uid)

source code

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

ExecWithUnusedUid(fn, all_uids, *args, **kwargs)

source code

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