shithub: fqa.9front.org

ref: e0311f7337e8c79c3d1106d81af1ec913d0a27aa

View raw version
.\" This troff source is processed to create all forms of the
.\" 9FRONT DASH 1 book and the http://fqa.9front.org website.
.\" NOTE: Purely experimental. Methods employed may change.
.\" troff -ms -mpictures fqa8.ms | page
.\" htmlroff -u -ms -mhtml fqa8.ms >fqa8.html
.de FG	\" .FG <basename>
.ie h .html - <img src="\\$1.\\$2" />
.el .BP \\$1.ps
.br
..
.po 1i \" page offset (from left)
.fp 1 R LucidaSans
.fp 2 I LucidaSansI
.fp 3 B LucidaSansB
.fp 4 BI LucidaSansI
.fp 5 CW LucidaCW
.paragraph 0
.margin 0
.HTML "FQA 8 - Using 9front
.html - <style type="text/css">body{font-size:10pt}; a{font-size:10pt}</style>
.html - <a href="fqa.html">FQA INDEX</a> |
.html - <a href="fqa7.html">FQA 7 - System Management</a> |
.html - <a href="fqa9.html">FQA 9 - Troubleshooting</a>
.html - <hr />
.SH
.LG
.ihtml h1 <h1>
FQA 8 - Using 9front
.ihtml h1
.NL
.R
.html - <a href="fqa8.html">html</a> |
.html - <a href="fqa8.pdf">pdf</a> |
.html - <a href="fqa8.ms">troff</a>

.FG using9front jpg

.FG rails jpg

When applied consistently, simple conventions can combine to provide powerful results. In Plan 9,
.I conventions
are preferred to
.I rules .
This section explores the Plan 9 approach to actually using the computer.
.bp
.html - <a name="8.1" />
.ihtml h2 <h2>
.SH
8.1 - rc
.R
.ihtml h2

