Merge of documentation updates to HEAD. These got missed somewhere along

[ira/wip.git] / docs / textdocs / samba-pdc-howto.txt

The Samba 2.2 PDC HowTo

David Bannon

   La Trobe University
     _________________________________________________________________
     _________________________________________________________________
   
   Comments, corrections and additions to <dbannon@samba.org>
   
   This document explains how to setup Samba as a Primary Domain
   Controller and applies to version 2.2.0. Before using these functions
   make sure you understand what the controller can and cannot do. Please
   read the sections below in the Introduction. As 2.2.0 is incrementally
   updated this document will change or become out of date very quickly,
   make sure you are reading the most current version.
   
   Please note this document does not apply to Samba2.2alpha0,
   Samba2.2alpha1, Samba 2.0.7, TNG nor HEAD branch.
   
   It does apply to the current (post November 27th) cvs.
   
   Also available is an updated version of Jerry Carter's NTDom FAQ that
   will answer lots of the special 'tuning' questions that are not
   covered here. Over the next couple of weeks some of the items here
   will be moved to the FAQ.
   
   Table of Contents
   1. Introduction
          
        What can we do ?
        What can't we do ?
                
   2. Installing
          
        Start Up Script
        Config File
                
              A sample conf file
              PDC Config Parameters
                      
        Special directories
                
   3. User and Machine Accounts
          
        Logon Accounts
        Machine Accounts
        Joining the Domain
        User Accounts
        Domain Admin Accounts
                
   4. Profiles, Policies and Logon Scripts
          
        Profiles
        Policies
        Logon Scripts
                
   5. Passwords and Authentication
          
              Syncing Passwords
              Using PAM
              Authenticating other Samba Servers
                      
   6. Background
          
              History
              The Future
              Getting further help
     _________________________________________________________________
   
Chapter 1. Introduction

   This document will show you one way of making Version 2.2.0 of Samba
   perform some of the tasks of a NT Primary Domain Controller. The
   facilities described are built into Samba as a result of development
   work done over a number of years by a large number of people. These
   facilities are only just beginning to be officially supported and
   although they do appear to work reliably, if you use them then you
   take the risks upon your self. This document does not cover the
   developmental versions of Samba, particularly Samba-TNG
   
   Note that Samba 2.0.7 supports significently less of the NT Domain
   facilities compared with 2.2.0
   
   This document does not replace the text files DOMAIN_CONTROL.txt,
   DOMAIN.txt (by John H Terpstra) or NTDOMAIN.txt (by Luke Kenneth
   Casson Leighton). Those documents provide more detail and an insight
   to the development cycle and should be considered 'further reading'.
     _________________________________________________________________
   
What can we do ?

     * Permit 'domain logons' for Win95/98, NT4 and W2K workstations from
       one central password database. WRT W2K, please see the section
       about adding machine accounts and the Intro in the FAQ.
     * Grant Administrator privileges to particular domain users on an NT
       or W2K workstation.
     * Apply policies from a domain policy file to NT and W2K (?)
       workstation.
     * Run the appropriate logon script when a user logs on to the domain
       .
     * Maintain a user's local profile on the server.
     * Validate a user using another system via smb (such as smb_pam) and
       soon winbind (?).
     _________________________________________________________________
   
What can't we do ?

     * Become or work with a Backup Domain Controller (a BDC).
     * Participate in any sort of trust relationship (with either Samba
       or NT Servers).
     * Offer a list of domain users to User Manager for Domains on the
       Security Tab etc).
     * Be a W2K type of Domain Controller. Samba PDC will behave like an
       NT PDC, W2K workstations connect in legacy mode.
     _________________________________________________________________
   
Chapter 2. Installing

   Installing consists of the usual download, configure, make and make
   install process. These steps are well documented elsewhere. The FAQ
   discusses getting pre-release versions via CVS. Then you need to
   configure the server.
     _________________________________________________________________
   
