PADL Software Pty Ltd

PADL Software Pty Ltd

 

About PADL

Articles

Commercial Software

Contacting PADL

Documentation

Open Source Software

Partners

Purchasing

Research and Development

Technical Support


 

Installation Instructions

This document describes installating the binary distribution of XAD.

The following conventions are used in this document:

  • Examples are shown in a fixed space font
  • Commands to be typed by the user are shown in bold fixed space font
  • The "#" prompt is used to signify that you should be logged in as root; "%" is used otherwise

1. Unpacking the distribution

The binary distribution of XAD consists of a set of RPMs. There are separate packages for SuSE Linux 9.1 and Red Hat Enterprise Linux 3.

Please note that at present, other operating systems, architectures, and distributions are not supported.

DescriptionSuSE 9.1RHEL 3
XAD Directory Services (DB)xad_db-7-1.i586.rpmxad_db-7-1.i386.rpm
XAD Directory Services (DNS)xad_bind-3-2.i586.rpmxad_bind-3-2.i586.rpm
XAD Directory Services (LDAP)xad_ldap-2.2.17-2.i586.rpmxad_ldap-2.2.17-2.i386.rpm
XAD Directory Services (Local Cache)nss_updatedb-1-3.i586.rpmnss_updatedb-1-3.i386.rpm
XAD Directory Services (Name Service Integration)nss_ldap-226-1.i586.rpmnss_ldap-226-1.i386.rpm
XAD Domain Services (Framework)xad_framework-327-1.i586.rpmxad_framework-327-1.i386.rpm
XAD Domain Services (RPC Runtime)xad_dcerpc-47-1.i586.rpmxad_dcerpc-47-1.i386.rpm
XAD Domain Services (SMB Server)xad_samba-14-1.i586.rpmxad_samba-14-1.i386.rpm
XAD Security Services (Cached Credentials Authentication)pam_ccreds-1-3.i586.rpmpam_ccreds-1-3.i386.rpm
XAD Security Services (Kerberos)xad_heimdal-87-1.i586.rpmxad_heimdal-87-1.i386.rpm
XAD Security Services (LDAP Authentication)pam_ldap-176-1.i586.rpmpam_ldap-176-1.i386.rpm
XAD Security Services (Kerberos Authentication)pam_krb5-4-1.i586.rpmpam_krb5-4-1.i386.rpm
XAD Security Services (OpenSSL)Not requiredxad_openssl-0.9.7d-1.i386.rpm
XAD Security Services (SASL)xad_sasl-19-1.i586.rpmxad_sasl-19-1.i386.rpm
XAD Security Services (Network Time)xad_ntp-1-1.i586.rpmxad_ntp-1.1.i386.rpm

Please note that the version numbers may differ from those above.

RPM will install these in order of dependency. Pre-requisite packages for all installations include Perl and make. RHEL in addition requires its own OpenSSL library, because the one shipped is linked against a different (and incompatible) Kerberos library.

For SuSE Linux:

# mkdir /tmp/xad
# cd /tmp/xad
# tar xzvf xad_linux-i586-suse.tar.gz
# cd /tmp/xad/usr/src/redhat/RPMS/i586
# rpm –Uvh *.rpm

For RHEL:

# mkdir /tmp/xad
# cd /tmp/xad
# tar xzvf xad_linux-i386-rh.tar.gz
# cd /tmp/xad/usr/src/redhat/RPMS/i386
# rpm –Uvh *.rpm

Binaries for all packages are installed into /usr/xad. However, a symbolic link is created from /usr/xad/lib/libnss_ldap.so.2 into /lib.

When installing on SuSE Linux 9.1, ensure that you have NPTL installed (check that /lib/tls exists). It appears that some versions of glibc shipped with SuSE Linux 9.1 included only LinuxThreads.

The installation cannot be relocated in this release (at least not without providing a symbolic link into /usr/xad). Thus, ensure that you have sufficient space on the root or /usr partition for installing XAD and creating your database.

NB: If you wish to use group policies, the file system hosting the system volume (/usr/xad/var/sysvol) must support POSIX ACLs. You may need to add the "acl" option to /etc/fstab to enable this.

2. Configuring a new domain

The dcinit script performs most tasks involved in configuring a new domain. This must be run as root. You must accept the End User License Agreement before installation will proceed.

