Sidai team: blessed naming

This document gives our (the Sidai team's) choices for naming, and the reasons for them. Being an Arusha player does not require that you follow them.

Background reading: on good namespaces.

Names for files and directories

Per-site areas for installed package-stuff; visible from all machines; ours include...

/sys/.-ark-install-ia32-linux-rh6.2
/sys/.-ark-install-sparc-solaris2.6
/sys/.-ark-install-ALL
/sys/.-ark-install-ia32-linux-rh6.2-web-server

Per-site ARK work areas; visible from all machines: we use...

/sys/ark-builds
/sys/ark-state
/sys/ark-gen-pkg

Per-site other generally-useful areas (not ARK-specific); e.g., we have:

/d/cvsroot
/d/open-src
/d/vendor-stuff

Names for filesystems (partitions)

`System' partitions/filesystems: Filesystems that hold the traditional stuff that comes from the system vendor -- stuff in /usr, /etc, /var, and so on -- should be left as it is. Trying to "tidy" such things, however deserved, leads to madness.

We are deeply in favor of vendors following the Filesystem Hierarchy Standard (FHS) and any other relevant standards for file naming.

`Non-system' partitions/filesystems: These should be named /._disk1, /._disk2, and so on, renumbering for each machine.

Aside: user-hostile and user-friendly file naming...

User-hostile names begin with /._
(device-dependent, as we saw with /._disk1, above) or /.-
(device-independent; many examples to follow).

User-friendly names are, well, normal; e.g. /our/bin/netscape.

The sole purpose of "user-hostile" pathnames is so, if the users are tempted to use them, they will know they are dealing with Deep Magic. If you don't do something like this, you will find users putting things like /net/solomon/disk7/fred/bin in their PATHs, and then wondering why their world collapses when you move things around.

Access to `non-system' partitions is via automounted filesystems, named...

We recommend that these ``chunks of data'' be managed with the Sidai dchunks machinery. (But it is optional.)

As far as naming goes, we recommend that each ``chunk'' have a device-independent name (so you can move it around) and that it have exactly one name.

We use the automounter to do all such naming. So, what automount maps should you have, and how should they map to the /._disks? We recommend:

/home/<user-id>:

Very common. The (indirect) automount map entry would be:

<user-id>  <hostname>:/._disk<N>/home/&

/sys/<something>:

When we keep ARK-ish `somethings', e.g. package builds, state directories, golden install areas, ...

Under /sys, we would have both user-hostile and user-friendly names, depending on whether the user should ever need to be bothered with that chunk of stuff.

For example, a (curious) user might want to snoop around the build area for GCC, and would find it in /sys/ark-builds/gcc--3.2 (friendly). Contrariwise, a user has no reason to care about the ``golden copy'' install areas for Linux packages; so we call that /sys/.-ark-install-ia32-linux (hostile).

Finally: automount map entries might be:

ark-builds                <hostname>:/._disk<N>/sys/&
.-ark-install-ia32-linux  <hostname>:/._disk<N>/sys/&

Note: an (older) alternative is to put all the sys somethings under /d (below).

/workspace/<person>:

Places where people do version-controlled work, e.g., check things out from a CVS repository. A relevant automount map entry might be:

<person>  <hostname>:/._disk<N>/workspace/&

(Or just let people use CVS in their home directories; may be a problem if home directories are small, or workspaces are huge.)

/proj/<project>:

Non-version-controlled stuff for a particular project; this sort of thing is often done.

(As you can tell, our first question is: Why isn't the project using version control for its stuff? Or: why aren't /workspaces sufficient?)

Anyway, the automount map entry would be:

<project>  <hostname>:/._disk<N>/proj/&

/d/<something>:

Catch-all set of names for everything else.

We kinda like our very non-committal /d solution, because it has very little (Shannon) information content in the name, and will therefore tend to wear well.

Why /d? Simply because it's as short as possible, and it's very easy to type.

Finally: an automount map entriy might be:

open-src                <hostname>:/._disk<N>/d/&

/._net/<hostname>:

We avoid the /net map; it makes it just Too Easy to litter your system with device-dependent pathnames, from which you will never escape.

If we did do such a time, we'd call it /._net, emphasizing the device-dependent nature of the beast (and warning users: Here Be Dragons.)

User-visible names related to add-on software packages

Also, we think there should be no more than a handful of such GNU-naming-shaped "bundles", simply because people won't be able to remember them all if there are more than that.

In fact, users tend to prefer exactly one such bundle.

Finally, users should not have to change their startup files (.profile, etc.) in any way in order to make use of packages coming and going. (Most users never touch the startup files they're given, and you really should have a scheme where That's OK.)

(The Sidai user setup scheme is one way of handling site-wide user setups [.profile, .cshrc, and the like] that fits the bill.)

So, we're trying to get by with only two ``bundles'': that works for us:

/usr/local:

A combination of tools that (a) Really Must Be Local to the machine in question, and that (b) we really want users to use in preference to any other versions around.

In this view, /usr/local is fairly small. In our experience, it comes down to interpreters (shells, Perl, Python, etc.) and setuid (or other Somewhat Sensitive) programs.

/our:

Other stuff we've added to the system.

Thus, one might expect /our/bin/netscape to be the local favorite way of starting Netscape; /our/info/make.info would be the GNU Make manual; /our/lib/libdb.a would be the Berkeley DB library archive for static linking...

The standard ARK package-management makes it easy for tools to pop in and out of a user-visible namespace organized in this way. For example, a tiny edit in your XML file for GCC will automagically cause it to migrate from /our/bin/gcc to /our/swdevp/bin/gcc (if, for instance, you decided to move software-development tools to their own ``bundle'' [not recommended]).

Pathnames related to ARK code

Per-host directories: For each ``bundle'' of user-visible package stuff, we need a ``deploy area''. We use the following:

In the latter two cases, it is Deeply Important that the deploy area is on the same partition as the ``bundle''.

General (per-site) directories: First, you will need one ``install area'' per proto-host that you install things for. At a three-platform site, you might need:

/sys/.-ark-install-hppa-hpux10.20
/sys/.-ark-install-ia32-linux-rh6.2
/sys/.-ark-install-sparc-solaris2.6
/sys/.-ark-install-ALL
/sys/.-ark-install-ia32-linux-rh6.2-amanda-server
/sys/.-ark-install-ia32-linux-rh6.2-mail-server
/sys/.-ark-install-ia32-linux-rh6.2-web-server

Other generally-useful pathnames

Names for proto-hosts

.:slicker .:slimy .:slinger   .:slippy .:clarence
   |          |        |           |        |
   ---------------------           ----------
        |             |             |      |
 .:std-sparc-solaris  |             |  .:std-ia32-linux
        |             ---------------           |
 .:sparc-solaris2.6         |           .:ia32-linux-rh6.1
        |                 .:ALL                 |
 .:sparc-solaris            |             .:ia32-linux
        |                sidai:ALL              |
 sidai:solaris                            sidai:linux

So, what's in the name, say, sparc-solaris2.6?

First, a proto-host names those real hosts that have it as a prototype (see prototypes as a naming tool...); the string of characters in the name has no significance. You can name your proto-host fluffy-the-penguin instead of sparc-solaris2.6 if you want to.

Now, whatever names you use, we would like proto-hosts (and, in general, proto-things) to be rigorous beasties. We'd like to have <properties> associated with them, and some kind of machine-checking to make sure that the properties don't suffer undue entropy.

So, for example, a sparc-solaris2.6 (or f-the-p?) proto-host might have a property that runs uname -a and sees if it really is 2.6.

But notice that even something like ``it's Solaris 2.6'' is NOT WELL-DEFINED, at least in any meaningful multi-site way. At your site, you might want sparc-solaris2.6 to include some particular set of OS patches; at my site, I might strongly not want some of those patches. You might want to insist on certain kernel-parameter tunings; I might not. And so on.

Furthermore, the definition of sparc-solaris2.6 is likely to change over time, even at one site. For example, last week it might've meant "OS patches up through May 2000"; this week, it might mean "OS patches up through Oct 2000".

So: all "interesting" proto-hosts are site-specific; ideally, they should have lots of machine-checked properties.

Collaboration-wise: teams that see eyeball-to-eyeball on definitions of semantically-rich proto-hosts can join forces, and create proto-hosts that capture their common notions.

Meanwhile, the proto-hosts that we're currently supplying under team Sidai (host/{solaris,hpux,linux}.xml) are semantically-poor. I don't think there's much we can say that's certain to be true across many ARK sites. Not much more than "if it's Solaris, you'll find `make' in /usr/ccs/bin"...

So, should a more-specific proto-host be solaris-web-server or sparc-solaris2.6-web-server? The first part of the answer, above and long-windedly, is "the name doesn't matter".

But of course names do matter. They make it easier for us to talk not-at-cross-purposes.

The name solaris-web-server fails the following test: the name does not give a good indication of what's in the proto-host's prototype path. Put another way: it doesn't tell us anything about the 90% of the "inheritance iceberg" that we can't see.

I would expect packages put on a proto-host web-server to be platform-independent; on solaris-web-server, would work on any old Solaris thing.