Using the zoneupdate program for controlled automation

You can use the zoneupdate.exe program with command line options to provision profiles in controlled way, allowing you to verify that profiles and access rights are defined correctly for subsets of users or groups without affecting the production environment.

At a minimum, you must specify the zone name or canonical name for the zone to use the zoneupdate.exe program. The command line options are similar to the options available on the Provisioning tab when you display a zone’s properties.

For example, to use the provisioning properties defined for a zone, you only need to specify the zone name at the command line:

zoneupdate default

If you use the canonical name for the zone, you specify the full path to the zone:

zoneupdate "centrify.com/program data/Centrify/zones/default"

You can override the default provisioning properties for a zone by specifying one or more of the following command line options.

Options are not case-sensitive. If you specify an option more than once, only the last value is used.

Use this option To specify
/z:ZoneName

or

/SourceZone:ZoneName

The name of a source zone. If you do not specify a zone name and there’s not a source zone defined in the zone’s provisioning properties, you cannot use the zoneupdate command to copy user or group attributes from one zone to another.

A source zone is required for classic zones. It is optional for parent hierarchical zones, but can be useful if you are migrating from classic to hierarchical zones.

/d:DomainName

or

/Domain:DomainName

The name of the domain to process. If you do not specify a domain name, the zoneupdate program processes the Active Directory domain to which the computer is joined.

/dc:DCName

or

/DomainController:DCName

The name of the target domain controller to connect. No option - This will use the default domain controller of target domain.

/uu:Option

or

/UserUid:Option

The method to use to set the user’s numeric identifier (UID) value. You can specify any one of the following values:

  • Auto to generate UIDs based on the Active Directory domain name and the RID of a user object. This setting is equivalent to selecting Generate from user SID in the Provisioning tab.
  • AppleScheme to generate UIDs based on the Apple algorithm for generating numeric identifiers from the Active Directory user object's objectGuid. This setting is equivalent to selecting Generate using Apple scheme in the Provisioning tab.
  • RFC2307 to use the uidNumber attribute in the Active Directory RFC2307 schema for the user’s UID value.
  • ZoneDefault to use the UID defined on the User Defaults tab for the zone. If there’s no default value, the Next UID value for the zone is used.
  • SourceZone to copy the UID from the same user in a specified source zone.
  • EmployeeId to copy the UID from the employeeId attribute of the user object.
  • EmployeeNumber to copy the UID from the employeeNumber attribute of the user object.
  • uidNumber to copy the UID from the uidNumber attribute of the user object.

If you don’t use one of these values, you can set the UID to not have any value. For example:

/uu:empty

If you use this setting, users will have an incomplete profile in the zone.

/un:Option

or

/UserName:Option

The method to use to set the user’s name. You can specify any one of the following values:

  • sAMAccountName to use the Active Directory user’s sAMAccountName attribute as the UNIX user name.
  • CN to use the user's common name (CN) attribute as the UNIX user name.
  • RFC2307 to use the uid attribute in the Active Directory RFC2307 schema as the UNIX user name.
  • ZoneDefault to use the user name defined on the User Defaults tab for the zone. If there’s no default value zone, the sAMAccountName is used.
  • SourceZone to copy the user name from the same user in a specified source zone.

If you don’t use one of these values, you can set the user name to an explicit value. For example:

/un:hunter
/us:Option

or

/UserShell:Option

The method to use to specify the user’s default login shell. You can specify any one of the following values:

  • RFC2307 to use the loginShell attribute in the Active Directory RFC2307 schema as the default shell.
  • ZoneDefault to use the shell specified on the User Defaults tab for the zone.
  • SourceZone to copy the shell defined for the user in a specified source zone.

If you don’t use one of these values, you can set the login shell using an explicit value. For example:

/us:/bin/bash
/uh:Option

or

/UserHomeDirectory:Option

The method to use to specify the user’s default home directory. You can specify any one of the following values:

  • RFC2307 to use the unixHomeDirectory attribute in the Active Directory RFC2307 schema for a user as the default home directory.
  • ZoneDefault to use the home directory specified on the User Defaults tab for the zone.
  • SourceZone to copy the home directory defined for the user in a specified source zone.

If you don’t use one of these values, you can set the home directory to an explicit value. For example:

/uh:/home/hunter
/ug:Option

or

/UserPrimaryGroup:Option

The method to use to specify the user’s primary group identifier. You can specify any one of the following values:

  • AppleScheme to generate the user’s primary group identifier (GID) based on the Apple algorithm for generating numeric identifiers from the Active Directory objectGuid for the user’s primary group. Note that the user's primary group must configured for the zone. If the primary group is not configured for the zone, an error will be logged in the Windows Event Log when the user is provisioned. This setting is equivalent to selecting Generate using Apple scheme in the Provisioning tab.
  • PrimaryGroupSID to generate the user’s primary group identifier (GID) based on the Centrify algorithm for generating numeric identifiers from the Active Directory security identifier of the user’s primary group.
  • PrivateGroup to set the user's primary GID value to be the same as the user‘s UID value.
  • RFC2307 to use the gidNumber attribute f in the Active Directory RFC2307 schema as the primary group identifier or a user.
  • ZoneDefault to use the primary group specified on the User Defaults tab in the zone. If there’s no default value, zoneupdate.exe will stop provisioning the user.
  • SourceZone to copy the primary group defined for the user in a specified source zone.

