doc/en_US.ISO8859-1/articles/pxe/article.sgml

<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
]>

<article>
  <articleinfo>
    <title>FreeBSD Jumpstart Guide</title>

    <authorgroup>
      <author>
        <firstname>Alfred</firstname>
        <surname>Perlstein</surname>

        <affiliation>
          <address><email>alfred@FreeBSD.org</email></address>
        </affiliation>
      </author>
    </authorgroup>

    <pubdate>$FreeBSD$</pubdate>

    <legalnotice id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.intel;
      &tm-attrib.general;
    </legalnotice>

    <abstract>
      <para>This article details the method used to allow machines to install
        FreeBSD using the &intel; PXE method of booting a machine over a network.
        </para>
    </abstract>
  </articleinfo>

  <sect1 id="introduction">
    <title>Introduction</title>

    <warning>
      <para>This procedure will make the <quote>Server</quote> both insecure and dangerous,
        it is best to just keep the <quote>Server</quote> on its own hub and not in any way
        accessible by any machines other than the <quote>Clients</quote>.</para>
    </warning>

    <para>Terminology:</para>

    <informaltable frame="none" pgwide="1">
      <tgroup cols="2">

        <tbody>
          <row>
            <entry>Server</entry>
            <entry>The machine offering netboot and install options.</entry>
          </row>

          <row>
            <entry>Client</entry>
            <entry>The machine that will have FreeBSD installed on it.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>Requires:
      Clients supporting the &intel; PXE netboot option, an Ethernet connection.
      </para>

    <para>Please let me know if you come across anything you have problems with
      or suggestions for additional documentation.</para>

    <para>If you would like someone to train/implement a specific netinstall system
      for you, please send email so that we can discuss terms.</para>

    <para>I would also like to thank &a.ps; and &a.jhb; for doing most of the
      programming work on pxeboot, the interface to the &intel; PXE (netboot)
      system.</para>
  </sect1>

  <sect1 id="server-config">
    <title>Server Configuration</title>

    <procedure>
      <step>
        <para>Install DHCP: Install <filename role="package">net/isc-dhcp3-server</filename> you can use this config file
          <ulink url="dhcpd.conf">
          <filename>dhcpd.conf</filename></ulink>, stick it in <filename>/usr/local/etc/</filename>.</para>
      </step>

      <step>
        <para>Enable tftp:</para>
	
        <procedure>
          <step>
            <para>Make a directory <filename>/usr/tftpboot</filename></para>
          </step>

          <step>
            <para>Add this line to your
              <filename>/etc/inetd.conf</filename>:</para>
	