NB: the default database cache size is 64 MB. If you are running on a system with limited memory, you may wish to reduce this; edit the file /usr/xad/share/dcinit/templates/DB_CONFIG.

The local machine name should be listed in /etc/hosts with a non-loopback IP address, with either the unqualified host name or the host name with the suffix of the domain being configured. The system hostname must be set similarly. These steps are critical; clients may not be able to local the directory server otherwise.

If you intend to use SSL/TLS with XAD, please read XAD PKI Configuration Notes.

When running dcinit, you will be prompted for the DNS and downlevel (NetBIOS) domain name. You must enter an administrator password when prompted; this cannot be aborted.

An example run of dcinit is provided below:

# /usr/xad/sbin/dcinit
You must read and accept the End User License Agreement to continue.
Press enter to display it.
...
Do you accept? (yes/no) yes
Enter the domain name for this domain: [] xad.example.com
Enter the downlevel name for this domain: [XAD] EXAMPLE-XAD
Do you want this machine to be a primary DNS server: [no] yes
====================================================================
        Root Domain: DC=xad,DC=example,DC=com
             Forest: DC=xad,DC=example,DC=com
       Netbios Name: EXAMPLE-XAD
        Domain GUID: ebd2c9f4-e811-11d7-822d-0000e2589820
         Domain SID: S-1-5-21-546855138-11650-299362321
====================================================================
>>> Cleaning staging directory tree
>>> Preparing staging directory tree
>>> Saving copy of domain configuration
>>> Configuring Domain Name Server
>>> Configuring nss_ldap
>>> Creating startup scripts
>>> Preparing LinkEngine Naming Context
>>> Preparing Schema Naming Context
>>> Generating Aggregate Schema
>>> Preparing Configuration Naming Context
>>> Preparing Domain Naming Context
>>> Configuring XAD Directory Services
>>> Configuring XAD Security Services
>>> Configuring System Volume
>>> Configuring Group Policy Objects
>>> Configuring SMB Server
>>> Configuring XAD Domain Services
>>> Making staging directory tree live
>>> Removing Domain DIB
>>> Removing Configuration DIB
>>> Removing Schema DIB
>>> Removing LinkEngine DIB
>>> Importing LinkEngine Naming Context into LDAP Server (off-line)
>>> Importing Schema Naming Context into LDAP Server (off-line)
>>> Starting LDAP Server in Administration Mode
...
>>> Importing Configuration Naming Context into LDAP Server
>>> Importing Config Naming Context (Back-Links) into LDAP Server
>>> Importing Domain Naming Context (Back-Links) into LDAP Server
>>> Stopping LDAP Server
...
>>> Starting LDAP Server in Administration Mode (GC)
...
>>> Setting krbtgt password
Changing XAD password for krbtgt...
>>> Setting machine password
Changing XAD password for DC1$...
>>> Setting Administrator password
Changing XAD password for Administrator...
New XAD password:
Verify XAD password:
>>> Configuring Kerberos keytab
>>> Stopping LDAP Server (GC)
...
>>> Cleaning staging directory tree

Configure XAD for automatic startup with following command:

# chkconfig xad on

Once dcinit has run, you will need to configure DNS and nss_ldap. Instructions for doing so are provided below.

3. Configuring DNS

If you answered “yes” to the question “Do you want this machine to be a primary DNS server?” when running DNS, then the DNS server (BIND) will be configured and started by the XAD startup script. By default it will be configured to accept Kerberos secured dynamic DNS updates from Windows clients.

If you answered “no” to this question, you can promote the machine to a primary DNS server by moving /usr/xad/etc/named.conf.default to /usr/xad/etc/named.conf; BIND will be started the next time XAD is started.

The DNS zone file is named domain.dns.tld.zone and is placed in /usr/xad/var/named; for example, the zone file for xad.example.com would be found in /usr/xad/var/named/xad.example.com.zone. You can move this file to another machine, and edit the NS record appropriately, if you do not wish to use the machine on which you installed XAD as a name server.

BIND is not configured to perform recursive name resolution, nor is it configured to forward DNS queries to another name server. It is authoritative only for the localhost, 0.0.127.in-addr.arpa domains, along with the XAD domain you configured.

NB: If you are running BIND on the domain controller, you should also use it for name resolution by placing the following lines in /etc/resolv.conf:

nameserver 127.0.0.1
search xad.example.com

