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 $
7 the /etc/rc.d/{initdiskless,diskless} scripts support a slightly different
8 diskless boot process than the one documented in the rest of this file.
10 I am not deleting the information below because it contains some
11 useful background information on diskless operation, but for the
12 actual details you should look at diskless(8), /etc/rc.d/initdiskless,
14 and the /usr/share/examples/diskless/clone_root script which can
15 be useful to set up clients and server for diskless boot.
17 -----------------------------------------------------------------------
19 TEMPLATING machine configurations
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.
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
32 (1) Avoiding overwriting run-time generated files
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
41 The templating mechanism must avoid copying over such files.
43 (2) Customizing machines.
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
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>.
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
64 The /conf/ directory hierarchy is stored on the template and
65 distributed to all the machines along with the rest of the root
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.
72 RUN-TIME GENERATED OR MODIFIED FILES IN / or /USR
82 /root/.ssh/identity.pub
83 /root/.ssh/random_seed
84 /root/.ssh/known_hosts
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 )
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.
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
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'.
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.
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.
128 With sshd, add 'HostKey' and 'RandomSeed' directives to specify
129 /var/db for the location of the host key and run-time sshd
132 HostKey /var/db/ssh_host_key
133 RandomSeed /var/db/ssh_random_seed
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.
141 TYPICAL CUSTOMIZED CONFIGRATION SOFTLINKS
143 The following files typically need to be turned into softlinks
144 to /conf/ME/<filename>:
146 /etc/ccd.conf -> /conf/ME/ccd.conf
162 /root/.k5login -> /conf/ME/root/.k5login
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.
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.
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.
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.
191 TEMPLATE COPYING AND SAFETY
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:
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
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.
211 This is a templating function.
213 * The program refuses to delete a directory on the destination
214 being replaced by a softlink or file on the source.
216 This is a safety mechanism
218 * The program is capable of maintaing MD5 check cache files and
219 doing an MD5 check between source and destination during the
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.
226 This is a templating and a safety mechanism.
228 * The program uses a copy-to-tmp-and-rename methodology allowing
229 it to be used to update live filesystems.
231 This is a templating mechanism.
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 ).
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
245 Whatever script you use that does the NFS mounts should ensure that the
246 mount succeeded before continuing with the cpdup.
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:
255 # /root/.cpignore contains
258 # /root/.ssh/.cpignore contains
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.
270 SECURITY CONSIDERATIONS WITH NFS ROOT EXPORT FROM TEMPLATE MACHINE
271 SECURITY CONSIDERATIONS WITH NFS USR EXPORT FROM TEMPLATE MACHINE
273 There are some serious security considerations that must be taken into
274 account when exporting / and /usr on the template machine.
276 * only export read-only
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.
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.
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.
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.
293 * DON'T EXPORT /var ! Either that, or don't put the private keys
294 in /var/db ... put them somewhere else.
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.