README.TEMPLATING revision 92302
192302SluigiIMPORTANT NOTE: 243240Sdillon 392302SluigiAs of Feb. 11, 2002 (and indeed, for quite some time before that), 492302Sluigithe /etc/rc.diskless{1,2} scripts support a slightly different 592302Sluigidiskless boot process than the one documented in the rest of 692302Sluigithis file (which is 3 years old). 792302Sluigi 892302SluigiI am not deleting the information below because it contains some 992302Sluigiuseful background information on diskless operation, but for the 1092302Sluigiactual details you should look at /etc/rc.diskless1, /etc/rc.diskless2, 1192302Sluigiand the /usr/share/examples/diskless/clone_root script which can 1292302Sluigibe useful to set up clients and server for diskless boot. 1392302Sluigi 1492302Sluigi--- $FreeBSD: head/share/examples/diskless/README.TEMPLATING 92302 2002-03-15 06:47:38Z luigi $ --- 1592302Sluigi------------------------------------------------------------------------ 1692302Sluigi 1743240Sdillon TEMPLATING machine configurations 1843240Sdillon 1943240Sdillon Matthew Dillon 2043240Sdillon dillon@backplane.com 2143240Sdillon 2243240Sdillon This document describes a general mechanism by which you can template 2343240Sdillon / and /usr. That is, to keep a 'master template' of / and /usr on a 2443240Sdillon separate machine which is then used to update the rest of your machines. 2543240Sdillon 2643240Sdillon Generally speaking, you can't simply mirror /. You might be able to 2743240Sdillon get away with mirroring /usr. There are two main problems involved with 2843240Sdillon templating: 2943240Sdillon 3043240Sdillon (1) Avoiding overwriting run-time generated files 3143240Sdillon 3243240Sdillon By default, the system maintains a number of files in the root 3343240Sdillon partition. For example, sendmail will dbm /etc/aliases into 3443240Sdillon /etc/aliases.db. vipw or chpass or other password related routines 3543240Sdillon will regenerate the password dbm's /etc/spwd.db, /etc/pwd.db, and 3643240Sdillon passwd. /etc/namedb/s might contain generated secondaries. And 3743240Sdillon so forth. 3843240Sdillon 3943240Sdillon The templating mechanism must avoid copying over such files. 4043240Sdillon 4143240Sdillon (2) Customizing machines. 4243240Sdillon 4343240Sdillon Customizing machines is actually considerably simpler. You create 4443240Sdillon a configuration hierarchy and convert the configuration files that 4543240Sdillon have to be customized into softlinks that run through a special 4643240Sdillon softlink in the configuration directory. This will work for every 4743240Sdillon configuration file except possibly /etc/master.passwd 4843240Sdillon 4943240Sdillon For example, /etc/resolv.conf would be turned into a softlink to 5043240Sdillon /conf/ME/resolv.conf, and /conf/ME itself would be a softlink to 5143240Sdillon /conf/<HOSTNAME>. The actual resolv.conf configuration file 5243240Sdillon would reside in /conf/<HOSTNAME>. 5343240Sdillon 5443240Sdillon If you have a lot of hosts, some configuration files may be commonly 5543240Sdillon classified. For example, all your shell machines might have the 5643240Sdillon same /etc/resolv.conf. The solution is to make 5743240Sdillon /conf/<HOSTNAME>/resolv.conf a softlink to a common directory, say 5843240Sdillon /conf/HT.SHELL/resolv.conf. It may sound a little messy, but this 5943240Sdillon sort of categorization actually makes the sysadmins job much, much 6043240Sdillon easier. 6143240Sdillon 6243240Sdillon The /conf/ directory hierarchy is stored on the template and 6343240Sdillon distributed to all the machines along with the rest of the root 6443240Sdillon partition. 6543240Sdillon 6643240Sdillon This type of customization is taken from my direct experience 6743240Sdillon instituting such a system at BEST. At the time, BEST had over 45 6843240Sdillon machines managed from a single template. 6943240Sdillon 7043240Sdillon RUN-TIME GENERATED OR MODIFIED FILES IN / or /USR 7143240Sdillon 7243240Sdillon /etc/aliases.db 7343240Sdillon /etc/master.passwd 7443240Sdillon /etc/spwd.db 7543240Sdillon /etc/pwd.db 7643240Sdillon /etc/passwd 7743240Sdillon /etc/namedb/s 7843240Sdillon /root/.history 7943240Sdillon /root/.ssh/identity 8043240Sdillon /root/.ssh/identity.pub 8143240Sdillon /root/.ssh/random_seed 8243240Sdillon /root/.ssh/known_hosts 8343240Sdillon /conf/ME 8443240Sdillon /kernel* ( note 2 ) 8543240Sdillon /dev ( note 3 ) 8643240Sdillon /var ( note 4 ) 8743240Sdillon /home ( note 4 ) 8843240Sdillon /lost+found 8943240Sdillon 9043240Sdillon /usr/lost+found 9143240Sdillon /usr/home ( note 4 ) 9243240Sdillon /usr/crash ( note 5 ) 9343240Sdillon /usr/obj ( note 5 ) 9443240Sdillon /usr/ports ( note 5 ) 9543240Sdillon /usr/src ( note 5 ) 9643240Sdillon /usr/local/crack ( note 5 ) 9743240Sdillon /usr/X11R6/lib/X11/xdm/xdm-errors ( note 6 ) 9843240Sdillon /usr/X11R6/lib/X11/xdm/xdm-pid ( note 6 ) 9943240Sdillon /usr/local/etc/ssh_host_key ( note 6 ) 10043240Sdillon /usr/local/etc/ssh_host_key.pub ( note 6 ) 10143240Sdillon /usr/local/etc/ssh_random_seed ( note 6 ) 10243240Sdillon 10343240Sdillon /conf/ME ( note 7 ) 10443240Sdillon 10543240Sdillon note 2: You typically want to update kernels manually and *NOT* 10643240Sdillon template them as a safety measure. This also allows you to run 10743240Sdillon different kernels on different machines or. 10843240Sdillon 10943240Sdillon note 3: /dev must be updated manually. Some devices, such as tty's and 11043240Sdillon pty's, use the access and/or modify time and/or user/group 11143240Sdillon operationally and regenerating the devices on the fly would be 11243240Sdillon bad. 11343240Sdillon 11443240Sdillon note 4: /var and /home are usually separately mounted partitions and 11543240Sdillon thus would not fall under the template, but as a safety measure 11643240Sdillon the template copier refuse to copy directories named 'home'. 11743240Sdillon 11843240Sdillon note 5: These are directories that are as often created directly on 11943240Sdillon /usr as they are separately-mounted partitions. You typically 12043240Sdillon do not want to template such directories. 12143240Sdillon 12243240Sdillon note 6: Note that you can solve the problem of xdm and sshd creating 12343240Sdillon files in /usr. With xdm, edit /usr/X11R6/lib/xdm/xdm-config 12443240Sdillon and change the errorLogFile and pidFile config lines. 12543240Sdillon 12643240Sdillon With sshd, add 'HostKey' and 'RandomSeed' directives to specify 12743240Sdillon /var/db for the location of the host key and run-time sshd 12843240Sdillon random seed: 12943240Sdillon 13043240Sdillon HostKey /var/db/ssh_host_key 13143240Sdillon RandomSeed /var/db/ssh_random_seed 13243240Sdillon 13343240Sdillon note 7: In this example, /conf/ME is the machine customizer and must 13443240Sdillon be pointed to the /conf/<full-host-name>/ directory, which is 13543240Sdillon different for each machine. Thus, the /conf/ME softlink 13643240Sdillon should never be overwritten by the templating copy. 13743240Sdillon 13843240Sdillon 13943240Sdillon TYPICAL CUSTOMIZED CONFIGRATION SOFTLINKS 14043240Sdillon 14143240Sdillon The following files typically need to be turned into softlinks 14243240Sdillon to /conf/ME/<filename>: 14343240Sdillon 14443240Sdillon /etc/ccd.conf -> /conf/ME/ccd.conf 14543240Sdillon /etc/ipfw.conf ... 14643240Sdillon /etc/fstab 14743240Sdillon /etc/motd 14843240Sdillon /etc/resolv.conf 14943240Sdillon /etc/aliases 15043240Sdillon /etc/sendmail.cw 15143240Sdillon /etc/organization 15243240Sdillon /etc/named.conf 15343240Sdillon /etc/rc.conf.local 15443240Sdillon /etc/printcap 15543240Sdillon /etc/inetd.conf 15643240Sdillon /etc/login.conf 15743240Sdillon /etc/gettytab 15843240Sdillon /etc/ntp.conf 15943240Sdillon /etc/exports 16043240Sdillon /root/.k5login -> /conf/ME/root/.k5login 16143240Sdillon 16243240Sdillon And, of course, /conf/ME is usually a softlink to the appropriate 16343240Sdillon /conf/<full-host-name>/. Depending on your system configuration, 16443240Sdillon there may be other files not listed above that you have to worry about. 16543240Sdillon 16643808Sdillon In many cases, /conf/ME/filename is itself a softlink to 16743808Sdillon "../HT.xxxx/filename", where HT.xxxx is something like HT.STD ... this 16843808Sdillon added complexity actually makes it easier to manage multiple 16943808Sdillon classifications of machines. 17043808Sdillon 17143240Sdillon DELETION OF FILES 17243240Sdillon 17343240Sdillon Any file found on the template destination that does not exist in the 17443240Sdillon source and is not listed as an exception by the source should be deleted. 17543240Sdillon However, deletion can be dangerous and cpdup will ask for confirmation 17643240Sdillon by default. Once you know you aren't going to blow things up, you can 17743240Sdillon turn this feature off and update your systems automatically from cron. 17843240Sdillon 17943240Sdillon By formalizing the delete operation, you can be 100% sure that it is 18043240Sdillon possible to recreate / and /usr on any machine with only the original 18143240Sdillon template and a backup of the ( relatively few ) explicitly-excepted 18243240Sdillon files. The most common mistake a sysop makes is to make a change to a 18343240Sdillon file in / or /usr on a target machine instead of the template machine. 18443240Sdillon If the target machine is updated once a night from cron, the sysop 18543240Sdillon quickly learns not to do this ( because his changes get overwritten 18643240Sdillon overnight ). With a manual update, these sorts of mistakes can propogate 18743240Sdillon for weeks or months before they are caught. 18843240Sdillon 18943240Sdillon TEMPLATE COPYING AND SAFETY 19043240Sdillon THE CPDUP PROGRAM 19143240Sdillon 19243240Sdillon The 'cpdup' program is a program which efficiently duplicates a directory 19343240Sdillon tree. The program copies source to destination, duplicating devices, 19443240Sdillon softlinks, hardlinks, files, modification times, uid, gid, flags, perms, 19543240Sdillon and so forth. The program incorporates several major features: 19643240Sdillon 19743240Sdillon * The program refuses, absolutely, to cross partition boundries. 19843240Sdillon i.e. if you were copying the template /usr from an NFS mount to 19943240Sdillon your /usr, and you had a mount point called /usr/home, the 20043240Sdillon template copying program would *NOT* descend into /usr/home on 20143240Sdillon the destination. 20243240Sdillon 20343240Sdillon This is a safety. 20443240Sdillon 20543240Sdillon * The program accesses a file called .cpignore in each directory 20643240Sdillon it descending into on the source to obtain a list of exceptions 20743240Sdillon for that directory -- that is, files not to copy or mess with. 20843240Sdillon 20943240Sdillon This is a templating function. 21043240Sdillon 21143240Sdillon * The program refuses to delete a directory on the destination 21243240Sdillon being replaced by a softlink or file on the source. 21343240Sdillon 21443240Sdillon This is a safety mechanism 21543240Sdillon 21643240Sdillon * The program is capable of maintaing MD5 check cache files and 21743240Sdillon doing an MD5 check between source and destination during the 21843240Sdillon scan. 21943240Sdillon 22043240Sdillon * The program is capable of deleting files/directories on the 22143240Sdillon destination that do not exist on the source, but asks for 22243240Sdillon confirmation by default. 22343240Sdillon 22443240Sdillon This is a templating and a safety mechanism. 22543240Sdillon 22643240Sdillon * The program uses a copy-to-tmp-and-rename methodology allowing 22743240Sdillon it to be used to update live filesystems. 22843240Sdillon 22943240Sdillon This is a templating mechanism. 23043240Sdillon 23143240Sdillon * The program, by default, tries to determine if a copy is required 23243240Sdillon by checking modify times, file size, perms, and other stat 23343240Sdillon elements. If the elements match, it does not bother to copy 23443240Sdillon ( unless an MD5 check is being made, in which case it must read 23543240Sdillon the destination file ). 23643240Sdillon 23743240Sdillon You typically run cpdup on the target machine. The target machine 23843240Sdillon temporarily mounts the template machine's / and /usr via NFS, read-only, 23943240Sdillon and runs cpdup to update / and /usr. If you use this methodology note 24043240Sdillon that THERE ARE SECURITY CONSIDERATIONS! See 'SECURITY CONSIDERATIONS WITH 24143240Sdillon NFS' below. 24243240Sdillon 24343240Sdillon Whatever script you use that does the NFS mounts should ensure that the 24443240Sdillon mount succeeded before continuing with the cpdup. 24543240Sdillon 24643240Sdillon You should create .cpignore files in the appropriate directories on the 24743240Sdillon template machine's / and /usr partitions so as not to overwrite active 24843240Sdillon files on the target. The most critical .cpignore files should be 24943240Sdillon protected with 'chflags schg .cpignore'. Specifically, the ones in / 25043240Sdillon and /etc, but possibly others as well. For example, the .cpignore 25143240Sdillon hierarchy for protect /root is: 25243240Sdillon 25343240Sdillon # /root/.cpignore contains 25443240Sdillon .history 25543240Sdillon 25643240Sdillon # /root/.ssh/.cpignore contains 25743240Sdillon random_seed 25843240Sdillon known_hosts 25943240Sdillon authorized_keys 26043240Sdillon identity 26143240Sdillon identity.pub 26243240Sdillon 26343240Sdillon WHEN INITIALLY CONVERTING A TARGET MACHINE TO USE TEMPLATING, ALWAYS 26443240Sdillon MAKE A FULL BACKUP OF THE TARGET MACHINE FIRST! You may accidently delete 26543240Sdillon files on the target during the conversion due to forgetting to enter 26643240Sdillon items into appropriate .cpignore files on the source. 26743240Sdillon 26843240Sdillon SECURITY CONSIDERATIONS WITH NFS ROOT EXPORT FROM TEMPLATE MACHINE 26943240Sdillon SECURITY CONSIDERATIONS WITH NFS USR EXPORT FROM TEMPLATE MACHINE 27043240Sdillon 27143240Sdillon There are some serious security considerations that must be taken into 27243240Sdillon account when exporting / and /usr on the template machine. 27343240Sdillon 27443240Sdillon * only export read-only 27543240Sdillon 27643240Sdillon * the password file ( aka vipw ) may not contain any crypted passwords 27743240Sdillon at all. You MUST use ssh or kerberos to access the template machine. 27843240Sdillon 27943240Sdillon You can get away with giving only root a crypted password, but only 28043240Sdillon if you disallow network root logins and only allow direct root 28143240Sdillon logins on the console. 28243240Sdillon 28343240Sdillon * The machine's private ssh_host_key usually resides in /usr/local/etc. 28443240Sdillon You must move this key to /var/db. You can softlink link so no 28543240Sdillon modification of sshd_config is required. 28643240Sdillon 28743240Sdillon * The machine's private ~root/.ssh/identity file is also exposed by 28843240Sdillon the NFS export, you should move this file to /var/db as well and 28943240Sdillon put a softlink in ~root/.ssh. 29043240Sdillon 29143240Sdillon * DON'T EXPORT /var ! Either that, or don't put the private keys 29243240Sdillon in /var/db ... put them somewhere else. 29343240Sdillon 29443240Sdillon * You may want to redirect the location of the random_seed file, which 29543240Sdillon can be done by editing ~root/.ssh/sshd_config and 29643240Sdillon /usr/local/etc/sshd_config so it is not exposed either. 29743240Sdillon 29843240Sdillon -Matt 29943240Sdillon Matthew Dillon 30043240Sdillon dillon@backplane.com 30143240Sdillon 302