Joining Computers to a Domain and Zone

You have completed the preparation of the environment and added existing users and groups to Active Directory. The steps up to this point have not affected the day-to-day activities of any UNIX users or groups, and have not changed the configuration of any UNIX computers. The final step in the migration requires you to join UNIX computers to the Active Directory domain. This step does have the potential to affect end-users.

This section describes how to complete the migration by joining the target set of computers to an Active Directory domain and a Server Suite zone.

Using Adjoin on New Computers

You can run the adjoin command interactively or in a script to join UNIX computers to Active Directory. One advantage to using the adjoin command is that it enables you to add the join operation to the steps for building a new UNIX computer. For example, if you have a process for provisioning a new UNIX computer, you can add an adjoin step that allows the new UNIX computer to join itself to Active Directory. Provisioning new computers to join the domain when they are built ensures that there are no new local users being defined on those UNIX computers.

Running Adjoin Requires Unix and Active Directory Privileges

On UNIX, running adjoin requires you to log on as root, be a member of the wheel group, or have root equivalent privileges in the sudoers file. On Mac OS X computers, adjoin requires the administrator account and password.

Specifying the Required Options

The basic syntax for the adjoin command is:

adjoin [options] domain_name [--zone zone_name | --workstation]

The domain_name should be a fully-qualified domain name; for example, sales.acme.com. If you are using adjoin to provision new computers, there are several options you should specify on the command line or in the script.

  • Use the --container or -c option to specify the location for the computer account. Typically, you should use the organizational unit that you created for UNIX Servers and Workstation under the top-level UNIX organizational unit. It must be the location you used when you pre-created the computer object. For example:

    -c “ou=UNIX Server and Workstations,ou=UNIX”

  • Use the --selfserve or -S option to specify that you want the computer to join itself to the Active Directory domain.

  • Use the --zone or -z option to specify the name of the zone to join. You must specify a zone name unless you are joining Auto Zone using the --workstation option.

  • If you have a disjointed DNS environment where the Active Directory domain for the computer account does not match the name of the DNS domain, you must also specify the -name and
    --alias options. The --name option specifies the name of the Active Directory computer object and the --alias will be the fully-qualified DNS name of the computer.

  • Use the --computerpassword or -X to specify the password of the precreated computer account. You must also specify either --precreate or --selfserve. If you don't specify the password, the default password will be used.

For example, update your provisioning process for a new computer to include a command similar to the following:

adjoin -c "ou=UNIX Server and Workstations,ou=UNIX" -S -z production arcade.net

For complete information about adjoin options, see the adjoin man page.

Pre-staging Before Using Adjoin on a New Machine

When joining a large AD environment, the join procedure can take a very long time -- up to dozens of minutes. This becomes a concern in some use cases, such as starting an Amazon EC2 instance that needs to join the domain to provide service.

To speed up the adjoin process, the adjoin --prestage option uses existing cache files instead of populating cache from scratch.

Some preparation is required to take advantage of the --prestage option:

  • Prepare a pre-staged cache directory on a joined machine
  • Copy the cache directory to the new machine

Security Requirements

To use the --prestage option, ensure the following:

  • Joined and new machine requirements:

    • The --prestage option can only be used between machines that have the same platform, architecture, and Authentication Service (Centrify DirectControl) release version installed.
    • Adclient cache data encryption feature cannot be enabled on the joined machine. See the adclient.cache.encrypt parameter.

  • Pre-staged cache directory on joined machine requirements:

    • On a joined machine, create or designate a directory for the pre-staging cache files.
      • The directory must be in a safe path. That means all levels of parent directories are owned by system accounts.
      • The directory cannot be either group or world writable.

  • Content for the pre-staged cache directory on the joined machine:

    • Place the cache files (dz.cache, dc.cache, gc.cache,.idx and kset. files) in the specified directory.
    • Ensure the cache files are owned by system accounts.
    • Files cannot be either group or world writable.
    • Symlink is not allowed for the cache files.

  • Zone hierarchy changes are not allowed between the staging directory and the new machine. This includes:

    • zone name change
    • zone GUID change
    • zone schema change

Preparing to Use the --prestage Option

  1. Create a directory on a joined machine. For example, /pre.

  2. Stop adclient on that machine.

  3. Copy the /var/centrifydc/ directory to the pre-staged directory on the joined machine.

    For example:

    Copying the /var/centrifydc/ directory to the pre-staged directory, /pre, places a copy of the required files in /pre/centrifydc/.

  4. Verify the pre-staged directory on the joined machine contains all the .idx, .cache, and kset. files.

  5. Copy the pre-staged directory to the new machine.

    Use a method of your choice, such as scp or sftp.

    This is done so the pre-staged files are available locally on the new machine.

  6. Add the option to the adjoin command when adding the new machine. The syntax is:

    -E | --prestage <directory>

    where directory is the path to the pre-staged directory on the new machine.

    For example, if the pre-staged files are in directory, /pre/centrifydc/, use the following adjoin command.

    adjoin -z <zone> -E /pre/centrifydc<domain>

Verify Authentication After Joining the Domain By Logging On

As the final step in the initial migration, you should verify that authentication for an Active Directory user is successful. You can do this by logging on to the UNIX console using either the UNIX user name or the Active Directory User Principal Name for a user assigned to the UNIX Login role. When prompted, type the Active Directory password for the account. If you are able to log on using the Active Directory password, you know that authentication is being handled by Active Directory and the user account has been successfully migrated.

You should also verify that you can log on remotely using a secure shell (ssh) connection and that you can use other services such as ftp.

If users have trouble logging on after a UNIX computer has joined the domain, it is typically because they’re not assigned the UNIX Login role or don’t have a valid UNIX profile in the zone. You can use the Show Effective UNIX User Rights command to check which users have profiles and what roles have been assigned to users who have access to the selected computer.