
=head1 NAME

pxe-kexec - Read PXE configuration file and kexec entries


=head1 SYNOPSIS

pxe-kexec [options] [I<tftp_server>]


=head1 DESCRIPTION

=head2 Overview

B<pxe-kexec> is a tool that fetches PXE configuration from a TFTP server,
reads that PXE configuration file, prompts the user for an boot entry,
downloads the specified kernel and initrd and finally tries to boot the
kernel.

The normal process to boot with kexec(8) is that pxe-kexec loads the
kernel and invokes reboot(8). The shutdown script of the Linux distribution
then executes "kexec -e" at the very end. That is not implemented everywhere.
Therefore, pxe-kexec has a whitelist of Linux distributions that support
reboot with kexec. If the distribution is not on that whitelist, the
program quits with a warning. To bypass that warning, please use the
"--igore-whitelist" parameter. You can also use the "--force" parameter
to execute "kexec -e" to immediately boot the selected kernel, without
invoking shutdown(8)/reboot(8).

pxe-kexec meant to be used in an environment where pre-defined PXE
configurations exist but the user wants to use kexec(8) instead of rebooting.

Normally, the I<tftp_server> must be specified as first argument. If there's
no TFTP server specified, pxe-kexec looks in the DHCP info file for the
DHCP server and uses this one as TFTP server. This only works when the TFTP
server is running on the same machine as the DHCP server.

B<==E<gt> Please also read the section called "Update Info" E<lt>==>

=head2 Whitelist

As mentioned previously, a whitelist of Linux distributions that support
kexec-based rebooting is maintained. Currently following distributions
are on the whitelist:

=over 7

=item *

openSUSE, starting with version 11.0

=item *

Ubuntu, starting with version 9.04

=item *

Red Hat Enterprise Linux and CentOS, starting with version 5.3

=item *

Fedora Linux, starting with version 11

=item *

ARCH Linux

=back

Don't hesitate to send the author an email to add the distribution to the
whitelist. Please include the output of "pxe-kexec --print-distribution"
in that mail.



=head1 OPTIONS

Following options can be specified:

=over 7

=item B<-h> | B<--help>

Prints a short help.

=item B<-v> | B<--version>

Prints the version number to standard output.

=item B<-f> | B<--force>

Immediately load the kernel without invoking reboot(8). This does not execute
shutdown scripts, i.e. does not terminate daemons, network connections etc.

=item B<-L> | B<--load-only>

When that option is specified, the new kernel is only loaded. No reboot is
triggered and "kexec -e" is also not executed.

=item B<-w> | B<--ignore-whitelist>

Don't check if the detected Linux distribution is on the whitelist of
distributions that have kexec(8) in their shutdown script. Please don't
use that parameter without letting the author know which distribution
you use and how to detect that distribution. Then the distribution can be
added to the whitelist and other users profit from that experience.

=item B<-l> I<label> | B<--label> I<label>

Specifies the label that should be booted. Use that option if you already know
which I<label> you want to boot. This option implies "--quiet".

=item B<-i> | B<--interface> I<netif>

Uses I<netif> instead of the first (non-loopback and up) interface that is
found. Example: "eth5".

=item B<-n> | B<--noconfirm>

Don't ask the user for confirmation before booting an entry. Use that option
with care!

=item B<-Y> | B<--dry-run>

Don't execute call to kexec and don't switch the virtual console before
running "kexec -e". Instead, print the information which program would
be executed with which arguments to standard error.

=item B<-q> | B<--quiet>

Don't display the PXE messages that are added in the PXE configuration with
the I<say> keyword. Also don't display messages which PXE configuration files
the downloader tries to fetch.

=item B<-p> | B<--print-distribution>

Only prints the detected Linux distribution and exits. For example:

    Type        : Ubuntu
    Name        : Ubuntu
    Release     : 9.04
    Codename    : jaunty
    Description : Ubuntu 9.04

This option is very useful if your distribution is not on the whitelist
of Linux distributions that support kexec(8) in the reboot scripts and you
want to create a bugreport.

This command does not require root privileges.

=item B<-D> | B<--debug>

Enable debugging output. That's good for finding (and fixing!) bugs.

=item B<-d> | B<--nodelete>

Keep downloaded files.

=item B<-F> | B<--ftp>

Always use FTP instead of TFTP. Useful for servers that share TFTP root and
FTP root. (Passive) FTP has the advantage that it passes firewalls better
than TFTP.

=back

=head1   UPDATE INFO

=head2   Updating from 0.1.x to 0.2

Compared to version 0.1.x, the syntax has changed:

=over 7

=item *

The default label must now be set with the B<-l> I<label> option instead of
the 2nd argument. Example:

  % pxe-kexec mydhcp.mydomain.com SLES10-install-auto

is now

  % pxe-kexec -l SLES10-install-auto mydhcp.mydomain.com

=item *

pxe-kexec now uses the reboot mechanism by default: The kernel is loaded,
then the reboot is triggered and the reboot script of the Linux distribution
finally boots the kernel. This has the advantage of a clear shutdown.

The program keeps a database of Linux distributions that support kexec-based
reboot. If the currently active distribution is not on the whitelist, an
error is printed. (That whitelist can be ignored with "--ignore-whitelist".)

=item *

To use the previous behaviour, i.e. just execute "kexec -e" in pxe-kexec
at the end, you can still use the "--force" parameter. Example:

  % pxe-kexec mydhcp.mydomain.com

is now

  % pxe-kexec --force mydhcp.mydomain.com


=item *

If you want to have the old "dry-run" behaviour back, which in fact only
missed the last "kexec -e" step, you can use the option "--load-only".
Example:

  % pxe-kexec --dry-run mydhcp.mydomain.com

is now

 % pxe-kexec --load-only mydhcp.mydomain.com

=back


=head1   EXAMPLES

=over 7

=item B<pxe-kexec I<mydhcp.mydomain.com>>

Try to fetch the PXE configuration from I<mydhcp.mydomain.com>, display
the I<say> messages from that configuration, prompt for an entry, letting
the user confirm that entry and finally load that entry via kexec(8)
and reboot via reboot(8).

This only works if you distribution supports kexec-based rebooting, i.e.
it is in the internal whitelist.

=item B<pxe-kexec -n I<mydhcp.mydomain.com>>

Same as the previous example, but omit the final confirmation step.

=item B<pxe-kexec -l I<SLES10-install-auto> I<mydhcp.mydomain.com> >

Same as the first example, but don't prompt the user for the label to boot.
Directly boot the I<SLES10-install-auto> label, but letting the user confirm
that he really wants to boot this!

=item B<pxe-kexec -n -l I<SLES10-install-auto> I<mydhcp.mydomain.com>>

Same as the previous example, but without confirmation.

=item B<pxe-kexec -f I<mydhcp.mydomain.com>>

Same as the first example, but execute "kexec -e" at the end instead of
invoking reboot(8).

=item B<pxe-kexec -l I<mydhcp.mydomain.com>>

Same as the first example, but don't trigger a reboot. Instead, the kernel
is just loaded. If your distribution supports kexec-based rebooting, the
kernel will be loaded on next reboot. You can also run "kexec -e" manually
at any time.


=back

=head1 AUTHOR

The B<pxe-kexec> program and documentation has been written by Bernhard Walle
E<lt>bernhard@bwalle.deE<gt>.

=head1 BUGS

This program has no bugs. If you find a feature that should be removed,
please report to E<lt>bernhard@bwalle.deE<gt>
if you don't want to create an account.

=head1 SEE ALSO

kexec(8)


=cut

# vim: set spelllang=en_gb spell fdm=marker tw=78:
