Package ganeti :: Module uidpool
[hide private]
[frames] | no frames]

Module uidpool

source code

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)
Convert a user-id range definition into a string.
source code
 
FormatUidPool(uid_pool, separator=None)
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, utils, pathutils


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)

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

  1. 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)
    
  2. 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