Start Up Script

   Skip this section if you have a working Samba already. Everyone has
   their own favourite startup script. Here is mine, offered with no
   warrantee at all !


        #!/bin/sh
        # Script to control Samba server, David Bannon, 14-6-96
        #
        #
        PATH=/bin:/usr/sbin:/usr/bin
        export PATH
        case "$1" in
        'start')
                if [ -f /usr/local/samba/bin/smbd ]
                then
                        /usr/local/samba/bin/smbd -D
                        /usr/local/samba/bin/nmbd -D
                        echo "Starting Samba Server"
                fi
                ;;
        'conf')
                if [ -f /usr/local/samba/lib/smb.conf ]
                then
                        vi /usr/local/samba/lib/smb.conf
                fi
                ;;
        'pw')
                if [ -f /usr/local/samba/private/smbpasswd ]
                then
                        vi /usr/local/samba/private/smbpasswd
                fi
                ;;
        'who')
                /usr/local/samba/bin/smbstatus -b
                ;;
        'restart')
                psline=`/bin/ps  x | grep smbd | grep -v grep`

                if [ "$psline" != "" ]
                then
                        while [ "$psline" != "" ]
                        do
                                psline=`/bin/ps x | fgrep smbd | grep -v grep`
                                if [ "$psline" ]
                                then
                                        set -- $psline
                                        pid=$1
                                        /bin/kill -HUP $pid
                                        echo "Stopped $pid line = $psline"
                                        sleep 2
                                fi
                        done
                fi
                echo "Stopped Samba servers"
                ;;
        'stop')
                psline=`/bin/ps  x | grep smbd | grep -v grep`

                if [ "$psline" != "" ]
                then
                        while [ "$psline" != "" ]
                        do
                                psline=`/bin/ps x | fgrep smbd | grep -v grep`
                                if [ "$psline" ]
                                then
                                        set -- $psline
                                        pid=$1
                                        /bin/kill -9 $pid
                                        echo "Stopped $pid line = $psline"
                                        sleep 2
                                fi
                        done
                fi
                echo "Stopped Samba servers"
                psline=`/bin/ps x | grep nmbd | grep -v grep`
                if [ "$psline" ]
                then
                        set -- $psline
                        pid=$1
                        /bin/kill -9 $pid
                        echo "Stopped Name Server "
                fi
                echo "Stopped Name Servers"
                ;;
        *)
                echo "usage: samba {start | restart |stop | conf | pw | who}"
                ;;
        esac


   Use this script, or some other one, you will need to ensure its used
   while the machine is booting. (This typically involves /etc/rc.d,
   we'll be assuming that there is a script called samba in
   /etc/rc.d/init.d further down in this document.)
     _________________________________________________________________
   
Config File

A sample conf file

   Here is a fairly minimal config file to do PDC. It will also make the
   server become the browse master for the specified domain (not
   necessary but usually desirable). You will need to change only two
   parameters to make this file work, wins server and workgroup, plus you
   will need to put your own name (not mine!) in the domain admin users
   fields. Some of the parameters are discussed further down this
   document.
   
   Assuming you have used the default install directories, this file
   should appear as /usr/local/samba/lib/smb.conf. It should not be
   writable by anyone except root.
   
     Note: The 'add user script' parameter is a work-around, watch for
     changes !
     


        [global]
        security = user
        status = yes
        workgroup = { Your domain name here }
        wins server = { ip of a wins server if you have one }
        encrypt passwords = yes
        domain logons =yes
        logon script = scripts\%U.bat
        domain admin group = @adm
        add user script = /usr/sbin/adduser -n -g machines -c Machine -d /dev/n
ull -s /bin/false %m$
        guest account = ftp
        share modes=no
        os level=65
        [homes]
        guest ok = no
        read only = no
        create mask = 0700
        directory mask = 0700
        oplocks = false
        locking = no
        [netlogon]
        path = /usr/local/samba/netlogon
        writeable = no
        guest ok = no

     _________________________________________________________________
   
