BNS(4)                                                     BNS(4)

     NAME
          bns - Plan B name space file server and volume multiplexor

     SYNOPSIS
          bns [ -dDv ] [ -l ] [ -s srv ]

     DESCRIPTION
          Bns is used in Plan B to implement dynamic namespaces and to
          start system operation. This program is usually used as a
          replacement for init(8). See the examples section.

          As said in planb(1), in Plan 9, most resources are provided
          by file servers. In Plan B, a resource is provided by a vol-
          ume, which is a 9P file server that has a (global) name and
          attributes. Volumes imported to user name spaces through bns
          may be replaced at run time by bns without breaking the name
          space or blocking the client for too long while the network
          stack takes its time to declare the 9P connection broken.

          Bns is a file server that provides Plan B file volumes
          implemented by Plan 9  file servers.  It sits between
          clients and file servers and determines which file servers
          are to be used to provide each volume, depending on their
          availability and the client requirements for the volumes
          mounted.

          Initially, bns mounts itself in the name space of the
          caller, using the namespace described in
          /lib/namespace.planb that uses volumes to build the name
          space instead of direct attachments to particular file
          servers. This permits file-server switching and recovering.
          As an aid, bns automatically discovers volumes that corre-
          spond to / and to /usr as specified in the plan9.ini(8).

          A volume is identified by a global name. By convention, the
          name is the customary path where it is mounted. Besides the
          name, a volume has a set of attribute/value pairs. The set
          of attribute/value pairs is also known as the volume proper-
          ties. Attribute/value pairs specified by the user import
          requests are also known as constraints.

          Clients mount volumes by mounting the file #s/vol and using
          the attach spec to specify which volume name and constraints
          are required. See mount(2). Each attach to bns creates a new
          volume mount point.  Bns plugs into such mount point the
          file tree provided by any volume that matches the user sup-
          plied spec.  When the volume file server becomes unavailable
          (its connection breaks or a request is timed out) bns
          selects an alternate one (also matching the user con-
          strainst) and switches to it. When no volume is available,

     BNS(4)                                                     BNS(4)

          an empty directory is provided as the file tree for the
          mount point.  Note that volume switching happens only after
          I/O errors.

          Qids for files in a volume are rewritten by bns so that
          bind(2) requests to/from a volume file would work as
          expected, despite file server switching.  Fids in use by the
          client are re-created to continue working after the switch.

          However, any fid open for writing is kept untouched after a
          volume switch and therefore reports I/O errors for any oper-
          ation after the switch.

          The attach specifier used to mount volumes must have this
          format:

               flags name props | props | ...

          where flags is an optional flag field, as described later,
          name is the name for the volume and props is a sequence of
          attr=value pairs separated by space. If no props are given,
          any volume with given name matches the request. If props is
          given, the volume must have the specified attributes with
          the given values.

          More than one set of props may be given, separated by the
          vertical bar character, to specify preferences.  In this
          case, each props set is tried in left-to-right order to find
          matching volumes.  Volumes matching props on the left are
          preferred to those matching props specified on the right.
          Bns always tries to use a preferred volume (even if a less-
          preferred one was available and was being used). In this
          case, volume switching may happen also when a preferred vol-
          ume if found.

          The optional flags field must start with the - character and
          must be separated from the volume name by a space. Flag -U
          is used to request a union of volumes, which binds together
          all volumes matching the spec, and not just the first one
          found.  Flag -M is used to specify a required (must-have)
          volume, and makes all 9P transactions to be kept on hold
          during periods of time when no file server is available for
          the volume.  Flag -T requests bns not to timeout read,
          requests made on files (not on directories) in the volume.
          This option should be avoided, but it may be necessary when
          mounting devices where these requests might block for a long
          time even when there is no failure in the device, for exam-
          ple, a mouse or a plumbing port.

          A mount of #s/vol with the empty spec attaches to a file
          tree with a single directory that contains a file named vol.
          This file tree is attached during the initial Plan B

     BNS(4)                                                     BNS(4)

          namespace setup at /dev so that /dev/vol may be used to con-
          trol this program.

          Reading this file provides the list of volumes (and mount
          points) as known by the program.  A write to the file per-
          mits to modify this list, as explained below.

          Option -s asks bns to post srv into srv(3) instead of the
          default.

          Volumes are discovered either by means of adsrv(8) or by
          writes to /dev/vol using a precise format. In either case,
          bns receives one text line per known volume. Each line con-
          tains the following fields separated by white space:

          addr the network address for the 9P file server or the name
               for a 9P connection file.

          spec the mount(2) spec for the file tree.

          path the path in the server for the file tree.

          name the name of the volume.

          cnstr
               the constraint for the volume.

          A line starting with # is considered as a comment, and is
          ignored.

          The field cnstr may be omitted, if there are no constraints
          of interest for the volume.  Also, a line may omit both the
          spec and path fields, in which case the spec used is the
          empty string and the path is set to /.

          If option -l is given, the program polls the discovery ser-
          vice for files describing volumes (with the same format
          shown above). The discovery service must run  at
          tcp!$fs!11010 and conform to the protocol of adsrv(8).

          A write to /dev/vol with the format described above
          announces a new volume.  A write of a line

               del name cnstr

          disables those volumes matched by name and cnstr. This last
          field may be omitted. The special name * matches all the
          names.  A line with the same format, but using add instead
          of del, enables a previously disabled volume.  Constraints
          for a volume can be changed by a write of

               set name oldcnstr newcnstr

     BNS(4)                                                     BNS(4)

          this merges newcnstr into the constraints for volumes match-
          ing name and oldcnstr. The merge process adds new attributes
          and changes values for old attributes, but does not remove
          attributes.

          Flags -dDv activate various debug diagnostics, and may make
          the program very verbose (and slow). The flag -v shows vol-
          ume debug messages. The other two trace 9P messages with
          increasing verbosity.

          As a debug aid, a file volctl is posted into srv(3) to
          accept commands for debugging. The V command makes bns dump
          the state of its most important data structures, along with
          some statistics. The D command enables all the debug flags
          following. Use Dn to disable all debug flags. The Tvol com-
          mand activates a debug trace for the named volume. The N
          command deactivates all traces.  Other writes to the control
          file are handled as configuration commands.

     EXAMPLES
          Put this in your plan9.ini(8) to start your terminal using a
          Plan B name space, as determined by /lib/namespace.planb

          rootspec=yourfsspecforroot
          usrspec=yourfsspecforusr
          init=/386/bin/bns -l
          Your profile should check for the $planb environment vari-
          able, if you care.

          The following request mounts at /root the volume named /.
          The preferred volume is one provided by $fs and available
          through a network connection with a good latency.  Should
          that not be feasible, the next preferred one is a volume
          provided by the local system. If that is not available
          either, a volume from $fs is our last choice. The -M flag
          instructs bns to hold on when no volume is available given
          our spec.

          mount -aC /srv/vol /root '-M / sys='$fs' net=ok|sys='$sysname'|sys='$fs

          The next command builds a union of all volumes with name
          /devs/ui that are provided by the user issuing the request:

          mount -bc /srv/vol /devs '-U /devs/ui user='$user

          An example configuration file, which might be copied line-
          per-line to /dev/vol
           follows:
          tcp!whale!9fs  planb/active   /    /
          tcp!whale!9fs  planb/active   /386/bin  /bin 'arch=386 type=dir'
          tcp!aquamar!hx /devs/hx
          /srv/vfossil   main/active    /    /

     BNS(4)                                                     BNS(4)

          /srv/vfossil   main/active    /386/bin       /bin 'arch=386 type=dir'

     FILES
          /lib/namespace.planb for the default name space built at
          start time on Plan B machines.

     SOURCE
          /sys/src/cmd/bns

     SEE ALSO
          planb(1), init(8), plan9.ini(8), mount(2).

     BUGS
          Too young, therefore not so reliable.