/sys/doc/ Documentation archive

John Floren, 2007-03-21

Welcome, new user!

If you are reading this, you probably have an account on RIT's Computer Science
Plan 9 system.  This document will walk you through your first steps in Plan 9.
Remember, Plan 9 is not UNIX, although it is superficially similar.  If you get
frustrated, keep at it--Rome was not built in a day.  Plan 9 is far from most any
common operating system and takes some getting used to.  Hopefully, though, you'll
come to appreciate some of the useful concepts of Plan 9.

The first step is to log on.  Unless you have a spare computer around on which to
install Plan 9, you'll want to use the 'drawterm' client (details on booting a
Plan 9 terminal are at the end of this document).  Drawterm is available at
http://swtch.com/drawterm.  Download the client that is appropriate for your
operating system.  After you have drawterm, open a command prompt and run
"drawterm -a csplan9.rit.edu -c csplan9.rit.edu -u <username>".  If you are
on Windows, it's drawterm.exe and the -u option is not necessary.  A window should
appear and prompt for a password.  Type your password and hit enter.  If you have
never logged in before, you'll likely be stuck at a prompt that looks like
"csplan9%".  Run '/sys/lib/newuser' to set up your account; this is the only time
you'll ever need to do that.

You should now see a grey screen.  This is rio, the Plan 9 window manager.  Right
click anywhere and hold it; select "New" from the menu that appears.  Your cursor
will change to a cross.  Click and hold the right mouse button again, then sweep
the mouse diagonally and release the button to draw out a new terminal window.
Type 'ls' and 'pwd'--you're in your home directory and some of the familiar UNIX
commands obviously work.  If you were assigned a temporary password, now is
probably a good time to change it with 'passwd'.  If the output of a command goes
off the end of your window, press the down arrow to see more.

