Plan 9 on SDF VPS

Glenda
Figure 1. Glenda.

This is a tutorial for setting-up the Plan 9 from Bell Labs operating system in a VPS slice on SDF. The tutorial was aimed at participants in the SDF Plan 9 Boot Camp, but should also be useful to other SDF VPS users.

Contents

  1. Getting Involved
  2. Install and Start Plan 9 Server
  3. Plan 9 Server Configuration
  4. Drawterm Client
  5. Demo rio session
  6. Making Your Server Configuration Permanent
  7. Adding a User
  8. Configure Time Zone
  9. File Import and Export
  10. FTP Server Access
  11. Browsing the Web
  12. Plan 9 Boot Camp
  13. Links

0. Getting Involved

Plan 9 has active communities which mostly interact by email.

SDF hosts the plan9-l mailing list for participants in the Plan 9 Boot Camp. Email 'majordomo' and 'subscribe plan9-l' to join

1. Install and Start Plan 9 Server

  1. VPS registration

    After you VPS application (as either a Boot Camp participant or regular VPS user) has been processed, you will be sent an e-mail that indicates the host name of your VPS maintenance server (for example, vps9.sdf.org).

  2. VPS Maintenance Shell log-in

    From your SDF shell, use the command ssh vps9.sdf.org (or the VPS maintenance host indicated in your e-mail) to connect to your VPS Maintenance Shell.

    VPS Maintenance Shell
    Figure 2. The VPS Maintenance Shell menu.

    Make a note of your virtual machine's IP address, which is displayed in the header of the VPS Maintenance Shell menu (circled in red in Figure 2.).

    (Note: After each maintenance shell command has been executed, the system will prompt you with (continue). Press the Enter key and the menu will be redisplayed.)

  3. Install the Plan 9 image

    At the menu Command: prompt enter: x (Clean install).

    When prompted Do you wish to continue? (yes/no), enter yes. The install process will take about ninety seconds.

    Plan 9 clean install
    Figure 3. Output from Plan 9 clean install.

    Press Enter to return to the maintenance shell menu.

  4. Start Plan 9

    At the menu prompt enter: r (reset or start).

    At the root is from …: prompt, press Enter.

    At the user[none]: prompt, enter glenda, the built-in user.

    Plan 9 restart
    Figure 4. Output from Plan 9 start.

    You are at the Plan 9 console rc shell (the % prompt).

    At this point, your Plan 9 server is up and running. At any time, you can return to the VPS Maintenance Shell by typing Ctrl-], leave the maintenance shell by typing q (Disconnect) at the Command: prompt, and your server will continue to run until you issue a shutdown command (At the VPS Maintenance Shell enter s, or in rc enter fshalt).

    To return to the console rc shell, log-in to the VPS Maintenance Shell again, type c (Connect to your console) at the Command: prompt, then press Enter for a % prompt.

2. Plan 9 Server Configuration

In this step you will configure your Plan 9 server for networking and to allow connections from Drawterm, the graphical Plan 9 client that you will run on your PC.

You will configure your server by entering commands at the console rc shell. Rc shares many commands in common with the Unix Bourne shell on which it is based. For a guide to basic rc commands, see Plan 9 Rc Survival Guide. (The functionality of the console version of rc is limited compared to the full version which requires the rio graphical user environment, which will be provided by Drawterm.)

If you have shutdown your Plan 9 server, restart it as in step 1.d. Start Plan 9 above and log-in as user glenda.

  1. Configure your IP address
    
    % ip/ipconfig -g 205.166.94.1 ether /net/ether0 your-IP 255.255.255.0
    	
    (1)

    Replace your-IP with the IP address you recorded from the header of the VPS Maintenance Shell in step 1.b. VPS Maintenance Shell log-in.

  2. DNS resolution
    
    % echo 'ip=your-IP sys=plan9 dom=plan9 dns=205.166.94.20' >> /lib/ndb/local
    % ndb/cs
    % ndb/dns -r
    	
    (2)
    (3)
    (4)
  3. Set Drawterm user password
    
    % echo 'key proto=p9sk1 dom=plan9 user=glenda !password=password' >/mnt/factotum/ctl
    	
    (5)

    Replace password with the password you want to use when user glenda connects to your Plan 9 server using Drawterm.

  4. Listen for Drawterm connections
    
    % aux/listen1 -t tcp!*!ncpu /bin/cpu -R &
    	
    (6)

