http://gimel.esc.cam.ac.uk/james/rpld/src/rpld-1.4.tar.gz
[rpld.git] / rpld.conf.man
1 .\" 
2 .\"/*************************************************
3 .\"*     rpld - an IBM style RIPL server            *
4 .\"*************************************************/
5 .\"
6 .\"Copyright (c) 1999,2000, James McKenzie.
7 .\"                     All rights reserved
8 .\"Copyright (c) 1998,2000, Christopher Lightfoot.
9 .\"                     All rights reserved
10 .\"
11 .\"By using this file, you agree to the terms and conditions set
12 .\"forth in the LICENSE file which can be found at the top level of
13 .\"the rpld distribution.
14 .\"
15 .\"IBM is a trademark of IBM Corp.
16 .\"
17 .\"
18 .\"
19 .\" $Id: rpld.conf.man,v 1.7 2000/07/17 10:45:38 root Exp $;
20 .\"
21 .\" $Log: rpld.conf.man,v $
22 .\" Revision 1.7  2000/07/17 10:45:38  root
23 .\" #
24 .\"
25 .\" Revision 1.6  2000/07/17 10:43:34  root
26 .\" #
27 .\"
28 .\" Revision 1.5  2000/07/16 14:22:06  root
29 .\" #
30 .\"
31 .\" Revision 1.4  2000/07/16 14:05:28  root
32 .\" #
33 .\"
34 .\" Revision 1.3  2000/07/16 13:18:10  root
35 .\" #
36 .\"
37 .\" Revision 1.1  2000/07/16 13:16:33  root
38 .\" #
39 .\"
40 .\" Revision 1.7  1999/09/15 14:29:10  root
41 .\" #
42 .\"
43 .\" Revision 1.6  1999/09/15 01:22:18  root
44 .\" #
45 .\"
46 .\" Revision 1.5  1999/09/15 00:36:29  root
47 .\" #
48 .\"
49 .\" Revision 1.4  1999/09/15 00:22:07  root
50 .\" #
51 .\"
52 .\" Revision 1.3  1999/09/15 00:14:29  root
53 .\" #
54 .\"
55 .\" Revision 1.2  1999/09/14 21:25:59  root
56 .\" #
57 .\"
58 .\" Revision 1.1  1999/09/14 21:00:47  root
59 .\" #
60 .\"
61 .\" Revision 1.1  1999/09/14 17:19:37  root
62 .\" Initial revision
63 .\"
64 .\";
65 .Dd Jun 16, 2000
66 .Dt RPLD.CONF 5
67 .Os Linux
68 .Sh NAME
69 .Nm rpld.conf
70 .Nd rpld configuration file
71 .Sh DESCRIPTION
72 The 
73 .Xr rpld.conf
74 file is the configuration file for the
75 .Pa rpld(1)
76 program.
77 It consists of a number of HOST blocks of the form:
78 .Bd -literal -ffset indent
79 HOST {
80      ...
81 };
82
83 .Ed
84 Within the HOST blocks there can be 
85 ethernet, execute, framesize, blocksize, nospew, and pacing  directives 
86 and FILE blocks.
87 FILE blocks are of the form:
88 .Bd -literal -ffset indent
89         FILE {
90              ...
91         };
92
93 .Ed
94 Within FILE blocks there can be path, offset, length, load and linux directives.
95 Directives are of the form
96 .Bd -literal -ffset indent
97         foo = something;
98 or
99 .Bd -literal -ffset indent
100         bar;
101
102 .Ed
103 and are detailed below. Comments are allowed in the configuration file and
104 can either be in C-form (i.e. starting with /* and ending with */) or C++ form
105 (starting with // and ending at the line break).
106 .Pp
107 .Sh DIRECTIVES
108 .Pp
109 Directives are of the form 
110 .Bd -literal -ffset indent
111         foo = something;
112 or
113 .Bd -literal -ffset indent
114         bar;
115
116 .Ed
117 If something is a string it should be entered between quotes. Numbers are
118 assumed to be decimal unless preceded by 0x in which case they are interpreted
119 in hexadecimal. MAC addresses should be given as 6 octets in hexadecimal without
120 the leading 0x. The octets should be separated by colons.
121 .Bd -literal -ffset indent
122         number = 131;
123         hexnumber = 0x7382;
124         macaddr = 08:00:02:43:21:22;
125         string = "fish soup";
126
127 .Ed
128 .Bl -tag -width 0 -compact
129 .It Pa blocksize
130 This directive sets the maximum size in octets of data that is transmitted in
131 each
132 FILE.DATA.RESPONSE frame that the server sends. The block size should
133 be at least 48 octets smaller than the frame size. After the client negotiates
134 a frame size the block size is checked and if it is no longer 48 octets smaller
135 than frame size it is adjusted accordingly. Some buggy boot ROMs will fail
136 if block size is not a multiple of four, accordingly you should be aware of the
137 situation that could arise if the client was to negotiate the block size down
138 to something that wasn't a multiple of four.
139 .Bd -literal -ffset indent
140         blocksize = 528;
141
142 .Ed
143 .It Pa ethernet
144 This directive sets the MAC address of the client referenced
145 in this HOST block. It should either be formatted as six octets separated by colons. e.g..
146 .Bd -literal -ffset indent
147         ethernet = 00:60:6e:33:4f:2c;
148
149 .Ed
150 or it can be specified as a range of mac addresses as six octets separated by colons followed by a solidus and the number of bytes to match. So:
151 .Bd -literal --ffset indent
152         ethernet = 00:50:32:33:00:00/4;
153
154 .Ed
155 Will match anything of the form 00:50:32:33:xx:xx. It is expected that this 
156 support will be changed from bytes to bits in a future release.
157
158 .It Pa execute
159 This directive sets the execute address that control is transferred to when 
160 downloading has finished. It should be a number in either decimal or hexadecimal.
161 .Bd -literal -ffset indent
162         execute = 0x92000;
163
164 .Ed
165 It is not clear whether or not the client's Ethernet adapter is or should be shut down
166 prior to the transfer of control. This may cause problems on systems where the
167 Ethernet adapter in the client can do DMA directly into host memory. As the adapter may 
168 continue writing to the buffers that the boot ROM set up, it may be necessary
169 to download a small program to reset the Ethernet adapter. See code under the
170 .Pa nics/
171 directory in the source distribution for examples.
172 .It Pa framesize
173 This directive sets the maximum size of the frames that the server uses to
174 communicate with the client. The actual frame size used is negotiated between
175 the client and the server, the server will force the client to use this value
176 if it requests a larger one. The maximum frame size that Ethernet can support is
177 1500, and this is the default value.
178 .Bd -literal -ffset indent
179         framesize = 576;
180
181 .Ed
182 .It Pa length
183 This directive sets the number of octets transmitted to the client for this
184 FILE block. If this directive is not specified the server transmits data 
185 until an end of file condition occurs.
186 .Bd -literal -ffset indent
187         length = 4096;
188
189 .Ed
190 would send 4096 octets from the file.
191 .It Pa linux
192 This directive takes no argument. It indicates to 
193 .Xr rpld 1
194 that the file specified in the path directive is a Linux kernel image. 
195 .Xr rpld 1
196 then analyses the kernel image and generates three FILE blocks corresponding
197 to the primary boot loader, secondary boot loader, and data portions of the image.
198 It then sets a default execute address which points to the secondary boot loader
199 which is loaded at 0x90200. The execute address may be over-ridden with an execute
200 directive which appears AFTER the FILE block. 
201 .Bd -literal -ffset indent
202         linux;
203
204 .Ed
205 .Xr rpld 1
206 may have problems with bzImage kernels.
207 .It Pa load
208 This directive sets the load address for this FILE block. Data is read from 
209 .Pa offset
210 octets into the file at copied to the client starting at the address
211 specified by the load directive. The FILE block
212 .Bd -literal -ffset indent
213 FILE {
214         path = "/rplboot/fish";
215         offset = 512;
216         length = 4096;
217         load = 0x90200;
218 };
219
220 .Ed
221 would load 4096 octets from the file 
222 .Pa /rplboot/fish
223 starting 512 octets into the file into the
224 client's memory starting 
225 at address 0x90200. (so the 513th byte of the file will load to address 0x90200)
226 .It Pa nospew
227 This directive causes rpld to emit only one FILE.DATA.RESPONSE frame for SEND.FILE.REQUEST frame received. The usual behaviour is the client sends one FILE.DATA.RESPONSE frame which causes the server to transmit all the FILE.DATA.RESPONSE frames
228 in order (see 
229 .Pa pacing
230 ) Some RPL boot proms have made this sensible modification to the protocol. 
231 .Pa NB
232 if you
233 specify this directive when it is not required, most roms will send another 
234 SEND.FILE.REQUEST frame after a timeout of about one second. Some roms will only
235 make twenty or so retransmits before aborting the boot.
236 .It Pa offset
237 This directive sets the offset for this FILE block. Data is read from 
238 .Pa offset
239 octets into the file at copied to the client starting at the address
240 specified by the load directive.
241 .Bd -literal -ffset indent
242         offset = 512;
243
244 .Ed
245 .It Pa pacing
246 This directive sets the minimum time gap in us between sequential frames when
247 the 
248 .Pa nospew
249 option is NOT set. 1000 (or 1 ms) is a reasonable choice and the default. 
250 Increase this if the client has to issue retransmits.
251 .It Pa path
252 This directive sets the path to the file that is to be downloaded. The file
253 must exist, and is examined at startup and on reception of SEND.FILE.REQUEST
254 frames.
255 .Bd -literal -ffset indent
256         path = "/rplboot/fish";
257
258 .Ed
259 .El
260 .Sh NOTES
261 .Pp
262 The server downloads the FILE blocks in the inverse order to that in which
263 they were specified. Boot ROMs typically prefer the blocks to arrive in
264 decreasing load address, so you should specify them in increasing load address.
265 The server recalculates the length of all the files specified on reception of
266 a SEND.FILE.REQUEST frame. If the file changes size during downloading
267 the server will attempt to read to the original length of the file. If it 
268 encounters an end of file condition empty FILE DATA FRAMES will be sent. For Linux
269 kernel images the first sector of the kernel image will only be read from
270 disk when rpld is started. The first sector contains information such as the
271 default root device and the length of secondary boot loader.
272 You should therefore restart rpld if you change the version
273 of the kernel you are downloading. The order of directives is important: the
274 execute directive, if present, should always come after the 
275 .Pa linux
276 directive. 
277
278 .Sh Example
279 .Pp
280 A complete example file using every directive:
281 .Bd -literal -ffset indent
282 // Sample rpld.conf file 
283 /* (c) 1999 James McKenzie and
284  *          Christopher Lightfoot
285  *          All rights reserved.
286  */
287
288 HOST {
289         ethernet=08:00:02:32:1e:fc;
290         FILE {
291                 path="/rplboot/vmlinuz";
292                 linux;
293         };
294         FILE {
295                 path="/rplboot/vesarom.img";
296                 offset=0x200;
297                 length=0x400;
298                 load=0x92000;
299         };
300         execute=0x92000;
301         pacing=2000;
302 };
303
304 .Ed
305 .Sh FILES
306 .Bl -tag -width /etc/rpld.conf -compact
307 .It Pa /etc/rpld.conf
308 The
309 .Xr rpld 1
310 configuration file.
311 .El
312 .Sh SEE ALSO
313 .Xr rpld 1 ,
314 .Xr bootpd 1 ,
315 .Xr dhcpd 1 ,
316 .Xr http://gimel.esc.cam.ac.uk/james/rpld ;
317 .Sh AUTHORS AND COPYRIGHT
318 .Pp
319 (c) 1999,2000 James McKenzie, and Christopher Lightfoot. All rights reserved.