ldap

Tools to interface with the ACCRE internal and Vanderbilt LDAP servers including a client classes and a cli entry point.

class accre.ldap.ACCRELDAP(caching=False, ldap_id=None, auth=None, rootdn=False)[source]

Bases: BaseLDAP

Client for the ACCRE internal LDAP Service.

In order to improve performance when checking multiple VUNetID entries, instantiate the client with caching=True to avoid repeatedly fetching the same ID.

add_group(*, name, gid, passwd='', description='', members=())[source]

Add a new posix group to the directory. The group name, and gid are required. The password, description, and members will default to being unset in the directory.

If an optional attribute is given in as the empty string, then that attribute will not be set in the new LDAP entity, except for the members attribute which will not be set if if is an empty iterable.

Parameters:

  • name (str) – the name of the new group (required)

  • gid (int) – the numeric group ID

  • passwd (str) – the group password hash (usually unset)

  • members (list(str)) – member accounts of the group

Returns:

True on success, False on failure

Return type:

bool

add_group_member(group, user)[source]

Make the specified group a secondary group for the specified user.

Parameters:

  • group (str) – group to add the user to

  • user (str) – user to add to the group

Returns:

True on success

Return type:

bool

add_local_group(name)[source]

Add a user group record from a local group specified in /etc/group.

Parameters:

name (str) – Group name to import to LDAP from the local files

Returns:

True on success, False on failure

Return type:

bool

add_local_user(username)[source]

Add a user account record from a local user specified in /etc/passwd and /etc/shadow. This method requires that you are root.

Parameters:

username (str) – Username to import to LDAP from the local files

Returns:

True on success, False on failure

Return type:

bool

add_robot(*, cn, sn, vunetid, uid, mail, title, testrobot=False, legacy_uid=False)[source]

Add a new robot to the directory. This record will be used as an equivalent to VandyLDAP for verifying that the robot has a valid “vunetid”. A corresponding user record must be created to give a robot access to the cluster.

The assigned vunetid must be in the valid robot range (9200-9999) and must not conflict with an existing robot user, unless it is a test user and in the test robot range (9100-9199)

Parameters:

  • cn (str) – The full name or descriptive name of the robot

  • sn (str) – The surname or shorter name of the robot

  • vunetid (str) – The vunetid-equivalent (posix username) for the robot.

  • uid (int) – Numerical posix uid for the robot, must be in the valid robot UID range (9100-9999)

  • mail (str) – Vanderilt-equivalent email address for the robot

  • title (str) – Title to indicate general purpose of the robot, for example “testuser” for a test user

  • testrobot (bool) – If true, this robot is a test robot, must be in the test robot UID range (9100-9199) and may have a UID conflict

  • legacy_uid (bool) – If true, allow for a robot outside of the valid robot UID range. The new robot UID must still not conflict with other robots. Use with caution as this may shadow actual VUNetID UIDs.

Returns:

True on success, False on failure

Return type:

bool

add_user(*, username, passwd, uid, gid=None, homedir=None, shell=None, fullname='', lastpwchange=None, shadowmin=0, shadowmax=99999, shadowwarn=7)[source]

Add a new user account to the directory. The username, password, and uid are required. The gid will default to the uid, the shell to bash, the home directory to /home/<username>, and the last password change to the current date if not set.

If an optional attribute is given in as the empty string, then that attribute will not be set in the new LDAP entity.

Parameters:

  • username (str) – the username of the new user (required)

  • passwd (str) – the LDAP-formatted passwd hash for the new user (required)

  • uid (int) – the numeric UID of the new user (required)

  • gid (int) – the numeric group ID of the new user

  • shell (str) – the shell to use for the ner user

  • fullname (str) – the real (full) name of the new user

  • lastpwchange (int) – the number of days since the epoch of the last password change

  • shadowmin (int) – minimum number of days before the user password can be changed

  • shadowmax (int) – number of days since the last change before a user password expires

  • shadowwarn (int) – number of days before expiring that a user will be warned to change their password

Returns:

True on success, False on failure

Return type:

bool

change_user_group(username, group)[source]

Sets the primary group of the user to the numeric GID of the given group name.

Parameters:

  • username (str) – the username to receive a primary group change

  • group (str) – the name of the new primary group

Returns:

True on success, False on failure

Return type:

bool

change_user_password(username, new_password)[source]

Sets the password of the user to the value new_password. Note that this is the actual un-hashed password. The password is hashed using SHA512 with a salt of length 16. No strength checking is performed by this function. The shadowLastChange is also updated to the current date for the user.

Parameters:

  • username (str) – the username to receive a password change

  • new_password (str) – the unhashed value of the new password

