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