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.3 2008/07/08 12:08:29 thomas Exp $ 3 4IMPORTANT NOTE: 5 6For quite some time 7the /etc/rc.d/{initdiskless,diskless} scripts support a slightly different 8diskless boot process than the one documented in the rest of this file. 9 10I am not deleting the information below because it contains some 11useful background information on diskless operation, but for the 12actual details you should look at diskless(8), /etc/rc.d/initdiskless, 13/etc/rc.d/diskless, 14and the /usr/share/examples/diskless/clone_root script which can 15be 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 304