The Umbrellix Logo. Also a civil emblem of the Evdonia micronation. It's a transparent image with bottom-right corner stripes of red, grey white, celestial, and green.Umbrellix Umbrellix Software House

On directory hierarchies

Initially written starting the 7th of October, 2022 a.d., at 04:15 AM UTC, by Amelia Bjornsdottir (she, they).

Misleadingly, work on this document started after RFC 2 was finished.

Comment is invited; see contact to ask how to contact us personally. Comment publication is at the discretion of the author. Be sure to include “RFC 1” or “On the business of RFC 1” in your subject line so I know the RFC you are commenting on.

IETF RFC 2119 applies

To the extent that this document proposes a protocol or a requirement, the key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in IETF RFC 2119 and IETF RFC 8174.

Background

Putting /package, /command and /doc in their time and place

Some time between 2000 and when he stopped programming under his paradigm, the good professor Daniel Julius Bernstein proposed a partial alternative filesystem hierarchy for UNIX systems, after noticing that FHS was error-prone. This theme of realisation underscores much of Daniel’s work, and Paul Jarc’s continuation thereof. For instance, qmail and qlist were written because Daniel needed to manage a long mailing list, and sendmail kept dropping messages on the floor and took high quantities of resources, and had root bugs that would make IIS on Windows look good. ezmlm was effectively the continuation of qlist. We maintain privately a fork of ezmlm called Nightmare Lists, and it runs Lightning’s mailing lists on chatspeed.net. Anyway, enough of that tangent - we’re here on filesystem hierarchy business.

You Are Here - What material will we be covering in this essay?

/package is supposed to be (and is, within The DJB Way’s follower base) a globally-assigned hierarchy under which packages of software might unambiguously be installed and referred to. With the standard as it is, the standardization body for names under this hierarchy is Daniel and his delegates. This works perfectly fine for a niche standard as /package is - after all, that’s how Internet assigned names and numbers were handled by Jon Postel before the current structure of IANA was resolved - but we wouldn’t be here, in this document, Umbrellix RFC 1 (please note that that number has been assigned before, but we reassign it here due to the lack of documentation of what RFC1 was), if I thought that was a good enough explanation, and decided to pack up and go home from that. In this document, we propose an alternate hierarchy, /pkg based on a standard which is solely dependent on the standards on which domain names in the Internet are built, while permitting “on-speculation” unregistered use of various names, including usernames on public websites, and also providing a test area that is guaranteed to be unoccupied so long as umbrellix.net. remains alive.

/command is supposed to be (and is, within The DJB Way’s follower base) a globally-assigned directory under which packages assigned under /package may register globally-available filenames to be used on the search path. This is entirely the wrong model for several reasons, and we don’t use this on Lightning’s machine where we make extensive use of /command, though we accept slashcommand assignments as persuasive when naming disputes occur (they have not, at this time). In this document, we propose a method for deferring the administration of a similar hierarchy, /cmd, to local administration, while encouraging that disparate programs with similar names should be installed according to administrator, not packager, preference.

/doc is more of a framework into which one can plug any package hierarchy’s documentation files. In this document, after a critical evaluation, we effectively receive the bones of /doc as a sound means of organizing HTML man pages, albeit with critically deficient capabilities in multiple areas.

The Criticisms

The /package directory

TODO: actually criticise /package.

The /command directory

TODO: actually criticise /command.

The Directories

These names are blatant Unix-like shortenings of their DJB ancestors.

The /pkg directory

Unlike names under /package, names at the first level under /pkg are regular Internet hostnames. Internet hostnames that will never be valid, for instance, those where the TLD is a single character long, will never be valid and SHOULD NOT be used in publicly-disseminated /pkg repositories if a better name is available to you (which would include, theoretically, a Freenom domain name from Tokelau, Gabon, Equatorial Guinea, the Central African Republic, or Mali). Pseudo-domains ending in .onion or .onion. MAY be used as long as you or your allocator control the private key behind it. Use of valid Internet hostnames you do not control is considered “on-speculation” use. The trailing period that makes a domain name fully qualified SHALL be omitted from the canonical first level name, and a first level name MAY be symlinked to its fully qualified (with trailing period) form. It is considered to be implied that a domain name is fully qualified if used in /pkg. For on-speculation use related to a username, a domain MUST be separated from a username by a colon :. For on-speculation use related to the proprietor defining another standard like this (such as yp.to’s the /package hierarchy), their package names MUST be taken verbatim, even if they deviate from the following requirements.

The format of a package name at the second level is a name as allocated by the administrator of that hostname/on-spec name. Lists and details of allocations need not be public, but if they are, they SHOULD be made public via HTTP, in a format TBD, and SHOULD be rendered into a suitably visually-congruent layout of HTML or XHTML at /pkg, /pkg.html or /pkg.xhtml. The format TBD MUST be taken as authoritative if it exists and if the HTML or XHTML version differs.

The names of packages at the second level SHOULD follow the restrictions that apply to names under /package, vi⁊. lowercase ASCII letters, digits, the hyphen - when the next character is not a digit, the European addition sign +, and the directory separator /, and version numbers MUST (or SHOULD, if the package name is already deviant) also follow the restrictions applicable to version numbers under /package, except that ‘@’ is to be considered a digit for the purpose of hyphens and version numbers, and that if it is used in version numbers, it MUST be followed by a short, but unambiguous version control commit number from the repository the software comes from, which may contain any character valid in a package name except for the directory separator. If the number’s length exceeds seven characters, a seven character or more substring is acceptable if that is unambiguous, and the quantity of characters used SHOULD NOT vary from version to version.

As an example of licenced Internet hostname usage,

As a hypothetical example of licenced non-Internet hostname usage,

As an example of “on-speculation” Internet hostname usage, in lieu of a definition,

Under most circumstances, you will not have a problem if you make /pkg visible under /package/host - but be aware that this is not a recommended configuration, and it does not comply with /package if you install packages named “on-speculation.”

The /pkg/umbrellix.net/ directory

This section has moved. The friendly page for package name control for Umbrellix.net now resides at /pkg.html on this site.

The /cmd directory