SUBDIR+= pxe

#

# $FreeBSD: doc/en_US.ISO8859-1/articles/pxe/Makefile,v 1.5 2004/04/06 16:10:07 phantom Exp $

#

# Article: FreeBSD PXE Jumpstart Guide

DOC?= article

FORMATS?= html

INSTALL_COMPRESSED?=gz

INSTALL_ONLY_COMPRESSED?=

EXTRAS=		dhcpd.conf

EXTRAS+=	install.cfg

EXTRAS+=	loader.rc

EXTRAS+=	pkgmaker.sh

EXTRAS+=	post

EXTRAS+=	pre

SRCS=	article.sgml

afterinstall:

.for entry in ${EXTRAS}

	${INSTALL_DOCS} ${.CURDIR}/${entry} ${DESTDIR}

.endfor

DOC_PREFIX?= ${.CURDIR}/../../..

.include "${DOC_PREFIX}/share/mk/doc.project.mk"

<!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: doc/en_US.ISO8859-1/articles/pxe/article.sgml,v 1.27 2006/08/29 19:45:44 blackend Exp $</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>mdconfig -a -t vnode -f kern.flp -u 0</userinput> # (vnconfig vn0 kern.flp) associate a vndevice with the file

&prompt.root; <userinput>mount /dev/md0 /mnt</userinput> # (mount /dev/vn0 /mnt) 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 (i.e., 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>

# $Wintelcom: src/freebsd/pxe/doc/dhcpd.conf,v 1.2 2000/09/24 09:18:14 bright Exp $

# $FreeBSD: doc/en_US.ISO8859-1/articles/pxe/dhcpd.conf,v 1.2 2003/06/17 15:09:51 alfred Exp $

option subnet-mask 255.255.255.0;

option routers 10.8.253.254;

filename "pxeboot";

ddns-update-style none;

option domain-name "google.com";

option broadcast-address 10.8.253.255;

option domain-name-servers 10.8.0.7;

server-name "DHCPserver";

server-identifier 10.8.253.201;

default-lease-time 7200;

max-lease-time 7200;

subnet 10.8.253.0 netmask 255.255.255.0 {

	next-server 10.8.253.201;

	range 10.8.253.29 10.8.253.200;

}

# $Wintelcom: src/freebsd/pxe/doc/install.cfg,v 1.1 2000/07/14 12:42:05 bright Exp $

# $FreeBSD: doc/en_US.ISO8859-1/articles/pxe/install.cfg,v 1.2 2003/11/23 18:50:32 ceri Exp $

# This is the installation configuration file for our rackmounted FreeBSD 

# cluster machines

# Turn on extra debugging.

debug=YES

# Ok, this ought to turn off ALL prompting, don't complain to me that you

# lost a machine because you netbooted it on  the same subnet as this 

# box

nonInteractive=YES

noWarn=YES

tryDHCP=YES

################################

# My host specific data

hostname=booter

domainname=mydomain.com

# DHCP does this for us

#nameserver=10.0.0.1

#defaultrouter=10.0.0.1

#ipaddr=DHCP

#netmask=255.255.255.0

################################

################################

# Which installation device to use 

nfs=x.x.x.x:/usr/releng4

netDev=fxp0

tryDHCP=YES

mediaSetNFS

################################

################################

# Select which distributions we want.

dists= bin doc games manpages catpages proflibs dict info des compat1x compat20  compat21 compat22 compat3x crypto

distSetCustom

################################

################################

# Now set the parameters for the partition editor on sd0.  

disk=ad0

partition=all

bootManager=standard

diskPartitionEditor

#diskPartitionWrite

################################

################################

# All sizes are expressed in 512 byte blocks!

#

# A 96MB root partition, followed by a 0.5G swap partition, followed by

# a 1G /var, and a /usr using all the remaining space on the disk

#

ad0s1-1=ufs 1999999 /

ad0s1-2=swap 6485760 none

ad0s1-3=ufs 2097152 /var

ad0s1-4=ufs 0 /usr

# Let's do it!

diskLabelEditor

#diskLabelCommit

# OK, everything is set.  Do it!

installCommit

package=XFree86-3.3.6

packageAdd

#package=XFree86-aoutlibs-3.3.3

#packageAdd

package=XFree86-contrib-3.3.6

packageAdd

package=arpwatch-2.1.a4

packageAdd

package=bash-2.04

packageAdd

package=bison-1.28

packageAdd

package=bzip2-1.0.0

packageAdd

package=ctags-3.5.2

packageAdd

package=dvips2ascii-1.3

packageAdd

package=electricfence-2.0.5

packageAdd

package=emacs-20.6

packageAdd

package=enscript-letter-1.6.1

packageAdd

package=fping-1.20

packageAdd