In order to perform Internet name resolution, you will also need to do one or both of the following:

1. Configure BIND to query the root name servers for the Internet by adding the following to /etc/named.conf:

zone “.” {
    type hint;
    file “root.hint”;
};

2. Remove the “recursion no” directive, and add a “forwarders” line with the IP address of your upstream DNS server, so that the “options” stanza looks similar to the following:

options {
    directory “/usr/xad/var/named”;

    forwarders {
        1.2.3.4; // put your upstream DNS server here
    };
};

4. Configuring nss_ldap

The nss_ldap library allows the local POSIX environment to resolve users and groups a XAD domain. While configuring nss_ldap is optional, it is highly recommended; should you choose not to configure nss_ldap, you will need to synchronise XAD and POSIX accounts manually; this includes machine accounts (accounts ending with a ‘$’ sign, for example ‘DC1$’). With even a small domain the administrative overhead of doing this is significant.

Because system name service configuration is sensitive, dcinit does not enable nss_ldap for you. You must do this manually, by changing the following lines in /etc/nsswitch.conf:

passwd: compat
group: compat

to:

passwd: files ldap
group: files ldap

The name service cache daemon, nscd, must be restarted after running dcinit:

# /etc/init.d/nscd restart

See the PADL Documentation page for more information on configuring nss_ldap.

5. Configuring time services

By default, the Network Time Protocol (NTP) daemon is started on every domain controller. The version shipped with XAD has been enhanced to support signing responses in a manner compatible with the Windows Network Time service (w32time).

If you are running an existing NTP server, you have two choices:

  • Disable the XAD network time service by removing /usr/xad/etc/ntp.conf; you will need to configure Windows clients manually to use the new time server (they will not accept unsigned responses from ordinary NTP servers)
  • Migrate your existing NTP configuration to the XAD network time service

Note that only the master domain controller (PDC emulator) for the forest root is advertised as a "good" time server. When provisioning a replica, NTP follows the replication hierarchy. You can explicitly set the default NTP server by adding a "NTP Server" entry to /usr/xad/etc/xad.ini and regenerating the XAD configuration files with "dcmake rebuild_config".

6. Starting XAD

XAD should be started with the following command:

# /etc/init.d/xad start

Starting XAD services:
Domain Name Server                                         done
DCE RPC endpoint mapper                                    done
XAD Directory Services                                     done
XAD Security Services (KDC)                                done
XAD Security Services (Kerberos Password Change)           done
XAD Domain Services                                        done
NetBIOS Name Server                                        done
CIFS Server                                                done
CIFS Identity Mapper                                       done

Note that sometimes one or more services will appear to not start (“failed” instead of “done”) above), even though they have started. This is a known issue and is being investigated. The output above may differ between distributions.

7. Validating DNS and XAD Directory Services configuration

First, validate your DNS configuration with the following command (note that this is analogous to performing nltest /dsgetdc under Windows). The output should appear similar to the following:

% provision --locate-dc xad.example.com
XAD Domain Controller Provisioning Tool
Copyright (c) 2003 PADL Software Pty Ltd. All rights reserved.

           DC: \\dc1.xad.example.com
      Address: \\192.168.32.1
     Dom Guid: a0a87366-1956-1027-89f0-d7f332e2a7d3
     Dom Name: xad.example.com
  Forest Name: xad.example.com
 Dc Site Name: Default-First-Site
Our Site Name: Default-First-Site
        Flags: PDC GC DS LDAP KDC TIMESERV CLOSEST WRITABLE DNS_DC DNS_DOMAIN DNS_FOREST

Note that replicas will not show the PDC or WRITABLE flags.

If the above command fails, use the “nslookup” command to check that a DNS SRV record for the LDAP domain controller service can be located:

# nslookup
> set querytype=ANY
> _ldap._tcp.dc._msdcs.xad.example.com
Server: 192.168.32.1
Address: 192.168.32.1#53
_ldap._tcp.dc._msdcs. xad.example.com service = 0 100 389 dc1.xad.example.com.
> quit

If this fails, double-check that you configured DNS correctly using the instructions above. Note that replica SRV records must presently be added manually. If this succeeds, yet locating the DC failed, check the file /usr/xad/var/log/slapi.log for any error messages.

8. Validating XAD Security Services configuration

