Install the AD Bridge agent

Install the correct version for the operating system

Install the AD Bridge agent, the identity service that authenticates users, on each Linux or Unix computer that you want to connect to Active Directory.

⚠️

Important

Before installing the agent, we recommend that you upgrade your system with the latest security patches. see What is the AD Bridge agent?.

The procedure for installing the agent depends on the operating system of the target computer or virtual machine.

Check the Linux kernel release number

To run the AD Bridge agent on a Linux machine, the kernel release number must be 2.6 or later.

To determine the release number of the kernel, run the following command:

uname -r

Downgrade AD Bridge agent to earlier version

Before downgrading to an earlier AD Bridge version, a domain leave and uninstall purge are required to ensure configuration settings not supported by previous releases are removed. Otherwise, the previous release may not work properly.

ℹ️

Note

For more information on best practices, see Leave a domain and uninstall the AD Bridge agent.

Install requirements for the AD Bridge agent

This section lists requirements for installing and running the AD Bridge agent.

Environment variables

Before you install the AD Bridge agent, make sure that the following environment variables are not set:

• LD_LIBRARY_PATH
• LIBPATH
• SHLIB_PATH
• LD_PRELOAD

Setting any of these environment variables violates best practices for managing Unix and Linux computers, because it causes AD Bridge to use non-AD Bridge libraries for its services.

If you must set LD_LIBRARY_PATH, LIBPATH, or SHLIB_PATH for another program, put the AD Bridge library path (/opt/pbis/lib or /opt/pbis/lib64) before any other path, but keep in mind that doing so may result in side effects for other programs, as they will now use AD Bridge libraries for their services.

If joining the domain fails with an error message that one of these environment variables is set, stop all the AD Bridge services, clear the environment variable, make sure it is not automatically set when the computer restarts, and then try to join the domain again.

ℹ️

Note

For more information on best practices, see When Should I Set LD_LIBRARY_PATH?.

Uninstall SSSD and Centrify

AD Bridge is not compatible with System Security Services Daemon (SSSD) or Centrify. Uninstall SSSD and Centrify from any Linux computers where you want to deploy the AD Bridge agent.

Patch requirements

We recommend that the latest patches for an operating system be applied before installing AD Bridge.

Requirements for the agent

Locale

Configure the locale with UTF-8 encoding for every target computer.

Secure Shell

To properly process logon events with AD Bridge, the SSH server or client must support the UsePam yes option.

For single sign-on, both the SSH server and the SSH client must support GSSAPI authentication.

Other software

Telnet, rsh, rcp, rlogin, and other programs that use PAM for processing authentication requests are compatible with AD Bridge.

Networking requirements

Each Linux or Unix computer must have fully routed network connectivity to all the domain controllers that service the computer's Active Directory site. Each computer must be able to resolve A, PTR, and SRV records for the Active Directory domain, including at least the following:

• A domain.tld
• SRV _kerberos._tcp.domain.tld
• SRV _ldap._tcp.domain.tld
• SRV _kerberos._udp.sitename.Sites._msdcs.domain.tld
• A domaincontroller.domain.tld

Disk space requirements

The AD Bridge agent requires 100MB of disk space in the /opt mount point.

The agent also creates configuration files in /etc/pbis and offline logon information in /var/lib/pbis.

The AD Bridge agent caches Group Policy Objects (GPOs) in /var/lib/pbis.

Memory and CPU requirements

• RAM: The agent services and daemons can use between 9MB – 14MB:
  • Authentication service on a 300-user mail server is typically 7MB
  • Other services and daemons require between 500KB and 2MB each
• CPU: On a 2.0GHz single-core processor under heavy load with authentication requests is about 2 percent.

ℹ️

Note

For a description of the AD Bridge services and daemons, see What is the AD Bridge agent?.

Clock Skew requirements

For the AD Bridge agent to communicate over Kerberos with the domain controller's Kerberos key distribution center, the clock of the client must be within the domain controller's maximum clock skew, which is 300 seconds, or 5 minutes, by default.

ℹ️

Note

For more information, see What is the AD Bridge agent?.

Additional requirements for specific operating pystems

AIX

