Added sample rpld.conf file to load gPXE
[rpld.git] / rpld.man
1 .\" 
2 .\"/*************************************************
3 .\"*     rpld - an IBM style RIPL server            *
4 .\"*************************************************/
5 .\"
6 .\"Copyright (c) 1999,2000, James McKenzie.
7 .\"                     All rights reserved
8 .\"Copyright (c) 1998,2000, 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.man,v 1.12 2000/09/26 03:44:29 root Exp $;
20 .\"
21 .\" $Log: rpld.man,v $
22 .\" Revision 1.12  2000/09/26 03:44:29  root
23 .\" #
24 .\"
25 .\" Revision 1.11  2000/09/26 02:31:38  root
26 .\" #
27 .\"
28 .\" Revision 1.10  2000/07/17 10:43:34  root
29 .\" #
30 .\"
31 .\" Revision 1.9  2000/07/16 21:09:57  root
32 .\" #
33 .\"
34 .\" Revision 1.8  2000/07/16 14:22:06  root
35 .\" #
36 .\"
37 .\" Revision 1.7  2000/07/16 14:05:28  root
38 .\" #
39 .\"
40 .\" Revision 1.6  2000/07/16 13:18:10  root
41 .\" #
42 .\"
43 .\" Revision 1.1  2000/07/16 13:16:33  root
44 .\" #
45 .\"
46 .\" Revision 1.10  1999/09/15 01:22:18  root
47 .\" #
48 .\"
49 .\" Revision 1.9  1999/09/15 00:36:29  root
50 .\" #
51 .\"
52 .\" Revision 1.8  1999/09/15 00:25:57  root
53 .\" #
54 .\"
55 .\" Revision 1.7  1999/09/15 00:22:07  root
56 .\" #
57 .\"
58 .\" Revision 1.6  1999/09/15 00:14:29  root
59 .\" #
60 .\"
61 .\" Revision 1.5  1999/09/14 21:43:30  root
62 .\" #
63 .\"
64 .\" Revision 1.4  1999/09/14 21:37:08  root
65 .\" #
66 .\"
67 .\" Revision 1.3  1999/09/14 21:32:12  root
68 .\" #
69 .\"
70 .\" Revision 1.2  1999/09/14 21:25:59  root
71 .\" #
72 .\"
73 .\" Revision 1.1  1999/09/14 21:00:47  root
74 .\" #
75 .\"
76 .\" Revision 1.1  1999/09/14 17:19:37  root
77 .\" Initial revision
78 .\"
79 .\";
80 .Dd Jun 16, 2000
81 .Dt RPLD 8
82 .Os Linux
83 .Sh NAME
84 .Nm rpld
85 .Nd an RPL/RIPL remote boot server
86 .Sh SYNOPSIS
87 .Nm rpld 
88 [\fI-f\fR] [\fI-C\ configfile\fR] [\fI-i\ iface\fR] [\fI-s\ sap\fR] [\fI-h\fR] 
89 .Sh WARRANTY
90 .Nm rpld 
91 DOES NOT come with ANY WARRANTY, NOT even an IMPLIED WARRANTY.
92 .Sh OPTIONS
93 .Bl -tag -width Op
94 .It \fB\-f\fR
95 this flag causes \fBrpld\fR to run in the foreground, and not to fork and run as a daemon.
96 .It \fB\-C\fR\ \fIconfigfile\fR
97 causes \fBrpld\fR to read \fIconfigfile\fR rather than the default configuration file.
98 .It \fB\-i\fR\ \fIiface\fR
99 causes \fBrpld\fR to bind to network interface \fIiface\fR rather than the default. Because of the limitations of the LLC 802.2 protocol rpld can only bind to one interface.
100 .It \fB\-s\fR\ \fIsap\fR
101 changes the SAP number that \fBrpld\fR binds to. The IBM standard says this should be 0xf8 but most network cards seem to use 0xfc and some even use 0xf4. You can specify the sap as either a hex number with a leading 0x or a decimal one. Beware of specificing a SAP number which is used for system control packets on a machine with native llc support.
102 .It \fB\-h\fR
103 causes \fBrpld\fR to print a brief help message.
104 .El
105 .Sh DESCRIPTION
106 .Nm rpld 
107 will net-boot IBM style RPL boot ROMs. Communication between the client and the
108 server is done in LLC-1 ui/C frames with the source and destination SAP both 
109 being 0xfc. On booting the client transmits a FIND frame containing the client's
110 MAC address, adapter type and frame length. The server replies with a FOUND frame
111 containing the server's MAC address and a possibly smaller frame length. The
112 client issues a SEND.FILE.REQUEST frame requesting the first block of the boot
113 file. The server then issues a sequence of FILE.DATA.RESPONSE frames with 
114 increasing block numbers. The FILE.DATA.RESPONSE frames contain a load address
115 and an execute address and a flag. If the client fails to receive a  
116 FILE.DATA.RESPONSE frame within a certain period it sends another 
117 SEND.FILE.REQUEST frame requesting the block which follows the last block that
118 was successfully received. On the last FILE.DATA.RESPONSE frame the server
119 sets a special value of the flags which cause the client to transfer execution
120 to the execute address specified in the frame.
121 .Pp
122 The server starts by reading the configuration file in /etc/rpld.conf,
123 see 
124 .Pa rpld.conf(5),
125 After the configuration file has been read, it opens the system's
126 default network interface and listens for RPL frames.
127 The server recalculates the length of all the files to be downloaded every time
128 it receives a SEND.FILE.REQUEST frame. 
129 .Sh BUGS
130 .Bl -tag -width 0 -compact
131 .It
132 Solenopsis invicta Burens
133 .It
134 rpld doesn't support the new bzImage format correctly.
135 .It
136 rpld doesn't reload the first 512 octets of Linux kernels automatically.
137 .It
138 There is no way to make rpld re-read its configuration file.
139 .It
140 When concurrently serving multiple clients rpld will choose the pacing value of the slowest one.
141 .It
142 Partial ethernet addresses should be specified in bits not bytes.
143 .It
144 rpld needs to meet more network adapters.
145 .Sh NOTES
146 .Pp
147 IBM is a trademark of IBM Corp.
148 .Pp There are a number of drivers now provided with rpld read the README file
149 and the makefile in the distribution for more information.
150 .Sh FILES
151 .Bl -tag -width /etc/rpld.conf -compact
152 .Pp
153 .It Pa /usr/sbin/rpld
154 .It Pa /etc/rpld.conf
155 .It Pa /rplboot
156 .El
157 .Sh SEE ALSO
158 .Pp
159 .Bl -tag -width 0 -compact
160 .It Pa rpld\.conf(5),
161 .It Pa bootpd(1),
162 .It Pa dhcpd(1),
163 .It Pa http://gimel.esc.cam.ac.uk/james/rpld;
164 .El
165 .Sh AUTHORS AND COPYRIGHT
166 .Pp
167 (c) 1999,2000 James McKenzie, and Christopher Lightfoot. All rights reserved.