You can verify that XAD Security Services are running by attempting to acquire Kerberos credentials for Administrator. The Administrator password is that which you entered when running dcinit.

% kinit Administrator
Administrator@XAD.EXAMPLE.COM's Password:

You may also wish to perform a simple LDAP search (the search criteria below is arbitrary):

% ldapsearch -h localhost -LLL samAccountName=Administrator canonicalName
SASL/GSS-SPNEGO authentication started
SASL username:Administrator@XAD.EXAMPLE.COM
SASL SSF: 56
SASL installing layers
dn: cn=Administrator,cn=Users,dc=xad,dc=example,dc=com
canonicalName: xad.example.com/Users/Administrator

# refldap://xad.example.com/cn=Configuration,dc=xad,dc=example,dc=com??sub

9. Validating XAD Domain Services configuration

To validate that XAD Domain Services is operational:

% rpcclient -k localhost
rpcclient $> dsroledominfo
Machine Role = [5]
Directory Service is running.
Domain is in native mode.
rpcclient $> quit

A common reason for this not working is no UNIX account existing for Administrator – ensure that you have added an entry to /etc/passwd or have configured nss_ldap.

10. Joining a machine to the domain

These instructions apply to Windows XP. If you are using Windows 2000, note that SP3 or later is recommended.

  • Open Control Panel on the client
  • Double-click on System
  • Open the “Computer Name” tab
  • Click “Change”
  • Enter the DNS domain name in the “Domain” field
  • Enter the Administrator user name and password when prompted

11. Creating a user

First, authenticate to Kerberos (you do not need to be logged in as root, but you will need to authenticate as the Administrator):

% kinit Administrator
Administrator@XAD.EXAMPLE.COM's Password:
% pgo -D xad.example.com -s mallen -t user --add "Michael Allen"
XAD User and Group Provisioning Tool
Copyright (c) 2003 PADL Software Pty Ltd. All rights reserved.
Password:
Verify password:
Created user "Michael Allen"

Users can be created using just LDAP; the only mandatory attributes are the distinguished name and the object class, although usually you will wish to set the sAMAccountName attribute to the user's logon name to avoid one being randomly assigned. You may also wish to use the xad-adduser.sh and xad-deluser.sh scripts, which create user home and profile directories in addition to creating an account.