***USING PLAN 9***
Sweep out a couple of new windows.  Try running 'stats' in one to get a system
monitor.  Run 'rio' in another--it turns into a whole new instance of rio for you
to play with!  You'll find lots more programs under /bin, so experiment with them
and rio a bit.  The right-click menu options in rio are pretty self explanatory:
New creates a new window, Resize changes the size of an existing window, Move
moves an existing window, Delete destroys a window, and Hide gets a window out of
your way (it'll show up under the right-click menu now).  Remember that the button
used to select a menu item is also the one you use to activate it--if you select
Delete, you have to right-click a window to delete it.  Resize might be a little
weird the first time; select it, then right click on a window which will
disappear.  Draw out a window as though you were making a new window, then, when
you release the mouse button, you'll see your old window there in a different
size.  There's another menu available with a mid-click; Cut and Paste are pretty
self-explanatory, and Snarf is just the Plan 9 word for Copy.  Plumb will be
explained shortly.  Send takes whatever you have selected right now and sends it
to the shell as a new command.  Scroll is very useful in that it will make your
terminal automatically scroll with output; if this is not selected, you have to
hit the down arrow to see new output.  A lot of individual applications will have
similar menus, so try mid-clicking and right-clicking when you play with a new

With a little experimentation, you should become familiar with basic Plan 9 use.
You can send and read mail from the command line (read the 'mail' man page);
remember, when sending to other Plan 9 users, just send mail to their user
name--no hostname is necessary.  After you get used to the way windows work, you
can try some other things, like the primary editor, 'acme'.  It's too complex to
explain in this document; I suggest reading /usr/glenda/readme.acme and
/usr/glenda/readme.rio, as well as plenty of man pages (there are man pages for
almost everything; 'lookman' searches the man pages for a term).

Now, for some things that really show what Plan 9 is good at.  Type 'ftpfs
ftp.ibiblio.org' and login as anonymous.  You'll find yourself back at the prompt,
which is okay.  Change directory to '/n/ftp'.  You'll see that this directory
contains the files found in the top-level directory of ftp.ibiblio.org.  You can
now use the remote server as though it was part of the local filesystem; 'cd',
'ls', 'cp', etc.  will all work fine.  A similar (but more powerful) tool exists
for connecting to other Plan 9 machines.  All Plan 9 machines use 9p as their
service protocol, which among other things means that it's really easy to mount
another machine's filesystem for local use.  Type '9fs sources'.  /n/sources now
contains the files on Bell Labs' "sources" machine.  /n/sources/contrib contains a
lot of user-written source for Plan 9; I suggest browsing through the entire
sources tree.

Remember the "Plumb" item in the mid-click menu?  Plumb is a kind of "smart"
application that takes data from one program to another.  Start 'acme' in a
window, then type 'cpu(1)' in another, but don't hit enter.  Mid-click somewhere
on the word 'cpu(1)', then select "Plumb".  The manual page for the cpu command
should show up in acme.  Plumb also does similar operations with source files,
mail messages, images, and formatted documents.

Plan 9 contains most of your basic UNIX utilities, such as ls, cp, mv, tar, gzip,
etc.  You can discover other programs by looking around in /bin and reading man
pages; here's some Plan 9-specific programs worth checking out:
-acme: A fully-featured programmer's editor with mail, news, and wiki browsing
-sam: Another editor of a different sort; acts more like rio than acme does
-cpu: Connect to another Plan 9 machine
-stats: Show system load, memory, and other stats.  Can also monitor remote
-faces: Display icons to represent new mail; right-click icons to read
-winwatch: Manage your windows
-links: A port of the popular browser
-bsflite: A text-based AIM client
-bsfirc: A simple irc client
-epic: Another irc client
-vt: A vt100-type emulator; useful for connecting to UNIX machines
-yesterday: Find the path to the previous version of a file
-history: Find more previous versions of a file
-page: A versatile viewer--displays PostScript, PDF, images, and more!
-weather: Show weather based on an airport code.  Try 'weather roc'

Something you may find very handy about drawterm is /mnt/term.  In this directory,
you should find the root directory of your host system.  If I'm working from a
Linux box and I need to print a file, for example, I can run 'cp myfile.txt
/mnt/term/home/john/myfile.txt' to copy the file to my Linux drive.

One thing that is both a feature and a potential problem with Plan 9 is the Venti
archival fileserver.  All data that gets left on the system for more than a day
will end up permanently archived unless it is marked temporary ('chmod +t file'
makes a file temporary, 'ls -T' shows temporary files with a 't' in front).  The
fossil filesystem (think of it as a buffer for Venti) can only hold about 6 GB of
data.  This gets flushed to Venti every day, except for temporary files; if you
make too many temporary files, fossil will fill up and cause major problems.
Ephemeral filesystem snapshots are taken every hour and deleted after a few days.
If you want to create or download large files (over a hundred megabytes), please
make them temporary, as Venti space is limited.  Contact the admin (john) to get
the O.K.  before downloading many large files.  If you want to browse the old
archived files, '9fs dump' and '9fs snap' will mount the archives and the
temporary snapshots under /n/dump and /n/snap, respectively.  These are both
organized by year, month, day, and hour.  Again, please be considerate with your
filesystem usage--moderate consumption is okay, but using the system as a
music/video storage area or keeping lots of really .iso's around without the "t"
flag set are grounds for account removal.  If you have questions about the
filesystem, please email user 'john'.

For more help, Google for what you're looking for or read the Plan 9 wiki
(http://plan9.bell-labs.com/wiki/plan9/plan_9_wiki/).  There is also an excellent
collection of documents located in /sys/doc.  I suggest starting with 9.ps, which
can be read using the 'page' viewer ('page 9.ps').  Again, contact 'john' for
topic-specific documentation and general help.

You may also consider getting an account on a public Plan 9 server, if only to
experiment further with the possibilities of interconnected Plan 9 machines.  The
tip9ug system has been running for years and has a large community; more info is
available at http://www.tip9ug.jp.  Note that since the system is in Japan,
network latency could become an annoyance for heavily graphical programs.

This system has Inferno installed.  If you know what that is, enjoy.  If not, I
suggest looking into it.

More advanced Plan 9 information can be found in Francisco Ballesteros' book,
which can be read by pointing the mouse at the text /sys/doc/9.intro.pdf and

For any problem you experience, please contact John Floren.  RIT username jff8829,
csplan9.rit.edu username john.

Plan 9 is really meant to be used from a terminal booted into Plan 9 with a
fileserver providing a common root.  Although drawterm gives the illusion of such
an environment, it really can be much more pleasant to work from a terminal.
Using terminals also reduces load on the cpu servers, as programs will run on the
terminals by default.
If you have played with drawterm a bit and would like to try the real "Plan 9
experience" with a standalone terminal, you'll need a Pentium PC or better and a
Plan 9 cd (iso at the Plan 9 website).  Detailed installation instructions are
found on the wiki, but there are some specific things to know when installing for
a terminal.  First, you do not need a big hard drive, because you should not be
using it for anything besides booting; all your work will be stored on the
fileserver.  Anything around a gigabyte should be more than sufficient.  Second,
when prompted for filesystem, choose "fossil" rather than "fossil+venti", again
because the local hard disk doesn't need to be very fancy.  You should be able to
follow the wiki's instructions for the rest.  When you reboot the system, type
'tcp' when you get the "root is from" prompt.  Then give it for both
authentication and filesystem addresses.  Provide your csplan9 username and
password when prompted.  Once the system boots, you should find yourself able to
interact with Plan 9 as though you were using drawterm, except that programs you
run are executed on the terminal's processor instead of on the cpu server's
processor.  If you need more power, type 'cpu -h csplan9' to get a shell on the
cpu server.

This document could originally be found at: