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