BOOT(8)                                                   BOOT(8)

     NAME
          boot - connect to the root file server

     SYNOPSIS
          /boot/boot [ -fkm ] [ -uusername ] [ method!fs-addr ] [ args
          ]

     DESCRIPTION
          Boot is the first program run after a kernel has been
          loaded.  It connects to the file server that will serve the
          root, performs any authentication needed to connect to that
          server, and exec(2)'s the init(8) program.  It is 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 DOS file plan9.ini 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

               /386/9dos method!server

          (The first argument is ignored by boot.) Boot must determine
          the file server to use and a method with which to connect to
          it.  Typically this will name a file server on the network,
          or state that the root file system is on local disk and name
          the partition.  The complete list of methods is given below.

          Boot 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.  Boot will prompt for these.

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

               root is from (tcp, local!#S/sdC0/fs)[tcp]:

     BOOT(8)                                                   BOOT(8)

          A newline picks the default.  Other possible responses are
          method or method!address.  To aid in automatic reboot, the
          default is automatically taken on CPU servers if nothing is
          typed within 15 seconds.

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

        Terminal
          The terminal must have a username to set.  If none is speci-
          fied with 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:

          With most methods boot can now connect to the file server.
          However, with the serial line methods 9600 and 19200, the
          actual mechanics of setting up the complete connection are
          too varied to put into the boot program.  Instead boot lets
          the user set up the connection.  It prints a prompt on the
          console and then simulates a dumb terminal between the user
          and the serial line:

               Connect to file system now, type ctrl-d when done.
               (Use the view or down arrow key to send a break)

          The user can now type at the modem to dial the number.  What
          is typed depends on the modem and is beyond this discussion.

          When the user types a control-D, boot stops simulating a
          terminal and starts the file system protocol over the serial
          line.

          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 a
          command line to exec instead.

          If the kernel 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 the kernel will insert a user
          level cache process between the remote server and the local
          namespace that caches all remote accesses on the local

     BOOT(8)                                                   BOOT(8)

          partition.  The -f flag commands cfs 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 PC's.  PC's keep the informa-
          tion 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.

          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
                  args are passed to ipconfig(8) when configuring the
                  IP stack.  The plan9.ini(8) variables fs and auth
                  override the file server and authentication server
                  IP addresses obtained (if any) from DHCP during
                  ipconfig(8).

          local   connect to the local file system.  The first argu-
                  ment is a disk holding a file system.  Boot inspects
                  the disk.  If the disk is a fossil(4) file system,
                  it invokes /boot/fossil to serve it.  If the venti
                  environment variable (really, plan9.ini(8) variable)
                  is set, boot first arranges for fossil to be able to
                  contact the named venti(8) server.  The variable's
                  value can take the following forms:

                  /dev/sdC0/arenas
                       the file should be a venti partition with a
                       configuration stored on it using venti/conf
                       (see venti-fmt(8)). Boot will start a loopback
                       IP interface on 127.0.0.1 and start venti
                       announcing on tcp!127.1!17034 for venti service
                       and tcp!127.1!8000 for web service, using the
                       configuration stored in that partition.

     BOOT(8)                                                   BOOT(8)

                  /dev/sdC0/arenas tcp!*!17034
                       same as the last but specify an alternate venti
                       service address.  In this example, using * will
                       announce on all available IP interfaces (even
                       ones configured later) rather than just the
                       loopback device.  The loopback interface is
                       still configured.

                  /dev/sdC0/arenas tcp!*!17034 tcp!*!80
                       same as the last but specify alternate venti
                       service and web addresses.  The loopback inter-
                       face is still configured.

                  tcp!135.104.9.2!17034 [ args ]
                       the network address of a venti server running
                       on a separate machine.  Boot will configure the
                       IP stack by passing args, if any, to
                       ipconfig(8).

                  Fossil is invoked as

                       /boot/fossil -f partition -c 'srv -A fboot' -c 'srv -p fscons'

                  and boot then renames `/srv/fboot' to `/srv/boot',
                  so fossil.conf should not use the srv command to
                  create `fboot', `boot', nor `fscons'.

                  If the disk is not a fossil(4) partition, boot
                  invokes /boot/kfs.  A variety of programs, like
                  9660srv and dossrv(4) masquerade as kfs to allow
                  booting from alternate media formats, so as long as
                  the disk is not a fossil disk, no check is made that
                  the disk is in fact a kfs disk.  The args are passed
                  to kfs(4).

                  For the tcp method, the address must be a numeric IP
                  address.  If no address is specified, a file server
                  address will be found from another system on the
                  network using the BOOTP protocol and the Plan 9
                  vendor-specific fields.

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

          Start kfs(4) with extra disk buffers:

               bootargs=local!#S/sdC0/fs -B 4096

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

     BOOT(8)                                                   BOOT(8)

               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

     SOURCE
          /sys/src/9/boot

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

     BUGS
          The use of bootargs in general is odd.  The configuration
          specification for fossil and venti servers is particularly
          odd, but it does cover the common cases well.