NAME

mirror_ldap_groups.pl v2.4.0 - Mirror specified LDAP groups in Perforce.

SYNOPSIS

mirror_ldap_groups.pl [-c cfg_file] [-g group[,group2,...]] [-o user[,user2,...]] [-i|-b2] [-s ldap_server] [-p ldap_port] [-d|-D] [-n]

OR

mirror_ldap_groups.pl {-h|-man}

DESCRIPTION

Overview

This script is as a one-way integration from LDAP to Perforce. It mirrors group membership of a specified list of groups from an LDAP server, such as Active Directory (AD), into Perforce.

For each group processed, a corresponding Perforce group of the same name is created, and updated to contain the same users. If the users in AD do not yet exist in Perforce, Perforce accounts are created using the information available from AD (so long as there are available licenses). Changes to the FullName and Email address fields are detected in LDAP and propagated to Perforce.

If the LDAP group includes other groups, they are mirrored as Perforce subgroups by default. If the LDAP group is empty, a warning message is displayed, and processing continues. Empty LDAP groups are not treated as errors, and do not cause a non-zero return status.

The 'Users' and 'Subgroups' fields of the Perforce group spec are updated based on information from AD. Other fields, such as 'Owners', timeouts and Max* settings, are unaffected.

Usage Notes

The list of AD groups to process can be specified in the config file or the command line.

Upon completion, a summary of errors and updates is displayed.

This script is intended to be called routinely (e.g every 10 minutes by a cron job or other scheduler).

ARGUMENTS

-c[fg] cfg_file

Specify the config file to use. The default is mirror_ldap_groups.cfg in the current directory.

-g[roups] group[,group2,...]

Specify a comma-delimited list of LDAP groups to mirror in Perforce. Subordinate groups are implied and need not be listed explicitly.

-o[wners] user[,user2,...]

Specify a comma-delimited list of users to replace the 'Owners' field of the specified group(s).

-i[gnore]

If the -i flag is specified, any groups defined in LDAP that are members of the specified groups are ignored, rather than mirrored as Subgroups in Perforce. The 'Subgroups' field the group spec is unaffected with '-i'.

The '-i' flag is incompatible with '-b2'.

-b2

Specify '-b2' to enable a custom behavior for handling Subgroups in Perforce. When '-b2' is specified, any groups defined defined in LDAP that are members of the specified groups are ignored (similar to '-i'). Instead, the membership of any existing Subgroups defined in the group spec in Perforce is queried, and compared against the membership if the parent group. Perforce Subgroups may contain only a subset of the users defined in the specified group (the parent group) when '-b2' is specified. Any users detected in subgroups of the specified group are removed from the group. Other than removal from the group, those accounts are not otherwise affected.

The '-b2' flag is incompatible with '-i'.

-s[erver] ldap_server

Specify the LDAP server (DNS name or IP address). A default value can be configured by adding an LDAP_HOST value in the configuration file.

-p[ort] ldap_port

Specify the LDAP server port. A default value can be configured by adding an LDAP_PORT value in the configuration file.

-d[ebug]

Enable verbose debug mode.

-D[EBUG]

Same as '-d', but even more pedantic (verbose, noisy).

-n[oop]

Specify No Op mode, indicating that the script should display what it would do with given arguments and environment, but take no action that affects data. Users that would be added to Perforce are displayed, but those users are not actually added.

-h[elp]|-man

Display a usage message. The -h display a short synopsis only, while -man displays this manual page.

EXAMPLES

The p4master_run wrapper script is called first, providing the Perforce instance number. This ensures the necessary Perforce environment settings are loaded from /p4/common/bin/p4_vars.

These examples use the long options, e.g. '-groups' rather than '-g'; both styles are equivalent.

Example 1 - Automation Example

A typical usage example, as might be coded in the wrapper script:

p4master_run 1 mirror_ldap_groups.pl -groups p4.users -server ad.mycompany.com -port 389

Example 2 - Illustrating More Options

Example running against Perforce server instance 2, processing multiple groups and a non-default config file containing LDAP server and bind account info:

p4master_run 2 mirror_ldap_groups.pl -groups p4.dev,p4.qa,p4.automation -cfg mirror_ldap_groups.mycompany.cfg

Example 3 - No-Op

A No-Op Usage Example, with maximum verbosity:

p4master_run 1 mirror_ldap_groups.pl -groups p4.users -server ad.mycompany.com -port 389 -noop -DEBUG

Example 4 - Usage

Get usage info on the comand line:

mirror_ldap_groups.pl -h

or:

mirror_ldap_groups.pl -man

CONFIGURATION FILE

The config file must define the following values:

File Format

The config file contains variables names and their, separated by the first space on the line. Any subsequent spaces are interpreted as part of the value. Comment lines start with '#'. Blank lines are ignored, as are leading and trailing whitespace.

Required Entries

At a minimum, the config file must define these entries:

Optional Entries

If these optional values are defined, they don't need to be provided on the command line. If the corresponding command line flag is provided, the value in the config file is ignored.

USER REMOVAL

Users removed from LDAP are not automatically removed from Perforce.

User Removal Procedure

The following manual procedure illustrates how user accounts that do not exist in any Perforce group can be detected and optionally removed.

Users that do not exist in any group in Perforce can be detected with this command:

The users listed in the users_not_in_any_group.txt file can be considered candidates for removal.

The recommended procedure for removing a user is to use the P4Admin user interface to manually remove user accounts, following whatever policy and procedures are identified for removing users in your organization. Using P4Admin makes it easy to evaluate the impact of removing an account, indicating (for example) which workspaces will be removed. Workspace remove can be problematic if the user to be removed created (and thus is listed as the owner of) workspaces actively used by other users or official builds.

The script p4deleteuser.py is a forceful and potentially dangerous user removal script, as it will remove all workspaces for which the user is indicated as the owner, and cancel any checked out files. If you decide that script is appropriate, you can hand-edit and trim the list of users in users_not_in_any_group.txt to create a new file, users_to_remove.txt. Then remove those user accounts with this command:

The checkusers_not_in_group.py and p4deleteuser.py scripts can be found in the Maintenance folder of the Server Delpoyment Package (SDP).

RELATED SOFTWARE

This depends on several Perl Modules. Key modules are:

RETURN STATUS

Zero indicates normal completion, Non-Zero indicates an error. In event of a non-zero exit code, all output (stdout and stderr) should be scanned to determine the cause. Generaly a clearn indication will be given upon failure.