ifconfig(8): Use correct interface name when setting flags
[dragonfly.git] / share / examples / diskless / README.TEMPLATING
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
4 IMPORTANT NOTE:
5
6 For quite some time
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.
9
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,
13 /etc/rc.d/diskless,
14 and the /usr/share/examples/diskless/clone_root script which can
15 be 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