#!/bin/rc

echo '
g/toolkit overview:

This is a set of scripts to make it easy to connect to a distributed 9/g/rid of resources. They expect to be placed so as to be bound to /bin/g. Placing the g/ folder of scripts at either

/rc/bin/g
/usr/USERNAME/bin/rc/g

will do this given standard namespace bindings. The included mkfile will also build and install the 'recover' utility from contrib/paurea/recover4e and a slightly modified plumber.

These scripts are based on some of the semantics and functionality of the Inferno registry, 
and are in many ways compatible and interoperate with it. The scripts all share all assume
they will be operating within a namespace created by g/gridstart. 
This script sets up /tmp/grid and mntgens at /, /g, and /g/r

A SAMPLE GRID SESSION:
(beginning in an RC shell with an active net connection and other standard assumptions)
You begin a grid session by choosing a name for the session,and providing a routable IP address or domain name.This informs other nodes how to access any services you choose to provide:

g/gridstart grid20Aug08 55.44.122.254

This command prepares the namespace/filesystem and starts a rio window.All your subsequent scripts expect to be run within this namespace. We will set up a few more basic elements and then do this.

g/mklocalreg regjimbos 9001

This is optional, but recommended. It starts up a local service registry for you to export to other grid nodes and for them to announce services to.Providing a service registry helps keep the grid connected even when other nodes go offline. You need to make sure that the port you choose (9001 in the example) is correctly forwarded to your plan9 setup.

g/dialreg tcp!9gridchan.org!7888 inferno1

This command attaches to an external registry and imports its service information. This first attachment to a seed registry should be the last time you need to worry about specific ip addresses,the scripts will attempt to take care of dialing out from this point on. Now that you have made a local registry and attached a seed registry, you might choose to start

g/gridmaint

This runs in the background and takes care of automatically refreshing the /tmp/grid database which lists available services. It also checks and repairs broken network connections. Registries added subsequently will be brought into gridcrons namespace automatically. Now that you are inside the grid with a registry attached, you can do

g/listsvc 

at any time, to see a list of available services from all currently indexed registries. Note that this list can lag a bit because it depends on either gridcron running in the background, or the use of the gridcron subscripts (g/regrefresh, g/regcheck, g/regfix) to keep the service index in /tmp/grid updated. You can attach any 9p fileshare listed in the services with

g/getsvc NAMEOFSERVICE

Which will automatically mount the named service (you dont have to match capitalization) at 
/g/NAMEOFSERVICE/s
You will notice that your service registry isnt yet listed in the external registry you attached to. To make your registry known, you can do

g/tellreg regjimbos inferno1

This announces your registry serviceto the registry named inferno1 that you attached to previously. Now other grid nodes can announce services to your registry. This creates an overlapping, redundant index that keeps nodes connected -no matter what registry goes down. Lets setup a fileshare export now and announce it

g/sharefiles JimbosWallpapers atJimbos.dnsdojo.net 9002 /usr/jimbo/wallpapers

g/tellreg JimbosWallpapers inferno1
g/tellreg JimbosWallpapers regjimbos

Those commands started a fileshare export on port 9002 from the /usr/jimbo/wallpapers folder, then announced that service to the inferno1 registry, and the local regjimbos registry. Speaking of registries, you want to have several registries mounted and available.  There is a special command to do this easily. Any registries you see from g/listsvc can be attached using

g/getreg REGISTRYNAME

So, as an example, if a different node wants to attach the registry that you (jimbo) made in this example, assuming they are connected to a registry that lists it (such as reginferno1), they just do

g/getreg regjimbos

This sets up regjimbos as an attached registry and updates the service index with its contents. g/listsvc automatically filters out duplicate service entries, so its good to have your services announced to multiple registries,and to have multiple redundant registries attached. This is how the grid prevents the loss of a single service registry node from disrupting communications.

To see the current overview of your grid connections status, run

g/gstat

 In general once you have your session up and rolling, the commands you will be using are:

g/listsvc  #to see what services are available

g/getsvc SERVICENAME   #to attach the named service

g/getreg REGISTRYNAME   #to attach the named registry

g/sharefiles SERVICENAMENAME LOCATION PORT FOLDER   #to start a fileshare export

g/tellreg SERVICENAME REGISTRYNAME    #to announce a fileshare or registry service to the named registry

If you want to force registry and service checking, fixing, and updating manually, just run:

g/regupdate && g/svcupdate && g/regrepair && g/svcrepair

All gridmaint does is run those in sequence with pauses in between.You can check out all the information being tracked about your current grid session by looking /tmp/grid. 
/tmp/grid/log/log keeps a record of all grid commands. All the files are just flat text files and exploring the directories with Acme should make it pretty clear what information is where. Take care when exploring strange and unfamiliar namespaces. Share information.please send suggestions, bug reports, criticisms, questions, and strange proverbs to

plan9grid@sphericalharmony.com
' |fmt
