BOOT(8)                                                   BOOT(8)

     NAME
          boot, bootrc - connect to the root file server

     SYNOPSIS
          /boot/boot [ -fkm ] [ -uusername ] [ method!device ] [ args
          ]

     DESCRIPTION
          Boot is the first program run after a kernel has been
          loaded. It mounts bootfs.paq, a compressed filesystem con-
          tained in root(3), sets up the rc(1) environment and exe-
          cutes bootrc passing on its arguments.  Bootrc connects to
          the file server that will serve the root, performs any
          authentication needed to connect to that server, and exe-
          cutes the init(8) program. Both boot and bootrc are started
          by the kernel, never run directly by the user. See
          booting(8) for information about the process of loading the
          kernel (and boot) into memory.

          Once loaded, the kernel initializes its data structures and
          devices.  It sets the two environment variables /env/cputype
          and /env/terminal to describe the processor.  It then binds
          a place-holder file server, root(3), onto / and crafts an
          initial process whose sole function is to exec(2)
          /boot/boot, a binary which is compiled into root(3).

          The command line passed depends on the information passed
          from boot ROM to kernel.  Machines that boot directly from
          ROM (that is, most machines other than PCs) pass the boot
          line given to the ROM directly to boot.

          On the PC, each line in the file plan9.ini(8) of the form
          name=value is passed to the boot program as an environment
          variable with the same name and value.  The command line is

               /boot/boot method!device

          After boot passed its execution to bootrc, it must determine
          the fileserver to use and a method with which to connect to
          it.  Typically device will name a local disk partition or
          ethernet interface.  The complete list of methods is given
          below.

          Bootrc must also set a user name to be used as the owner of
          devices and all console processes and an encryption key to
          be used when challenged.  Bootrc will prompt for these.

          Method and device are prompted for first.  The prompt lists
          all valid methods, with the default in brackets, for exam-
          ple:

     BOOT(8)                                                   BOOT(8)

               bootargs is (tcp, il, local!device) [local!/dev/sdC0/fscache]

          A newline picks the default. Entering !rc breaks into the
          rc(1) shell.  Other possible responses are method,
          method!device or method!device args.

          The other interactions depend on whether the system is a
          terminal or a CPU server.

        Terminal
          A terminal must have a username set.  If not specified with
          the user= plan9.ini(8) parameter or the -u option, boot will
          prompt for one on the console:

               user:

          The user will also be prompted for a password to be used as
          an encryption key on each attach(5):

               password:

          Once connected, boot mounts the root file system before /
          and makes the connection available as #s/boot for subsequent
          processes to mount (see bind(2)). Boot completes by
          exec(2)'ing /$cputype/init -t.  If the -m option is given it
          is also passed as an option to init. If the environment
          variable init is set (via plan9.ini(8)), it is used as an
          argument to exec(2) instead.

          If the bootfs.paq has been built with the cache file system,
          cfs(4), the local disk partition /dev/sdXX/cache (where XX
          is a unit specifier) exists, and the root file system is
          from a remote server, then bootrc will insert a user level
          cache process between the remote server and the local names-
          pace that caches all remote accesses on the local partition.
          The -f flag commands cfs(4) to reformat the cache partition.

        CPU Servers
          The user owning devices and console processes on CPU servers
          and that user's domain and encryption key are read from
          NVRAM on all machines except PCs.  PCs keep the information
          in the disk partition /dev/sdXX/nvram.  If a -k option is
          given or if no stored information is found boot will prompt
          for all three items and store them.

               password:
               authid: bootes
               authdom: research.bell-labs.com

          The key is used for mutual authentication of the server and
          its clients.  The domain and id identify the owner of the
          key.

     BOOT(8)                                                   BOOT(8)

          Once connected, boot behaves as on the terminal except for
          exec(2)'ing /$cputype/init -c.

        Booting Methods
          The methods available to any system depend on what was com-
          piled into the kernel.  The complete list of booting methods
          are listed below.

          tcp     connect via Ethernet using the TCP protocol.  The
                  device and args are passed to ipconfig(8) when con-
                  figuring the IP stack.  The plan9.ini(8) variables
                  fs and auth override the file server and authentica-
                  tion servers obtained (if any) from DHCP during
                  ipconfig(8).

          il      the same as tcp but uses the IL protocol to connect
                  to the fileserver.

          local   connect to the local file system.  The device is a
                  disk partition file holding a file system.  Bootrc
                  inspects the disk partition with fstype(1) to deter-
                  mine the file system type and starts the appropriate
                  server with args.

     EXAMPLES
          On PCs, the default arguments to boot are constructed using
          the bootargs variable in plan9.ini(8).

          Start cwfs(4) in config mode:

               bootargs=local!/dev/sdC0/fscache -c

          Use an IP stack on an alternate ethernet interface with a
          static address and fixed file server and authentication
          server addresses.

               fs=192.168.0.2
               auth=192.168.0.3
               bootargs=tcp!-g 192.168.0.1 ether /net/ether1 \
                   192.168.0.50 255.255.255.0

          (The bootargs line is split only for presentation; it is one
          line in the file.)

     FILES
          #s/boot
          #//boot/boot
          #//boot/bootfs.paq

     SOURCE
          /sys/src/9/boot

     BOOT(8)                                                   BOOT(8)

     SEE ALSO
          root(3), dhcpd(8), init(8)

     BUGS
          The use of bootargs in general is odd.

     HISTORY
          Boot first appeared in Plan 9 from Bell Labs. It was rewrit-
          ten in rc for 9front (April, 2011).