Advanced Namespace Tools blog

31 December 2016

Writing a better README and basic install/use docs

I have written a lot of documentation for ANTS (probably too much) but the old README and other files in the base directory are just not good enough. I'm going to start ground-up rewrites beginning with the README.

README

Advanced Namespace Tools for 9front and Bell Labs Plan 9

This is a toolkit of additions and modifications to Plan 9. It is designed to make Plan 9 installations, on single machines or on networks, more flexible. ANTS has:

A modified boot process which creates an isolated administrative namespace independent of any root fileserver.
A modified kernel which accepts manipulation of process namespace via writes of standard namespace operations to the /proc/PID/ns files
Scripts for moving between and systematically altering namespaces such as "rerootwin" which is similar to chroot in unix and keeps the terminal devices at /mnt/term active.
Optional fossil/venti support with administrative scripts for progressive backup/replication and maintaining a log of rootscores
Hubfs 9p fs for networked persistent shell sessions and a lightweight general purpose multiclient read/write buffered message queue with pipelike hubfiles
Grio modified Rio with customizable appearance for color-coded namespace grouping, user-selectable additional menu command, and hubfs integration

Most of these components are synergistic, but not interdependent. The userspace programs and utilities do not generally depend on using the modified ANTS kernel.

Installing on 9front from source

Check that your 9front hg revision matched up with a compatible ANTS revision. The most recent tested 9front revision is 5641, the "GZ" release. Previously tested ANTS/9front revisions are listed in the INSTALLING file.The build script has a variety of possible targets. A basic sequence:

# compile everything but install nothing yet
build 9front
# install userspace components but not kernel/9fat
build fronthost 
# copy new kernel and tools to 9fat partition
9fs 9fat && cp 9ants /n/9fat/9ants && cp tools.tgz /n/9fat/tools.tgz
# add one line to /rc/bin/termrc for gui/terminal service
echo 'home=/usr/$user; cd; . $home/lib/profile' >>/rc/bin/termrc
# edit plan9.ini
acme /n/9fat/plan9.ini

To allow you to select between kernels at boot, you can set bootfile= in plan9.ini to not provide a value. Then at boot you will have to type "bootfile=9ants" or "bootfile=9pcf" (assuming that is your original kernel name) and then "boot". You will probably want to set "tgzfs=tools.tgz" and possibly "bootcmd=plan9rc". frontmods/plan9.ini has a minimal example that works with a fresh cwfs install to a qemu vm.

You may also wish to change "rio" to "grio" in your profile.

Using 9front/ANTS

The behavior of the standard user namespace should be unchanged, apart from the use of grio rather rio if desired. To access the special service namespace, either rcpu in (the default port is 17060) or, if using a terminal system, "hub hubfs" to connect to a peristent shell in that namespace. When connecting to the service namespace via Drawterm, add the -B flag. From within the service namespace, you may enter the standard namespace with this sequence:

rerootwin -f boot
service=con
. $home/lib/profile

With bootcmd=plan9rc set in plan9.ini, ANTS supports additional boot options, such as fossil+venti (requires installing fossil, partitioning hard drive correctly, and setting plan9.ini options.) or fully interactive boot with prompts for all options (with interactive=yes in plan9.ini).

Additional documentation found in the INSTALLING file and in the doc/ subdirectory.

Installing on Bell Labs from source

# compile everything but install nothing yet
build everything
# install userspace components but not kernel/9fat
build labshost 
# copy new kernel and tools to 9fat partition
9fat: && cp 9pcram.gz /n/9fat/9pcram.gz && cp tools.tgz /n/9fat/tools.tgz
# edit plan9.ini
acme /n/9fat/plan9.ini

A sample plan9.ini file with boot menu is found at doc/plan9.ini

Using Labs/ANTS

The behavior of the standard user namespace should be unchanged, apart from the use of grio rather rio if desired. To access the special service namespace, either cpu in (the default port is 17060) or, if using a terminal system, "hub hubfs" to connect to a peristent shell in that namespace. From within the service namespace, you may enter the standard namespace with the command:

rerootwin boot