rpld.conf - Man Page

The rpld.conf file is the configuration file for the rpld(1) program. It consists of a number of HOST blocks of the form:

HOST {
     ...
};

Within the HOST blocks there can be ethernet, execute, framesize, blocksize, nospew, and pacing directives and FILE blocks. FILE blocks are of the form:

	FILE {
	     ...
	};

Within FILE blocks there can be path, offset, length, load and linux directives. Directives are of the form

	foo = something;
or

bar;

and are detailed below. Comments are allowed in the configuration file and can either be in C-form (i.e. starting with /* and ending with */) or C++ form (starting with // and ending at the line break).

Directives are of the form

	foo = something;
or

bar;

If something is a string it should be entered between quotes. Numbers are assumed to be decimal unless preceded by 0x in which case they are interpreted in hexadecimal. MAC addresses should be given as 6 octets in hexadecimal without the leading 0x. The octets should be separated by colons.

number = 131; hexnumber = 0x7382; macaddr = 08:00:02:43:21:22; string = "fish soup";

blocksize

This directive sets the maximum size in octets of data that is transmitted in each FILE.DATA.RESPONSE frame that the server sends. The block size should be at least 48 octets smaller than the frame size. After the client negotiates a frame size the block size is checked and if it is no longer 48 octets smaller than frame size it is adjusted accordingly. Some buggy boot ROMs will fail if block size is not a multiple of four, accordingly you should be aware of the situation that could arise if the client was to negotiate the block size down to something that wasn't a multiple of four.

blocksize = 528;

ethernet

This directive sets the MAC address of the client referenced in this HOST block. It should either be formatted as six octets separated by colons. e.g..

ethernet = 00:60:6e:33:4f:2c;

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:

ethernet = 00:50:32:33:00:00/4;

Will match anything of the form 00:50:32:33:xx:xx. It is expected that this support will be changed from bytes to bits in a future release.

execute

This directive sets the execute address that control is transferred to when downloading has finished. It should be a number in either decimal or hexadecimal.

execute = 0x92000;

It is not clear whether or not the client's Ethernet adapter is or should be shut down prior to the transfer of control. This may cause problems on systems where the Ethernet adapter in the client can do DMA directly into host memory. As the adapter may continue writing to the buffers that the boot ROM set up, it may be necessary to download a small program to reset the Ethernet adapter. See code under the nics/ directory in the source distribution for examples.

framesize

This directive sets the maximum size of the frames that the server uses to communicate with the client. The actual frame size used is negotiated between the client and the server, the server will force the client to use this value if it requests a larger one. The maximum frame size that Ethernet can support is 1500, and this is the default value.

framesize = 576;

length

This directive sets the number of octets transmitted to the client for this FILE block. If this directive is not specified the server transmits data until an end of file condition occurs.

length = 4096;

would send 4096 octets from the file.

linux

This directive takes no argument. It indicates to rpld(1) that the file specified in the path directive is a Linux kernel image. rpld(1) then analyses the kernel image and generates three FILE blocks corresponding to the primary boot loader, secondary boot loader, and data portions of the image. It then sets a default execute address which points to the secondary boot loader which is loaded at 0x90200. The execute address may be over-ridden with an execute directive which appears AFTER the FILE block.

linux;

rpld(1) may have problems with bzImage kernels.

load

This directive sets the load address for this FILE block. Data is read from offset octets into the file at copied to the client starting at the address specified by the load directive. The FILE block

FILE { path = "/rplboot/fish"; offset = 512; length = 4096; load = 0x90200; };

would load 4096 octets from the file /rplboot/fish starting 512 octets into the file into the client's memory starting at address 0x90200. (so the 513th byte of the file will load to address 0x90200)

nospew

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 in order (see pacing ) Some RPL boot proms have made this sensible modification to the protocol. NB if you specify this directive when it is not required, most roms will send another SEND.FILE.REQUEST frame after a timeout of about one second. Some roms will only make twenty or so retransmits before aborting the boot.

offset

This directive sets the offset for this FILE block. Data is read from offset octets into the file at copied to the client starting at the address specified by the load directive.

offset = 512;

pacing

This directive sets the minimum time gap in us between sequential frames when the nospew option is NOT set. 1000 (or 1 ms) is a reasonable choice and the default. Increase this if the client has to issue retransmits.

path

This directive sets the path to the file that is to be downloaded. The file must exist, and is examined at startup and on reception of SEND.FILE.REQUEST frames.

path = "/rplboot/fish";

The server downloads the FILE blocks in the inverse order to that in which they were specified. Boot ROMs typically prefer the blocks to arrive in decreasing load address, so you should specify them in increasing load address. The server recalculates the length of all the files specified on reception of a SEND.FILE.REQUEST frame. If the file changes size during downloading the server will attempt to read to the original length of the file. If it encounters an end of file condition empty FILE DATA FRAMES will be sent. For Linux kernel images the first sector of the kernel image will only be read from disk when rpld is started. The first sector contains information such as the default root device and the length of secondary boot loader. You should therefore restart rpld if you change the version of the kernel you are downloading. The order of directives is important: the execute directive, if present, should always come after the linux directive.

A complete example file using every directive:

// Sample rpld.conf file
/* (c) 1999 James McKenzie and
 *          Christopher Lightfoot
 *          All rights reserved.
 */

HOST {
	ethernet=08:00:02:32:1e:fc;
 	FILE {
		path="/rplboot/vmlinuz";
		linux;
	};
	FILE {
		path="/rplboot/vesarom.img";
		offset=0x200;
		length=0x400;
		load=0x92000;
	};
	execute=0x92000;
	pacing=2000;
};

/etc/rpld.conf

The rpld(1) configuration file.

rpld(1), bootpd(1), dhcpd(1), http://gimel.esc.cam.ac.uk/james/rpld;

(c) 1999,2000 James McKenzie, and Christopher Lightfoot. All rights reserved.

rpld(8).