manual/network_boot/Network_Booting_Kitten_using_PXE.tex

   1 \documentclass[11pt]{article}
   2 \usepackage{times}
   3 \usepackage{fullpage}
   4
   5 \begin{document}
   6
   7 \title{\ \\ \LARGE\bf
   8 Booting Palacios/Kitten Over the Network Using PXE
   9 }
  10
  11 \author{Yuan Tang, Lei Xia}
  12
  13 \maketitle
  14
  15 PXE allows us to boot Kitten/Palacios (and a test guest) remotely from
  16 a network server, which makes testing Palacios on physical machines
  17 much easier.  The following gives instructions on how to set up the
  18 PXE server and client.  Although we explain this specifically in the
  19 context of Kitten/Palacios, PXE can be used to network boot most
  20 operating systems.
  21
  22
  23 In the following, we will assume there are two machines:
  24 \begin{itemize}
  25 \item {\em Server:}  This machine will serve Kitten/Palacios kernels over the network to client machines.
  26 \item {\em Client:}  This machine will request Kitten/Palacios kernels from the server machine.
  27 \end{itemize}
  28
  29 \section{How does it work?}
  30
  31 When the client machine starts up, PXE will first make a DHCP request
  32 to retrieve a temporary IP configuration.   The server will respond to
  33 this request.   Part of the response will indicate that the client
  34 should reconnect back to the server (this time using TCP or UDP) to
  35 retrieve more data using FTP.  The client will do so.  The server will
  36 respond by sending a small bootloader, the kernel, and additional
  37 files.   The client copies this content into relevant memory locations
  38 and jumps to it.   The bootloader then boots the kernel.    In the
  39 typical case with Palacios/Kitten, the kernel contains Kitten and
  40 Palacios, while the additional file contains the init task, which in
  41 turn has the guest image that's being tested embedded in it.
  42
  43
  44
  45 \section{What will we boot?}
  46
  47 PXE can be used to build quite complex boot paths.   For testing
  48 Palacios/Kitten, there are typically only two files involved, however:
  49 \begin{itemize}
  50 \item {\em  bzImage}:  This is the Kitten/Palacios kernel, typically
  51 located\\
  52 at \verb!your_kitten_path/arch/x86_64/boot/bzImage!.
  53 \item {\em init\_task}:  This is the Kitten init task.   It also
  54 contains the guest image that will be used for testing.  It is
  55 typically located at \verb!your_kitten_path/init_task!.
  56 \end{itemize}
  57
  58 For booting, we copy these files into \verb./tftpboot. on the server.
  59
  60
  61 \section{Client requirements}
  62
  63 PXE is a service that is implemented in the client machine's BIOS or
  64 on a network card's BIOS extensions.  Most modern machines, even
  65 inexpensive desktops and laptops, support it but have it turned off by
  66 default.  To turn it on, power cycle the client and enter the BIOS.
  67 There may be an option to enable it here, probably under local
  68 devices/networking.  If you can't find an option there, power cycle
  69 again and wait for the BIOS bootstrap message about your network
  70 card.  There should be an option to hit a key to go into its
  71 configuration screen, in which you should be able to turn on PXE.
  72
  73 \section{Server requirements}
  74
  75 \begin{itemize}
  76 \item DHCP server. DHCP enables the client get an IP address, and
  77 other configuration data automatically from the server.
  78 \item TFTP server.  After the client has an IP address, it will
  79 connect back to the TFTP server it to download the kernel and other
  80 files from the server.
  81 \item Firewall rules that allow access from the client to the DHCP
  82 server and TFTP server.  DHCP typically requires ports 67 and 68,
  83 while TFTP typically uses port 69.
  84 \item PXELINUX boot loader (\verb!pxelinux.0!) installed in
  85 \verb./tftpboot..  You may also want to have \verb.memdisk. in the
  86 same directory if you need to boot more ancient things.
  87 \end{itemize}
  88
  89
  90 \section{DHCP setup on the server}
  91
  92 Install the DHCP service, and configure the file {\em
  93 /etc/dhcpd.conf}.  You want to add the client's Ethernet MAC address
  94 to config file, allow the client to get an IP address/config from
  95 DHCP server at boot time.   Here is an example configuration:
  96 \begin{verbatim}
  97     option domain-name "cs.northwestern.edu";
  98     default-lease-time 600;
  99     max-lease-time 7200;
 100
 101     allow booting;
 102     allow bootp;
 103
 104     <-- Change below section according to your network configuration --->
 105     subnet 165.124.184.0 netmask 255.255.254.0 {
 106         range 165.124.184.90 165.124.184.95;
 107         option broadcast-address 165.124.184.255;
 108         option routers 165.124.184.1;
 109         option domain-name-servers 165.124.180.10;
 110     }
 111
 112     group {
 113       <--- In which IP address the booting machine can find the booting image -->
 114       next-server 165.124.184.209;
 115       host v-test-intel-lab {
 116         <-- Replace below with the IP address assigned to the booting machine -->
 117         fixed-address 165.124.184.92;
 118         <--- Replace below with the MAC address of the booting machine -->
 119         hardware ethernet  00:1B:21:41:CF:4C;
 120         filename "pxelinux.0";
 121       }
 122     }
 123 \end{verbatim}
 124
 125 Notice that you can readily add additional client machines by adding
 126 new \verb.host. entries.
 127
 128 Now you can start the DHCP server.
 129 \begin{verbatim}
 130 [jdoe@newskysaw test]$ service dhcpd restart
 131 \end{verbatim}
 132
 133
 134 \section{TFTP Setup}
 135
 136 After installing the tftp service, enable it by editing the file {\em
 137 /etc/xinetd.d/tftp} so that it looks similar to the following.
 138 Typically you can just delete the line {\em disable = yes}.
 139
 140 \begin{verbatim}
 141     service tftp
 142     {
 143         socket_type             = dgram
 144         protocol                = udp
 145         wait                    = yes
 146         user                    = root
 147         server                  = /usr/sbin/in.tftpd
 148         server_args             = -s /tftpboot
 149         per_source              = 11
 150         cps                     = 100 2
 151         flags                   = IPv4
 152     }
 153
 154 \end{verbatim}
 155
 156 You can now the Kitten/Palacios kernel and init task to the tftp boot
 157 directory, which typically is  {\em /tftpboot}:
 158 \begin{verbatim}
 159 [jdoe@newskysaw test]$ cp your_kitten_path/arch/x86_64/boot/bzImage  \
 160                               /tftpboot/bzImage
 161 [jdoe@newskysaw test]$ cp your_kitten_path/init_task /tftpboot/init_task
 162 \end{verbatim}
 163
 164 You will also want to be sure that you have copied \verb!pxelinux.0!
 165 and \verb.memdisk. to \verb./tftpboot/.
 166
 167 You can now start the TFTP service:
 168 \begin{verbatim}
 169     service xinetd restart
 170 \end{verbatim}
 171
 172
 173 \section{PXE Configuration}
 174
 175 We will now set up the PXE boot configuration.  Create the
 176 directory {\em pxelinux.cfg} in {\em /tftpboot}.  In {\em pxelinux.cfg},
 177 create a new file with the filename as the client's MAC
 178 address, prefaced with \verb.01-.:
 179 \begin{verbatim}
 180 [jdoe@newskysaw test]$ cd /tftpboot
 181 [jdoe@newskysaw test]$ cd pxelinux.cfg
 182 [jdoe@newskysaw test]$ touch 01-00-1b-21-41-cf-4c
 183 \end{verbatim}
 184 Edit this new confuration file ({\em 01-00-1b-21-41-cf-4c} here), to
 185 set up a boot option for the machine.   For Kitten/Palacios testing,
 186 the option typically looks like this:
 187 \begin{verbatim}
 188     default kitten
 189     label kitten
 190         kernel bzImage
 191         append serial.baud=115200 console=serial initrd=init_task
 192
 193     prompt 1
 194     timeout 20
 195 \end{verbatim}
 196
 197 Notice that your kernel bzImage file, and the init task file are both
 198 referenced.  These are the copies that are /tftpboot.  You can have
 199 multiple options in the configuration file, each with a different
 200 label.   You can learn more about these configurations by reading
 201 about PXELINUX.
 202
 203 You can readily add additional machines simply by creating files
 204 reflecting their MAC addresses.   This allows for one PXE server to
 205 support numerous test machines and developers.
 206
 207 \section{Testing}
 208
 209 At this point things should be ready to go. Power on the client
 210 machine, select network booting if prompted. PXE should then go
 211 searching for the DHCP server, find our server, configure, and then
 212 continue the boot process via TFTP.  Within seconds, you will see
 213 the Kitten/Palacios kernel start to boot.
 214
 215 If the client fails to connect to the PXE server, you should check the
 216 firewall settings, making sure they allow the client's connection
 217 requests.   Also, make sure the DHCP and TFTP services are actually
 218 running.
 219
 220 \section{Serial}
 221
 222 For testing, it is usually a good idea to connect the client machine
 223 to some other machine via the serial port.   Palacios and Kitten
 224 produce debugging and logging output via serial communication.   To
 225 connect two machines, you will want a null modem RS232 cable.
 226 Palacios and Kitten typically use 115200 bps communication.   If your
 227 machine's serial port is /dev/ttyS0, then execute the following to see
 228 the output:
 229 \begin{verbatim}
 230 stty -F /dev/ttyS0 115200
 231 cat /dev/ttyS0
 232 \end{verbatim}
 233
 234 Typical machines with a single port on the machine typically actually
 235 have a dual UART.   If you have such a machine, you may want to try
 236 \verb./dev/ttyS1. if \verb./dev/ttyS0. doesn't work.
 237
 238 We have also experienced some challenges using SIIG multiport serial
 239 interfaces, but these can usually be cleared up by configuring them
 240 using:
 241 \begin{verbatim}
 242 setserial /dev/ttySn uart 16950 baud_base 115200
 243 \end{verbatim}
 244
 245
 246 \end{document}
 247
 248
 249