On AIX computers, PAM must be enabled. LAM is supported only on AIX 5.x. PAM must be used exclusively on AIX 6.x.

ℹ️

Note

For more information, see Leave a domain and uninstall the AD Bridge agent.

Install the agent on Linux or Unix with the shell script

Install the agent using a shell script that contains a self-extracting executable.

To view information about the installer or to view a list of command-line options, run the installer package using --help command. For example (examples here are for RPM-based Linux platform):

./adbridge-##.#.#.###.linux.x86_64.rpm.sh --help

Run the install as root or with a user that has sudo rights.

1. Download or copy the shell script to the computer desktop.

⚠️

Important

If you FTP the file, select binary (or BIN), for the transfer as the installer includes some binary code that becomes corrupted in AUTO or ASCII mode.

1. As root, change the mode of the installer to executable:

   chmod a+x adbridge-##.#.#.###.linux.x86_64.rpm.sh
   

2. As root, run the installer:

   ./adbridge-##.#.#.###.linux.x86_64.rpm.sh
   

3. Follow the instructions in the installer.

Install the agent on Linux in silent install mode

Install the agent in silent install mode using the install command. For example, on a 64-bit RPM-based Linux system, the installation command would look like the following:

./adbridge-##.#.#.###.linux.x86_64.rpm.sh install

Install the agent on Unix from the command line

Install the AD Bridge agent on Sun Solaris and IBM AIX by using a shell script that contains a self-extracting executable, an SFX installer with a file name that ends in sh.

✅

Example

adbridge-##.#.#.###.solaris.sparc.pkg.sh

The examples shown here are for Solaris Sparc systems. For other Unix platforms, use the appropriate installer name.

ℹ️

Note

The name of a Unix installer for AD Bridge on installation media might be truncated to an eight-character file name with an extension. For example, l3499sus.sh is the truncated version of adbridge-##.#.#.###.solaris.sparc_64.pkg.sh.

To view a list of command-line options, run the following command on 32-bit OS:

./adbridge-##.#.#.###.solaris.sparc_32.pkg.sh --help

On a 64-bit OS

./adbridge-##.#.#.###.solaris.sparc_64.pkg.sh --help

1. Download or copy the installer to the computer desktop.
2. Change directories to the desktop.
3. As root, change the mode of the installer to executable:

chmod a+x adbridge-##.#.#.###.solaris.sparc_32.pkg.sh

On a 64-bit OS:

chmod a+x adbridge-##.#.#.###.solaris.sparc_64.pkg.sh

4. As root, run the installer:

   ./adbridge-##.#.#.###.solaris.sparc_32.pkg.sh
   

   On a 64-bit OS:

   ./adbridge-##.#.#.###.solaris.sparc_64.pkg.sh
   

5. Follow the instructions in the installer.

Install the agent in Solaris zones

Solaris zones are a virtualization technology created to consolidate servers. Primarily used to isolate an application, Solaris zones act as isolated virtual servers running on a single operating system, making each application in a collection of applications seem as though it is running on its own server. A Solaris Container combines system resource controls with the virtual isolation provided by zones.

Every zone server contains a global zone that retains visibility and control in any installed non-global zones. By default, the non-global zones share certain directories, including /usr, which are mounted read-only. The shared directories are writable only for the global zone.

By default, installing AD Bridge in the global zone results in it being installed in all the non-global zones. You can, however, use the following commands to control the zones that you install to.

Install options for embedded scripts

Use the following commands to pass the option to the embedded script.

Post install

To complete the installation after a new child zone is installed, booted, and configured, run the following command in the zone as root:

/opt/pbis/bin/postinstall.sh

You cannot join zones to Active Directory as a group. Each zone, including the global zone, must be joined to the domain independently of the other zones.

Caveats

There are some caveats when using AD Bridge with Solaris zones.

When you join a non-global zone to AD, an error occurs when AD Bridge tries to synchronize the Solaris clock with AD.

The error occurs because the root user of the non-global zone does not have root access to the underlying global system and thus cannot set the system clock. If the clocks are within the 5-minute clock skew permitted by Kerberos, the error will not be an issue.

Otherwise, you can resolve the issue by manually setting the clock in the global zone to match AD or by joining the global zone to AD before joining the non-global zone.