.DS
.I
rc was a startup script from very early times in Unix, shortened, as
Ken was wont to do, from runcom, the nearest thing CTSS had to a
shell\(emit could run up to six prespecified commands in background.
The name runcom came to be applied to the scripts as well as to their
interpreter.
.R
\(em Doug McIlroy
.DE
.html - <br />

The
.CW rc
shell was written by
.ihtml a <a href="http://en.wikipedia.org/wiki/Tom_Duff">
Tom Duff
.ihtml a
for
.ihtml a <a href="https://web.archive.org/web/20170601063844/http://www.cs.bell-labs.com/10thEdMan">
Research UNIX v10.
.ihtml a
It was later adopted as the shell for Plan 9. Some of its conventions are unusual compared with other command interpreters influenced by the
.ihtml a <a href="http://en.wikipedia.org/wiki/Bourne_shell">
Bourne shell.
.ihtml a
Although its syntax may seem strange at first, have patience;
.CW rc
was designed this way on purpose. Once its (few, but powerful) features are internalized,
.CW rc
simply gets out of the way.

Read:
.ihtml a <a href="http://doc.cat-v.org/plan_9/4th_edition/papers/rc">
.I
Rc - The Plan 9 Shell,
.R
.ihtml a
.ihtml a <a href="http://man.9front.org/1/rc">
.CW rc(1)
.ihtml a

.html - <a name="8.1.1" />
.ihtml h3 <h3>
.SH
8.1.1 - Prompts
.R
.ihtml h3

Creating an
.CW rc
function with the same name as your prompt allows you to easily double-click to select at the end of a previously typed line and then
.CW send
it using the mouse button 2 menu (see the discussion of
.CW rio
menus, below). This can be used to approximate a form of command history (see also the commands
.ihtml a <a href="http://git.9front.org/plan9front/plan9front/HEAD/rc/bin/%22/f.html">
"
.ihtml a
and
.ihtml a <a href="http://git.9front.org/plan9front/plan9front/HEAD/rc/bin/%22%22/f.html">
"",
.ihtml a
which print and execute the previous command, respectively).

Add something like this to your
.CW $home/profile :
.P1
fn term%{ $* }
.P2

In
.CW rc
the
.CW ;
character forces the end of a line and is treated as a noop when it appears alone, so it is also possible to create a simple prompt that would require no special prompt function in order for the prompt to be effectively ignored when selecting and sending:
.P1
prompt=\'; \'
.P2

Obviously, the prompt can be named however the user sees fit.

.html - <a name="8.1.2" />
.ihtml h3 <h3>
.SH
8.1.2 - /env
.R
.ihtml h3

.B Note:
Contents of the
.CW /env
directory are provided by the kernel and represent a separate accounting of the shell's environment;
.CW rc
reads
.CW /env
only on startup, and flushes/writes
.CW /env
only before executing programs.

.html - <a name="8.2" />
.ihtml h2 <h2>
.SH
8.2 - rio
.R
.ihtml h2
.html - <br />
.FG what jpg

.CW rio
is the Plan 9 window system. More accurately,
.CW rio
multiplexes input devices with and serves a file interface to a series of rectangles, inside the boundaries of which are drawn an arbitrary arrangement of pixels. Controlling the rectangles is more straightforward, and at the same time more flexible, than what is commonly expected from most "window managers."

Read:
.ihtml a <a href="http://man.9front.org/1/rio">
.CW rio(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/4/rio">
.CW rio(4)
.ihtml a

To effectively use
.CW rio ,
you need a three button mouse. If you only have a two button mouse you can emulate the middle button by holding down the
.CW shift
key whilst pressing the right button.

.B Note:
Button 1, 2, and 3 are used to refer to the left, middle, and right buttons respectively.

.html - <a name="8.2.1" />
.ihtml h3 <h3>
.SH
8.2.1 - The Pop-up Menu
.R
.ihtml h3

Pressing and holding down mouse button 3 on the gray desktop or on a shell window will give you a menu with the following options:

.ihtml ul <ul>
.CW
New

Resize

Move

Delete

Hide
.R
.ihtml ul

Pressing and holding down mouse button 2 on a shell window results in a menu with the following options:

.ihtml ul <ul>
.CW
cut

paste

snarf

plumb

look

send

scroll
.R
.ihtml ul

Select an item by releasing the button over the menu item. Rio uses the same button that started an action throughout that operation. If you press another button during the action the operation is aborted and any intermediate changes are reversed.

Each menu acts as a action verb selector which then requires an object (i.e. window) to be picked to indicate which window the verb is to act on. A further mouse action may then be required.

.html - <a name="8.2.2" />
.ihtml h3 <h3>
.SH
8.2.2 - Window control
.R
.ihtml h3

Clicking on a window brings it to the front.

You can directly change the shape of a window by clicking and dragging on the edge or corner of the window
border. Mouse button 1 or 2 will allow you to drag the edge or corner to a new size, and mouse button 3 will allow you to
move the window.

The mouse button 3 menu contains a list of all windows that are corrently obstructed by other windows. Selecting a label tops the window.

The pop-up menu remembers the last command chosen, so as a shortcut you can just press and release button
3 without moving the mouse between pressing and releasing to select the previous command again.

In addition,
.CW rio
serves a variety of files for reading, writing, and controlling windows. Some of them are virtual versions of system files for dealing with the display, keyboard, and mouse; others control operations of the window system itself. These files, as well as the
.ihtml a <a href="http://man.9front.org/1/rio">
.CW window(1)
.ihtml a
command, allow for controlling windows programmatically by reading and writing text strings. Thus simplifying the automated opening and placement of various windows with user scripts.

Read:
.ihtml a <a href="http://man.9front.org/4/rio">
.CW rio(4)
.ihtml a

.html - <a name="8.2.3" />
.ihtml h3 <h3>
.SH
8.2.3 - Text in rio windows
.R
.ihtml h3

Text in a
.CW rio
window may be freely manipulated, edited, altered, deleted and/or acted upon using either mouse chords or the options from the mouse button menus. (For an example, see the discussion of the use of
.CW rc
prompts, above.)

The special file
.CW /dev/text
(for the current window), or \f(CW/mnt/wsys/\fIn\f(CW/text\fR (for window \fIn\fR) contains all text that has already appeared in the window. The contents of this file may serve as a primitive form of command history (and may be acted upon using standard command line tools), but are lost when the window is closed.

Seriously, read:
.ihtml a <a href="http://man.9front.org/4/rio">
.CW rio(4)
.ihtml a

.html - <a name="8.2.4" />
.ihtml h3 <h3>
.SH
8.2.4 - Scrolling
.R
.ihtml h3

By default, a
.CW rio
window will fill up with text and then block, obviating the need for a separate pager program (though the
.ihtml a <a href="http://man.9front.org/1/p">
.CW p(1)
.ihtml a
pager program still ships with the system).

Endless scrolling may be enabled by selecting
.CW scroll
from the mouse button 2 menu.

The
.CW up
or
.CW down
arrow keys and
.CW pgup
or
.CW pgdwn
keys may be used to scroll up or down in consistently measured increments.

Holding down the
.CW shift
key and pressing the up or down arrow key will scroll a single line in the respective direction.

9front's
.CW rio
supports mousewheel scrolling. The heuristic employed is roughly the same as that of clicking in the scrollbar on the left of the window: when the mouse pointer is near the top of the window the scrolling increment is small, while as the mouse pointer approaches the bottom of the window the scrolling increment grows progressively larger. Presently this behavior is limited to
.CW rio ,
.CW sam ,
and
.CW mothra 
but may later be extended to other programs.

.B Note:
While the behavior of the arrow and page keys is fairly consistent between programs, mousewheel scrolling is not. So far,
.CW shift

.CW up
or
.CW down
is only supported in
.CW rio
windows.

.html - <a name="8.2.5" />
.ihtml h3 <h3>
.SH
8.2.5 - Mouse Chording
.R
.ihtml h3

Almost anywhere \(em
.ihtml a <a href="http://man.9front.org/1/sam">
.CW sam(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/1/acme">
.CW acme(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/1/rio">
.CW window(1)
.ihtml a
\(em you can use the following mouse chords:

.CW mb1
\(em Select text.

.CW
mb1 double click
.R
\(em Select word under cursor, or at the end/start of a line, select the whole line.

After selecting with
.CW mb1
and while still holding
.CW mb1
down (these chords also
 work with text selected by double-clicking, the double-click expansion happens when the second
 click starts, not when it ends):

.CW mb2
\(em Cut text.

.CW mb3
\(em Paste text (can be reverted by clicking
.CW mb2
immediately afterwards).

To snarf (copy), click
.CW mb2
immediately followed by
.CW mb3 .

.html - <a name="8.2.6" />
.ihtml h3 <h3>
.B
8.2.6 - Keyboard Shortcuts
.R
.ihtml h3

Almost anywhere \(em
.ihtml a <a href="http://man.9front.org/1/sam">
.CW sam(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/1/acme">
.CW acme(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/1/rio">
.CW window(1)
.ihtml a
\(em you can use the following shortcuts:

.CW Ctrl-u
\(em Delete from cursor to start of line.

.CW Ctrl-w
\(em Delete word before the cursor.

.CW Ctrl-h
\(em Delete character before the cursor.

.CW Ctrl-a
\(em Move cursor to start of the line.

.CW Ctrl-e
\(em Move cursor to end of the line.

.CW Ctrl-b
\(em Move cursor to the position immediately after the prompt. (\f(CWrio\fR only)

Read:
.ihtml a <a href="http://unix-kb.cat-v.org">
UNIX Keyboard Bindings
.ihtml a

In a
.ihtml a <a href="http://man.9front.org/1/rio">
.CW rio(1)
.ihtml a
window, scroll up or down one line by holding
.CW shift
and pressing the up or down arrow.
.bp
.html - <a name="8.2.7" />
.ihtml h3 <h3>
.SH
8.2.7 - Color scheme
.R
.ihtml h3

.CW rio
looks like this:

.FG rio-bell-labs png

\f(CWrio\fR's color scheme may be modified by editing the .c configuration files and re-compiling:

.FG rio-custom png

.B Note:
Someone will mock you for doing this.

See:
.ihtml a <a href="http://plan9.stanleylieber.com/rio">
http://plan9.stanleylieber.com/rio,
.ihtml a
.ihtml a <a href="https://ftrv.se/14">
https://ftrv.se/14
.ihtml a

.bp
.ihtml a  <a href="http://genius.cat-v.org/rob-pike">
Rob Pike,
.ihtml a
rio's author, was all like:

.ihtml ul <ul>
.QS
the clean appearance of the screen comes mostly from laziness, but the
color scheme is (obviously) deliberate. the intent was to build on an
observation by edward tufte that the human system likes nature and 
nature is full of pale colors, so something you're going to look at all day 
might best serve if it were also in relaxing shades.  renee french helped me with 
the specifics of the color scheme (she's a professional illustrator and my 
color vision is suspect), once i'd figured out how i wanted it to look.  
there are still some features of the color system that i put in that i think no 
one has ever noticed.  that's a good thing, in my opinion; the colors should 
fade away, if you'll pardon the expression. having used other systems with
different approaches to color screens, most especially windows XP (extra pukey),
i think tufte was right.
.QE
.ihtml ul

.ihtml a <a href="http://marc.info/?l=9fans&m=111558908224071">
Rob Pike, 2003
.ihtml a

.ihtml ul <ul>
.QS
The color scheme was an attempt to honor a point made originally
in a little brochure by Edward Tufte that the colors of nature are
soft and quiet and peaceful to look at, while most computer screens
are covered in glaring bright colors.  When color came to the system
I wanted it to be pleasant.
.QE
.ihtml ul

.ihtml a <a href="http://marc.info/?l=9fans&m=121475380122105">
Rob Pike, 2008
.ihtml a

See:
.ihtml a <a href="http://www.edwardtufte.com/">
edwardtufte.com
.ihtml a

.html - <a name="8.2.8" />
.ihtml h3 <h3>
.SH
8.2.8 - Why is rio like this?
.R
.ihtml h3
.html - <br />
.FG mouse gif

Window systems should be transparent. That's the argument put forward in
.ihtml a <a href="http://doc.cat-v.org/bell_labs/transparent_wsys/">
the famous paper
.ihtml a
by rio's author,
.ihtml a <a href="http://genius.cat-v.org/rob-pike/">
Rob Pike.
.ihtml a

.FG mouse2 gif

Beyond this, Rob offered
.ihtml a <a href="http://marc.info/?l=9fans&m=111558805207697">
an explanation
.ihtml a
(in response to a question on the 9fans mailing list) of some of the choices made in the design of
.CW 8½
and 
.CW rio :

.ihtml ul <ul>
.QS
> functioning cursor keys would still be a speed benefit.

This feels true but is false.  There were some fascinating experiments
done a few years ago in which people were given a long, tedious
editing task.  Some of the people were keyboard fans, some were mouse
fans.  Both folks were asked to do the task two ways, in random order,
once using the mouse to do the editing, once using cursor keys etc.
Regardless of their predilections, which was stated up front, after
the experiment everyone who did the task agreed that it was faster to
use the keyboard than the mouse to complete the task.  Everyone.
Here's the kicker: everyone was wrong.  They were being timed, and in
fact the reverse was true.  Although they thought the keyboard was
faster, doing the task using the mouse was faster for everyone, by a
substantial fraction.

The explanation, besides the obvious that arrow keys are actually
pretty slow if you're going more than a line or character, is that
people feel the mouse wastes time because you need to grab it and move
it, but it's time well spent.  The part of the brain that uses
keyboard commands to move the cursor is a higher-order function, and
thinking and planning how to use the keys to get to the destination
blocks thinking about the editing task at hand.  But using the mouse
is done by a lower-order part of the brain, which keeps the editing
part of the brain clear.  There's less task switching going on when
you use the mouse, so you work more efficiently.

If you don't believe me, the story is here:

http://www.asktog.com/readerMail/1999-12ReaderMail.html

Thanks to some forgotten 9fan who mentioned this a while back.
I didn't know about these experiments when I said, long ago, that
using arrow keys to point at a display is like telling someone how to
go somewhere by giving directions, while using a mouse is like
pointing at a map.  In fact, I never used a screen editor until I had
a mouse, for just this reason.
.QE
.ihtml ul

.ihtml a <a href="http://marc.info/?l=9fans&m=111558805207697">
Rob Pike, 2001
.ihtml a

.html - <a name="8.2.9" />
.ihtml h3 <h3>
.SH
8.2.9 - tips
.R
.ihtml h3

.html - <a name="8.2.9.1" />
.ihtml h4 <h4>
.SH
8.2.9.1 - Taking a screenshot
.R
.ihtml h4

To capture the entire screen:
.P1
topng </dev/screen >screen.png
.P2

To capture only the current window:
.P1
topng </dev/window >window.png
.P2

It is also possible to capture
.I other
windows:
.P1
topng </dev/wsys/\fIn\fR/window >window.png
.P2
where
.I n
is the number of the window being captured.

Read:
.ihtml a <a href="http://man.9front.org/4/rio">
.CW rio(4)
.ihtml a

.html - <a name="8.2.9.2" />
.ihtml h4 <h4>
.SH
8.2.9.2 - Prevent console messages from overwriting the screen
.R
.ihtml h4

To capture console messages in a
.CW rio
window, open a new window and:
.P1
cat /dev/kprint
.P2

.html - <a name="8.3" />
.ihtml h2 <h2>
.SH
8.3 Text Editors
.R
.ihtml h2

.html - <a name="8.3.1" />
.ihtml h3 <h3>
.SH
8.3.1 - sam
.R
.ihtml h3

The text editor
.CW sam
was created by
.ihtml a <a href="http://genius.cat-v.org/rob-pike">
Rob Pike,
.ihtml a
and included in
.ihtml a <a href="http://doc.cat-v.org/unix/">
Research UNIX V9
.ihtml a
(circa 1986), and later included with Plan 9.

See:
.ihtml a <a href="http://sam.cat-v.org">
http://sam.cat-v.org
.ihtml a

Read:

.ihtml a <a href="http://doc.cat-v.org/plan_9/4th_edition/papers/sam/">
.I
The Text Editor sam
.R
.ihtml a
\(em The original paper by Rob Pike.

.ihtml a <a href="http://doc.cat-v.org/bell_labs/sam_lang_tutorial/">
.I
A Tutorial for the Sam Command Language
.R
.ihtml a
\(em Documents the editing language.

.ihtml a <a href="http://sam.cat-v.org/cheatsheet/">
.I
sam quick reference card
.R
.ihtml a

.ihtml a <a href="http://man.9front.org/1/sam">
.CW sam(1)
.ihtml a
man page

.ihtml a <a href="http://sam.cat-v.org/sam-fans/">
http://sam.cat-v.org/sam-fans/
.ihtml a
\(em sam-fans mailing list archive

.FG danflavin jpg

.ihtml a <a href="http://www.moma.org/collection/artist.php?artist_id=1911">
Dan Flavin,
.ihtml a
.I
Document for Untitled (to the “innovator” of Wheeling Peachblow),
.R
1968

.html - <a name="8.3.1.1" />
.ihtml h4 <h4>
.SH
8.3.1.1 - Scrolling
.R
.ihtml h4

9front's slightly modified version of
.CW sam
supports mousewheel scrolling in the same manner as
.CW rio .

Read:
.ihtml a <a href="fqa8.html#8.2.4">
.I
FQA 8.2.4 - Scrolling
.R
.ihtml a

.html - <a name="8.3.1.2" />
.ihtml h4 <h4>
.SH
8.3.1.2 - Mouse Chording
.R
.ihtml h4

9front
.CW sam
supports the same mouse chording as
.CW rio .

Read:
.ihtml a <a href="fqa8.html#8.2.5">
.I
FQA 8.2.5 - Mouse Chording
.R
.ihtml a

.html - <a name="8.3.1.3" />
.ihtml h4 <h4>
.SH
8.3.1.3 - Why does sam have a separate snarf buffer from rio?
.R
.ihtml h4

The program's author,
.ihtml a <a href="http://genius.cat-v.org/rob-pike">
Rob Pike,
.ihtml a
says:

.ihtml ul <ul>
.QS
was a consequence of running over 1200 baud when sam was first
written.  you didn't want every cut and paste to bounce off the remote
end at that speed.  nowadays that argument has less weight.  on the
other hand, i still kinda like that you can have an editing session
that doesn't corrupt what you have in rio's snarf buffer.  i tried the
unified way in acme and i often (not always) miss the old way.
.QE
.ihtml ul

.ihtml a <a href="http://marc.info/?l=9fans&m=111558891922244">
Rob Pike, 2003
.ihtml a

.html - <a name="8.3.1.4" />
.ihtml h4 <h4>
.SH
8.3.1.4 - Keyboard Shortcuts
.R
.ihtml h4

.CW Esc
\(em Cut (and consequently, snarf) the selected text.

.CW Ctrl-b
\(em Switch focus to the edit window.

.html - <a name="8.3.2" />
.ihtml h3 <h3>
.SH
8.3.2 - acme
.R
.ihtml h3

.DS
.I
There is also an alternative user interface, acme(4), that some people use as their editor.
.R
\(em Geoff Collyer
.DE

The text editor
.CW acme
was created by
.ihtml a <a href="http://genius.cat-v.org/rob-pike">
Rob Pike.
.ihtml a
It builds on the
.CW
sam
.R
command language, and adds new features, which have proven very popular.

See:

.ihtml a <a href="http://acme.cat-v.org">
http://acme.cat-v.org
.ihtml a

.ihtml a <a href="http://acme.cat-v.org/readme">
The Acme Readme
.ihtml a

.ihtml a <a href="http://doc.cat-v.org/plan_9/4th_edition/papers/acme/">
.I
Acme: A User Interface for Programmers
.R
.ihtml a
\(em The original paper by Rob Pike.

.ihtml a <a href="http://man.cat-v.org/plan_9/1/acme">
acme(1)
.ihtml a
\(em Commands: acme, win, awd, interactive text windows.

.ihtml a <a href="http://man.cat-v.org/plan_9/4/acme">
acme(4)
.ihtml a
\(em The file system interface: control files for text windows.

.ihtml a <a href="https://research.swtch.com/acme">
A Tour Of Acme
.ihtml a
\(em Video tutorial by Russ Cox explaning the main features and principles of Acme.

.FG cyclogram gif

.ihtml a <a href="http://www.edwardtufte.com/tufte/posters">
Handmade cyclogram
.ihtml a
by Russian cosmonaut, Georgi Grechko.


.html - <a name="8.4" />
.ihtml h2 <h2>
.SH
8.4 - Internet
.R
.ihtml h2
.html - <br />
.FG internet jpg

Sending and receiving bits via alien protocols.

.html - <a name="8.4.1" />
.ihtml h3 <h3>
.SH
8.4.1 - Mail
.R
.ihtml h3

Read:
.ihtml a <a href="http://man.9front.org/1/mail">
.CW mail(1) ,
.ihtml a
.ihtml a <a href="fqa7.html#7.7">
.I
FQA 7.7 - Mail server configuration and maintenance
.R
.ihtml a

.html - <a name="8.4.1.1" />
.ihtml h4 <h4>
.SH
8.4.1.1 - upasfs
.R
.ihtml h4

From
.ihtml a <a href="http://man.9front.org/4/upasfs">
.CW upasfs(4) :
.ihtml a
.ihtml ul <ul>
.QS
Fs is a user level file system that caches mailboxes and
presents them as a file system.  A user normally starts fs
in his/her profile after starting plumber(4) and before
starting a window system, such as rio(1) or acme(1). The
file system is used by nedmail(1), acme(1)'s mail reader,
and imap4d and pop3 (both pop3(8)) to parse messages.  Fs
also generates plumbing messages used by biff and faces(1)
to provide mail announcements.
.QE
.ihtml ul

Read:
.ihtml a <a href="http://man.9front.org/4/upasfs">
.CW upasfs(4) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/8/pop3">
.CW pop3(8) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/1/faces">
.CW faces(1)
.ihtml a

.html - <a name="8.4.1.1.1" />
.ihtml h5 <h5>
.SH
8.4.1.1.1 - Reading gmail via IMAP
.R
.ihtml h5
.P1
upas/fs -f /imaps/imap.gmail.com/your.username@gmail.com
.P2

The first time this command is run, you should see an error that looks something like this:
.P1
upas/fs imap: server certificate 22471E10D5C1E41768048EF5567B27F532F33
	not recognized
upas/fs: opening mailbox: bad server certificate
.P2

To add this certificate to your system, type:
.P1
echo \'x509 sha1=22471E10D5C1E41768048EF5567B27F532F33\' \e
	>>/sys/lib/tls/mail
.P2

Once
.CW upas/fs
is running, you can open as many additional gmail mailboxes (labels) as you wish:
.P1
echo open /imaps/imap.gmail.com/your.username@gmail.com/yourlabel \e
	yourlabel >/mail/fs/ctl
.P2

.B Note:
Opening large mailboxes over a slow 9p link will be very slow.

.html - <a name="8.4.1.1.2" />
.ihtml h5 <h5>
.SH
8.4.1.1.2 - Sending mail with gmail
.R
.ihtml h5

Add your gmail password to the factotum:
.P1
echo 'key proto=pass server=smtp.gmail.com service=smtp \e
	user=your.username@gmail.com !password=yourpassword'\e
	>/mnt/factotum/ctl
.P2

Modify
.CW /mail/lib/remotemail
to gateway mail through your gmail account:
.P1
#!/bin/rc
shift
sender=your.username@gmail.com
shift
addr=tcp!smtp.gmail.com!587
shift
fd=`{/bin/upas/aliasmail -f $sender}
switch($fd){
case *.*
	;
case *
	fd=gmail.com
}
exec /bin/upas/smtp -u your.username@gmail.com \e
	-a -h $fd $addr $sender $*
.P2

Read:
.ihtml a <a href="http://man.9front.org/6/rewrite">
.CW rewrite(6)
.ihtml a

To actually use the gateway you have to setup your
.CW /mail/lib/rewrite
by including and adjusting the contents of
.CW /mail/lib/rewrite.gateway .
Change
.CW YOURDOMAIN.DOM
to
.CW gmail.com :

.P1
...
# append the local domain to addresses without a domain
local!"(.+)"		alias		\e1@gmail.com
local!(.*)		alias		\e1@gmail.com
...
.P2

And adjust your
.CW /lib/ndb/local :
.P1
echo smtp=gmail.com >> /lib/ndb/local
.P2

Before this will work you need to retrieve the certificate hash. This can be done
by trying to send an e-mail and then looking for the hash in the log:
.P1
echo hello | mail -s test your.username@gmail.com
.P2

Then look in
.CW /sys/log/smtp
for the following error:
.P1
cert for smtp.gmail.com not recognized:
	sha256=wnu7Uuzq4MlyJHP90+8f2smoh6x3cj0dG5z02jJlX42
.P2

Add the certificate to your system:
.P1
echo 'x509 sha256=wnu7Uuzq4MlyJHP90+8f2smoh6x3cj0dG5z02jJlX42' \e
	>> /sys/lib/tls/smtp
.P2

You should now be able to send e-mail through gmail!  I'm sorry.

.B Note:
This configuration breaks local e-mail delivery.

.html - <a name="8.4.1.2" />
.ihtml h4 <h4>
.SH
8.4.1.2 - nedmail
.R
.ihtml h4

.CW nedmail
is a command line mail client similar to the classic mail client shipped with
.ihtml a <a href="http://doc.cat-v.org/unix/">
Research UNIX.
.ihtml a

Read:
.ihtml a <a href="http://man.9front.org/1/nedmail">
.CW nedmail(1)
.ihtml a

.SH
8.4.1.2.1 - mother
.R
.ihtml h4

.CW mother
is a clone of
.CW nedmail ,
written in
.CW rc .
It offers some convenient new features and is easy to extend.

Download it here:
.ihtml a <a href="http://plan9.stanleylieber.com/mother/">
http://plan9.stanleylieber.com/mother/
.ihtml a

.SH
8.4.1.2.2 - Nail
.R
.ihtml h4

.CW Nail
is a clone of acme's
.CW Mail ,
written in c.  It offers some convenient new features.

.B Update:
.CW Nail
has been renamed
.CW Mail
and integrated into
.CW acme
to replace the original
.CW Mail.
Just type
.CW Mail
to use
.CW Nail.

.html - <a name="8.4.1.3" />
.ihtml h4 <h4>
.SH
8.4.1.3 - nupas
.R
.ihtml h4

Read:
.ihtml a <a href="http://plan9.stanleylieber.com/_books/comp/plan9/nupas.pdf">
.I
Scaling Upas,
.R
.ihtml a
by Erik Quanstrom
.B Note:
Erik's nupas has been merged with 9front's upas.

.html - <a name="8.4.2" />
.ihtml h3 <h3>
.SH
8.4.2 - NNTP
.R
.ihtml h3

Read:
.ihtml a <a href="http://man.9front.org/1/newt">
.CW newt(1) ,
.ihtml a <a href="http://man.9front.org/4/nntpfs">
.CW nntpfs(4)
.ihtml a

.html - <a name="8.4.3" />
.ihtml h3 <h3>
.SH
8.4.3 - IRC
.R
.ihtml h3

.html - <a name="8.4.3.1" />
.ihtml h4 <h4>
.SH
8.4.3.1 - ircrc
.R
.ihtml h4

.CW ircrc
is an IRC client implemented in
.CW rc .
It is included with 9front.

Read:
.ihtml a <a href="http://man.9front.org/1/ircrc">
.CW ircrc(1)
.ihtml a

.html - <a name="8.4.3.2" />
.ihtml h4 <h4>
.SH
8.4.3.2 - irc7
.R
.ihtml h4

A persistent IRC client was written in the c programming language by Andrey Mirtchovski. It has been modified slightly by 9front users (mainly, adding an
.CW -e
flag to the
.CW ircsrv
program that implements SSL connections).
.html - Download it here:
.ihtml a <a href="https://code.9front.org/hg/irc7">
https://code.9front.org/hg/irc7
.ihtml a

.html - <a name="8.4.3.3" />
.ihtml h4 <h4>
.SH
8.4.3.3 - ircs
.R
.ihtml h4

A persistent, logging IRC client inspired by the classic Plan 9 IRC client
.CW irc7 .

.html - Download it here:
.ihtml a <a href="http://shithub.us/kemal/ircs/HEAD/info.html">
http://shithub.us/kemal/ircs/HEAD/info.html
.ihtml a

.html - <a name="8.4.3.4" />
.ihtml h4 <h4>
.SH
8.4.3.4 - wircrc
.R
.ihtml h4

A windowed version of
.CW ircrc
was implemented in rc by cinap_lenrek.
Several unsanctioned versions with various additions have since occasionally been spotted.

.html - Download them here: <a href="http://felloff.net/usr/cinap_lenrek/wircrc">cinap's</a>, <a href="http://9front.org/extra/rc/wircrc">sl's</a>, <a href="http://contrib.9front.org/spew/rc/wircrc">spew's</a>, <a href="http://contrib.9front.org/qwx/rc/wircrc">qwx's</a>.

.html - <a name="8.4.4" />
.ihtml h3 <h3>
.SH
8.4.4 - FTP
.R
.ihtml h3

Read:
.ihtml a <a href="http://man.9front.org/4/ftpfs">
.CW ftpfs(4)
.ihtml a

.html - <a name="8.4.5" />
.ihtml h3 <h3>
.SH
8.4.5 - HTTP
.R
.ihtml h3
.html - <br />
.FG wwwhat gif

.html - <a name="8.4.5.1" />
.ihtml h4 <h4>
.SH
8.4.5.1 - mothra
.R
.ihtml h4
.html - <br />
.FG betweenthelines jpg

.CW mothra
is the standard web browser.  It is a trivial program written in 1995 by Tom Duff. It ignores Javascript, CSS and many HTML tags. It was dropped from Plan 9 after the 2nd Edition, but has been picked up and (somewhat) refined for 9front.
.CW mothra
now uses
.CW webfs ,
and no longer supports non-HTTP protocols.

Read:
.ihtml a <a href="http://man.9front.org/1/mothra">
.CW mothra(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/4/webfs">
.CW webfs(4)
.ihtml a

.html - <a name="8.4.5.2" />
.ihtml h4 <h4>
.SH
8.4.5.2 - abaco
.R
.ihtml h4

no.

.html - <a name="8.4.5.3" />
.ihtml h4 <h4>
.SH
8.4.5.3 - hget
.R
.ihtml h4

.CW hget
is a command line HTTP client (similar to programs such as
.CW curl
or
.CW wget )
that started out as a c program in Plan 9 from Bell Labs, but was re-implemented in
.CW rc
for 9front.
.CW hget
now uses
.CW webfs
and no longer supports non-HTTP protocols.

Read:
.ihtml a <a href="http://man.9front.org/1/hget">
.CW hget(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/4/webfs">
.CW webfs(4)
.ihtml a

.html - <a name="8.4.5.4" />
.ihtml h4 <h4>
.SH
8.4.5.4 - charon
.R
.ihtml h4

The
.ihtml a <a href="http://en.wikipedia.org/wiki/Inferno_os">
Inferno
.ihtml a
operating system can be run hosted on Plan 9, and includes a GUI web browser called
.ihtml a <a href="http://en.wikipedia.org/wiki/Charon_(web_browser)">
charon,
.ihtml a
which implements ECMASCRIPT 1.0 as well as additional HTML attributes.

.B Note:
.CW charon
is ancient and is not really a sufficient replacement for 9front's web browsers. The rudimentary javascript support can be useful for some simple tasks.

.html - <a name="8.4.5.5" />
.ihtml h4 <h4>
.SH
8.4.5.5 - i
.R
.ihtml h4

There exists an unfinished/buggy port of
.CW charon
from Inferno's limbo programming language to Plan 9 c.
.html - Source is available here: <a href="http://plan9.stanleylieber.com/src/i.tgz">i.tgz</a>

.ihtml - <a name="8.4.5.6" />
.ihtml h4 <h4>
.SH
8.4.5.6 - NetSurf
.R
.ihtml h4

.FG netsurf png

NetSurf has been ported to Plan 9 (APE + native frontend).  It nearly works.

Download it here:
.ihtml a <a href="https://github.com/netsurf-plan9/nsport">
https://github.com/netsurf-plan9/nsport
.ihtml a

.html - <a name="8.4.6" />
.ihtml h3 <h3>
.SH
8.4.6 - SSH
.R
.ihtml h3

Several SSH clients exist for Plan 9, none of which are perfect.

.html - <a name="8.4.6.1" />
.ihtml h4 <h4>
.SH
8.4.6.1 - ssh
.R
.ihtml h4

9front used to ship with the original Plan 9 native SSH1 client from Bell Labs. It has since been replaced
with a new SSH2 client that has been written from scratch. The new client supports only chacha20-poly1305 cipher
and curve25519 Diffie-Hellman for key exchange. RSA public key and password authentication are supported
with factotum. 

Read:
.ihtml a <a href="http://man.9front.org/1/ssh">
.CW ssh(1)
.ihtml a

.html - <a name="8.4.6.1.1" />
.ihtml h4 <h4>
.SH
8.4.6.1.1 - sshfs
.R
.ihtml h4

9front ships with an sshfs client that implements the SFTP protocol over the existing
.ihtml a <a href="http://man.9front.org/1/ssh">
.CW ssh(1)
.ihtml a
client.

Read:
.ihtml a <a href="http://man.9front.org/1/sshfs">
.CW sshfs(1)
.ihtml a

.html - <a name="8.4.6.1.2" />
.ihtml h4 <h4>
.SH
8.4.6.1.2 - sshnet
.R
.ihtml h4

Outgoing and incoming TCP connections can be proxied to an SSH server using the
.ihtml a <a href="http://man.9front.org/4/sshnet">
.CW sshnet(4)
.ihtml a
filesystem.

Read:
.ihtml a <a href="http://helpful.cat-v.org/Blog/2020/05/06/0/">
Free Carrots #1: VNC over SSH
.ihtml a

.FG rails jpg

.html - <a name="8.4.6.5.1" />
.ihtml h5 <h5>
.SH
8.4.6.5.1 - Mounting a remote u9fs share over SSH
.R
.ihtml h5

The
.ihtml a <a href="http://openbsd.stanleylieber.com/u9fs">
.CW u9fs
.ihtml a
program runs on UNIX and serves an unencrypted
.ihtml a <a href="http://man.9front.org/2/9p">
.CW 9P(2)
.ihtml a
share. It is possible to mount such a share over SSH.

.P1
srv -s 5 -e \'ssh -u sl -h wm \'\'/usr/local/bin/u9fs \e
	-u sl -na none\'\'\' wm /n/wm
.P2

An SSH connection is opened to remote UNIX host
.CW wm ,
logged in with user
.CW sl
and mounted on Plan 9 under
.CW /n/wm .

Read:
.ihtml a <a href="http://man.9front.org/4/srv">
.CW srv(4)
.ihtml a

.html - <a name="8.4.7" />
.ihtml h3 <h3>
.SH
8.4.7 - secstore
.R
.ihtml h3

Typing in lots of passwords over and over again is annoying.

Secstore authenticates to a secure-store server using a
password and optionally a hardware token, then saves or
retrieves a file.  This is intended to be a credentials
store (public/private keypairs, passwords, and other
secrets) for a
.CW factotum .

Read:
.ihtml a <a href="fqa7.html#7.4.3">
.I
FQA 7.4.3 - secstored
.R
.ihtml a
for information on setting up the secstore server, and:
.ihtml a <a href="fqa7.html#7.4.3.1">
.I
FQA 7.4.3.1 - Adding users to secstore
.R
.ihtml a
to add users.

Once a user has been added to
.CW secstored ,
the user may add to the file read by
.CW factotum
at startup. To do so, open a new window and type
.P1
% ramfs -p; cd /tmp
% auth/secstore -g factotum
secstore password: [user's secstore password]
% echo \'key proto=apop dom=x.com user=ehg !password=hi\' >> factotum
% auth/secstore -p factotum
secstore password: [user's secstore password]
% read -m factotum > /mnt/factotum/ctl
.P2
and delete the window.  The first line creates an ephemeral
memory-resident workspace, invisible to others and automatically
removed when the window is deleted.  The next three
commands fetch the persistent copy of the secrets, append a
new secret, and save the updated file back to secstore.  The
final command loads the new secret into the running
.CW factotum .

The
.CW ipso
command packages this sequence into a convenient
script to simplify editing of files stored on a secure
store.  It copies the named files into a local
.CW ramfs
and
invokes
.CW \\$editor
on them.  When the editor exits,
.CW ipso
prompts the user to confirm copying modified or newly created
files back to secstore. If no file is mentioned,
.CW ipso
grabs all the user's files from secstore for editing.

By default,
.CW ipso
will edit the secstore files and, if one of
them is named factotum, flush current keys from
.CW factotum
and load the new ones from the file.

Read:
.ihtml a <a href="http://man.9front.org/1/secstore">
.CW secstore(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/8/secstore">
.CW secstore(8)
.ihtml a

.html - <a name="8.4.8" />
.ihtml h3 <h3>
.SH
8.4.8 - drawterm
.R
.ihtml h3

.CW drawterm
is a program that users of non-Plan 9 systems can use to establish graphical cpu connections with Plan 9 cpu servers.  Just as a real Plan 9 terminal does,
.CW drawterm
serves its local name space as well as some devices (the keyboard, mouse, and screen) to a remote cpu server, which mounts this name space on
.CW /mnt/term
and starts a shell. Typically, either explicitly or via the profile, one uses the shell to start
.CW rio .
The original version is effectively abandoned, but is available here:
.ihtml a <a href="http://swtch.com/drawterm">
.CW http://swtch.com/drawterm
.ihtml a

.FG embraceextendextinguish png

There also exists a fork of Russ Cox's drawterm that incorporates features from 9front, most importantly DP9IK authentication support (see
.ihtml a <a href="http://man.9front.org/6/authsrv">
.CW authsrv (6))
.ihtml a
and the TLS based
.ihtml a <a href="http://man.9front.org/1/rcpu">
.CW rcpu (1)
.ihtml a
protocol:
.ihtml a <a href="http://drawterm.9front.org">
.CW http://drawterm.9front.org .
.ihtml a

.B Note:
The fork is the preferred version of drawterm for use with 9front because the old auth protocol is considered deprecated and the old CPU listeners are now disabled by default.

Pending integration of article from:
.ihtml a <a href="http://wiki.9front.org/drawterm">
.CW http://wiki.9front.org/drawterm
.ihtml a
.bp
.html - <a name="8.4.8.1" />
.ihtml h3 <h3>
.SH
8.4.8.1 - Connect to Plan 9 from a mobile device
.R
.ihtml h3

Use an SSH client to connect to a remote UNIX SSH server that can run the 9front fork's
.CW
drawterm -G:
.R

.ihtml a <a href="http://helpful.cat-v.org/Blog/2017/11/29/0/">
http://helpful.cat-v.org/Blog/2017/11/29/0/
.ihtml a

.FG iosprompt2openbsdtmuxdrawterm9front png

.html - <a name="8.4.8.2" />
.ihtml h3 <h3>
.SH
8.4.8.2 - drawterm behind firewalls
.R
.ihtml h3

.CW
drawterm
.R
connects to the cpu service, which normally listens on TCP port 17019, after authenticating against the auth server, which normally listens on TCP port 567. Authentication against the auth server is bypassed when connecting as the auth server's hostowner.

On the occasion you find yourself behind a firewall that blocks the auth/ticket TCP port 567, or the cpu TCP port 17019, you can configure your auth or cpu servers to listen on different ports.

To configure the auth server to listen on TCP port 80, in addition to TCP port 567:
.P1
cd /bin/service.auth
cp tcp567 tcp80
.P2
From your command line, or script, use Plan 9 dial strings:
.P1
drawterm -a tcp!<auth_server>!80 -h <cpu_server> -u <username>
.P2
example:
.P1
drawterm -a tcp!auth.9front.org!80 -h cpu.9front.org -u ken
.P2
To configure your cpu server to listen on a different port:
.P1
cd /rc/bin/service
cp tcp17019 tcp23
.P2
From your command line:
.P1
drawterm -a tcp!auth.9front.org!80 -h tcp!cpu.9front.org!23 -u ken
.P2
This will attempt to connect to your auth server on TCP port 80 (HTTP) and to your cpu server on TCP port 23 (Telnet).

Note: The same use of Plan 9 dial strings works for specifying auth servers on Plan 9 VMs behind firewalls. Use the dial string for auth in
.CW /lib/ndb/local :
.CW auth=tcp!<auth_server>!80

Read:
.ihtml a <a href="http://man.9front.org/8/listen">
.CW listen(8) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/6/authsrv">
.CW authsrv(6) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/2/dial">
.CW dial(2)
.ihtml a

.html - <a name="8.4.9" />
.ihtml h3 <h3>
.SH
8.4.9 - Peer to Peer (P2P)
.R
.ihtml h3

You know what we mean.

.ihtml - <a name="8.4.9.1" />
.ihtml h3 <h3>
.SH
8.4.9.1 - Tinc
.R
.ihtml h3

.CW tinc
 implements the mesh peer to peer VPN protocol from
.ihtml a <a href="https://www.tinc-vpn.org/ as of version 1.0.32">
https://www.tinc-vpn.org/
.ihtml a
as of version 1.0.32.

Read:
.ihtml a <a href="http://man.9front.org/8/tinc">
.CW tinc(8)
.ihtml a

.ihtml - <a name="8.4.9.2" />
.ihtml h3 <h3>
.SH
8.4.9.2 - Torrents
.R
.ihtml h3

.ihtml - <a name="8.4.9.2.1" />
.ihtml h3 <h3>
.SH
8.4.9.2.1 - ip/torrent
.R
.ihtml h3

Native client. Works great. Does not support magnet links.

Read:
.ihtml a <a href="http://man.9front.org/1/torrent">
.CW torrent(1)
.ihtml a

.ihtml - <a name="8.4.9.2.2" />
.ihtml h3 <h3>
.SH
8.4.9.2.2 - torrent
.R
.ihtml h3

Client written in Go. Works great. Supports magnet links.

Download it here:
.ihtml a <a href="https://github.com/anacrolix/torrent">
.CW https://github.com/anacrolix/torrent
.ihtml a

.html - <a name="8.5" />
.ihtml h2 <h2>
.SH
8.5 - Audio
.R
.ihtml h2

Pending integration of article at
.ihtml a <a href="http://nopenopenope.net/posts/audio">
.CW http://nopenopenope.net/posts/audio
.ihtml a

Thanks, qwx!

Meanwhile, read:
.ihtml a <a href="http://man.9front.org/1/audio">
.CW audio(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/3/audio">
.CW audio(3)
.ihtml a

Use:
.ihtml a <a href="http://man.9front.org/1/play">
.CW play(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/1/zuke">
.CW zuke(1)
.ihtml a

.html - <a name="8.6" />
.ihtml h2 <h2>
.SH
8.6 - External Media
.R
.ihtml h2

.html - <a name="8.6.1" />
.ihtml h3 <h3>
.SH
8.6.1 - Mount an ISO9660 CD-ROM
.R
.ihtml h3
.P1
mount <{9660srv -s >[0=1]} /n/iso /dev/sdD1/data # cd-rom drive
.P2

or:
.P1
mount <{9660srv -s} /n/iso /path/to/9front.iso
.P2

Read:
.ihtml a <a href="http://man.9front.org/4/dossrv">
.CW dossrv(4)
.ihtml a

.html - <a name="8.6.2" />
.ihtml h3 <h3>
.SH
8.6.2 - Burn a CD-ROM
.R
.ihtml h3
.P1
cdfs
cp 9front.iso /mnt/cd/wd
rm /mnt/cd/wd
.P2

Read:
.ihtml a <a href="http://man.9front.org/4/cdfs">
.CW cdfs(4)
.ihtml a

.html - <a name="8.6.3" />
.ihtml h3 <h3>
.SH
8.6.3 - Mount a FAT formatted USB device
.R
.ihtml h3

FAT formatted USB devices are automatically mounted under the
.CW /shr
directory.

.B Note:
Devices must be FAT or FAT32 formatted; exFAT is not supported.
.bp
.html - <a name="8.7" />
.ihtml h2 <h2>
.SH
8.7 - Emulation
.R
.ihtml h2

.html - <a name="8.7.1" />
.ihtml h3 <h3>
.SH
8.7.1 - Linux Emulation
.R
.ihtml h3
.html - <br />
.FG linuxburden jpg

.CW linuxemu
is a program that can execute Linux/i386 ELF binaries on Plan 9. Semi-modern web browsers and other Linux programs may be run using
.CW linuxemu
(if necessary, in conjunction with the
.CW equis
X11 server).
.html - <p>Download it here: <a href="http://plan9.stanleylieber.com/src/linuxemu3.tgz">linuxemu3.tgz</a><p>The equis X11 server is available from <a href="http://9front.org/extra/">9front.org/exra/</a>, or <a href="http://www.quanstro.net/magic/man2html/1/contrib">contrib(1)</a>).

.B Note:
.CW linuxemu
can only be run on a Plan 9 system booted with a
.CW 386
kernel and binaries.

BOOTSTRAP

To run
.CW linuxemu ,
you need a Linux root file system packed into a tarball:

.ihtml a <a href="http://felloff.net/usr/cinap_lenrek/mroot-linuxemu.tbz">
http://felloff.net/usr/cinap_lenrek/mroot-linuxemu.tbz
.ihtml a

.ihtml a <a href="http://plan9.stanleylieber.com/linuxemu/mroot.tgz">
http://plan9.stanleylieber.com/linuxemu/mroot.tgz
.ihtml a

The
.CW mroot-linuxemu.tbz
version contains no symlinks and can be extracted with plain Plan 9 tools
.CW bunzip
and
.CW tar .

The
.CW mroot.tgz
version contains the same Debian Sarge base as
.CW mroot-linuxemu.tbz ,
but with several additional packages pre-installed:

.ihtml ul <ul>
.IP
9base

dmenu-4.1.1

dwm-5.8.2

gcc 3.3.5

linux-kernel-headers

mercurial 0.9.4

opera 10.11

python 2.3.5

xlib-dev
.LP
.ihtml ul

and more.

You can create your own
.CW mroot
with
.CW debootstrap
on Debian Linux, or help write an installer that unpacks and installs an alternative distribution on Plan 9... In any case,
.CW linuxemu
is not hardwired to any Linux distribution!

RUNNING

Use the provided
.CW linux
script to chroot into your Linux
.CW mroot .
The
.CW linux
script is necessary because for Linux programs to run, shared
libraries from your
.CW mroot
have to appear in its
.CW /lib
and
.CW /usr/lib
directories, while configuration files are expected to be in
.CW /etc .
The script will build a private namespace and then bind the Linux
.CW mroot
over the Plan 9 root. The original Plan 9 namespace is mounted within
.CW linuxemu
under
.CW /9 .

Assuming
.CW mroot
is located in the current directory, start
.CW linuxemu
like this:
.P1
linux -r ./mroot /bin/bash -i
.P2

If the
.CW -r
option is omitted, the Linux
.CW mroot
defaults to
.CW /sys/lib/linux
on the Plan 9 machine.

In the Linux
.CW mroot ,
.CW /etc/resolv.conf
should be changed to match your network nameserver. In addition,
.CW /etc/apt/sources.list
should be updated to a working Debian mirror. Sarge packages can still be accessed at:

.CW
deb http://archive.debian.org/debian-archive/debian sarge main
.R

EXAMPLES

Linux X11 programs may be used in conjunction with the
.CW equis
X11 server. For example, to run the Opera web browser under your Linux
.CW mroot ,
start
.CW equis
in a
.CW rio
window, start
.CW linuxemu
in another
.CW rio
window and then from within
.CW linuxemu :
.P1
dwm & # X11 window manager
opera & # web browser
.P2

Opera should (eventually) appear in the
.CW equis
window. A window manager (this example uses dwm) is recommended so that X11 programs interact with window resources properly.

DEBUGGING

If
.CW linuxemu
crashes, use acid to figure out what's going on:
.P1
mk acid
acid -l linuxemu.acid <pid>
.P2
Then you can issue the following commands:
.P1
ustk()
.P2
dump a (userspace) stacktrace for the current thread:
.P1
umem(Current())		dump the memory mappings
ufds(Current())		dump the filedescriptor table
utrace(Current())	dump the internal tracebuffer
			(enabled by -d option)
.P2
Use
.CW xasm()
and
.CW xcasm()
for disassembly for Linux code.

Read:
.ihtml a <a href="http://man.9front.org/1/acid">
.CW acid(1)
.ihtml a

You can also enable full trace logging:
.P1
linux -r ./mroot -dd /bin/bash -i >[2]/tmp/linuxemu.log
.P2

This slows
.CW linuxemu
down considerably. In case of race conditions, it often happens that the bug disappears when doing full trace logging!

.html - <a name="8.7.2" />
.ihtml h3 <h3>
.SH
8.7.2 - Nintendo
.R
.ihtml h3
.html - <br />
.FG nintendo png

Emulators for several Nintendo video game consoles ship with the system:

.ihtml ul <ul>
.IP
.ihtml a <a href="http://git.9front.org/plan9front/plan9front/HEAD/sys/src/games/gb/f.html">
gb
.ihtml a
\(em Game Boy

.ihtml a <a href="http://git.9front.org/plan9front/plan9front/HEAD/sys/src/games/gba/f.html">
gba
.ihtml a
\(em Game Boy Advance

.ihtml a <a href="http://git.9front.org/plan9front/plan9front/HEAD/sys/src/games/nes/f.html">
nes
.ihtml a
\(em Nintendo Entertainment System

.ihtml a <a href="http://git.9front.org/plan9front/plan9front/HEAD/sys/src/games/snes/f.html">
snes
.ihtml a
\(em Super Nintendo Entertainment System
.LP
.ihtml ul

Read:
.ihtml a <a href="http://man.9front.org/1/nintendo">
.CW nintendo(1)
.ihtml a

.html - <a name="8.7.3" />
.ihtml h3 <h3>
.SH
8.7.3 - Sega
.R
.ihtml h3
.html - <br />
.FG sega png

An emulator for the Sega Megadrive/Genesis video game console ships with the system:

.ihtml ul <ul>
.IP
.ihtml a <a href="http://git.9front.org/plan9front/plan9front/HEAD/sys/src/games/md/f.html">
md
.ihtml a
\(em Sega Mega Drive/Genesis
.LP
.ihtml ul

Read:
.ihtml a <a href="http://man.9front.org/1/sega">
.CW sega(1)
.ihtml a

.html - <a name="8.7.4" />
.ihtml h3 <h3>
.SH
8.7.4 - Commodore
.R
.ihtml h3
.html - <br />
.FG c64 jpg

An emulator for the Commodore 64 home computer ships with the system:

.ihtml ul <ul>
.IP
.ihtml a <a href="http://git.9front.org/plan9front/plan9front/HEAD/sys/src/games/c64/f.html">
c64
.ihtml a
\(em Commodore 64
.LP
.ihtml ul

Read:
.ihtml a <a href="http://man.9front.org/1/commodore">
.CW commodore(1)
.ihtml a

.html - <a name="8.7.5" />
.ihtml h3 <h3>
.SH
8.7.5 - PC
.R
.ihtml h3
.html - <br />
.FG ibmpc jpg

An emulator for PC compatible computers ships with the system:

.ihtml ul <ul>
.IP
.ihtml a <a href="http://git.9front.org/plan9front/plan9front/HEAD/sys/src/cmd/vmx/f.html">
vmx
.ihtml a
\(em virtual PC
.LP
.ihtml ul

Read:
.ihtml a <a href="http://man.9front.org/1/vmx">
.CW vmx(1) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/3/vmx">
.CW vmx(3)
.ihtml a

.html - <a name="8.7.5.1" />
.ihtml h3 <h3>
.SH
8.7.5.1 - Virtualization Using vmx(1)
.R
.ihtml h3
.html - <br />
.FG vmxmulticat png

.ihtml a <a href="http://man.9front.org/1/vmx">
.CW vmx(1)
.ihtml a
simulates a virtual PC running a specified kernel file, by using
virtualization extensions found on recent intel processors.
Currently, only 9front and recent Linux and OpenBSD kernels are supported.

The virtual PC is configured on \f(CWvmx(1)\fR's command line, and the hardware
specified is seen as virtio devices.
It will use one of the host's CPU cores, and will run on the same
architecture as the host.

.B Note:
\f(CWvmx\fR executes the operating system's kernel directly, acting
as a bootloader.
It therefore needs explicit support for it unless the kernel is
in multiboot format.

.B Note:
\f(CWvmx\fR currently works on intel processors only, and requires a
number of virtualization features.
To check if your processor is supported, use
.ihtml a <a href="http://man.9front.org/8/cpuid">
.CW icanhasvmx(8) .
.ihtml a

Basic examples:

• Boot 386 kernel with 1 GB of RAM, a 9front iso as a disk, a network
  interface through ether0 and a 640x480 framebuffer:

.P1
vmx -M 1G -d 9front.iso -n ether0 -v 640x480 /386/9pc
.P2

• Instead of a framebuffer, use
.ihtml a <a href="http://man.9front.org/1/con">
.CW con(1)
.ihtml a
to connect to the console:

.P1
window -scroll \'bind \'\'#|\'\' /n/p; \e
	<>[3]/n/p/data1 {echo 3 >/srv/pipe; \e
	con -r /n/p/data}\'
vmx -c /srv/pipe -M 1G -d 9front.iso /386/9pc \'console=0\'
.P2

.html - <a name="8.7.5.1.1" />
.ihtml h3 <h3>
.SH
8.7.5.1.1 Block Devices
.R
.ihtml h3

It may be desirable to attach a disk to the virtual PC.
One may then specify a number of files to be used as raw disk images
with the \f(CW-d\fR flag.
The files may be virtually anything so long as
.CW vmx(1)
can overwrite them.

The common options here include plain files,
.ihtml a <a href="http://man.9front.org/3/sd">
.CW sd(3)
.ihtml a
disks, or ISO images.

The fastest way to generate a big plain file is to create a sparse file.
For example, to create a 4 GB sparse file with
.ihtml a <a href="http://man.9front.org/1/dd">
.CW dd(1) :
.ihtml a

.P1
dd </dev/zero -of dicks -bs 1 -count 1 \e
	-seek `{echo 4*1024*1024*1024-1 | pc -n}
.P2

Using a real disk might yield somewhat faster performance.
For example, using a USB:

.P1
vmx -d 9front.iso -d /dev/sdUxxxxx/data -v 640x480 /386/9pc
.P2

Use real disks with caution!
.CW vmx
may induce kernel panics in the guest, for instance through bugs or
quirks in the virtio devices' implementation.
Beware that the host crashing may also trash your disks -- for instance,
giving the guest too much memory, which is always allocated in full on start
up, will trigger an OOM on the host.

.html - <a name="8.7.5.1.2" />
.ihtml h3 <h3>
.SH
8.7.5.1.2 Ethernet
.R
.ihtml h3

If network connectivity is required, the \f(CW-n\fR parameter specifies an
interface to bridge as a virtio ethernet card. \f(CWvmx(1)\fR will then send and receive traffic on this interface like the host.
Wireless ethernet interfaces may also be used without any additional work.
The interface can also be a dial string or a plain file.
The emulated card's MAC address is random by default, and can be changed
using an optional \f(CWea:\fR prefix.

For example, to bridge an ethernet interface and use \f(CWDE:AD:BE:EF:CA:FE\fR for the virtio device's MAC:

.P1
vmx -d 9.img -n ea:deadbeefcafe!ether0 -v 640x480 /386/9pc
.P2

.html - <a name="8.7.5.1.2" />
.ihtml h3 <h3>
.SH
8.7.5.1.3 OpenBSD
.R
.ihtml h3

.ihtml a <a href="http://www.openbsd.org">
OpenBSD
.ihtml a
kernels may change radically between releases.
Only 6.1 and later have been tested.
Keep in mind that the versions of the kernel passed to \f(CWvmx(1)\fR and the system
provided on a disk must be in sync.

Besides the various kernel files and optional devices, little is needed to
coerce OpenBSD to work.

To use the OpenBSD installer, first find a \f(CWbsd.rd\fR kernel.
To then use an existing OpenBSD install, use a \f(CWbsd\fR kernel instead.
A networked install may be used if an ethernet interface is specified on
the command line: it will use OpenBSD's
.ihtml a <a href="https://man.openbsd.org/vio">
.CW vio(4)
.ihtml a
driver.
Otherwise, an \f(CWinstall??.fs\fR file may be used as a disk.

.B Note:
OpenBSD/386 does not support plain framebuffer graphics.
You would need to either use VESA, or configure a COM device and add
a \f(CWtty=\fR option to the command line.

For example, to install OpenBSD 6.2 to a disk file using an install image and VESA graphics:

.P1
vmx -d obsd.img -d install62.fs -v vesa:640x480 bsd.rd
.P2

Boot options are given as the kernel's command line.
The root device is specified with the \f(CWdevice=\fR option, and if unset, is
queried by OpenBSD's bootloader.

To use VESA with X11, one must specify the -v argument with a vesa: prefix,
one or more display modes, and set \f(CWmachdep.allowaperture=2\fR.

Example usage:

.P1
vmx -M 1G -c /srv/pipe -n ether0 -d /dev/sdUa2595/data \e
	-v vesa:640x480,800x600,1024x768 \e
	bsd \'tty=com0\' \'device=sd0a\' \'db_console=on\'
.P2

.FG openbsdvmweb png

.html - <a name="8.7.5.1.4" />
.ihtml h3 <h3>
.SH
8.7.5.1.4 Linux
.R
.ihtml h3

You will need both a kernel and an initrd which will be used as a module.
You must also specify the root disk on the kernel's command line.
The most convenient way to obtain a kernel is to extract it from the ISO; read 
.ihtml a <a href="http://man.9front.org/4/dossrv">
.CW 9660srv(4)
.ihtml a

An example with Alpine Linux:

.P1
vmx -M 1G -n ether0 -d alpine-standard-3.6.2-x86_64.iso \e
	-d alp.img -m initramfs-hardened -v vesa:800x600 \e
	vmlinuz-hardened
.P2

After installation:

.P1
vmx -M 1G -n ether0 -d alp.img \e
	-m initramfs-hardened -v vesa:800x600 \e
	vmlinuz-hardened \'root=/dev/vda1\'
.P2

Recent versions of Alpine Linux might require specifying the \f(CWrootfstype=\fR parameter.
Typically, its value will be \f(CWext4\fR.

.html - <a name="8.7.5.1.5" />
.ihtml h3 <h3>
.SH
8.7.5.1.5 Windows NT
.R
.ihtml h3

.FG vmxntpaint png

Classified.

.html - <a name="8.8" />
.ihtml h2 <h2>
.SH
8.8 - Additional Software
.R
.ihtml h2

.html - <a name="8.8.1" />
.ihtml h3 <h3>
.SH
8.8.1 - 9front sources server
.R
.ihtml h3

Additional 9front software is available from a 9P share that is accessible from any Plan 9 system:
.P1
9fs 9front
.P2

The following files and directories will then be available under
.CW /n/ :

.ihtml ul <ul>
.IP
.CW 9front/
\(em 9front source

.CW 9front.torrent
\(em torrent of current 9front ISO image

.CW extra/
\(em third party software source

.CW fqa/
\(em troff sources for 9front Frequently Questioned Answers

.CW hardware/
\(em known working hardware (sysinfo, firmware, manuals, etc.)

.CW iso/
\(em current 9front ISO image(s)
.LP
.ihtml ul

.html - <a name="8.8.2" />
.ihtml h3 <h3>
.SH
8.8.2 - 9front contrib
.R
.ihtml h3

Some 9front users maintain a contrib directory on an official 9front 9P share (similar to the
.ihtml a <a href="https://9p.io/wiki/plan9/Contrib_index/index.html">
contrib
.ihtml a
arrangement provided by Bell Labs [now deprecated]) that is accessible from any Plan 9 system:
.P1
9fs 9contrib
.P2

User directories will then be available under
.CW /n/contrib/.

These directories are also accessible via HTTP:
.ihtml a <a href="http://contrib.9front.org">
.CW http://contrib.9front.org
.ihtml a

.html - <a name="8.8.3" />
.ihtml h2 <h2>
.SH
8.8.3 - Other public 9p servers
.R
.ihtml h2

A list of active public 9p servers is maintained here:
.ihtml a <a href="http://www.9paste.net/qrstuv/9pindex">
http://www.9paste.net/qrstuv/9pindex
.ihtml a

.html - <a name="8.8.4" />
.ihtml h2 <h2>
.SH
8.8.4 - Advanced Namespace Tools for Plan 9
.R
.ihtml h2

ANTS is a collection of modifications and additional software which adds new namespace manipulation capabilities to Plan 9. It is free software based on 9front and uses the same licensing, MIT for original code, LPL for modifications of Bell Labs source.  Download it here:
.ihtml a <a href="http://9gridchan.info">
http://9gridchan.info
.ihtml a

.html - <a name="8.8.5" />
.ihtml h2 <h2>
.SH
8.8.5 - Even More Additional Software
.R
.ihtml h2
.P1
> Anyways how about a list of software.

http://shithub.us/git/repos.html
https://github.com/henesy/awesome-plan9
https://sr.ht/projects?search=%23plan9
https://github.com/Plan9-Archive
https://github.com/topics/plan9
.P2

.html - <a name="8.8.6" />
.ihtml h2 <h2>
.SH
8.8.6 - Community Maintained Link For Additional Software
.R
.ihtml h2

.ihtml a <a href="http://wiki.9front.org/extra">
http://wiki.9front.org/extra
.ihtml a

.html - <a name="8.9" />
.ihtml h2 <h2>
.SH
8.9 - Bootstrapping architectures not included on the ISO
.R
.ihtml h2

.html - <a name="8.9.1" />
.ihtml h3 <h3>
.SH
8.9.1 - amd64
.R
.ihtml h3

To setup the
.CW amd64
port, install the
.CW 386
port from the ISO, then cross compile and install the
.CW amd64
binaries and kernel.  Or, simply install from the amd64 ISO.

Read:
.ihtml a <a href="fqa5.html#5.2.2.1">
.I
FQA 5.2.2.1 - Cross compiling,
.R
.ihtml a
.ihtml a <a href="fqa7.html#7.2.5">
.I
FQA 7.2.5 - How do I install a new kernel?
.R
.ihtml a

.html - <a name="8.9.2" />
.ihtml h3 <h3>
.SH
8.9.2 - Raspberry Pi
.R
.ihtml h3

The most convenient way to use an rpi is to cross compile and install the
.CW arm
binaries and the
.CW bcm
kernel on the network file server, and then tcp boot the rpi.

Read:
.ihtml a <a href="fqa5.html#5.2.2.1">
.I
FQA 5.2.2.1 - Cross compiling,
.R
.ihtml a
.ihtml a <a href="fqa6.html#6.7.1">
.I
FQA 6.7.1 - How do I tcp boot?
.R
.ihtml a

Updated instructions for installing directly onto the rpi's sd card are detailed in
.ihtml a <a href="appendixj.html">
.I
Appendix J - Junk
.R
.ihtml a

.html - <a name="8.9.3" />
.ihtml h3 <h3>
.SH
8.9.3 - arm64
.R
.ihtml h3
.P1
# create directory for arm64 files
mount -c /srv/boot /root
mkdir /root/arm64
cd /
. /sys/lib/rootstub

# build arm64 compilers
for(i in /sys/src/cmd/7[acl]){cd $i && mk install}

# build remaining arm64 binaries
cd /sys/src
objtype=arm64
mk install
.P2

Read:
.ihtml a <a href="fqa5.html#5.2.2.1">
.I
FQA 5.2.2.1 - Cross compiling,
.R
.ihtml a
.ihtml a <a href="fqa7.html#7.2.5">
.I
FQA 7.2.5 - How do I install a new kernel?
.R
.ihtml a

.html - <a name="8.10" />
.ihtml h2 <h2>
.SH
8.10 - ACPI
.R
.ihtml h2
.html - <br />
.FG acpi gif

Plan9front currently has partial ACPI support for PCI interrupt routing and system shutdown.

.html - <a name="8.10.1" />
.ihtml h3 <h3>
.SH
8.10.1 - Enabling ACPI
.R
.ihtml h3

ACPI is now enabled by default.
For machines without ACPI, disable it with the presence of
.CW *acpi=0
boot parameter.

The command
.CW aux/acpi
presents at mountpoint (default
.CW /mnt/acpi)
an interface to the ACPI. If a service is specified, the interface will be posted at
.CW /srv/service
as well.

Read:
.ihtml a <a href="http://man.9front.org/8/acpi">
.CW acpi(8)
.ihtml a

.html - <a name="8.12" />
.ihtml h2 <h2>
.SH
8.12 - Revision Control
.R
.ihtml h2

.html - <a name="8.12.1" />
.ihtml h3 <h3>
.SH
8.12.1 - cvs
.R
.ihtml h3

OpenCVS was ported to Plan 9.

Download it here:
.ihtml a <a href="http://plan9.stanleylieber.com/src/cvs.tgz">
http://plan9.stanleylieber.com/src/cvs.tgz
.ihtml a

An implementation of a
.CW cvs
(client) file server, called
.CW cvsfs ,
was also created for Plan 9.

Download it here:
.ihtml a <a href="http://plan9.stanleylieber.com/src/cvsfs.tgz">
http://plan9.stanleylieber.com/src/cvsfs.tgz
.ihtml a

.html - <a name="8.12.2" />
.ihtml h3 <h3>
.SH
8.12.2 - git
.R
.ihtml h3

There is a native
.CW git
implementation available for Plan 9 called
.CW git9 .
It has been added to the 9front distribution, but
upstream is still located here:
.ihtml a <a href="http://shithub.us/ori/git9/HEAD/info.html">
http://shithub.us/ori/git9/HEAD/info.html
.ihtml a

A guide for
.CW git9
has been posted here:
.ihtml a <a href="http://wiki.9front.org/git9">
http://wiki.9front.org/git9
.ihtml a

Previously someone else wrote a shell script wrapper that attempts to replicate some basic
.CW git
actions by downloading a zip file from the repository and performing operations on it.  Download it here:
.ihtml a <a href="http://plan9.stanleylieber.com/rc/git">
http://plan9.stanleylieber.com/rc/git
.ihtml a

.html - <a name="8.12.3" />
.ihtml h3 <h3>
.SH
8.12.3 - Mercurial
.R
.ihtml h3

9front used to ship with
.ihtml a <a href="https://www.mercurial-scm.org">
Mercurial.
.ihtml a
Before being replaced with
.ihtml a <a href="http://man.9front.org/1/git">
.CW
git(1)
.R
.ihtml
and redacted from the distribution, the source for both Python and Mercurial were archived here:
.ihtml a <a href="http://git.9front.org/plan9front/pyhg/HEAD/info.html">
http://git.9front.org/plan9front/pyhg/HEAD/info.html
.ihtml a

Read:
.ihtml a <a href="http://fqa.9front.org/fqa5.html#5.2.1.1">
.I
FQA 5.2.1.1 - hgrc
.R
.ihtml a

See also:
.ihtml a <a href="http://man.9front.org/4/hgfs">
.CW hgfs(4)
.ihtml a

.html - <a name="8.12.4" />
.ihtml h3 <h3>
.SH
8.12.4 - svn
.R
.ihtml h3

No.

.html - <a name="8.13" />
.ihtml h2 <h2>
.SH
8.13 - Video
.R
.ihtml h2

.html - <a name="8.13.1" />
.ihtml h3 <h3>
.SH
8.13.1 - treason
.R
.ihtml h3

A video player for 9front. It can play H.264, AV1, VP8 and VP9-encoded MP4/MKV video files. Only 8-bit per component YUV 4:2:0 is supported atm.

Download it here:
.ihtml a <a href="https://sr.ht/~ft/treason/">
https://sr.ht/~ft/treason/
.ihtml a

.html - <hr />
.html - <a href="fqa.html">FQA INDEX</a> |
.html - <a href="fqa7.html">FQA 7 - System Management</a> |
.html - <a href="fqa9.html">FQA 9 - Troubleshooting</a>