Returns:

True on success, False on failure

Return type:

bool

change_user_shell(username, shell)[source]

Sets the login shell of the user to the value new_password. Note that this is the full path to the shell executable file.

Parameters:

  • username (str) – the username to receive a password change

  • shell (str) – the path to the new shell executable

Returns:

True on success, False on failure

Return type:

bool

delete_group(name)[source]

Remove the specified posix group from the directory.

Parameters:

name (str) – the group name to be removed

Returns:

True on success, False on failure

Return type:

bool

delete_robot(cn)[source]

Remove the specified robot record from the directory.

Parameters:

cn (str) – the full/descriptive name of the robot to be removed

Returns:

True on success, False on failure

Return type:

bool

delete_user(username)[source]

Remove the specified user account from the directory.

Parameters:

username (str) – the username to be removed

Returns:

True on success, False on failure

Return type:

bool

exists(accreid)[source]

Check if the given ACCRE ID exists on the server

Parameters:

accreid (str) – the ACCRE ID to be checked

Returns:

True if the ACCRE ID exists

Return type:

bool

group_exists(accregroup)[source]

Check if the given ACCRE group exists on the server

Parameters:

accregroup (str) – the ACCRE group name to be checked

Returns:

True if the ACCRE group exists

Return type:

bool

group_membership()[source]

Return a dict keyed by group names with a list of members as the value for each group.

Returns:

Membership of all groups

Return type:

dict(str,list(str))

is_robot_locked(robotid)[source]

Return true if the robot is locked/inactive. A robot is considered locked if it has “locked” in its titles.

Parameters:

robotid (str) – vunetid-equivalent for the robot

Returns:

True if locked/inactive

Return type:

bool

list_group_gids()[source]

Return a list of group names and corresponding numeric gids as tuples.

Returns:

All names and gids of posix groups in the directory

Return type:

list(tuple(str, int))

list_groups()[source]

Return a list of group names of all posix groups currently in the directory.

Returns:

All names of posix groups in the directory

Return type:

list(str)

list_robots(active=False)[source]

Return a list of usernames of all registered robots currently in the directory.

Parameters:

active (bool) – Only list active robots if set to true, where a robot is defined as active if it has a title of ‘locked’

Returns:

All usernames of robots in the directory

Return type:

list(str)

list_users(active=False)[source]

Return a list of usernames of all cluster users currently in the directory.

Parameters:

active (bool) – Only list active users if set to true, where a user is defined as active if its shell is not /bin/false or /sbin/nologin

Returns:

All usernames of cluster users in the directory

Return type:

list(str)

posixgroup(accregroup)[source]

Return a PosixGroup named tuple with the group information equivalent to an /etc/group entry for the given ACCRE group

Parameters:

accregroup (str) – the ACCRE group to be checked

Returns:

Posix group information for the user

Return type:

accre.util.PosixGroup

posixuser(accreid)[source]

Return a PosixUser named tuple with the user information equivalent to an /etc/passwd entry for the given ACCRE ID

Parameters:

accreid (str) – the ACCRE ID to be checked

Returns:

Posix user information for the user

Return type:

accre.util.PosixUser

remove_group_member(group, user)[source]

Remove the specified user from the specified group. Note: this method does not work for the primary group of a user.

Parameters:

  • group (str) – group to remove the user from

  • user (str) – user to remove from the group

Returns:

True on success

Return type:

bool

robot_exists(robotid)[source]

Check if the given vunetid-equivalent exists on the server

Parameters:

externalid (str) – the vunetid-equivalent to be checked

Returns:

True if the vunetid-equivalent exists

Return type:

bool

robot_info(robotid)[source]

Return a dictionary of information about the specified robot vunetid-equivalent including the full name (fullname), uid (uid), Vanderbilt-equivalent email (vanderbilt_email), and titles, where titles indicate the purpose(s) of the robot and if it is a locked account.

Parameters:

robotid (str) – the vunetid-equivalent to be checked

Returns:

fullname, uid, vanderbilt_email, and titles

Return type:

dict

set_robot_lock(cn, value)[source]

Set the robot account lock to True or False for the given full or descriptive name of the account. This is equivelent to a VUNetID being locked in the VUIT LDAP.

Parameters:

  • cn (str) – Full or descriptive name for the robot to (un)lock

  • value (bool) – Locked (True) or unlocked (False)

Returns:

True on success, False on failure

Return type:

bool

shadowuser(accreid)[source]

Return a ShadowUser named tuple with the user information equivalent to an /etc/shadow entry for the given ACCRE ID. Note that only the most privileged LDAP users will be able to access the actual password hash. Also note that inactive, expire, and res are unused fields and will be set to empty strings.