example:

/ug:empty

If you use this setting, users will have an incomplete profile in the zone.

  • GroupMembership to set the user's primary GID based on the user’s Active Directory group membership. If a user is a member of the Active Directory groups ops-mgrs and ops-labs and one of those groups has a UNIX profile in the zone but not the other, the group with the UNIX profile in the zone will be used as the primary GID for the user. If both group have a UNIX profile in the zone, the one with higher priority will be used. You can set the priority for selecting the primary group to use in the Access Manager console. If the priority is the same, zoneupdate.exe will stop provisioning the user.

If you don’t use one of these values, you can set the primary GID to not have any value.

 

/uc:Option

or

/UserGecos:Option

The method to use to specify the user’s GECOS field. You can specify any one of the following values:

  • RFC2307 to use the gecos attribute in the Active Directory RFC2307 schema for a user.
  • ZoneDefault to use the value defined for the GECOS field on the User Defaults tab for the zone.

If you don’t use one of these values, you can set the primary GID value to an explicit value. For example:

/uc:Thompson, Hunter S.
/gg:Option

or

/GroupGid:Option

The method to use to set the group numeric identifier (GID) value. You can specify any one of the following values:

  • Auto to generate the GID based on the Active Directory domain name and the RID of a group object. This setting is equivalent to selecting Generate from group SID in the Provisioning tab.
  • AppleScheme to generate GIDs based on the Apple algorithm for generating numeric identifiers from the Active Directory group object's objectGuid. This setting is equivalent to selecting Generate using Apple scheme in the Provisioning tab.
  • RFC2307 to use the gidNumber attribute in the Active Directory RFC2307 schema for the group GID value.
  • ZoneDefault to use the GID defined on the Group Defaults tab for the zone. If there’s no default value, the Next GID value for the zone is used.
  • SourceZone to use the GID defined for the group in a specified source zone.

If you don’t use one of these values, you can set the GID to not have any value. For example:

/gg:empty

If you use this setting, groups will have an incomplete profile in the zone.

/gn:Option

or

/GroupName:Option

The method to use to set the group name. You can specify any one of the following values:

  • samAccountName to use the Active Directory group samAccountName attribute as the UNIX group name.
  • CN to use the group's common name (CN) attribute as the UNIX group name.
  • RFC2307 to use the cn attribute in the Active Directory RFC2307 schema as the UNIX group name.
  • ZoneDefault to use the group name defined on the Group Defaults tab for the zone. If there’s no default value, the sAMAccountName is used.
  • SourceZone to copy the group name from the group in a specified source zone.

If you don’t use one of these values, you can set the group name to an explicit value. For example:

/gn:apps-lab
/u:ADGroupName

or

/UserSource:ADGroupName

An Active Directory group to use to populate a Centrify zone with users. Use the sAMAccountName and, optionally, the domain name to identify the group. For example, to use the Active Directory engineers group in the currently connected domain to populate users in the default zone:

zoneupdate /u:engineers default

To use the Active Directory engineers group in a specific domain, you can use the /d:DomainName option or group_name@domain_name. For example to use the Active Directory engineers group in the testdomain.org domain to populate users in the default zone:

zoneupdate /u:engineers@testdomain.org default 
/g:ADGroupName

or

/GroupSource:ADGroupName

An Active Directory group to use to populate a Centrify zone with groups. Use the sAMAccountName and, optionally, the domain name to identify the group. For example, to use the Active Directory employees group in the currently connected domain to populate groups in the default zone:

zoneupdate /g:employees default
/v

or

/Verbose

Display detailed information about the provisioning of users and groups. When you use this option, the output format is:

Group: groupname:gid
User: uid:username:shell:home:primarygid
/p

or

/Preview

Preview the users or groups to be provisioned or removed. In preview mode, the zoneupdate.exe program does not create or remove any UNIX profiles.

/el

or

/EventLog: Level

Enable logging to the Event log. You can use the Event Viewer to check the log results. For the log level, you can specify any one of the following values:

  • None - don't write any provisioning activities to the Event log. This is the default setting.
  • Normal - Write only the name of the provisioned users and groups to the Event log.
  • Verbose - Write the UNIX profiles for the provisioned users and groups to the Vent log.
/l

or

/Log:Level

Enable logging and set the level of detail recorded in the log file. For the log level, you can specify any one of the following values:

  • Error to log only error messages.
  • Warning to log warnings and error messages.
  • Information to log informational messages, warnings, and errors.
  • Verbose to log all messages, including details about the user and group profiles created or removed.

Logging is off by default. If you enable logging, the default file location for the log file is:

C:\Users\user_name\AppData\Roaming\Centrify\Zone Provisioning Agent\Log

You can change the default log file path by modifying the following registry key:

HKEY_LOCAL_MACHINE\Software\Centrify ZPA\LogLevel