INSTALL

   1 BUILDING AND INSTALLATION
   2
   3 There are two different ways to build pam_krb5_migrate.  The first mode
   4 generates a module which will update a Kerberos database on the local
   5 machine; the second mode generates a module which updates against a remote
   6 KDC using the Kerberos5 kadmin protocol.
   7
   8 Ideally, I would like to combine both sets of functionality in a single
   9 binary; however, the client and server kadmin libraries export the same
  10 API, and ld doesn't like using two different functions of the same name.
  11 :)  If anybody knows of a good, portable way to do this, let me know.
  12
  13 The default is to use the kadmin protocol to talk to the KDC remotely.  If
  14 you need the local option, edit the Makefile and uncomment the LIBS and
  15 KLOCAL lines near the top, commenting out the settings for the remote
  16 option.
  17
  18 At a later date, you will be able to control this using a configure
  19 script.  Alternatively, if people think that it would be useful, I may
  20 have it build both types of module under different names.  This is an
  21 alpha release, and I'm always open to suggestion.
  22
  23 After editing the makefile, run 'make all install' to build the module and
  24 install it in /lib/security/.
  25
  26
  27 SETTING UP THE PAM_KRB5_MIGRATE MODULE
  28
  29 If you do not already have a KDC, you will need to set up a Kerberos
  30 database for your realm.  See the Kerberos V5 Installation Guide for
  31 details.
  32
  33 If you will be updating against a live database from a machine other than
  34 the KDC, or if you intend to run the migration module on more than one
  35 machine at a time, you will need to use kadmin (or kadmin.local) to create
  36 a special Kerberos principal called pam_migrate/<hostname>, where
  37 <hostname> is the full domain name (FQDN) of the host where you're
  38 deploying the pam module.
  39
  40 % kadmin.local
  41 Authenticating as principal admin/admin@REALM with password.
  42 kadmin.local:  addprinc -randkey pam_migrate/hostname@REALM
  43 WARNING: no policy specified for pam_migrate/hostname@REALM; defaulting to no policy
  44 Principal "pam_migrate/hostname@REALM" created.
  45
  46 Then extract the key for this principal to a keytab for use on the host:
  47
  48 kadmin.local:   ktadd -k /var/kerberos/krb5kdc/hostname.keytab pam_migrate/hostname
  49 Entry for principal pam_migrate/hostname with kvno 4, encryption type DES cbc mode with CRC-32 added to keytab
  50 WRFILE:/var/kerberos/krb5kdc/hostname.keytab.
  51 Entry for principal pam_migrate/hostname with kvno 4, encryption type Triple DES cbc mode raw added to keytab
  52 WRFILE:/var/kerberos/krb5kdc/hostname.keytab.
  53
  54
  55 This principal should *only* have permission to add principals to the
  56 database and should have no other permissions.  To give the principal
  57 permission to add to the database, add this line to the top of your
  58 kadm5.acl file:
  59
  60 pam_migrate/hostname@REALM              a
  61
  62 You can also give all principals of the form pam_migrate/<hostname>
  63 permission to add by using the line
  64
  65 pam_migrate/*@REALM                     a
  66
  67 You will then need to copy your new keytab (securely!) to the appropriate
  68 machine and install it as /etc/security/pam_krb5.keytab.  Like all
  69 keytabs, this file should be readable only by root and should be treated
  70 with the utmost care when transferring it to the destination host.
  71 *Anyone with access to this keytab will be able to create new Kerberos
  72 principals in your realm.*
  73
  74 If you plan to add principals to a local database, you won't need to do
  75 any of the above.  So long as the pam module has access to write to the
  76 database (generally only if the calling application runs as root), you
  77 will be able to edit without authentication.