RPLD.CONF(5)

📦 version 1.8, in fedora 43, fedora 44

💖 RPLD.CONF(5) 💖

File Formats Manual — ok bestie, settle in, this is the manual page for RPLD.CONF, section 5 of the File Formats Manual, and we are gonna understand it together. 🎀

🌸 NAME 🌸

rpld.conf — the rpld configuration file, aka the little text file that runs the whole vibe. ✨

🦋 DESCRIPTION 🦋

So rpld.conf is the configuration file for the rpld(1) program. Periodt. It's made up of a bunch of HOST blocks that look like this:

HOST {
     ...
};

Inside those HOST blocks you can have ethernet, execute, framesize, blocksize, nospew, and pacing directives, plus FILE blocks. And FILE blocks look like:

FILE {
     ...
};

Inside FILE blocks you get path, offset, length, load and linux directives. Now — directives themselves are shaped like:

foo = something;

or

bar;

and they're all detailed down below, no cap. 💅

Oh and comments are allowed, obviously. You can do them C-style (starts with /* and ends with */) or C++-style (starts with // and ends at the line break). Both valid, both iconic.

✨ DIRECTIVES ✨

Okay so, reminder, directives are shaped like:

foo = something;

or

bar;

If something is a string, put it between quotes, bestie. Numbers are assumed decimal unless you prefix them with 0x, in which case they're read as hexadecimal. MAC addresses go in as 6 octets in hexadecimal without the leading 0x, and the octets get separated by colons. Like:

number = 131;
hexnumber = 0x7382;
macaddr = 08:00:02:43:21:22;
string = "fish soup";
  • blocksize — this one sets the max size, in octets, of the data transmitted in each FILE.DATA.RESPONSE frame the server sends. The block size should be at least 48 octets smaller than the frame size. Once the client negotiates a frame size, the block size gets checked, and if it's no longer 48 octets smaller than the frame size it gets adjusted accordingly. Now listen — some buggy boot ROMs will fail if block size isn't a multiple of four, so you should be aware of the situation that could arise if the client negotiates the block size down to something that wasn't a multiple of four. 😭
blocksize = 528;
  • ethernet — sets the MAC address of the client referenced in this HOST block. Format it as six octets separated by colons, e.g.
ethernet = 00:60:6e:33:4f:2c;

or you can specify it as a range of mac addresses: 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. Heads up though — it's expected that this support will be changed from bytes to bits in a future release. 👀

  • execute — sets the execute address that control is transferred to when downloading has finished. Should be a number in decimal or hexadecimal.
execute = 0x92000;
Now here's the tea: 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. Since 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 — sets the maximum size of the frames the server uses to communicate with the client. The actual frame size used is negotiated between the client and the server, and the server will force the client to use this value if the client requests a larger one. The maximum frame size Ethernet can support is 1500, and that's the default value. slay.
framesize = 576;
  • length — sets the number of octets transmitted to the client for this FILE block. If you don't specify it, the server just transmits data until an end of file condition occurs.
length = 4096;

would send 4096 octets from the file. simple as that.

  • linux — takes no argument. It tells 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. Then it 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;
ngl, rpld(1) may have problems with bzImage kernels. 💀
  • load — sets the load address for this FILE block. Data is read from offset octets into the file and copied to the client starting at the address specified by the load directive. So this 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) math queen behavior fr fr 🧚

  • nospew — makes rpld emit only one FILE.DATA.RESPONSE frame for each 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. so like, don't just sprinkle it around bestie 😭
  • offset — sets the offset for this FILE block. Data is read from offset octets into the file and copied to the client starting at the address specified by the load directive.
offset = 512;
  • pacing — 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 — 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";

📝 NOTES 📝

okay this part is important, pay attention bestie:

  • 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. no skipping this one 😤
  • The order of directives is important: the execute directive, if present, should always come after the linux directive.

🎀 Example 🎀

A complete example file using every directive — chef's kiss, she ate:

// 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;
};

🌈 FILES 🌈

  • /etc/rpld.conf — the rpld(1) configuration file. that's the one, that's the file 💖

👑 SEE ALSO 👑

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.

and that's the whole page bestie!! 🫶 this was RPLD.CONF(5) from the Linux manual, dated Jun 16, 2000 — go forth and configure, you absolute icon ✨💅🎀

📦 where this page comes from