<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title></title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:support@ActiveState.com" />
</head>
<body style="background-color: white">
<ul id="index">
<li><a href="#NAME">NAME</a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#Overview">Overview</a></li>
<li><a href="#Usage-Notes">Usage Notes</a></li>
</ul>
</li>
<li><a href="#ARGUMENTS">ARGUMENTS</a>
<ul>
<li><a href="#c-fg-cfg_file">-c[fg] cfg_file</a></li>
<li><a href="#g-roups-group-group2">-g[roups] group[,group2,...]</a></li>
<li><a href="#o-wners-user-user2">-o[wners] user[,user2,...]</a></li>
<li><a href="#i-gnore">-i[gnore]</a></li>
<li><a href="#b2">-b2</a></li>
<li><a href="#s-erver-ldap_server">-s[erver] ldap_server</a></li>
<li><a href="#p-ort-ldap_port">-p[ort] ldap_port</a></li>
<li><a href="#d-ebug">-d[ebug]</a></li>
<li><a href="#D-EBUG">-D[EBUG]</a></li>
<li><a href="#n-oop">-n[oop]</a></li>
<li><a href="#h-elp--man">-h[elp]|-man</a></li>
</ul>
</li>
<li><a href="#EXAMPLES">EXAMPLES</a>
<ul>
<li><a href="#Example-1---Automation-Example">Example 1 - Automation Example</a></li>
<li><a href="#Example-2---Illustrating-More-Options">Example 2 - Illustrating More Options</a></li>
<li><a href="#Example-3---No-Op">Example 3 - No-Op</a></li>
<li><a href="#Example-4---Usage">Example 4 - Usage</a></li>
</ul>
</li>
<li><a href="#CONFIGURATION-FILE">CONFIGURATION FILE</a>
<ul>
<li><a href="#File-Format">File Format</a></li>
<li><a href="#Required-Entries">Required Entries</a></li>
<li><a href="#Optional-Entries">Optional Entries</a></li>
</ul>
</li>
<li><a href="#USER-REMOVAL">USER REMOVAL</a>
<ul>
<li><a href="#User-Removal-Procedure">User Removal Procedure</a></li>
</ul>
</li>
<li><a href="#RELATED-SOFTWARE">RELATED SOFTWARE</a></li>
<li><a href="#RETURN-STATUS">RETURN STATUS</a></li>
</ul>
<h1 id="NAME">NAME</h1>
<p>mirror_ldap_groups.pl v2.4.0 - Mirror specified LDAP groups in Perforce.</p>
<h1 id="SYNOPSIS">SYNOPSIS</h1>
<p>mirror_ldap_groups.pl [-c <i>cfg_file</i>] [-g <i>group</i>[,<i>group2</i>,...]] [-o <i>user</i>[,<i>user2</i>,...]] [-i|-b2] [-s <i>ldap_server</i>] [-p <i>ldap_port</i>] [-d|-D] [-n]</p>
<p>OR</p>
<p>mirror_ldap_groups.pl {-h|-man}</p>
<h1 id="DESCRIPTION">DESCRIPTION</h1>
<h2 id="Overview">Overview</h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h2 id="Usage-Notes">Usage Notes</h2>
<p>The list of AD groups to process can be specified in the config file or the command line.</p>
<p>Upon completion, a summary of errors and updates is displayed.</p>
<p>This script is intended to be called routinely (e.g every 10 minutes by a cron job or other scheduler).</p>
<h1 id="ARGUMENTS">ARGUMENTS</h1>
<h2 id="c-fg-cfg_file">-c[fg] <i>cfg_file</i></h2>
<p>Specify the config file to use. The default is mirror_ldap_groups.cfg in the current directory.</p>
<h2 id="g-roups-group-group2">-g[roups] <i>group</i>[,<i>group2</i>,...]</h2>
<p>Specify a comma-delimited list of LDAP groups to mirror in Perforce. Subordinate groups are implied and need not be listed explicitly.</p>
<h2 id="o-wners-user-user2">-o[wners] <i>user</i>[,<i>user2</i>,...]</h2>
<p>Specify a comma-delimited list of users to replace the 'Owners' field of the specified group(s).</p>
<h2 id="i-gnore">-i[gnore]</h2>
<p>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'.</p>
<p>The '-i' flag is incompatible with '-b2'.</p>
<h2 id="b2">-b2</h2>
<p>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.</p>
<p>The '-b2' flag is incompatible with '-i'.</p>
<h2 id="s-erver-ldap_server">-s[erver] <i>ldap_server</i></h2>
<p>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>
<h2 id="p-ort-ldap_port">-p[ort] <i>ldap_port</i></h2>
<p>Specify the LDAP server port. A default value can be configured by adding an LDAP_PORT value in the configuration file.</p>
<h2 id="d-ebug">-d[ebug]</h2>
<p>Enable verbose debug mode.</p>
<h2 id="D-EBUG">-D[EBUG]</h2>
<p>Same as '-d', but even more pedantic (verbose, noisy).</p>
<h2 id="n-oop">-n[oop]</h2>
<p>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.</p>
<h2 id="h-elp--man">-h[elp]|-man</h2>
<p>Display a usage message. The -h display a short synopsis only, while -man displays this manual page.</p>
<h1 id="EXAMPLES">EXAMPLES</h1>
<p>The <code>p4master_run</code> wrapper script is called first, providing the Perforce instance number. This ensures the necessary Perforce environment settings are loaded from <code>/p4/common/bin/p4_vars</code>.</p>
<p>These examples use the long options, e.g. '-groups' rather than '-g'; both styles are equivalent.</p>
<h2 id="Example-1---Automation-Example">Example 1 - Automation Example</h2>
<p>A typical usage example, as might be coded in the wrapper script:</p>
<p><code>p4master_run 1 mirror_ldap_groups.pl -groups p4.users -server ad.mycompany.com -port 389</code></p>
<h2 id="Example-2---Illustrating-More-Options">Example 2 - Illustrating More Options</h2>
<p>Example running against Perforce server instance 2, processing multiple groups and a non-default config file containing LDAP server and bind account info:</p>
<p><code>p4master_run 2 mirror_ldap_groups.pl -groups p4.dev,p4.qa,p4.automation -cfg mirror_ldap_groups.mycompany.cfg</code></p>
<h2 id="Example-3---No-Op">Example 3 - No-Op</h2>
<p>A No-Op Usage Example, with maximum verbosity:</p>
<p><code>p4master_run 1 mirror_ldap_groups.pl -groups p4.users -server ad.mycompany.com -port 389 -noop -DEBUG</code></p>
<h2 id="Example-4---Usage">Example 4 - Usage</h2>
<p>Get usage info on the comand line:</p>
<p><code>mirror_ldap_groups.pl -h</code></p>
<p>or:</p>
<p><code>mirror_ldap_groups.pl -man</code></p>
<h1 id="CONFIGURATION-FILE">CONFIGURATION FILE</h1>
<p>The config file must define the following values:</p>
<h2 id="File-Format">File Format</h2>
<p>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.</p>
<h2 id="Required-Entries">Required Entries</h2>
<p>At a minimum, the config file must define these entries:</p>
<ul>
<li><p>LDAP_BIND_USER</p>
<p>Define a static 'bind' account that has enough access within LDAP query basic user data and read group data.</p>
</li>
<li><p>LDAP_BIND_PASSWORD</p>
<p>Define the password for the LDAP_BIND_USER.</p>
</li>
<li><p>LDAP_READ_DN</p>
<p>Define the DN string for the bind user. Your resident LDAP guru can help provide this.</p>
</li>
<li><p>DEFAULT_EMAIL_DOMAIN</p>
<p>Define a default email domain, just in case the LDAP query for a user's email comes up blank. This is used to guess the user's email domain as <i>userid@default_email_domain</i>.</p>
</li>
</ul>
<h2 id="Optional-Entries">Optional Entries</h2>
<p>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.</p>
<ul>
<li><p>LDAP_HOST</p>
<p>Specify the LDAP or Active Directory server (DNS name or IP address). If LDAP_HOST is defined in the config file, the '-s' flag is not required on the command line.</p>
</li>
<li><p>LDAP_PORT</p>
<p>Specify the port to connect to LDAP on. This corresponds to the '-p' flag on the command line. If the LDAP_PORT value is defined in the config file, the '-s' flag is not required on the command line.</p>
</li>
<li><p>LDAP_GROUPS</p>
<p>The LDAP_GROUPS value may list a single group or a comma-delimted list of groups. If the LDAP_GROUPS value is defined in the config file, the '-g' flag is not required on the command line.</p>
</li>
</ul>
<h1 id="USER-REMOVAL">USER REMOVAL</h1>
<p>Users removed from LDAP are not automatically removed from Perforce.</p>
<h2 id="User-Removal-Procedure">User Removal Procedure</h2>
<p>The following manual procedure illustrates how user accounts that do not exist in any Perforce group can be detected and optionally removed.</p>
<p>Users that do not exist in any group in Perforce can be detected with this command:</p>
<ul>
<p><code>checkusers_not_in_group.py</code> > <code>users_not_in_any_group.txt</code></p>
<p><code>cat users_not_in_any_group.txt</code></p>
</ul>
<p>The users listed in the <code>users_not_in_any_group.txt</code> file can be considered candidates for removal.</p>
<p>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.</p>
<p>The script <code>p4deleteuser.py</code> 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 <code>users_not_in_any_group.txt</code> to create a new file, <code>users_to_remove.txt</code>. Then remove those user accounts with this command:</p>
<ul>
<p><code>p4deleteuser.py users_to_remove.txt</code></p>
</ul>
<p>The <code>checkusers_not_in_group.py</code> and <code>p4deleteuser.py</code> scripts can be found in the Maintenance folder of the Server Delpoyment Package (SDP).</p>
<h1 id="RELATED-SOFTWARE">RELATED SOFTWARE</h1>
<p>This depends on several Perl Modules. Key modules are:</p>
<ul>
<li><p><b>OS.pm</b> - Abstraction layer for platform (e.g. Mac/Linux/Windows) variations.</p>
</li>
<li><p><b>Cmd.pm</b> - Shell command line wrapper.</p>
</li>
<li><p><b>Misc.pm</b> - Misc Perl utils.</p>
</li>
<li><p><b>Msg.pm</b> - Message interface to encourage consistent look and feel, and simplify logging.</p>
</li>
</ul>
<h1 id="RETURN-STATUS">RETURN STATUS</h1>
<p>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.</p>
</body>
</html>
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #1 | 27246 | Jessie Fernandez | Branch for Jessie Fernandez | ||
| //guest/perforce_software/sdp/dev/Unsupported/Samples/bin/mirror_ldap_groups.pl.html | |||||
| #1 | 26681 | Robert Cowham |
Removing Deprecated folder - if people want it they can look at past history! All functions have been replaced with standard functionality such as built in LDAP, or default change type. Documentation added for the contents of Unsupported folder. Changes to scripts/triggers are usually to insert tags for inclusion in ASCII Doctor docs. |
||
| //guest/perforce_software/sdp/dev/Server/Unix/p4/common/custom/auth/mirror_ldap_groups.pl.html | |||||
| #1 | 19921 | C. Thomas Tyler |
Reviving LDAP group mirroring scripts, refactored into a different directory. These were deleted because the built-in LDAP authentication mechanism provides a fully supported solution with similar functionality, and since using built-in features is preferred for customers with no compelling reason to use a custom solution. However, some customers require Two Factor Authentication, and that can only be achieved with old-school external authentication triggers and supplemental custom automation. This change introduces a new /p4/common/custom folder, with an 'auth' subfolder as the first example of a custom module. This folder is intended to be for things that are to be distributed with SDP, but are for customers with specific requirements that are not expected to be broadly applicable. The SDP solution would be an interim to provide a two-factor authentication option until such time as that can be offered in the server. As of July 2016, adding built-in support for two-factor authentication is not on the Helix Versioning Engine product roadmap (job048959). |
||
| //guest/perforce_software/sdp/dev/Server/Unix/p4/common/bin/mirror_ldap_groups.pl.html | |||||
| #1 | 10638 | C. Thomas Tyler | Populate perforce_software-sdp-dev. | ||
| //guest/perforce_software/sdp/main/Server/Unix/p4/common/bin/mirror_ldap_groups.pl.html | |||||
| #1 | 10148 | C. Thomas Tyler | Promoted the Perforce Server Deployment Package to The Workshop. | ||