README.TEMPLATING revision 130786
133965SjdpIMPORTANT NOTE: 233965Sjdp 333965SjdpAs of Feb. 11, 2002 (and indeed, for quite some time before that), 433965Sjdpthe /etc/rc.diskless{1,2} scripts support a slightly different 533965Sjdpdiskless boot process than the one documented in the rest of 633965Sjdpthis file (which is 3 years old). 733965Sjdp 833965SjdpI am not deleting the information below because it contains some 933965Sjdpuseful background information on diskless operation, but for the 1033965Sjdpactual details you should look at /etc/rc.diskless1, /etc/rc.diskless2, 1133965Sjdpand the /usr/share/examples/diskless/clone_root script which can 1233965Sjdpbe useful to set up clients and server for diskless boot. 13218822Sdim 1433965Sjdp--- $FreeBSD: head/share/examples/diskless/README.TEMPLATING 130786 2004-06-20 13:17:37Z mpp $ --- 1594548Sobrien------------------------------------------------------------------------ 1694548Sobrien 1794548Sobrien TEMPLATING machine configurations 1894548Sobrien 1933965Sjdp Matthew Dillon 2033965Sjdp dillon@backplane.com 21130570Sobrien 22130570Sobrien This document describes a general mechanism by which you can template 2394548Sobrien / and /usr. That is, to keep a 'master template' of / and /usr on a 2494548Sobrien separate machine which is then used to update the rest of your machines. 2594548Sobrien 2694548Sobrien Generally speaking, you can't simply mirror /. You might be able to 2794548Sobrien get away with mirroring /usr. There are two main problems involved with 2894548Sobrien templating: 2994548Sobrien 3094548Sobrien (1) Avoiding overwriting run-time generated files 3194548Sobrien 3294548Sobrien By default, the system maintains a number of files in the root 3394548Sobrien partition. For example, sendmail will dbm /etc/aliases into 3494548Sobrien /etc/aliases.db. vipw or chpass or other password related routines 3594548Sobrien will regenerate the password dbm's /etc/spwd.db, /etc/pwd.db, and 36218822Sdim passwd. /etc/namedb/s might contain generated secondaries. And 3794548Sobrien so forth. 3894548Sobrien 3994548Sobrien The templating mechanism must avoid copying over such files. 40130570Sobrien 41130570Sobrien (2) Customizing machines. 42130570Sobrien 43130570Sobrien Customizing machines is actually considerably simpler. You create 44130570Sobrien a configuration hierarchy and convert the configuration files that 45130570Sobrien have to be customized into softlinks that run through a special 46130570Sobrien softlink in the configuration directory. This will work for every 47130570Sobrien configuration file except possibly /etc/master.passwd 48130570Sobrien 49130570Sobrien For example, /etc/resolv.conf would be turned into a softlink to 50130570Sobrien /conf/ME/resolv.conf, and /conf/ME itself would be a softlink to 51130570Sobrien /conf/<HOSTNAME>. The actual resolv.conf configuration file 52130570Sobrien would reside in /conf/<HOSTNAME>. 53130570Sobrien 54130570Sobrien If you have a lot of hosts, some configuration files may be commonly 55130570Sobrien classified. For example, all your shell machines might have the 56130570Sobrien same /etc/resolv.conf. The solution is to make 57130570Sobrien /conf/<HOSTNAME>/resolv.conf a softlink to a common directory, say 58130570Sobrien /conf/HT.SHELL/resolv.conf. It may sound a little messy, but this 59130570Sobrien sort of categorization actually makes the sysadmins job much, much 60130570Sobrien easier. 61130570Sobrien 62130570Sobrien The /conf/ directory hierarchy is stored on the template and 63130570Sobrien distributed to all the machines along with the rest of the root 64130570Sobrien partition. 65130570Sobrien 66130570Sobrien This type of customization is taken from my direct experience 67130570Sobrien instituting such a system at BEST. At the time, BEST had over 45 68130570Sobrien machines managed from a single template. 69130570Sobrien 70218822Sdim RUN-TIME GENERATED OR MODIFIED FILES IN / or /USR 71218822Sdim 72218822Sdim /etc/aliases.db 73218822Sdim /etc/master.passwd 74218822Sdim /etc/spwd.db 75218822Sdim /etc/pwd.db 7694548Sobrien /etc/passwd 7794548Sobrien /etc/namedb/s 7894548Sobrien /root/.history 7994548Sobrien /root/.ssh/identity 8094548Sobrien /root/.ssh/identity.pub 8194548Sobrien /root/.ssh/random_seed 8294548Sobrien /root/.ssh/known_hosts 8394548Sobrien /conf/ME 8494548Sobrien /kernel* ( note 2 ) 8594548Sobrien /dev ( note 3 ) 8694548Sobrien /var ( note 4 ) 8794548Sobrien /home ( note 4 ) 88130570Sobrien /lost+found 89130570Sobrien 9033965Sjdp /usr/lost+found 9133965Sjdp /usr/home ( note 4 ) 92218822Sdim /usr/crash ( note 5 ) 93130570Sobrien /usr/obj ( note 5 ) 9460484Sobrien /usr/ports ( note 5 ) 9560484Sobrien /usr/src ( note 5 ) 96104844Sobrien /usr/local/crack ( note 5 ) 97104844Sobrien /usr/X11R6/lib/X11/xdm/xdm-errors ( note 6 ) 98104844Sobrien /usr/X11R6/lib/X11/xdm/xdm-pid ( note 6 ) 99130570Sobrien /usr/local/etc/ssh_host_key ( note 6 ) 100104844Sobrien /usr/local/etc/ssh_host_key.pub ( note 6 ) 101104844Sobrien /usr/local/etc/ssh_random_seed ( note 6 ) 102130570Sobrien 10360524Sobrien /conf/ME ( note 7 ) 10460484Sobrien 10560484Sobrien note 2: You typically want to update kernels manually and *NOT* 106130570Sobrien template them as a safety measure. This also allows you to run 10760484Sobrien different kernels on different machines or. 10894548Sobrien 10933965Sjdp note 3: /dev must be updated manually. Some devices, such as tty's and 11033965Sjdp pty's, use the access and/or modify time and/or user/group 111130570Sobrien operationally and regenerating the devices on the fly would be 11260484Sobrien bad. 11394548Sobrien 11433965Sjdp note 4: /var and /home are usually separately mounted partitions and 11533965Sjdp thus would not fall under the template, but as a safety measure 116130570Sobrien the template copier refuse to copy directories named 'home'. 11733965Sjdp 11894548Sobrien note 5: These are directories that are as often created directly on 11933965Sjdp /usr as they are separately-mounted partitions. You typically 12033965Sjdp do not want to template such directories. 121130570Sobrien 12260484Sobrien note 6: Note that you can solve the problem of xdm and sshd creating 12394548Sobrien files in /usr. With xdm, edit /usr/X11R6/lib/xdm/xdm-config 12433965Sjdp and change the errorLogFile and pidFile config lines. 12533965Sjdp 126130570Sobrien With sshd, add 'HostKey' and 'RandomSeed' directives to specify 12733965Sjdp /var/db for the location of the host key and run-time sshd 12833965Sjdp random seed: 12933965Sjdp 13033965Sjdp HostKey /var/db/ssh_host_key 13133965Sjdp RandomSeed /var/db/ssh_random_seed 13233965Sjdp 13333965Sjdp note 7: In this example, /conf/ME is the machine customizer and must 13433965Sjdp be pointed to the /conf/<full-host-name>/ directory, which is 13533965Sjdp different for each machine. Thus, the /conf/ME softlink 13633965Sjdp should never be overwritten by the templating copy. 13760484Sobrien 13894548Sobrien 13933965Sjdp TYPICAL CUSTOMIZED CONFIGRATION SOFTLINKS 14033965Sjdp 141130570Sobrien The following files typically need to be turned into softlinks 14260484Sobrien to /conf/ME/<filename>: 14394548Sobrien 14460484Sobrien /etc/ccd.conf -> /conf/ME/ccd.conf 14560484Sobrien /etc/ipfw.conf ... 146130570Sobrien /etc/fstab 147130570Sobrien /etc/motd 14877317Sobrien /etc/resolv.conf 14977317Sobrien /etc/aliases 150218822Sdim /etc/sendmail.cw 151218822Sdim /etc/organization 152218822Sdim /etc/named.conf 153218822Sdim /etc/rc.conf.local 154218822Sdim /etc/printcap 155218822Sdim /etc/inetd.conf 156218822Sdim /etc/login.conf 15794548Sobrien /etc/gettytab 15877317Sobrien /etc/ntp.conf 15977317Sobrien /etc/exports 16094548Sobrien /root/.k5login -> /conf/ME/root/.k5login 16133965Sjdp 16294548Sobrien And, of course, /conf/ME is usually a softlink to the appropriate 16333965Sjdp /conf/<full-host-name>/. Depending on your system configuration, 16433965Sjdp there may be other files not listed above that you have to worry about. 16560484Sobrien 16660484Sobrien In many cases, /conf/ME/filename is itself a softlink to 16794548Sobrien "../HT.xxxx/filename", where HT.xxxx is something like HT.STD ... this 16860484Sobrien added complexity actually makes it easier to manage multiple 16960484Sobrien classifications of machines. 170218822Sdim 171218822Sdim DELETION OF FILES 17260484Sobrien 17360484Sobrien Any file found on the template destination that does not exist in the 174218822Sdim source and is not listed as an exception by the source should be deleted. 175218822Sdim However, deletion can be dangerous and cpdup will ask for confirmation 17638889Sjdp by default. Once you know you aren't going to blow things up, you can 17738889Sjdp turn this feature off and update your systems automatically from cron. 17833965Sjdp 17960484Sobrien By formalizing the delete operation, you can be 100% sure that it is 18094548Sobrien possible to recreate / and /usr on any machine with only the original 18133965Sjdp template and a backup of the ( relatively few ) explicitly-excepted 18233965Sjdp files. The most common mistake a sysop makes is to make a change to a 18333965Sjdp file in / or /usr on a target machine instead of the template machine. 18433965Sjdp If the target machine is updated once a night from cron, the sysop 18533965Sjdp quickly learns not to do this ( because his changes get overwritten 18633965Sjdp overnight ). With a manual update, these sorts of mistakes can propagate 18733965Sjdp for weeks or months before they are caught. 18833965Sjdp 18933965Sjdp TEMPLATE COPYING AND SAFETY 19033965Sjdp THE CPDUP PROGRAM 19133965Sjdp 19233965Sjdp The 'cpdup' program is a program which efficiently duplicates a directory 19333965Sjdp tree. The program copies source to destination, duplicating devices, 19460484Sobrien softlinks, hardlinks, files, modification times, uid, gid, flags, perms, 19594548Sobrien and so forth. The program incorporates several major features: 19633965Sjdp 19733965Sjdp * The program refuses, absolutely, to cross partition boundaries. 198218822Sdim i.e. if you were copying the template /usr from an NFS mount to 199218822Sdim your /usr, and you had a mount point called /usr/home, the 200130570Sobrien template copying program would *NOT* descend into /usr/home on 201130570Sobrien the destination. 202218822Sdim 203218822Sdim This is a safety. 20460484Sobrien 20560484Sobrien * The program accesses a file called .cpignore in each directory 206218822Sdim it descends into on the source to obtain a list of exceptions 207218822Sdim for that directory -- that is, files not to copy or mess with. 20889870Sobrien 20989870Sobrien This is a templating function. 210218822Sdim 211218822Sdim * The program refuses to delete a directory on the destination 21289870Sobrien being replaced by a softlink or file on the source. 21389870Sobrien 214218822Sdim This is a safety mechanism 21560484Sobrien 21694548Sobrien * The program is capable of maintaining MD5 check cache files and 21733965Sjdp doing an MD5 check between source and destination during the 21833965Sjdp scan. 219218822Sdim 220218822Sdim * The program is capable of deleting files/directories on the 221218822Sdim destination that do not exist on the source, but asks for 22260484Sobrien confirmation by default. 22360484Sobrien 224218822Sdim This is a templating and a safety mechanism. 225218822Sdim 22660484Sobrien * The program uses a copy-to-tmp-and-rename methodology allowing 22760484Sobrien it to be used to update live filesystems. 228218822Sdim 229218822Sdim This is a templating mechanism. 23089870Sobrien 23189870Sobrien * The program, by default, tries to determine if a copy is required 232218822Sdim by checking modify times, file size, perms, and other stat 233218822Sdim elements. If the elements match, it does not bother to copy 234218822Sdim ( unless an MD5 check is being made, in which case it must read 235218822Sdim the destination file ). 236130570Sobrien 23777317Sobrien You typically run cpdup on the target machine. The target machine 23877317Sobrien temporarily mounts the template machine's / and /usr via NFS, read-only, 23989870Sobrien and runs cpdup to update / and /usr. If you use this methodology note 24089870Sobrien that THERE ARE SECURITY CONSIDERATIONS! See 'SECURITY CONSIDERATIONS WITH 24189870Sobrien NFS' below. 24299470Sobrien 24399470Sobrien Whatever script you use that does the NFS mounts should ensure that the 24499470Sobrien mount succeeded before continuing with the cpdup. 245218822Sdim 246218822Sdim You should create .cpignore files in the appropriate directories on the 247218822Sdim template machine's / and /usr partitions so as not to overwrite active 24877317Sobrien files on the target. The most critical .cpignore files should be 24977317Sobrien protected with 'chflags schg .cpignore'. Specifically, the ones in / 25077317Sobrien and /etc, but possibly others as well. For example, the .cpignore 25177317Sobrien hierarchy for protect /root is: 25233965Sjdp 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 accidently delete 265 files on the target during the conversion due to forgetting to enter 266 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 302