share/examples/diskless/README.TEMPLATING

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