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.