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.