Some group policy settings may log PAM errors in the non-global zones even though they function as expected. The cron group policy setting is one example:

Wed Nov 7 16:26:02 PST 2009 Running Cronjob 1 (sh)
            Nov 7 16:26:01 zone01 last message repeated 1 time
        Nov 7 16:27:00 zone01 cron[19781]: pam_lsass(cron): request failed

Depending on the group policy setting, these errors may result from file access permissions, attempts to write to read-only directories, or both.

By default, Solaris displays auth.notice syslog messages on the system console. Some versions of AD Bridge generate significant authentication traffic on this facility-priority level, which may lead to an undesirable amount of chatter on the console or clutter on the screen.

To redirect the traffic to a file instead of displaying it on the console, edit your /etc/syslog.conf file as follows:

Change this:

*.err;kern.notice;auth.notice /dev/sysmsg

To this:

*.err;kern.notice /dev/sysmsg
        auth.notice /var/adm/authlog

⚠️

Important

Make sure that you use tabs, not spaces, to separate the facility.priority information (on the left) from the action field (on the right). Using spaces will cue syslog to ignore the entire line.

AD Bridge on Solaris 11

This section is intended for administrators installing AD Bridge to Solaris targets.

What's new with the AD Bridge Solaris 11 installer

There are two ways to install Solaris 11:

• Traditional shell script using the legacy SVR4 packaging mechanism
• IPS repository install using Oracle's preferred IPS packaging mechanism

There is a P5P file that can be uploaded to your local IPS repository.

Upload packages with the P5P file

If using the pkgrecv command.

✅

Example

pkgrecv –s ./adbridge-##.#.#.###-solaris11-<ARCH>.p5p –d <repository> adbridge.<ARCH>

Confirm the package added to repository

Verify that the AD Bridge package with publisher BeyondTrust has been added to the repository:

pkgrepo list –s <repository>

Install the agent in Solaris 11 zones

After the files are uploaded to the local IPS repository and the global zone can access the IPS repository, then non-global zones can also access the repository.

In the zone, run the following IPS package command:

pkg install ADBridge\*

Upgrade an operating system using AD Bridge

Follow the steps to upgrade an operating system:

• Leave the domain.
• Uninstall the agent.
• Upgrade the operating system.
• Install the correct agent for the new version of the operating system.
• Join an Active Directory domain.

ℹ️

Note

For more information about uninstalling agents, see Install the AD Bridge agent.

Configure SELinux in AD Bridge

ℹ️

Note

Be sure to review the latest SELinux documentation. Start with the SELinux wiki.

Install SELinux on unsupported platforms

If you install SELinux on an unsupported platform, a message similar to the following is displayed:

SELinux found to be present, enabled, and enforcing. You may either provide a policy at /opt/pbis/share/pbis.pp --OR-- SELinux must be disabled or set to permissive mode by editing the file /etc/selinux/config and rebooting. For instructions on how to edit the file to disable SELinux, see the SELinux man page.

1. Create a compiled policy. To get started creating an SELinux policy for AD Bridge, use existing policy sources located under version directories: /opt/pbis/share/rhel.
2. Rename the policy pbis.pp and place it in the /opt/pbis/share directory.
3. Run the installation again. The pbis.pp file is installed.

Configure SELinux after installation

After installation of AD Bridge with SELinux, security denials might occur. Security denials caused by the current policy are reported in the /var/log/audit/audit.log log file.

You can resolve security denial issues automatically or manually.

Automatically resolve security denials

To create a policy to resolve existing denials involving applications and resources with pbis in the name:

1. Type:

   grep pbis /var/log/audit/audit.log | audit2allow -M pbislocal
   

2. The file pbislocal.pp is a compiled policy module and can be loaded with semodule -i pbislocal.pp.

Manually resolve security denials

The procedure is similar to automatically resolving security denials. However, you can edit the policy file pbislocal.te:

1. Type:

   grep pbis /var/log/audit/audit.log | audit2allow -m pbislocal > pbislocal.te
   

2. To build a compiled policy, execute the following command in the directory where pbislocal.te is located:

   make -f /usr/share/selinux/devel/Makefile
   

3. Load the module with semodule -i pbislocal.pp.