12. Common administrative tasks

  • Recovering the directory after a dirty shutdown (this is automatically performed by the startup script)
    # /usr/xad/sbin/dcmake recover_db
  • Backing up the directory (LDIF files will be in /usr/xad/var/ds/*/backup.ldif)
    # /usr/xad/sbin/dcmake backup_db
  • Re-provisioning a domain (this will destroy all information in the existing domain)
    # /usr/xad/sbin/dcmake unconfigure remove_db
    # /usr/xad/sbin/dcinit
  • Re-provisioning a domain, maintaining the existing domain GUID and SID (this will destroy all information in the existing domain)
    # /usr/xad/sbin/dcmake all

13. Configuring a replica

Configuring a replica is similar to configuring a new domain, except that the dcrepl script is used instead of dcinit. You must acquire administrator Kerberos credentials on the new replica, which may require manual configuration (at least DNS should be functional).

# kinit Administrator@XAD.EXAMPLE.COM
Administrator@XAD.EXAMPLE.COM's Password:
kinit: NOTICE: ticket renewable lifetime is 1 week
# dcrepl dc1.xad.example.com
You must read and accept the End User License Agreement to continue.
Press enter to display it.
...
Do you accept? (yes/no) yes
=========================================================================
        Root Domain: DC=xad,DC=example,DC=com
          Forest NC: DC=xad,DC=example,DC=com
       Netbios Name: EXAMPLE-XAD
        Domain GUID: ebd2c9f4-e811-11d7-822d-0000e2589820
         Domain SID: S-1-5-21-546855138-11650-299362321
=========================================================================
>>> Cleaning staging directory tree
>>> Preparing staging directory tree
>>> Saving copy of domain configuration
>>> Configuring Domain Name Server
>>> Configuring nss_ldap
>>> Creating startup scripts
>>> Preparing Schema Naming Context
>>> Generating Aggregate Schema
>>> Configuring XAD Directory Services
>>> Configuring XAD Security Services
>>> Configuring System Volume
>>> Configuring Group Policy Objects
>>> Configuring SMB Server
>>> Configuring XAD Domain Services
>>> Removing /usr/xad/var/locks
>>> Removing /usr/xad/var/run
>>> Making staging directory tree live
>>> Removing old machine account (if necessary)
>>> Removing old keytab (if necessary)
>>> Joining this machine to the domain
Created domain controller account <CN=DC2,ou=Domain Controllers,dc=xad,dc=example,dc=com>
Created server object <cn=DC2,cn=Servers,cn=Default-First-Site-Name,cn=Sites,cn=Configuration,dc=xad,dc=example,dc=com>
Created DSA settings object <cn=NTDS
Settings,cn=DC2,cn=Servers,cn=Default-First-Site-Name,cn=Sites,cn=Configuratio n,dc=xad,dc=example,dc=com>
Set Kerberos password for SAM account DC2$
Extracted machine password to keytab /usr/xad/var/ds/kdc/krb5.keytab
>>> Removing Domain DIB
>>> Removing Configuration DIB
>>> Removing Schema DIB
>>> Removing LinkEngine DIB
>>> Cleaning staging directory tree

The replica will sync with the master DSA when it is first started. Once you have verified that the replica is operating correctly, then you should publish DNS SRV records for the replica in DNS (these should be identical to the master except that you should not publish a SRV record for the "_pdc" service). You can use the /usr/xad/var/share/dcinit/genReplicaDNSConfig.pl script to create the necessary resource records to add to DNS.

14. Miscellaneous

Seven daemons are started when XAD is booted. These are listed below, in order of dependency:

  • kdc: XAD Security Services (KDC)
  • named: Domain Name Server
  • nmbd: NetBIOS Name Server
  • ntpd: XAD Security Services (Network Time)
  • rpcd: DCE RPC endpoint mapper
  • slapd: XAD Directory Services
  • smbd: CIFS file server
  • winbindd: CIFS security identity mapper
  • xadsd: XAD Domain Services
  • xadpasswdd: XAD Security Services (Kerberos Password Change)

xadsd will send output to syslog.

For further debugging, you can start xadsd in interactive mode with the –F option. If you have a checked build, you can also start it in verbose debugging mode with the –d option – note that this will generate a lot of debug output.

Other XAD-specific log files are to be found in /usr/xad/var/log:

  • /usr/xad/var/log/slapi.log: LDAP server plug-in log file
  • /usr/xad/var/log/kdc.log: Kerberos KDC log file
  • /usr/xad/var/log/samba.*: CIFS server log files

You may wish to disable storage of LAN Manager (LM) hashes. To do this, enter the following command on a domain controller:

# /usr/xad/sbin/provision -p NoLMHash -v 1 --set-ds-property localhost

15. Directory structure

/usr/xad all files (except for nss_ldap and pam_ldap) are below this root

  • bin: user tools
  • lib: shared libraries and plugins
  • lib/sasl2: SASL plugins
  • lib/perl/XAD: dcinit Perl modules
  • libexec: system daemons
  • man: manual pages
  • private: used by the SMB server
  • sbin: administrator tools
  • share: architecture-agnostic files
  • share/dcinit: domain controller provisioning tools and templates
  • var: user data
  • var/ds: directory service data
  • var/ds/config: configuration partition
  • var/ds/domain: domain partition
  • var/ds/kdc: KDC configuration (this is symbolically linked to /var/heimdal)
  • var/ds/linkengine: back-link partition
  • var/ds/schema: schema partition
  • var/log: log files
  • var/netlogon: Net Logon share
  • var/rpc: RPC end points
  • var/run: PID files, other run time information
  • var/sysvol: System Volume share

Note that the aforementioned symbolic links are always recreated at provisioning time.

There are no configuration files in the default distribution; these are created from templates when the domain controller is provisioned.

16. Administrative tools

The provision, pgo, and xtrust tools are provided for ongoing maintainence of the XAD directory. dcinit and dcrepl are used, respectively, to provision new and replica directory servers. In addition, you may use the kadmin program in local mode to manage Kerberos attributes of principals. Note that this tool can only be used to manage Kerberos principal attributes.

Active Directory  management tools can be used, with some limitations, to manage XAD directory information. The NT 4.0 user and group management tools are not supported.


Home | Bugzilla

Copyright 2004 PADL Software Pty Ltd ABN 16 085 895 585. All rights reserved.
PADL is a registered trademark of PADL Software Pty Ltd.