README.TEMPLATING revision 43240
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 DELETION OF FILES 152 153 Any file found on the template destination that does not exist in the 154 source and is not listed as an exception by the source should be deleted. 155 However, deletion can be dangerous and cpdup will ask for confirmation 156 by default. Once you know you aren't going to blow things up, you can 157 turn this feature off and update your systems automatically from cron. 158 159 By formalizing the delete operation, you can be 100% sure that it is 160 possible to recreate / and /usr on any machine with only the original 161 template and a backup of the ( relatively few ) explicitly-excepted 162 files. The most common mistake a sysop makes is to make a change to a 163 file in / or /usr on a target machine instead of the template machine. 164 If the target machine is updated once a night from cron, the sysop 165 quickly learns not to do this ( because his changes get overwritten 166 overnight ). With a manual update, these sorts of mistakes can propogate 167 for weeks or months before they are caught. 168 169 TEMPLATE COPYING AND SAFETY 170 THE CPDUP PROGRAM 171 172 The 'cpdup' program is a program which efficiently duplicates a directory 173 tree. The program copies source to destination, duplicating devices, 174 softlinks, hardlinks, files, modification times, uid, gid, flags, perms, 175 and so forth. The program incorporates several major features: 176 177 * The program refuses, absolutely, to cross partition boundries. 178 i.e. if you were copying the template /usr from an NFS mount to 179 your /usr, and you had a mount point called /usr/home, the 180 template copying program would *NOT* descend into /usr/home on 181 the destination. 182 183 This is a safety. 184 185 * The program accesses a file called .cpignore in each directory 186 it descending into on the source to obtain a list of exceptions 187 for that directory -- that is, files not to copy or mess with. 188 189 This is a templating function. 190 191 * The program refuses to delete a directory on the destination 192 being replaced by a softlink or file on the source. 193 194 This is a safety mechanism 195 196 * The program is capable of maintaing MD5 check cache files and 197 doing an MD5 check between source and destination during the 198 scan. 199 200 * The program is capable of deleting files/directories on the 201 destination that do not exist on the source, but asks for 202 confirmation by default. 203 204 This is a templating and a safety mechanism. 205 206 * The program uses a copy-to-tmp-and-rename methodology allowing 207 it to be used to update live filesystems. 208 209 This is a templating mechanism. 210 211 * The program, by default, tries to determine if a copy is required 212 by checking modify times, file size, perms, and other stat 213 elements. If the elements match, it does not bother to copy 214 ( unless an MD5 check is being made, in which case it must read 215 the destination file ). 216 217 You typically run cpdup on the target machine. The target machine 218 temporarily mounts the template machine's / and /usr via NFS, read-only, 219 and runs cpdup to update / and /usr. If you use this methodology note 220 that THERE ARE SECURITY CONSIDERATIONS! See 'SECURITY CONSIDERATIONS WITH 221 NFS' below. 222 223 Whatever script you use that does the NFS mounts should ensure that the 224 mount succeeded before continuing with the cpdup. 225 226 You should create .cpignore files in the appropriate directories on the 227 template machine's / and /usr partitions so as not to overwrite active 228 files on the target. The most critical .cpignore files should be 229 protected with 'chflags schg .cpignore'. Specifically, the ones in / 230 and /etc, but possibly others as well. For example, the .cpignore 231 hierarchy for protect /root is: 232 233 # /root/.cpignore contains 234 .history 235 236 # /root/.ssh/.cpignore contains 237 random_seed 238 known_hosts 239 authorized_keys 240 identity 241 identity.pub 242 243 WHEN INITIALLY CONVERTING A TARGET MACHINE TO USE TEMPLATING, ALWAYS 244 MAKE A FULL BACKUP OF THE TARGET MACHINE FIRST! You may accidently delete 245 files on the target during the conversion due to forgetting to enter 246 items into appropriate .cpignore files on the source. 247 248 SECURITY CONSIDERATIONS WITH NFS ROOT EXPORT FROM TEMPLATE MACHINE 249 SECURITY CONSIDERATIONS WITH NFS USR EXPORT FROM TEMPLATE MACHINE 250 251 There are some serious security considerations that must be taken into 252 account when exporting / and /usr on the template machine. 253 254 * only export read-only 255 256 * the password file ( aka vipw ) may not contain any crypted passwords 257 at all. You MUST use ssh or kerberos to access the template machine. 258 259 You can get away with giving only root a crypted password, but only 260 if you disallow network root logins and only allow direct root 261 logins on the console. 262 263 * The machine's private ssh_host_key usually resides in /usr/local/etc. 264 You must move this key to /var/db. You can softlink link so no 265 modification of sshd_config is required. 266 267 * The machine's private ~root/.ssh/identity file is also exposed by 268 the NFS export, you should move this file to /var/db as well and 269 put a softlink in ~root/.ssh. 270 271 * DON'T EXPORT /var ! Either that, or don't put the private keys 272 in /var/db ... put them somewhere else. 273 274 * You may want to redirect the location of the random_seed file, which 275 can be done by editing ~root/.ssh/sshd_config and 276 /usr/local/etc/sshd_config so it is not exposed either. 277 278 -Matt 279 Matthew Dillon 280 dillon@backplane.com 281 282