http://gimel.esc.cam.ac.uk/james/rpld/src/rpld-1.2.tar.gz
[rpld.git] / doc / rpld.conf.5
1 <beginning of page>
2 RPLD.CONF ( 5 ) UNIX Programmer's Manual RPLD.CONF ( 5 )
3 NAME                 
4  rpld.conf <-> rpld configuration file
5 DESCRIPTION                 
6  The rpld.conf file is the configuration file for the rpld(1) program. It
7  consists of a number of HOST blocks of the form:
8  HOST {
9   ...
10  };
11  Within the HOST blocks there can be ethernet, execute, framesize and
12  blocksize directives and FILE blocks. FILE blocks are of the form:
13   FILE {
14    ...
15   };
16  Within FILE blocks there can be path, offset, length, load and linux di<hy>
17  rectives. Directives are of the form
18   foo = something;
19  or
20   bar;
21  and are detailed below. Comments are allowed in the configuration file
22  and can either be in C-form (i.e. starting with /* and ending with */) or
23  C++ form (starting with // and ending at the line break).
24 DIRECTIVES                 
25  Directives are of the form
26   foo = something;
27  or
28   bar;
29  If something is a string it should be entered between quotes. Numbers are
30  assumed to be decimal unless preceded by 0x in which case they are inter<hy>
31  preted in hexadecimal. MAC addresses should be given as 6 octets in hex<hy>
32  adecimal without the leading 0x. The octets should be separated by
33  colons.
34   number = 131;
35   hexnumber = 0x7382;
36   macaddr = 08:00:02:43:21:22;
37   string = "fish soup";
38  blocksize
39  This directive sets the maximum size in octets of data that is trans<hy>
40  mitted in each FILE.DATA.RESPONSE frame that the server sends. The
41  block size should be at least 48 octets smaller than the frame size.
42  After the client negotiates a frame size the block size is checked and
43  if it is no longer 48 octets smaller than frame size it is adjusted ac<hy>
44  cordingly. Some buggy boot ROMs will fail if block size is not a multi<hy>
45  ple of four, accordingly you should be aware of the situation that
46  could arise if the client was to negotiate the block size down to some<hy>
47  thing that wasn't a multiple of four.
48   blocksize = 528;
49 <beginning of page>
50  ethernet
51  This directive sets the MAC address of the client referenced in this
52  HOST block. It should be formatted as six octets separated by colons.
53  e.g..
54   ethernet = 00:60:6e:33:4f:2c;
55  execute
56  This directive sets the execute address that control is transferred to
57  when downloading has finished. It should be a number in either decimal
58  or hexadecimal.
59   execute = 0x92000;
60  It is not clear whether or not the client's Ethernet adapter is or
61  should be shut down prior to the transfer of control. This may cause
62  problems on systems where the Ethernet adapter in the client can do DMA
63  directly into host memory. As the adapter may continue writing to the
64  buffers that the boot ROM set up, it may be necessary to download a
65  small program to reset the Ethernet adapter. See code under the nics/
66  directory in the source distribution for examples.
67  framesize
68  This directive sets the maximum size of the frames that the server uses
69  to communicate with the client. The actual frame size used is negotiat<hy>
70  ed between the client and the server, the server will force the client
71  to use this value if it requests a larger one. The maximum frame size
72  that Ethernet can support is 1500, and this is the default value.
73   framesize = 576;
74  length
75  This directive sets the number of octets transmitted to the client for
76  this FILE block. If this directive is not specified the server trans<hy>
77  mits data until an end of file condition occurs.
78   length = 4096;
79  would send 4096 octets from the file.
80  linux
81  This directive takes no argument. It indicates to rpld(1) that the file
82  specified in the path directive is a Linux kernel image. rpld(1) then
83  analyses the kernel image and generates three FILE blocks corresponding
84  to the primary boot loader, secondary boot loader, and data portions of
85  the image. It then sets a default execute address which points to the
86  secondary boot loader which is loaded at 0x90200. The execute address
87  may be over-ridden with an execute directive which appears AFTER the
88  FILE block.
89   linux;
90  rpld(1) may have problems with bzImage kernels.
91  load
92  This directive sets the load address for this FILE block. Data is read
93  from offset octets into the file at copied to the client starting at
94  the address specified by the load directive. The FILE block
95  FILE {
96   path = "/rplboot/fish";
97   offset = 512;
98   length = 4096;
99   load = 0x90200;
100  };
101  would load 4096 octets from the file /rplboot/fish starting 512 octets
102  into the file into the client's memory starting at address 0x90200. (so
103 <beginning of page>
104  the 513th byte of the file will load to address 0x90200)
105  offset
106  This directive sets the offset for this FILE block. Data is read from
107  offset octets into the file at copied to the client starting at the ad<hy>
108  dress specified by the load directive.
109   offset = 512;
110  path
111  This directive sets the path to the file that is to be downloaded. The
112  file must exist, and is examined at startup and on reception of
113  SEND.FILE.REQUEST frames.
114   path = "/rplboot/fish";
115 NOTES                 
116  The server downloads the FILE blocks in the inverse order to that in
117  which they were specified. Boot ROMs typically prefer the blocks to ar<hy>
118  rive in decreasing load address, so you should specify them in increasing
119  load address. The server recalculates the length of all the files speci<hy>
120  fied on reception of a SEND.FILE.REQUEST frame. If the file changes size
121  during downloading the server will attempt to read to the original length
122  of the file. If it encounters an end of file condition empty FILE DATA
123  FRAMES will be sent. For Linux kernel images the first sector of the ker<hy>
124  nel image will only be read from disk when rpld is started. The first
125  sector contains information such as the default root device and the
126  length of secondary boot loader. You should therefore restart rpld if
127  you change the version of the kernel you are downloading. The order of
128  directives is important: the execute directive, if present, should always
129  come after the linux directive.
130 Example                 
131  A complete example file using every directive:
132  // Sample rpld.conf file
133  /* (c) 1999 James McKenzie and
134   * Christopher Lightfoot
135   * All rights reserved.
136   */
137  HOST {
138   ethernet=08:00:02:32:1e:fc;
139    FILE {
140    path="/rplboot/vmlinuz";
141    linux;
142   };
143   FILE {
144    path="/rplboot/vesarom.img";
145    offset=0x200;
146    length=0x400;
147    load=0x92000;
148   };
149   execute=0x92000;
150  };
151 FILES                 
152  /etc/rpld.conf The rpld(1) configuration file.
153 SEE  ALSO               
154  rpld(1),  bootpd(1),  dhcpd(1), 
155  http://bullard.esc.cam.ac.uk/~james/rpld; 
156 AUTHORS  AND  COPYRIGHT             
157 <beginning of page>
158  (c) 1999 James McKenzie, and Christopher Lightfoot. All rights reserved.
159  Linux  Sep 14, 1999 4