DocumentationRelease Notes
Documentation

Join an Active Directory domain

Suggest Edits

You can join computers to Active Directory using the command line utility (CLI):

ℹ️

Note

For more information about the Domain Join tool CLI commands, see Domain Join tool commands for AD Bridge.

Overview

When AD Bridge joins a computer to an Active Directory domain, it uses the hostname of the computer to create the name of the computer object in Active Directory. From the hostname, the AD Bridge domain join tool attempts to derive a fully qualified domain name. By default, the AD Bridge domain join tool creates the Linux and Unix computer accounts in the default Computers container in Active Directory.

ℹ️

Note

After you join a domain for the first time, you must restart the computer before you can log on. If you cannot restart the computer, you must restart each service or daemon that looks up users or groups through the standard nsswitch interface, which includes most services that authenticate users, groups, or computers. You must, for instance, restart the services that use Kerberos, such as sshd.

Pre-create accounts in Active Directory

You can create computer accounts in Active Directory before you join your computers to the domain. When you join a computer to a domain, AD Bridge associates the computer with the pre-existing computer account when AD Bridge can find it.

To locate the computer account, AD Bridge first looks for a computer account with a DNS hostname that matches the hostname of the computer. If the DNS hostname is not set, AD Bridge then looks for the name of a computer account that matches the computer's hostname, but only when the computer's hostname is 15 characters or less.

Therefore, when the hostname of your computer is more than 15 characters, set the DNS hostname for the computer account to ensure that the correct computer account is found. If no match is found, AD Bridge creates a computer account.

Privileges and permissions for Active Directory accounts

To join a computer to a domain, use credentials for an Active Directory account that has privileges to join computers to the domain and the full name of the domain that you want to join.

The level of privileges that you need is set by Microsoft Active Directory and is typically the same as performing the corresponding action on a Windows computer.

ℹ️

Note

For more information, see the following:

Create local accounts in AD Bridge

After you join a domain, AD Bridge creates two local user accounts:

  • ComputerName\Administrator: The account is disabled until you run mod-user with the root account. You are prompted to reset the password the first time you use the account.
  • ComputerName\Guest

You can view information about these accounts by executing the following command: /opt/pbis/bin/enum-users

✅

Example

User info (Level-2):
====================
Name:                       EXAMPLE-01\Administrator
UPN:                        Administrator@EXAMPLE-01
Generated UPN:              YES
Uid:                        1500
Gid:                        1544
Gecos:                      <null>Shell: /bin/sh
Home dir:                   /
LMHash length:              0
NTHash length:              0
Local User:                 YES
Account disabled:           TRUE
Account Expired:            FALSE
Account Locked:             FALSE
Password never expires:     FALSE
Password Expired:           TRUE
Prompt for password change: YES
User can change password:   NO
Days till password expires: -149314


User info (Level-2):
====================
Name:                       EXAMPLE-01\Guest
UPN:                        Guest@EXAMPLE-01
Generated UPN:              YES
Uid:                        1501
Gid:                        1546
Gecos:                      <null>Shell: /bin/sh
Home dir:                   /tmp
LMHash length:              0
NTHash length:              0
Local User:                 YES
Account disabled:           TRUE
Account Expired:            FALSE
Account Locked:             TRUE
Password never expires:     FALSE
Password Expired:           FALSE
Prompt for password change: YES
User can change password:   NO
Days till password expires: -149314

Join Active Directory from the command line

On Linux or Unix computers, the location of the domain join command-line utility is  /opt/pbis/bin/domainjoin-cli.

When you join a domain by using the command-line utility, AD Bridge uses the hostname of the computer to derive a fully qualified domain name (FQDN), and then automatically sets the FQDN in the /etc/hosts file.

You can also join a domain without changing the /etc/hosts file.

ℹ️

Note

For more information, see Join an Active Directory domain.

Before you join a domain

To join a domain, ensure the following are in place:

  • The computer's name server can find the domain. Run the command:
nslookup domainName
  • The computer can reach the domain controller. Run the command:
ping domainName

Join a computer to Active Directory

Run the following command as root.

Replace domainName with the FQDN of the domain that you want to join and joinAccount with the user name of an account that has privileges to join computers to the domain:

/opt/pbis/bin/domainjoin-cli join domainName joinAccount

✅

Example

/opt/pbis/bin/domainjoin-cli join example.com Administrator

ℹ️

Note

On agent machines, execute the sudo su command before you run the domainjoin-cli command.

Join a Linux or Unix computer to an organizational unit

Run the following command as root.