PDC Config Parameters

   There are a huge range of parameters that may appear in a smb.conf
   file. Some that may be of interest to a PDC are :
   
   add user script
          This parameter specifies a script (or program) that will be run
          to add a user to the system. Here it is being used to add a
          machine, not a user. This is probably not very nice and may
          change. But it does work !
          
          For this example, I have a group called 'machines', entries can
          be added to /etc/passwd using a programme called /usr/adduser
          and the other parameters are chosen as suitable for a machine
          account. Works for RH Linux, your system may require changes.
          
   domain admin group = @adm
          This parameter specifies a unix group whose members will be
          granted admin privileges on a NT workstation when logged onto
          that workstation. See the section called Domain Admin Accounts.
          
   domain admin users = user1 users2
          It appears that this parameter does not funtion correctly at
          present. Use the 'domain admin group' instread. This parameter
          specifies a unix user who will be granted admin privileges on a
          NT workstation when logged onto that workstation. See the
          section called Domain Admin Accounts.
          
   encrypt passwords = yes
          This parameter must be 'yes' to allow any of the recent service
          pack NTs to logon. There are some reg hacks that turn off
          encrypted passwords on the NTws itself but if you are going to
          use the smbpasswd system (and you should) you must use
          encrypted passwords.
          
   logon script = scripts\%U.bat
          This will make samba look for a logon script named after the
          user (eg joeblow.bat). See the section further on called Logon
          Scripts
          
     Note: Note that the slash is like this '\', not like this '/'. NT
     is happy with both, win95 is not !
     
   logon path
          Lets you specify where you would like users profiles kept. The
          default, that is in the users home directory, does encourage a
          bit of fiddling.
     _________________________________________________________________
   
Special directories

   You need to create a couple of special files and directories. Its nice
   to have some of the binaries handy too, so I create links to them.
   Assuming you have used the default samba location and have not changed
   the locations mentioned in the sample config file, do the following :


        mkdir /usr/local/samba/netlogon
        mkdir /usr/local/samba/netlogon/scripts
        mkdir /usr/local/samba/private
        touch /usr/local/samba/private/smbpasswd
        chmod go-rwx /usr/local/samba/private/smbpasswd
        cd /usr/local/sbin
        ln -s /usr/local/samba/bin/smbpasswd
        ln -s /usr/local/samba/bin/smbclient
        ln -s /etc/rc.d/init.d/samba

   Make sure permissions are appropriate !
   
   OK, if you have used the scripts above and have a path to where the
   links are do this to start up the Samba Server :
   
   samba start
   
   Instead, you might like to reboot the machine to make sure that you
   got the init stuff right. Any way, a quick look in the logs
   /usr/local/samba/var/log.smbd and /usr/local/samba/var/log/nmbd will
   give you an idea of what's happening. Assuming all is well, lets
   create some accounts...
     _________________________________________________________________
   
Chapter 3. User and Machine Accounts

