How to use Winbind authentication with Debian-edu
-------------------------------------------------

$Id$

What is Winbind authentication
------------------------------
Winbind authentication is a methode of using a Windows Domain Controller
running Active Directory (AD) for authentication, instead of LDAP which is
used in a normal Debian-edu installation.

What makes Winbind differ from LDAP
-----------------------------------
Although AD is based on LDAP, it is not straight forward to use Active
Directory as a ldapserver. There used to be some addon for AD to make it
work like a normal LDAP-server, and make it possible for Unix-clients to
authenticate against it, but this addon is no longer availible/maintained.


How Winbind authentication works
--------------------------------
The term winbind authentication is maybe the wrong term. What is actually
involved here is
 krb5 - Kerberos, used to authenticate against AD
 winbind - Used to fetch user info from AD
 pammount - Mount home/workdirectories from Windows File-server
 samba - What glues everything together

The machine to use Winbind authentication has to become a member of the
AD-controlled domain. This is done by "Joining" the domain. Then the
workstation can fetch the userlist, and enumerate the users. When the user
logs in, the username and password is checked against the AD, and if
permitted, the homedir is created locally on the workstation. After the
homedir is created locally a defined set of folders are mounted from the
windows fileserver. These folders are only availible when the user is
logged in. when the user logs out, the mounted folders are unmounted, and
only the locally created directory remains.

Configuration files for Winbind authentication
----------------------------------------------
In debian-edu-config, there are some predefined configuration files for
using winbind authentication. These all have "-winbind-debian-edu" as part
of their names. Some of them are just softlinked into place, others are
templates with placeholders for domainname, authentication servers and
such.

Configurationfiles for pam (used as is):
 /etc/pam.d/common-account-winbind-debian-edu
 /etc/pam.d/common-auth-winbind-debian-edu
 /etc/pam.d/common-password-winbind-debian-edu
 /etc/pam.d/common-session-winbind-debian-edu

Template for samba configuration:
 /etc/samba/smb-winbind-debian-edu.conf
Template for pammount configuration:
 /etc/security/pam_mount-winbind-debian-edu.conf
Template for Kerberos configuration:
 /etc/krb5-winbind-debian-edu.conf

The templates have placeholders for the following variables:
 DOMAIN - the domain for the Windows/samba network
 HOSTNAME - hostname to be used for the client, will be autodetected if not
            specified
 REALM - Kerberos realm used in AD
 PWSERVER - The AD server that the clients authenticate against
 HDSERVER - Server that holds the homedirectories. 

Preparing for setting up winbind authentication
-----------------------------------------------
Use a sarge based debian-edu installation CD. 
There is 2 packages involved, 
 debian-edu-config - holds the configurationfiles/templates
 debian-edu-install - fetches the correct packages necesarry to get the
                      winbind authentication working
Versions needed: 
 debian-edu-config >= 0.397+svn2912
 debian-edu-install >= 0.645+svn2888

There are a few things that needs to be set up correctly in the network. 
* Working NTP-server - Kerberos is picky about this. 
* DHCP and DNS - It's important that the client can lookup the authentication
server. If you use Lessdisks-based workstation, it's also important that the
gateway for the lessdisks-clients are resolved. For a normal debian-edu
installation, the gateway for the lessdisks workstation should be
ltspserver, and the ip of this should be 192.168.0.254. Please check this
for your installation

Setting up winbind authentication
---------------------------------
Install a Debian-edu workstation or Thin client server. After the
installation is done run the script to set authentication
 /usr/lib/debian-edu-install/debian-edu-winbind

the script takes some parameters
 -d DOMAIN        - your Windows domain
 -r REALM         - your Kerberos realm
 -pw PWSERVER     - name of your password Server
 -home HOMESERVER - name of your home server
 -u ADMIN         - Username of Administrator
 -host HOSTNAME   - (optional) Samba name for the host

For a (maybe not so) typical school, the full command line would be
 /usr/lib/debian-edu-install/debian-edu-winbind \
                            -d SKOLE \
			    -r LAN.SKOLE.VGS.NO \
			    -pw elevfs1.lan.skole.vgs.no \
			    -home elevfs1.lan.skole.vgs.no \
			    -u Administrator

			    
If you want to set up Diskless workstations, you need to first install a
Thin client server, and then run the installation script for
debian-edu-lessdisks:
 /usr/lib/debian-edu-install/debian-edu-lessdisks ws

then before setting up winbind authentication, you would have to mount the
cdrom manually
 mount /media/cdrom
and then remount the cdrom inside the lessdisks chroot
 mount --bind /media/cdrom /var/lib/lessdisks/mirrors/archives/default

then you may run the winbind script:
 lessdisks-chroot -- /usr/lib/debian-edu-install/debian-edu-winbind \ 
                            -d SKOLE \
			    -r LAN.SKOLE.VGS.NO \
			    -pw elevfs1.lan.skole.vgs.no \
			    -home elevfs1.lan.skole.vgs.no \
			    -u Administrator


Error checking
--------------
Things that have gone wrong before: 
- The clock is wrong - make sure the ntp-services is set up correctly. For
  now, sarge depends upon an external ntp-server (pool.ntp.org), but should
  be fixed so that it would use a local server (ntp). For a diskless
  workstation installation, both the server where the installation is
  performed, and the diskless client should be checked
- wrong domain name - please be sure to use the complete domain name. Test
  using "host server" should give you some help.
- gateway for diskless clients. Debian-edu uses ltspserver as the gateway
  for the thin client network. this must resolv. It may be sufficient to
  just edit /etc/hosts on the thin-client-server