Replace organizationalUnitName with the path and name of the organizational unit that you want to join, domainName with the FQDN of the domain, and joinAccount with the user name of an account that has privileges to join computers to the target OU:

/opt/pbis/bin/domainjoin-cli join --ou organizationalUnitName domainName joinAccount.

✅

Example

/opt/pbis/bin/domainjoin-cli join --ou Engineering example.com Administrator

Join a Linux or Unix computer to a nested organizational unit

Run the following command as root, replacing these values:

  • path with the AD path to the OU from the top down, with each node separated by a forward slash (/).

  • organizationalUnitName with the name of the organizational unit that you want to join.

  • domainName with the FQDN of the domain.

  • joinAccount with the user name of an AD account that has privileges to join computers to the target OU:

    /opt/pbis/bin/domainjoin-cli join --ou path/organizationalUnitName domainName joinAccount

✅

Example

Here is an example of how to join a deeply nested OU.

domainjoin-cli join --ou topLevelOU/middleLevelOU/LowerLevelOU/TargetOU example.com Administrator

Join Active Directory without changing /etc/hosts

When you use the AD Bridge domain join tool, AD Bridge uses the host name of the computer to derive a fully qualified domain name (FQDN) and automatically sets the computer’s FQDN in the /etc/hosts file.

To join a Linux computer to the domain without changing the /etc/hosts file, run the following command as root. Replace:

  • domainName: the FQDN of the domain to join
  • joinAccount: the user account with privileges to join computers to the domain
/opt/pbis/bin/domainjoin-cli join --ignore hostname domainName joinAccount

✅

Example

/opt/pbis/bin/domainjoin-cli join --ignore hostname example.com Administrator

ℹ️

Note

After you join a domain for the first time, you must restart the computer before you can log on.

If the computer fails to join the domain

Make sure the computer's FQDN is correct in /etc/hosts. For the computer to process tickets in compliance with the Kerberos protocol and to function properly when it uses cached credentials in offline mode or when its DNS server is offline, there must be a correct FQDN in /etc/hosts.

ℹ️

Note

For more information on GSS-API requirements, see RFC 2743.

You can determine the FQDN of a computer running Linux or Unix by executing the following command:

ping -c 1 `hostname`

When you execute this command, the computer looks up the primary host entry for its hostname. In most cases, this means that it looks for its hostname in /etc/hosts, returning the first FQDN name on the same line. For example, the correct entry for the hostname qaserver, in /etc/hosts:

10.100.10.10 qaserver.corpqa.example.com qaserver

If the entry in /etc/hosts incorrectly lists the hostname (or anything else) before the FQDN, the computer's FQDN becomes, using the malformed example below, qaserver:

10.100.10.10 qaserver qaserver.corpqa.example.com

If the host entry cannot be found in /etc/hosts, the computer looks for the results in DNS instead. This means that the computer must have a correct A record in DNS. If the DNS information is wrong and you cannot correct it, add an entry to /etc/hosts.

Automatically join an agent to a domain

You can prepare a computer account and automate the domain join process.

Create a computer account in Active Directory

  1. Using Active Directory Users and Computers, create a Computer account in your preferred OU.
  2. The Computer Name must be configured to correctly match the AD Bridge agent hostname.
  3. Check the Assign this computer account as a pre-Windows 2000 computer box to assign this computer a password that is based on the new computer name.
  4. Select the permissions: Write access and Reset Password access.

Run a domain join script on the agent

On the AD Bridge agent host, create a script that will run after a reboot (for example, a cron job) and will run the following command:

/opt/pbis/bin/domainjoin-cli join <YOUR_DOMAIN> `hostname -s`$ `hostname -s`

Files modified when you join a domain

Some system files are changed when a computer is joined to a domain. The files that change depend on the platform, the distribution, and the system's configuration.

Run the following command to see a list of the changes:

domainjoin-cli join --advanced --preview domainName

ℹ️

Note

Not all the following files are present on all computers.

The following files might be modified.

  • /etc/nsswitch.conf (on AIX, the file is /etc/netsvcs.conf)
  • /etc/pam.conf on AIX and Solaris
  • /etc/pam.d/* on Linux
  • /etc/ssh/{ssh_config,sshd_config} (or wherever sshd configuration is located)
  • /etc/hosts
  • /etc/{hostname,HOSTNAME,hostname.*}
  • /etc/krb5.conf
  • /etc/krb5/krb5.conf
  • /etc/login.defs (modified when syslog group policy is set with Enable AD Bridge Auditing)

ℹ️

Note

For information on how to join a domain without modifying /etc/hosts, see Join an Active Directory domain.

Updated 15 days ago

©2003-2025 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.