Logon Accounts

   This section is very nearly out of date already ! It appears that
   while you are reading it, Jean Francois Micou is making it redundant !
   Jean Francois is adding facilities to add users (via User Manager) and
   machines (when joining the domain) and it looks like these facilities
   will make it into the official release of 2.2.
   
   Every user and NTws (and other samba servers) that will be on the
   domain must have its own passwd entry in both /etc/passwd and
   /usr/local/samba/private/smbpasswd . The /etc/passwd entry is really
   only to reserve a user ID. The NT encrypted password is stored in
   /usr/local/samba/private/smbpasswd. (Note that win95/98 machines don't
   need an account as they don't do any security aware things.)
   
   Samba 2.2 will now create these entries for us. Carefull set up is
   required and there may well be some changes to this system before its
   released.
     _________________________________________________________________
   
Machine Accounts

     Note: There is an entry in the ntdom FAQ explaining how to create
     machine entries manually.
     
   At present to have the machine accounts created when a machine joins
   the domain a number of conditions must be met :
   
   Only root can do it !
          There must be an entry in /usr/local/samba/private/smbpasswd
          for root and root must be mentioned in domain admins. This may
          be fixed some time in the future so any 'domain admin' can do
          it. If you don't like having root as a windows logon account,
          make the machine entries manually (both of them).
          
   Use the add user script
          Again, this looks a bit like a 'work around'. Use a suitable
          command line to add a machine account see above, and pass it
          %m$, that is %m to get machine name plus the '$'. Now, this
          means you cannot use the add user script to really add users
          ....
          
   Only for W2K
          This automatic creation of machine accounts does not work for
          NT4ws at present. Watch this space.
     _________________________________________________________________
   
Joining the Domain

   You must have either added the machine account entries manually (NT4
   ws) or set up the automatic system (W2K), see Machine Accounts before
   proceeding.
   
   Windows NT
          
          + (this step may not be necessary some time in the near
            future). On the samba server that is the PDC, add a machine
            account manually as per the instructions in the FAQ Then give
            the command smbpasswd -a -m {machine} substituting in the
            client machine name.
          + Logon to the NTws in question as a local admin, go to the
            Control Panel, Network IdentificationTag.
          + Press the Change button.
          + Enter the Domain name (from the 'Workgroup' parameter,
            smb.conf) in the Domain Field.
          + Press OK and after a few seconds you will get a 'Welcome to
            Whatever Domain'. Allow to reboot.
            
   Windows 2000
          
          + Logon to the W2k machine as Administrator, go to the Control
            Panel and double click on Network and Dialup Connections.
          + Pull down the Advanced menu and choose Network
            Identification. Press Properties .
          + Choose Domain and enter the domain name. Press 'OK'.
          + Now enter a user name and password for a Domain Admin (Who
            must be root until a pre-release bug is fixed) and press
            'OK'.
          + Wait for the confirmation, reboot when prompted.
            
          To remove a W2K machine from the domain, follow the first two
          steps then choose Workgroup, enter a work group name (or just
          WORKGROUP) and follow the prompts.
     _________________________________________________________________
   
User Accounts

   Again, doing it manually (cos' the auto way is not working
   pre-release). In our simple case every domain user should have an
   account on the PDC. The account may have a null shell if they are not
   allowed to log on to the unix prompt. Again they need an entry in both
   the /etc/passwd and /usr/local/samba/private/smbpasswd. Again a
   password is not necessary in /etc/passwd but the location of the home
   directory is honoured. To make an entry for a user called Joe Blow you
   would typically do the following :
   
   adduser -g users -c 'Joe Blow' -s /bin/false -n joeblow
   
   smbpasswd -a joeblow
   
   And you will prompted to enter a password for Joe. Ideally he will be
   hovering over your shoulder and will, when asked, type in a password
   of his choice. There are a number of scripts and systems to ease the
   migration of users from somewhere to samba. Better start looking !
     _________________________________________________________________
   
Domain Admin Accounts

   Certain operations demand that the logged on user has Administrator
   privileges, typically installing software and doing maintenance tasks.
   It is very simple to appoint some users as Domain Admins, most likely
   yourself. Make sure you trust the appointee !
   
   Samba 2.2 recognizes particular users as being domain admins and tells
   the NTws when it thinks that it has got one logged on. In the smb.conf
   file we declare that the Domain Admin group = @adm. Any user who is a
   menber of the unix group 'adm' is treated as a Domain Admin by a NTws
   when logged onto the Domain. They will have full Administrator rights
   including the rights to change permissions on files and run the system
   utilities such as Disk Administrator. Add users to the group by
   editing /etc/group/. You do not need to use the 'adm' group, choose
   any one you like.
   
   Further, and this is very new, they will be allowed to create a new
   machine account when first connecting a new NT or W2K machine to the
   domain. However, at present, ie pre-release, only a Domain Admin who
   also happens to be root can do so. 
     _________________________________________________________________
   
Chapter 4. Profiles, Policies and Logon Scripts

Profiles

   NT Profiles should work if you have followed the setup so far. A
   user's profile contains a whole lot of their personal settings, the
   contents of their desktop, personal 'My Documents' and so on. When
   they log off, all of the profile is copied to their directory on the
   server and is downloaded again when they logon on again, possibly on
   another client machine.
   
   Sounds great but can be a bit of a bug bear sometimes. Users let their
   profiles get too big and then complain about how long it takes to log
   on each time. This sample setup only supports NT profiles, rumor has
   it that it is also possible to do the same on Win95, my users don't
   know and I'm not telling them.
   
     Note: There is more info about Profiles (including for W95/98) in
     the FAQ.
     _________________________________________________________________
   
Policies

   Policies are an easy way to make or enforce specific characteristics
   across your network. You create a ntconfig.pol file and every time
   someone logs on with their NTws, the settings you put in ntconfig.pol
   are applied to the NTws. Typical setting are things like making the
   date appear the way you want it (none of these 2 figure years here) or
   maybe suppressing one of the splash screens. Perhaps you want to set
   the NTws so it does not keep users profiles on the local machine.
   Cool. The only problem is making the ntconfig.pol file itself. You
   cannot use the policy editor that comes with NTws.
   
     Note: See the FAQ for pointers on how to get a suitable Policy
     Editor.
     
   The Policy Editor (and associated files) will create a ntconfig.pol
   file using the parameters Microsoft thought of and parameters you
   specify by making your own template file.
   
   In our example configuration here, Samba will expect to find the
   ntconfig.pol file in /usr/local/samba/netlogon. Needless to say (I
   hope !), it is vitally important that ordinary users don't have write
   permission to the Policy files.
     _________________________________________________________________
   
Logon Scripts

   In the sample config file above there is a line logon script =
   scripts\%U.bat
   
     Note: Note that the slash is like this '\' not like this '/'. NT is
     happy with both, win95 is not !
     
   This allows you to run a dos batch file every time someone logs on.
   The batch file is located on the server, in the sample install
   mentioned here, its in /usr/local/samba/netlogon/scripts and is named
   after the user with .bat appended, eg Joe Blow's script is called
   /usr/local/samba/netlogon/scripts/joeblow.bat.
   
     Note: There is a suggestion that user names longer than 8
     characters may cause problems with some systems being unable to run
     logon scripts. This is confirmed in earlier versions when
     connecting using W95, comments about other combinations ??
     
   You could use a line like this logon script = default.bat and samba
   will supply /usr/local/samba/netlogon/default.bat for any client and
   every user. Maybe you could use %m and get a client machine dependant
   logon script. You get the idea...
   
   Note that the file is a dos batch file not a Unix script. It runs dos
   commands on the client computer with the logon user's permissions. It
   must be a dos file with each line ending with the dos cr/lf not a nice
   clean newline. Generally, its best to create the initial file on a DOS
   system and copy it across.
   
   There is lots of very clever uses of the Samba replaceable variables
   such ( %U = user, %G = primary group, %H = client machine, see the
   'man 5 smb.conf') to give you control over which script runs when a
   particular person logs on. (Gee, it would be nice to have a
   default.bat run when nothing else is available.)
   
   Again, it is vitally important that ordinary users don't have write
   permission to other peoples, or even probably their own, logon script
   files.
   
   A typical logon script is reproduced below. Note that it runs separate
   commands for win95 and NT, that's because NT has slightly different
   behaviour when using the net use .. command. Its useful for lots of
   other situations too. I don't know what syntax to use for win98, I
   don't use it here.


                rem Default logon script, create links to this file.

                net time \\bioserve /set /yes
                @echo off
                if %OS%.==Windows_NT. goto WinNT

                :Win95
                net use k: \\trillion\bio_prog
                net use p: \\bcfile\homes
                goto end
                :WinNT
                net use k: \\trillion\bio_prog /persistent:no
                net use p: \\bcfile\homes /persistent:no

                :end
     _________________________________________________________________
   
Chapter 5. Passwords and Authentication

   So far our configuration assumes that ordinary users don't have unix
   logon access. A change to the adduser line above would allow unix
   logon but it would be with passwords that may be different from the NT
   logon. Clearly that won't suit everyone. Trying to explain to users
   that they need to change their passwords in two seperate places is not
   fun. Further, even if they cannot do a unix logon there are other
   processes that might require authentication. We have a nice securely
   encrypted password in /usr/local/samba/private/smbpasswd, why not use
   it ?
     _________________________________________________________________
   
Syncing Passwords

   Yes, its possible and seems the easiest way (initially anyway). The
   FAQ details how to do so in the sections What is password sync and
   should I use it ? and How do I get remote password (unix and SMB)
   changing working ?
     _________________________________________________________________
   
Using PAM

   Pam enabled systems have a much better solution available. The Samba
   PDC server will offer to authenticate domain users to other processes
   (either on this server or on the domain). With a suitable pam stack
   such as Pam_smb you can get any pam aware application looking to the
   samba password and can leave the password field in /etc/shadow or
   /etc/passwd invalid.
     _________________________________________________________________
   
Authenticating other Samba Servers

   In a domain that has a number of servers you only need one password
   database. The machines that don't have their own ask the PDC to check
   for them. This will work fine for a domain controlled by either a
   Samba or NT machine.
   
   To do so the Samba machine must be told to refer to the PDC and where
   the PDC is. See the section in the NTDom FAQ called How do I get my
   samba server to become a member ( not PDC ) of an NT domain?
     _________________________________________________________________
   
Chapter 6. Background

History

   It might help you understand the limitations of the PDC in Samba if
   you read something of its history. Well, the history as I understand
   it anyway.
   
   For many years the Samba team have been developing Samba, some time
   ago a number of people, possibly lead by Luke Leighton started
   contributing NT PDC stuff. This was added to the 'head' stream (that
   would eventually become the next version) and later to a seperate
   stream (NTDom). They did so much that eventually this development
   stream was so mutated that it could not be merged back into the main
   stream and was abandoned towards the end of 1999. And that was very
   sad because many users, myself include had become heavily dependant on
   the NTController facilities it offered. Oh well...
   
   The NTDom team continued on with their new found knowledge however and
   built the TNG stream. Intended to be carefully controlled so that it
   can be merged back into the main stream and benefiting from what they
   learnt, it is a very different product to the origional NTDom product.
   However, for a number of reasons, the merge did not take place and now
   TNG is being developed at http://www.samba-tng.org.
   
   Now, the NTDom things that the main strean 2.0.x version does is based
   more on the old (initial version) abandoned code than on the TNG
   ideas. It appears that version 2.2.0 will also include an improved
   version of the 2.0.7 domain controller charactistics, not the TNG
   ways. The developers have indicated that 2.2.0 will be further
   developed incrementally and the ideas from TNG incorporated into it.
   
   One more little wriggle is worth mentioning. At one stage the NTDom
   stream was called Samba 2.1.0-prealpha and similar names. This is most
   unfortunate because at least one book published advises people who
   want to use NTDom Samba to get version 2.1.0 or later. As main stream
   Samba will soon be called 2.2.0 and NOT officially supporting NTDom
   Controlling functions, the potential for confusion is certainly there.
     _________________________________________________________________
   
The Future

   There is a document on the Samba mirrors called 'Development' . It
   offers the 'best guess' of what is planned for future releases of
   Samba.
   
   The future of Samba as a Primary Domain Controller appears rosie,
   however be aware that its the future, not the present. The developers
   are strongly committed to building a full featured PDC into Samba but
   it will take time. If this version does not meet your requirements
   then you should consider (in no particular order) :
   
     * Wait. No, we don't know how long. Repeated asking won't help.
     * Investigate the development versions, TNG perhaps or HEAD where
       new code is being added all the time. Realise that development
       code is often unstable, poorly documented and subject to change.
       You will need to use cvs to download development versions.
     * Join one of the Samba mailing lists so that you can find out what
       is happening on the 'bleeding edge'.
     _________________________________________________________________
   
Getting further help

   This document cannot possibly answer all your questions. Please
   understand that its very likely that someone has been confrounted by
   the same problem that you have. The FAQ discusses a number of possible
   paths to take to get further help :
   
     * Documents on the Samba Sites.
     * Other web sites.
     * Mailing list.
       
   There is some discussion about guide lines for using the Mailing Lists
   on the accompanying FAQ, please read them before posting.