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