share/examples/diskless/README.TEMPLATING

   1 # $FreeBSD: src/share/examples/diskless/README.TEMPLATING,v 1.2.4.1 2002/02/12 17:49:13 luigi Exp $
   2 # $DragonFly: src/share/examples/diskless/README.TEMPLATING,v 1.2 2003/06/17 04:36:57 dillon Exp $
   3
   4 IMPORTANT NOTE:
   5
   6 As of Feb. 11, 2002 (and indeed, for quite some time before that),
   7 the /etc/rc.diskless{1,2} scripts support a slightly different
   8 diskless boot process than the one documented in the rest of
   9 this file (which is 3 years old).
  10
  11 I am not deleting the information below because it contains some
  12 useful background information on diskless operation, but for the
  13 actual details you should look at /etc/rc.diskless1, /etc/rc.diskless2,
  14 and the /usr/share/examples/diskless/clone_root script which can
  15 be useful to set up clients and server for diskless boot.
  16
  17 -----------------------------------------------------------------------
  18
  19                       TEMPLATING machine configurations
  20
  21                             Matthew Dillon
  22                             dillon@backplane.com
  23
  24     This document describes a general mechanism by which you can template
  25     / and /usr.  That is, to keep a 'master template' of / and /usr on a
  26     separate machine which is then used to update the rest of your machines.
  27
  28     Generally speaking, you can't simply mirror /.  You might be able to
  29     get away with mirroring /usr.  There are two main problems involved with
  30     templating:
  31
  32     (1) Avoiding overwriting run-time generated files
  33
  34         By default, the system maintains a number of files in the root
  35         partition.  For example, sendmail will dbm /etc/aliases into
  36         /etc/aliases.db.  vipw or chpass or other password related routines
  37         will regenerate the password dbm's /etc/spwd.db, /etc/pwd.db, and
  38         passwd.  /etc/namedb/s might contain generated secondaries.  And
  39         so forth.
  40
  41         The templating mechanism must avoid copying over such files.
  42
  43     (2) Customizing machines.
  44
  45         Customizing machines is actually considerably simpler.  You create
  46         a configuration hierarchy and convert the configuration files that
  47         have to be customized into softlinks that run through a special
  48         softlink in the configuration directory.  This will work for every
  49         configuration file except possibly /etc/master.passwd
  50
  51         For example, /etc/resolv.conf would be turned into a softlink to
  52         /conf/ME/resolv.conf, and /conf/ME itself would be a softlink to
  53         /conf/<HOSTNAME>.  The actual resolv.conf configuration file
  54         would reside in /conf/<HOSTNAME>.
  55
  56         If you have a lot of hosts, some configuration files may be commonly
  57         classified.  For example, all your shell machines might have the
  58         same /etc/resolv.conf.  The solution is to make
  59         /conf/<HOSTNAME>/resolv.conf a softlink to a common directory, say
  60         /conf/HT.SHELL/resolv.conf.  It may sound a little messy, but this
  61         sort of categorization actually makes the sysadmins job much, much
  62         easier.
  63
  64         The /conf/ directory hierarchy is stored on the template and
  65         distributed to all the machines along with the rest of the root
  66         partition.
  67
  68         This type of customization is taken from my direct experience
  69         instituting such a system at BEST.  At the time, BEST had over 45
  70         machines managed from a single template.
  71
  72                 RUN-TIME GENERATED OR MODIFIED FILES IN / or /USR
  73
  74         /etc/aliases.db
  75         /etc/master.passwd
  76         /etc/spwd.db
  77         /etc/pwd.db
  78         /etc/passwd
  79         /etc/namedb/s
  80         /root/.history
  81         /root/.ssh/identity
  82         /root/.ssh/identity.pub
  83         /root/.ssh/random_seed
  84         /root/.ssh/known_hosts
  85         /conf/ME
  86         /kernel*        ( note 2 )
  87         /dev    ( note 3 )
  88         /var    ( note 4 )
  89         /home   ( note 4 )
  90         /lost+found
  91
  92         /usr/lost+found
  93         /usr/home       ( note 4 )
  94         /usr/crash      ( note 5 )
  95         /usr/obj        ( note 5 )
  96         /usr/ports      ( note 5 )
  97         /usr/src        ( note 5 )
  98         /usr/local/crack ( note 5 )
  99         /usr/X11R6/lib/X11/xdm/xdm-errors ( note 6 )
 100         /usr/X11R6/lib/X11/xdm/xdm-pid    ( note 6 )
 101         /usr/local/etc/ssh_host_key       ( note 6 )
 102         /usr/local/etc/ssh_host_key.pub   ( note 6 )
 103         /usr/local/etc/ssh_random_seed    ( note 6 )
 104
 105         /conf/ME        ( note 7 )
 106
 107         note 2: You typically want to update kernels manually and *NOT*
 108                 template them as a safety measure.  This also allows you to run
 109                 different kernels on different machines or.
 110
 111         note 3: /dev must be updated manually.  Some devices, such as tty's and
 112                 pty's, use the access and/or modify time and/or user/group
 113                 operationally and regenerating the devices on the fly would be
 114                 bad.
 115
 116         note 4: /var and /home are usually separately mounted partitions and
 117                 thus would not fall under the template, but as a safety measure
 118                 the template copier refuse to copy directories named 'home'.
 119
 120         note 5: These are directories that are as often created directly on
 121                 /usr as they are separately-mounted partitions.  You typically
 122                 do not want to template such directories.
 123
 124         note 6: Note that you can solve the problem of xdm and sshd creating
 125                 files in /usr.  With xdm, edit /usr/X11R6/lib/xdm/xdm-config
 126                 and change the errorLogFile and pidFile config lines.
 127
 128                 With sshd, add 'HostKey' and 'RandomSeed' directives to specify
 129                 /var/db for the location of the host key and run-time sshd
 130                 random seed:
 131
 132                 HostKey /var/db/ssh_host_key
 133                 RandomSeed /var/db/ssh_random_seed
 134
 135         note 7: In this example, /conf/ME is the machine customizer and must
 136                 be pointed to the /conf/<full-host-name>/ directory, which is
 137                 different for each machine.  Thus, the /conf/ME softlink
 138                 should never be overwritten by the templating copy.
 139
 140
 141                 TYPICAL CUSTOMIZED CONFIGRATION SOFTLINKS
 142
 143     The following files typically need to be turned into softlinks
 144     to /conf/ME/<filename>:
 145
 146         /etc/ccd.conf           -> /conf/ME/ccd.conf
 147         /etc/ipfw.conf          ...
 148         /etc/fstab
 149         /etc/motd
 150         /etc/resolv.conf
 151         /etc/aliases
 152         /etc/sendmail.cw
 153         /etc/organization
 154         /etc/named.conf
 155         /etc/rc.conf.local
 156         /etc/printcap
 157         /etc/inetd.conf
 158         /etc/login.conf
 159         /etc/gettytab
 160         /etc/ntp.conf
 161         /etc/exports
 162         /root/.k5login          -> /conf/ME/root/.k5login
 163
 164     And, of course, /conf/ME is usually a softlink to the appropriate
 165     /conf/<full-host-name>/.  Depending on your system configuration,
 166     there may be other files not listed above that you have to worry about.
 167
 168     In many cases, /conf/ME/filename is itself a softlink to
 169     "../HT.xxxx/filename", where HT.xxxx is something like HT.STD ... this
 170     added complexity actually makes it easier to manage multiple
 171     classifications of machines.
 172
 173                                 DELETION OF FILES
 174
 175     Any file found on the template destination that does not exist in the
 176     source and is not listed as an exception by the source should be deleted.
 177     However, deletion can be dangerous and cpdup will ask for confirmation
 178     by default.  Once you know you aren't going to blow things up, you can
 179     turn this feature off and update your systems automatically from cron.
 180
 181     By formalizing the delete operation, you can be 100% sure that it is
 182     possible to recreate / and /usr on any machine with only the original
 183     template and a backup of the ( relatively few ) explicitly-excepted
 184     files.  The most common mistake a sysop makes is to make a change to a
 185     file in / or /usr on a target machine instead of the template machine.
 186     If the target machine is updated once a night from cron, the sysop
 187     quickly learns not to do this ( because his changes get overwritten
 188     overnight ).  With a manual update, these sorts of mistakes can propogate
 189     for weeks or months before they are caught.
 190
 191                             TEMPLATE COPYING AND SAFETY
 192                                THE CPDUP PROGRAM
 193
 194     The 'cpdup' program is a program which efficiently duplicates a directory
 195     tree.  The program copies source to destination, duplicating devices,
 196     softlinks, hardlinks, files, modification times, uid, gid, flags, perms,
 197     and so forth.  The program incorporates several major features:
 198
 199         *   The program refuses, absolutely, to cross partition boundries.
 200             i.e. if you were copying the template /usr from an NFS mount to
 201             your /usr, and you had a mount point called /usr/home, the
 202             template copying program would *NOT* descend into /usr/home on
 203             the destination.
 204
 205             This is a safety.
 206
 207         *   The program accesses a file called .cpignore in each directory
 208             it descending into on the source to obtain a list of exceptions
 209             for that directory -- that is, files not to copy or mess with.
 210
 211             This is a templating function.
 212
 213         *   The program refuses to delete a directory on the destination
 214             being replaced by a softlink or file on the source.
 215
 216             This is a safety mechanism
 217
 218         *   The program is capable of maintaing MD5 check cache files and
 219             doing an MD5 check between source and destination during the
 220             scan.
 221
 222         *   The program is capable of deleting files/directories on the
 223             destination that do not exist on the source, but asks for
 224             confirmation by default.
 225
 226             This is a templating and a safety mechanism.
 227
 228         *   The program uses a copy-to-tmp-and-rename methodology allowing
 229             it to be used to update live filesystems.
 230
 231             This is a templating mechanism.
 232
 233         *   The program, by default, tries to determine if a copy is required
 234             by checking modify times, file size, perms, and other stat
 235             elements.  If the elements match, it does not bother to copy
 236             ( unless an MD5 check is being made, in which case it must read
 237             the destination file ).
 238
 239     You typically run cpdup on the target machine.  The target machine
 240     temporarily mounts the template machine's / and /usr via NFS, read-only,
 241     and runs cpdup to update / and /usr.  If you use this methodology note
 242     that THERE ARE SECURITY CONSIDERATIONS!  See 'SECURITY CONSIDERATIONS WITH
 243     NFS' below.
 244
 245     Whatever script you use that does the NFS mounts should ensure that the
 246     mount succeeded before continuing with the cpdup.
 247
 248     You should create .cpignore files in the appropriate directories on the
 249     template machine's / and /usr partitions so as not to overwrite active
 250     files on the target.  The most critical .cpignore files should be
 251     protected with 'chflags schg .cpignore'.  Specifically, the ones in /
 252     and /etc, but possibly others as well.  For example, the .cpignore
 253     hierarchy for protect /root is:
 254
 255         # /root/.cpignore contains
 256         .history
 257
 258         # /root/.ssh/.cpignore contains
 259         random_seed
 260         known_hosts
 261         authorized_keys
 262         identity
 263         identity.pub
 264
 265     WHEN INITIALLY CONVERTING A TARGET MACHINE TO USE TEMPLATING, ALWAYS
 266     MAKE A FULL BACKUP OF THE TARGET MACHINE FIRST!  You may accidently delete
 267     files on the target during the conversion due to forgetting to enter
 268     items into appropriate .cpignore files on the source.
 269
 270         SECURITY CONSIDERATIONS WITH NFS ROOT EXPORT FROM TEMPLATE MACHINE
 271         SECURITY CONSIDERATIONS WITH NFS USR EXPORT FROM TEMPLATE MACHINE
 272
 273     There are some serious security considerations that must be taken into
 274     account when exporting / and /usr on the template machine.
 275
 276         * only export read-only
 277
 278         * the password file ( aka vipw ) may not contain any crypted passwords
 279           at all.  You MUST use ssh or kerberos to access the template machine.
 280
 281           You can get away with giving only root a crypted password, but only
 282           if you disallow network root logins and only allow direct root
 283           logins on the  console.
 284
 285         * The machine's private ssh_host_key usually resides in /usr/local/etc.
 286           You must move this key to /var/db.  You can softlink link so no
 287           modification of sshd_config is required.
 288
 289         * The machine's private ~root/.ssh/identity file is also exposed by
 290           the NFS export, you should move this file to /var/db as well and
 291           put a softlink in ~root/.ssh.
 292
 293         * DON'T EXPORT /var !  Either that, or don't put the private keys
 294           in /var/db ... put them somewhere else.
 295
 296         * You may want to redirect the location of the random_seed file, which
 297           can be done by editing ~root/.ssh/sshd_config and
 298           /usr/local/etc/sshd_config so it is not exposed either.
 299
 300                                         -Matt
 301                                         Matthew Dillon
 302                                         dillon@backplane.com
 303