Basic configuration of your Plan 9 server is now complete. You may exit the Plan 9 console (Ctrl-]) and the VPS Maintenance Shell (q) and your server will continue running.

If you restart your server (use rc command fshalt, then the VPS Maintenance Shell command r), you will have to reenter (1), (3), (4), (5), and (6) above. To make your server configuration persistent over restarts, see section 5. Making Your Server Configuration Permanent.

3. Drawterm Client

Drawterm is a graphics terminal emulator that you run on your client PC. Drawterm implements the rio Plan 9 windowing system and connects to your Plan 9 server.

  1. Install Drawterm on your PC

    Download and install Drawterm on your PC. Drawterm is available as a package for many Linux-based distributions — check your package manager. Source code and precompiled binaries for several operating systems are available from https://swtch.com/drawterm/. Building instructions for NetBSD are here.

  2. Run Drawterm

    Start Drawterm on your client PC with the following command line arguments:

    
    $ drawterm -a your-IP -c your-IP -u glenda
    	
    (7)

    Replace your-IP with the IP address you recorded from the header of the VPS Maintenance Shell in step 1.b. VPS Maintenance Shell log-in.

    Drawterm will display the Plan 9 log-in screen.

    Plan 9 log-in
    Figure 5. Plan 9 log-in in Drawterm.
  3. Login to your Plan 9 server

    Type the password you set for user glenda in (5) then press Enter. (No cursor will be displayed and the entered password will not be echoed on the log-in screen.)

    If your log-in is successful, Drawterm will connect to your Plan 9 server and start the rio window manager with an empty desktop.

    rio desktop
    Figure 6. Empty rio desktop.
  4. Open a terminal window

    Right-click and hold anywhere on the rio desktop to open the pop-up menu ("New/Resize/Move/Delete/Hide"). Continue holding down the right mouse button, move the pointer over New, then release the mouse button.

    When the mouse pointer changes to a "+" cursor, right-click and hold on the desired position for the terminal window's upper-left corner, drag the mouse to the desired position for the window's lower-right corner (a red frame will appear to indicated the new window's border), then release the mouse button.

    rio will create a terminal window and run rc.

    Terminal window
    Figure 7. Terminal window.

4. Demo rio session

The built-in glenda user account includes a script, riostart, that creates a demonstration rio session by starting several common Plan 9 programs:

stats
display graphs of system activity
faces
mailbox interface
acme
editor / interactive text windows; acme will open the file readme.acme, a tutorial explaining basic acme usage.
rc
command terminal; the contents of the file readme.rio, a tutorial on rio and rc will be printed in the terminal window.

To run riostart, enter the following command in a terminal window:


% cd $home; riostart
    
(8)
Demo rio session
Figure 8. Demo rio session.

To bring a partially hidden window to the foreground, left-click anywhere in the window.

5. Making Your Server Configuration Permanent

As mentioned in section 2. Plan 9 Server Configuration, most of the configuration performed (1), (3), (4), (5), and (6) in that section will be lost if you restart your Plan 9 server.

To make the server configuration persistent over restarts, you have to add the configuration commands to the file /rc/bin/termrc.local. This can be accomplished by entering the following rc commands at either the Plan 9 console of your VPS Maintenance Shell, or a rio terminal window.

(Enter the commands while logged-in as user glenda.)


% echo 'ip/ipconfig -g 205.166.94.1 ether /net/ether0 your-IP 255.255.255.0' >> /rc/bin/termrc.local
% echo 'ndb/cs' >> /rc/bin/termrc.local
% echo 'ndb/dns -r' >> /rc/bin/termrc.local
% echo 'echo ''key proto=p9sk1 dom=plan9 user=glenda !password=password'' >/mnt/factotum/ctl' >> /rc/bin/termrc.local
% echo 'aux/listen1 -t tcp!*!ncpu /bin/cpu -R &' >> /rc/bin/termrc.local
    
(9)
(10)
(11)
(12)
(13)

Alternatively, you may add the commands (1), (3), (4), (5), and (6) to /rc/bin/termrc.local with a text editor — either acme, the graphical editor, if you are running rio in Drawterm, or ed, the line-oriented text editor, in either rio or the Plan 9 server console.

6. Adding a User

After you have familiarized yourself with Plan 9 using the built-in user glenda, you may wish to add a user to your system (this is optional).

Enter the following commands in a rio terminal window or the Plan 9 server console:

  1. Connect to file server console
    
    % con -l /srv/fscons
    	
    (14)
  2. Create new user and add to sys group
    
    prompt: uname user user
    prompt: uname sys +user
    	
    (15)
    (16)

    Replace user with the desired name for the new user.

  3. Exit file server console

    Type Ctrl-\, then at the >>> prompt enter q.

  4. Set Drawterm password for new user

    Set the Drawterm password for the new user using command (5), substituting the new user name for "glenda" and the desired password for password.

  5. Log-in as new user

    Restart Drawterm using command (7), substituting the new user name for "glenda". Enter the new user's password at the Plan 9 log-in screen.

  6. Initialize new user environment

    Open a terminal window and enter the following command:

    
    % /sys/lib/newuser
    	
    (17)

7. Configure Time Zone

Set your Plan 9 server's time zone to your local time zone.

  1. Shutdown your server with the command fshalt (rio terminal window or server console).
  2. From the VPS Maintenance Shell, restart your server (r command).
  3. Log-in as user adm.
  4. On the server console, enter the command cd /adm/timezone.
  5. List the time zone files with the command lc.
  6. Pick the file that corresponds to your local time zone and copy it to file local with the command cp your-zone local
  7. Use ed to edit the file /rc/bin/termrc and set the environment variable TIMESYNCARGS to (-n pool.ntp.org).
  8. Shutdown your server with the command fshalt and restart.

8. File Import and Export

Drawterm automatically mounts your client PC's file system at /mnt/term in your Plan 9 namespace. This can be used to copy files from your PC into Plan 9, or from Plan 9 to your client PC using normal file copy commands (cp in rc).

9. FTP Server Access

You can also transfer files between your Plan 9 server and your SDF shell account via the SDF FTP server.

From your Plan 9 terminal window, enter the command:


% ftpfs -a ftp@sdf.org sdf.org
    
(18)

In your Plan 9 namespace, Plan 9-related files on the FTP server are in the directory /n/ftp/pub/sdf/plan9/. From your SDF cluster shell account that directory is accessible at /ftp/pub/sdf/plan9/.

Contents of note (paths are relative to Plan 9 root directory above):

contrib
SDF user contributions. Create a subdirectory with your SDF user name for your own contributions.
dist/9*.tar.gz
Plan 9 distribution files.
dist/9front/
9front distribution files.
plan9bunnysmblack.jpg
Plan 9 mascot Glenda image.

10. Browsing the Web

You can use Abaco to browse the web. (Abaco is available in a default Plan 9 system.)

  1. Create webcookies file (first time only)
    
    % touch $home/lib/webcookies
    	
    (19)
  2. Start webfs and abaco
    
    % webfs; abaco
    	
    (20)
abaco
Figure 9. Abaco Web browser.

When abaco starts, you can go to a webpage by clicking "New" with the middle button of the mouse, typing the address in the row below the one with "Del Snarf Get …" (see the previous figure: it's the one where the current address is), and pressing "Enter" on your keyboard. You can follow links by clicking on them, as is usual, with the left button (the shape of the cursor won't change, though).

The version of webfs in the VPS Plan 9 image does not support HTTPS Web pages.

11. Plan 9 Boot Camp

SDF periodically runs a Plan 9 Boot Camp which is open to anyone with an SDF user account. This Plan 9 Boot Camps are announced on the bboard and are typically a seasonal quarterly occurrence and run for 3 months.

In 2009 SDF moved to running 9xen-pae thanks to work done at Sandia/Los Alamos. Since then 9front has made significant improvements and SDF moved to using 9front pc64 exclusively in 2020.

Activities of the SDF Plan 9 Boot Camp include:

  1. Installation or pre-generated Plan 9 instance under Xen
  2. Self Guided Discoveries in: ed, network configuration
  3. Self Guided Discoveries in: drawterm (from your computer), rio and stats
  4. Self Guided Discoveries in: acme, sam, abaco, mothra and man
  5. Self Guided Discoveries in: mapdemo, catclock, juggle and tetris
  6. Self Guided Discoveries in: 9front and contrib via ftpfs
  7. Self Guided Discoveries in: 9fans mailing list and faces

[Details on each of the above mini-projects should be expanded into its own section, or separate tutorial. Some of the mini-projects overlap with content earlier in this tutorial.]

During the SDF Plan 9 Boot Camp you are encouraged to make screenshots and videos of your Self Guided Discoveries and share your experiences on plan9-l to inspire others to do the same.

Tutorials

Utilities

Videos

Books


$Id: VPS_Plan9.html,v 1.52 2023/08/04 07:38:50 hc9 Exp $