package=gawk-3.0.4

packageAdd

package=gdbm-1.8.0

packageAdd

package=gettext-0.10.35

packageAdd

package=gmake-3.79

packageAdd

package=ispell-3.1.20c

packageAdd

package=less-352

packageAdd

package=libgnugetopt-1.1

packageAdd

package=libtool-1.3.4

packageAdd

package=linux_base-6.1

packageAdd

package=linux_devtools-6.1

packageAdd

package=lmbench-1.1

packageAdd

package=m4-1.4

packageAdd

package=mprof-3.0

packageAdd

package=mtr-0.42

packageAdd

package=nmap-2.53

packageAdd

package=pine-4.21

packageAdd

package=portscanner-1.0

packageAdd

package=portsentry-1.0

packageAdd

package=python-1.5.2

packageAdd

package=rpm-2.5.6

packageAdd

package=rsaref-2.0

packageAdd

package=rsync-2.4.3

packageAdd

package=screen-3.9.5

packageAdd

package=stlport-3.01

packageAdd

package=tcsh-6.09.00

packageAdd

package=tk-8.0.5

packageAdd

package=vim-lite-5.6.70

packageAdd

package=wget-1.5.3

packageAdd

package=word2x-0.005

packageAdd

package=zip-2.3

packageAdd

package=zsh-3.0.7

packageAdd

#

# this last package is special.  It is used to configure the machine.

# it installs several files (like /root/.rhosts) and its installation

# script tweaks several options in /etc/rc.conf

#

package=mypkg-1.0

packageAdd

shutdown

\ $Wintelcom: src/freebsd/pxe/doc/loader.rc,v 1.1 2000/07/15 07:20:37 bright Exp $

\ $FreeBSD: doc/en_US.ISO8859-1/articles/pxe/loader.rc,v 1.1 2003/06/17 08:21:40 alfred Exp $

echo Loading Kernel...

load /kernel

echo Loading mfsroot...

load -t mfs_root /mfsroot

echo booting...

echo \007\007

echo initializing h0h0magic...

set vfs.root.mountfrom="ufs:/dev/md0c"

boot

#!/bin/sh

# $Wintelcom: src/freebsd/pxe/doc/pkgmaker.sh,v 1.1 2000/07/14 12:42:05 bright Exp $

# $FreeBSD: doc/en_US.ISO8859-1/articles/pxe/pkgmaker.sh,v 1.1 2003/06/17 08:21:40 alfred Exp $

PKGNAME=${1}

PKGDIR=`pwd`/${PKGNAME}/

pkg_create -i ${PKGDIR}pre -I ${PKGDIR}post -f ${PKGDIR}PLIST  -s ${PKGDIR} -p / -d ${PKGDIR}DESCR -c ${PKGDIR}COMMENT ${PKGNAME}.tgz

#!/bin/sh

# $Wintelcom: src/freebsd/pxe/doc/post,v 1.1 2000/07/14 12:42:05 bright Exp $

# $FreeBSD: doc/en_US.ISO8859-1/articles/pxe/post,v 1.2 2003/11/05 10:59:34 ceri Exp $

echo post-install

set PATH=/bin:/usr/local/bin:/sbin:/usr/sbin:/usr/bin:/usr/bin/X11

export PATH

# do timezone

cp /usr/share/zoneinfo/America/Los_Angeles /etc/localtime

conf="/etc/rc.conf.local"

rm $conf

echo 'sendmail_enable="NO"' >> $conf

echo 'dumpdev="/dev/ad0s1b"' >> $conf

echo 'sshd_enable="YES"' >> $conf

echo 'linux_enable="YES"' >> $conf

# set up IP address and hostname

if=`ifconfig fxp1 inet | grep '[ 	]*inet' | sed 's/[ 	]*//'`

echo "ifconfig_fxp1=\"${if}\"" >> $conf

name=`echo $if | sed 's/[ 	][ 	]*/ /g' | cut -f2 -d" " | cut -f4 -d.`

echo "hostname=\"suyy${name}\"" >> $conf

echo "network_interfaces=\"fxp0 fxp1 lo0\"" >> $conf

# set up gateway, parse netstat output

gw=`netstat -rn | grep '^default' | sed 's/[ 	][ 	]*/ /g' | cut -f2 -d" "`

echo "defaultrouter=\"${gw}\"" >> $conf

pwd_mkdb -p /etc/master.passwd

exit 0

#!/bin/sh

# $Wintelcom: src/freebsd/pxe/doc/pre,v 1.1 2000/07/14 12:42:05 bright Exp $

# $FreeBSD: doc/en_US.ISO8859-1/articles/pxe/pre,v 1.1 2003/06/17 15:34:24 alfred Exp $

echo pre-install

exit 0