<programlisting>tftp    dgram   udp     wait    nobody  /usr/libexec/tftpd    tftpd /usr/tftpboot</programlisting>
          </step>
        </procedure>

      </step>

      <step>
        <para>Enable NFS:</para>
	
        <procedure>
          <step>
            <para>Add this to <filename>/etc/rc.conf</filename>:</para>

	    <programlisting>nfs_server_enable="YES"</programlisting>
          </step>

          <step>
            <para>Add this to <filename>/etc/exports</filename>:</para>

	    <programlisting>/usr -alldirs -ro</programlisting>
          </step>
        </procedure>
      </step>

      <step>
        <para>Reboot to enable the new services or start them
          manually.</para>
      </step>
    </procedure>
  </sect1>

  <sect1 id="bootstrap-config">
    <title>Bootstrap Setup</title>

    <procedure>
      <step>
        <para>Download bootfiles: Download the
          <ulink
	  url="&snapshots.stable;/floppies/kern.flp">
          kern.flp</ulink> and
          <ulink
	  url="&snapshots.stable;/floppies/mfsroot.flp">
          mfsroot.flp</ulink> floppy images.</para>
      </step>

      <step>
        <para>Set up tftp/pxe-boot directory:</para>
	
        <procedure>
          <step>
            <para>Put pxeboot in the boot directory:</para>
	
	    <screen>&prompt.root; <userinput>rm -rf /usr/obj/*</userinput>
&prompt.root; <userinput>cd /usr/src/sys/boot</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>cp /usr/src/sys/boot/i386/pxeldr/pxeboot /usr/tftpboot</userinput></screen>
          </step>

          <step>
            <para>Using the vndevice mount the <filename>kern.flp</filename>
	      file and copy its contents to
	      <filename>/usr/tftpboot</filename>:</para>

	    <screen>&prompt.root; <userinput>vnconfig vn0 kern.flp</userinput>    # associate a vndevice with the file
&prompt.root; <userinput>mount /dev/vn0 /mnt</userinput>      # mount it
&prompt.root; <userinput>cp -R /mnt /usr/tftpboot</userinput> # copy the contents to /usr/tftpboot
&prompt.root; <userinput>umount /mnt</userinput>              # unmount it
&prompt.root; <userinput>vnconfig -u vn0</userinput>          # disassociate the vndevice from the file</screen>
          </step>
        </procedure>
      </step>

      <step>
        <para>Compile a custom kernel for the clients (particularly to avoid
          the device config screen at boot) and stick it in
          <filename>/usr/tftpboot</filename>.</para>
      </step>

      <step>
        <para>Make a special <filename>loader.rc</filename> to and install it
          in <filename>/usr/tftpboot/boot/loader.rc</filename> so that it
          does not prompt for the second disk, here is
          <ulink url="loader.rc">mine</ulink>.</para>
      </step>

      <step>
        <para>Extract the installer and helper utilities from the mfsroot disk
          and uncompress them, put them in <filename>/usr/tftpboot</filename>
          as well:</para>

	<screen>&prompt.root; <userinput>vnconfig vn0 mfsroot.flp</userinput>         # associate a vndevice with the file
&prompt.root; <userinput>mount /dev/vn0 /mnt</userinput>              # mount it
&prompt.root; <userinput>cp /mnt/mfsroot.gz /usr/tftpboot</userinput> # copy the contents to /usr/tftpboot
&prompt.root; <userinput>umount /mnt</userinput>                      # unmount it
&prompt.root; <userinput>vnconfig -u vn0</userinput>                  # disassociate the vndevice from the file
&prompt.root; <userinput>cd /usr/tftpboot</userinput>                 # get into the pxeboot directory
&prompt.root; <userinput>gunzip mfsroot.gz</userinput>                # uncompress the mfsroot</screen>
      </step>

      <step>
        <para>Make your sysinstall script <filename>install.cfg</filename>, you
          can use
          <ulink url="install.cfg">mine</ulink>
          as a template, but you must edit it.</para>
      </step>

      <step>
        <para>Copy the sysinstall script into the extracted and uncompressed
          mfsroot image:</para>

	<screen>&prompt.root; <userinput>cd /usr/tftpboot</userinput>
&prompt.root; <userinput>vnconfig vn0 mfsroot</userinput>
&prompt.root; <userinput>mount /dev/vn0 /mnt</userinput>
&prompt.root; <userinput>cp install.cfg /mnt</userinput>
&prompt.root; <userinput>umount /mnt</userinput>
&prompt.root; <userinput>vnconfig -u vn0</userinput></screen>
      </step>
    </procedure>
  </sect1>

  <sect1 id="install-setup">
    <title>Install Setup</title>

    <procedure>
      <step>
        <para>Put the install files in an NFS accessible location on the
	  Server. Make a directory corresponding the 'nfs' directive in the
	  <filename> install.cfg</filename> file and mirror the FreeBSD
	  install files there, you will want it to look somewhat like
	  this:</para>

	<screen>ABOUT.TXT       TROUBLE.TXT     compat20        floppies        ports
ERRATA.TXT      UPGRADE.TXT     compat21        games           proflibs
HARDWARE.TXT    XF86336         compat22        info            src
INSTALL.TXT     bin             compat3x        kern.flp
LAYOUT.TXT      catpages        crypto          manpages
README.TXT      cdrom.inf       dict            mfsroot.flp
RELNOTES.TXT    compat1x        doc             packages</screen>
      </step>

      <step>
        <para>Copy the compressed packages into the packages/All directory
          under <filename>nfs</filename>.</para>
      </step>

      <step>
        <para>Make sure you have an <filename>INDEX</filename> file prepared
	  in the packages directory. You can make your own
	  <filename>INDEX</filename> entries like so:</para>

	<programlisting>alfred-1.0||/|Alfred install bootstrap||alfred@FreeBSD.org||||</programlisting>

        <para>Then you can install custom packages, particularly your own
	  custom post-install package.</para>
      </step>
    </procedure>
  </sect1>

  <sect1 id="custom-postinst-package">
    <title>Custom Post-Install Package</title>

    <para>You can use the script <ulink url="pkgmaker.sh"><filename>pkgmaker.sh
      </filename></ulink> to create a
      custom package for post install, the idea is to have it install and
      configure any special things you may need done.
      <filename>pkgmaker</filename> is run in the directory above the package
      you wish to create with the single argument of the package (ie mypkg)
      which will then create a mypkg.tgz for you to include in your sysinstall
      package.</para>

    <para>Inside your custom package dir you will want a file called
      <filename>PLIST</filename> which contains all the files that you wish to
      install and be incorporated into your package.</para>

    <para>You will also want files called
      <ulink url="pre"><filename>pre</filename></ulink> and
      <ulink url="post"><filename>post</filename></ulink>
      in the directory, these are shell scripts
      that you want to execute before and after your package is
      installed.</para>

    <para>Since this package is in your <filename>install.cfg</filename> file
      it should be run and do the final configuration for you.</para>
  </sect1>
</article>