Parameters:

accreid (str) – the ACCRE ID to be checked

Returns:

Shadow user information for the user

Return type:

accre.util.ShadowUser

user_record(vunetid)[source]

dump record of an accre user into a dictionary with all LDAP attributes

Parameters:

vunetid (str) – ACCRE user username/VUNetID

Returns:

Dictionary with full LDAP record information

class accre.ldap.BaseLDAP(caching=False, ldap_id=None, auth=None, rootdn=False)[source]

Bases: object

Base LDAP client for configured services

In order to improve performance when checking multiple VUNetID entries, instantiate the client with caching=True to avoid repeatedly fetching the same ID.

connect()[source]

Bind a new connection to the configured LDAP server

disconnect()[source]

Unbind the current connection to the configured LDAP server

class accre.ldap.VUDS(caching=False, ldap_id=None, auth=None, rootdn=False)[source]

Bases: BaseLDAP

Client for VUDS (Vanderbilt Directory Services) using the ACCRE resource ID with administrative privileges to the ACCRE_Users group in DS.

Note that this client has also inherited the functionality of the old “VandyLDAP” client which queried eLDAP. As eLDAP has now been retired, VandyLDAP is now a reference to this class which provides the equivalent API as well as possible but querying VUDS instead.

In order to improve performance when checking multiple VUNetID entries, instantiate the client with caching=True to avoid repeatedly fetching the same ID.

add_accre_users(new_users)[source]

Add new user VUNetIDs from a list to the ACCRE_Users group in DS. Note that a single invalid VUNetID will cause the whole operation to fail, so adding one at a time may be preferable.

Parameters:

new_users (list(str)) – List of new user VUNetIDs to add

Returns:

True on operation success, False on failure

Return type:

bool

delete_accre_users(del_users)[source]

Remove existing user VUNetIDs from a list to the ACCRE_Users group in DS.

Parameters:

del_users (list(str)) – List of user VUNetIDs to delete

Returns:

True on operation success, False on failure

Return type:

bool

exists(vunetid)[source]

Check if the given vunetid exists on the server

Parameters:

vunetid (str) – the vunetid to be checked

Returns:

True if the vunetid exists

Return type:

bool

exists_numeric(uid)[source]

Check if the given numeric UID corresponds to a vunetid on the server

Parameters:

uid (str) – the numeric UID to be checked

Returns:

True if the UID exists

Return type:

bool

info(vunetid)[source]

Return a dictionary of information about the specified vunetid including the full name (fullname), uid (uid) and Vanderbilt email (vanderbilt_email).

Parameters:

vunetid (str) – the vunetid to be checked

Returns:

fullname, uid, and vanderbilt_email

Return type:

dict

info_numeric(uid)[source]

Return a dictionary of information about the specified vunetid including the full name (fullname), uid (uid) and Vanderbilt email (vanderbilt_email).

Parameters:

uid (str) – the numeric UID to be checked

Returns:

fullname, uid, and vanderbilt_email

Return type:

dict

is_active(vunetid)[source]

Check if the given vunetid is an active employee, student, or affiliate of the university

Deprecated since version This: logic is no longer valid for VUNet affiliate accounts, do not use

Parameters:

vunetid (str) – the vunetid to be checked

Returns:

True if the vunetid is active

Return type:

bool

is_locked(vunetid)[source]

Returns False.

In the past, this method checked if the given vunetid is locked due to becoming an inactive VUnetID or having an expired VUNet password.

Deprecated since version This: logic is no longer valid following the eLDAP to VUDS transition as there is no nsaccountlocked property, do not use.

Parameters:

vunetid (str) – the vunetid to be checked

Returns:

False

Return type:

bool

list_accre_users()[source]

Get a list of current accre user VUNetIDs from the ACCRE_Users group in DS.

Returns:

VUNetIDs of all users in the ACCRE_Users DS group

Return type:

list(str)

list_groups_by_gid(gid)[source]

Lists all group names in VUDS corresponding to a given numeric gid. In principle this should return a list of no more than one group, but in the past there have been gid collisions.

Parameters:

gid (int) – the numeric gid to be checked

Returns:

names of all groups with the numeric gid in vuds

Return type:

list(str)

accre.ldap.VandyLDAP

alias of VUDS

accre.ldap.accre_cli()[source]

CLI entry point for Vanderbilt LDAP access

Run accreldap --help for usage

accre.ldap.vandy_cli()[source]

CLI entry point for Vanderbilt VUDS LDAP access

Run vandyldap --help for usage