.\" 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 fqa7.ms | page .\" htmlroff -u -ms -mhtml fqa7.ms >fqa7.html .de FG \" .FG .ie h .html - .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 7 - System Management .html - .html - FQA INDEX | .html - FQA 6 - Networking | .html - FQA 8 - Using 9front .html -
.SH .LG .ihtml h1

FQA 7 - System Management .ihtml h1 .NL .R .html - html | .html - pdf | .html - troff .FG orgchart jpg .html - .ihtml h2

.SH 7.1 - Plan 9 Services Overview .R .ihtml h2 .html -
.FG plan9network png In order to be an effective system manager it is a good idea to understand how the system is designed, and how it is intended to be used. A Plan 9 installation consists of a disk file server, an authentication server, and one or more cpu servers and terminals\(emall sharing the same disk file system. That said, Plan 9 services may be run on separate machines, all together on one machine, or in various combinations. The original design of Plan 9 assumed that each network service would run on separate hardware; by design, individual components of the system are generally unaware if they co-exist on the same machine or are distributed amongst separate machines. This document will describe individual services as if they are all running separately. Read: .ihtml a .I Designing Plan 9, .R .ihtml a .ihtml a .I Plan 9 From Bell Labs, .R .ihtml a .ihtml a .I The Organization of Networks in Plan 9 .R .ihtml a .html - .ihtml h3

.SH 7.1.1 - What is the kernel? .R .ihtml h3 The kernel is a service that provides processes and resources to users active on an individual machine. Every Plan 9 machine boots a kernel. At boot time the kernel takes on the identity of .CW $user (the user who logs in at the console), which becomes the .CW hostowner of the system. The .CW hostowner in turn 1.) controls access to the kernel's resources, 2.) serves as the auth identity (\f(CWauthid\fR) of the machine and the services it provides. .B Note: The .CW hostowner differs from the concept of .CW root on a UNIX system, where a single user .CW root may take control of all processes .I and files on the system. By contrast, even the .CW hostowner of a Plan 9 file server cannot violate file permissions on the file server, except when permissions checking is disabled on the console or when entering special commands at the console of the file server. The .CW hostowner controls only the .I processes running on the local machine. This fundamental separation between control of processes and file permissions is exploited throughout the Plan 9 system, but can be confusing for users coming from a UNIX background. .html - .ihtml h3

.SH 7.1.2 - What is the file server? .R .ihtml h3 In a traditional Plan 9 network there is one disk file server, typically the only machine with a physical hard disk, that serves files to all other machines on the network. In most cases, other machines are either diskless or only use their disks for local caching. Ken Thompson's original Plan 9 file server ran a unique, special-purpose kernel that .I only served files, and whose configuration could only be changed at the console. In 9front, the file server runs a normal kernel and typically also runs as a cpu server (for remote access). 9front supports two different disk file systems for use on the file server: .CW cwfs and .CW hjfs . .CW cwfs is a userspace port of Ken Thompson's original Plan 9 file server. .CW hjfs is a new, experimental file server that stores both the cache and worm on a single partition (and thus requires less disk space to be used effectively). Both are reasonably robust. Read: .ihtml a .I The Plan 9 File Server .R .ihtml a (deprecated, but partially applies to \f(CWcwfs\fR), .ihtml a .CW cwfs(4) , .ihtml a .ihtml a .CW hjfs(4) .ihtml a .B Note: Since most Plan 9 systems have no disk, security of the file server is largely protected from breaches of security in its clients. The fewer the programs that run on the file server, the more isolated it can be from security holes in programs. .B Note: Users seeking access to the file server must be added as a user on the file system itself, and, if auth is enabled, added to the auth server's user database. .B Note: Some users choose to run remote cpu or auth servers as stand-alone systems, each with their own local disk file systems. The distinction between all these types of systems is fuzzy and can become even fuzzier as services are enabled and disabled in different combinations. .html - .ihtml h3

.SH 7.1.3 - What is the auth server? .R .ihtml h3 The auth server manages authentication for an entire Plan 9 network. It boots a normal kernel but is usually run on a separate, diskless machine that performs no other functions, in order to reduce the danger of a security breach compromising its kernel processes. That said, the auth server is usually also configured as a cpu server, for remote access. .B Note: The .ihtml a .CW cron(8) .ihtml a service should be run only on the auth server, where it can authenticate itself to access any of the other machines on the network. Read: .ihtml a .I Security in Plan 9, .R .ihtml a .ihtml a .I FQA 7.4 - Auth server configuration and maintenance, .R .ihtml a .ihtml a .CW auth(8) .ihtml a .html - .ihtml h3

.SH 7.1.4 - What is the cpu server? .R .ihtml h3 The cpu server is used for remote computation. A cpu server's kernel runs processes in isolation, on only that machine. The boot process of a cpu server (defined as such by setting .CW service=cpu in the machine's .CW plan9.ini or equivalent) may be examined by reading the .CW /rc/bin/cpurc script, which is executed at boot time. Running as a cpu server causes the kernel to adjust certain resource values that ultimately determine the behavior of the machine. For example, the .CW cpurc script starts certain programs only if the machine is recognized as a cpu server. Common use cases for a separate cpu server are: To execute programs compiled for a different architecture than that of the terminal; To execute programs closer to the data they are operating upon (for example, if the terminal is running over a slow link but the cpu server is on the same ethernet segment as the file server); To execute processes in physical isolation from other processes. In the early days of Plan 9, a cpu server was often significantly more powerful than the (often, special-purpose) hardware used for diskless terminals. Today, terminals are typically powerful computers in their own right, and the need for a separate machine running only as a cpu server is less common. That said, it can be useful to execute unstable or unpredictable programs on a separate machine so that frequently crashing and/or rebooting does not affect one's immediate workspace environment\(emespecially when testing new code. In the case of remote (mail, web, etc.) servers, it is also likely that cpu access would be desired. In practice, the disk file server, the auth server, and even some terminals will often run their own cpu listeners, to enable remote access to the processes controlled by their kernels. .B Note: Users seeking access to a cpu server must first be added on the file system of the cpu server's corresponding file server (for permission to access and modify files) as well as the user database of its designated auth server (for login authentication). Read: .ihtml a .I The Organization of Networks in Plan 9, .R .ihtml a .ihtml a .CW rcpu(1) .ihtml a .html - .ihtml h3

.SH 7.1.5 - What is a terminal? .R .ihtml h3 The terminal is the machine at which the Plan 9 user is most often physically located. Usually diskless, the terminal will almost always run with graphics enabled (for launching the .CW rio GUI or other graphical programs). The boot process of a terminal (defined as such by setting .CW service=terminal in the machine's .CW plan9.ini or equivalent) may be examined by reading the .CW /rc/bin/termrc script, which is executed at boot time. .B Note: Many Plan 9 users run stand-alone systems that operate\(emeffectively\(emas a combined terminal and file server. For example, inside a virtual machine such as qemu, or booted from hard disk on a laptop. In this case the Plan 9 network is entirely self-contained, running one kernel on one machine, which renders auth and cpu services superfluous. This configuration trades some of the inherent security of separate hardware and kernel boundaries for the convenience of combining the whole system into a single, bootable instance. .B Note: Terminal users who do not run stand-alone machines or who wish to access Plan 9 network resources must first be added to the file system of the network's file server, and to the user database of the network's auth server. .html - .ihtml h2

.SH 7.2 - Kernel configuration and maintenance .R .ihtml h2 .html - .ihtml h3

.SH 7.2.1 - How do I mount the 9fat partition? .R .ihtml h3 9front has done away with the scripts .CW 9fat: , .CW c: , and so forth, that are found in the .ihtml a Bell Labs Plan 9 .ihtml a distribution. Instead, use the .CW 9fs script to mount the 9fat partition: .P1 9fs 9fat .P2 If you are not at the console, or if .CW #S has not already been bound over .CW /dev : .P1 bind -b \'#S\' /dev # bind the local hard drive kernel device over /dev 9fs 9fat /dev/sdXX/9fat # specify the full path to the corresponding 9fat .P2 .B Note: .CW 9fs 9fat .R posts a file descriptor in .CW /srv/dos . If this file already exists and is already in use, .CW 9fs 9fat .R will fail. If no other process is using the file it is safe to simply remove it and run .CW 9fs 9fat .R again. Read: .ihtml a .CW dossrv(4) .ihtml a .html - .ihtml h3

.SH 7.2.2 - How do I modify plan9.ini? .R .ihtml h3 Mount the .CW 9fat partition and then edit the file .CW /n/9fat/plan9.ini . .B Note: The file must end with a newline. Read: .ihtml a .CW plan9.ini(8) .ihtml a .html - .ihtml h3

.SH 7.2.3 - Kernel configuration file .R .ihtml h3 Kernel configuration files are stored in the kernel directory and share the name of the kernel to which they apply. For example, the configuration file for the .CW pc kernel is .CW /sys/src/9/pc/pc . .html - .ihtml h3

.SH 7.2.4 - Kernel drivers .R .ihtml h3 Kernel driver source files are located in the kernel source directory. For example, the .CW pc kernel source is located in .CW /sys/src/9/pc . .html - .ihtml h3

.SH 7.2.5 - How do I install a new kernel? .R .ihtml h3 To build and install the new kernel(s) on the file system: For 386: .P1 cd /sys/src/9/pc mk install # kernel is copied to /386/9pc .P2 For amd64: .P1 cd /sys/src/9/pc64 mk install # kernel is copied to /amd64/9pc64 .P2 For arm / bcm (Raspberry Pi, etc.): .P1 cd /sys/src/9/bcm mk install # kernel is copied to /arm/9pi2 .P2 For arm64 / bcm64 (Raspberry Pi 3): .P1 cd /sys/src/9/bcm64 mk install # kernel is copied to /arm64/9pi3 .P2 For 386 and amd64 machines with local disk, it may be desired to install the new bootloader and kernels onto the .CW 9fat partition, in order to boot directly from disk. .B Note: The bootloader needs to be continuous on disk, so simply copying over the original file does not produce the desired effect. Instead: .P1 9fs 9fat rm /n/9fat/9bootfat cp /386/9bootfat /n/9fat/ chmod +al /n/9fat/9bootfat # defrag magic .P2 then copy the desired kernels: For 386: .P1 cp /386/9pc /n/9fat/ .P2 For amd64: .P1 cp /amd64/9pc64 /n/9fat/ .P2 Finally, if a different kernel is being installed than the one currently running, edit .CW plan9.ini and change .CW bootfile to point to the new kernel. Read: .ihtml a .I FQA 7.2.2 - How do I modify plan9.ini? .R .ihtml a .html - .ihtml h2

.SH 7.3 - Fileserver configuration and maintenance .R .ihtml h2 .html - .ihtml h3

.SH 7.3.1 - Adding users .R .ihtml h3 Add a new user on the file server: For .CW cwfs : .P1 echo newuser username >>/srv/cwfs.cmd .P2 For .CW hjfs : .P1 echo newuser username >>/srv/hjfs.cmd .P2 If needed, make the new user a member of another group (example: upas): For .CW cwfs : .P1 echo newuser upas +username >>/srv/cwfs.cmd .P2 For .CW hjfs : .P1 echo newuser upas +username >>/srv/hjfs.cmd .P2 Both file servers store their user database in .CW /adm/users . Examine this file, and the contents of the .CW /usr directory, to evaluate success. .B Note: It is also possible to access the control file interactively: For .CW cwfs : .P1 con -C /srv/cwfs.cmd .P2 For .CW hjfs : .P1 con -C /srv/hjfs.cmd .P2 From here commands may be entered directly. Type .CW Ctrl-\e .R to resume the .CW con prompt, followed by .CW q to quit. .B Note: New users are created without a profile, mail directory, tmp directory (needed to edit files with .CW sam ) or other confections. To install a default profile for a new user, upon first login as that user, run: .P1 \&/sys/lib/newuser .P2 then edit .CW /usr/username/lib/profile to your own specifications. The .CW newuser file system command is described in the man pages .ihtml a .CW fs(8) .ihtml a (for \f(CWcwfs\fR) and .ihtml a .CW hjfs(8) . .ihtml a The default system .CW /lib/namespace does the following: .P1 bind -c /n/other/usr/$user/tmp /usr/$user/tmp .P2 For .CW cwfs users, it may be desirable to store the user's .CW tmp directory on the .CW other partition: .P1 mkdir /n/other/usr/$user/tmp .P2 .html - .ihtml h3

.SH 7.3.2 - Configuring nvram .R .ihtml h3 The cpu kernel checks the .CW nvram file for valid auth credentials and attempts to copy them into .CW factotum so that the machine may boot without manual intervention. To configure the .CW nvram , run the command .CW auth/wrkey , which will prompt for an .CW authid , .CW authdom , .CW secstore key, .R and .CW password . .CW password (twice) The .CW authid is a synonym for the .CW hostowner of the machine and should be a valid user that has already been (or will be) added to the corresponding auth server, in this case .CW glenda . The .CW authdom is the authentication domain for the machine, in this case .CW 9front . The .CW secstore key .R and .CW password are secret passwords of eight characters or more in length. The .CW password is the password belonging to the .CW authid user on the auth server responsible for the .CW authdom entered above. The .CW secstore key .R is the password of the user on the secure-store server (Read: .ihtml a .I FQA 7.4.3 - secstored). .R .ihtml a If the .CW secstore client (Read: .ihtml a .I FQA 8.4.7 - secstore) .R .ihtml a is not being used on this machine (for example, if this is the auth server where .CW secstored will run), just hit .CW enter at the .CW secstore key: .R prompt. Run the command .CW auth/wrkey : .P1 bad nvram key bad authentication id bad authentication domain # You may not see these errors. authid: glenda authdom: 9front secstore key: [glenda's secstore password] password: [glenda's password] confirm password: [glenda's password again] .P2 To ensure that the correct nvram partition is found in all cases, an .CW nvram line should be added to .CW /n/9fat/plan9.ini . .P1 nvram=#S/YOURDRIVE/nvram .P2 .B Note: Booting the file system with authentication enabled and an invalid .CW nvram file will cause .CW auth/wrkey to be run automatically at startup. Read: .ihtml a .CW auth(8) .ihtml a .html - .ihtml h3

.SH 7.3.3 - Setting up a listener for network connections .R .ihtml h3 In order for remote machines to mount the file system of the file server, the file server must first be running a network listener. This section details the steps required to transform a terminal with disk (the result of a default install of 9front) into a disk file server for other machines. The first step is to switch from the terminal service to the cpu service by editing the .CW service line in .CW /n/9fat/plan9.ini : .P1 service=cpu .P2 Read: .ihtml a .I FQA 7.2.2 - How do I modify plan9.ini? .R .ihtml a Before rebooting, configure the nvram: .ihtml a .I FQA 7.3.2 - Configuring nvram. .R .ihtml a This allows the machine to load auth credentials from the .CW nvram file into .CW factotum , so that it can continue to boot without manual intervention. Reboot: .P1 fshalt -r .P2 .FG authbikestick jpg .B ACHTUNG! The next step (on cwfs; not needed on hjfs) is to enable authentication on the file server, to \fIprevent unauthorized users from accessing the disk over the network.\fR At the .CW bootargs prompt, retype the default and add the .CW -c flag to enter the file server's config mode. At the .CW config prompt, type .CW noauth twice to toggle authentication on the file server. Finally, type .CW end to continue with the boot process: .P1 bootargs is (tcp, local!device) [local!/dev/sdXX/fscache] local!/dev/sdXX/fscache -c config: noauth auth is now disabled config: noauth auth is now enabled config: end .P2 The machine will now continue to boot. Once booted, the next step is to configure the file server to listen for connections from remote hosts. Modify the .CW bootargs of the file server in .CW /n/9fat/plan9.ini : For cwfs: .P1 bootargs=local!/dev/sdXX/fscache -a tcp!*!564 .P2 For hjfs: .P1 bootargs=local!/dev/sdXX/fs -m 702 -A -a tcp!*!564 .P2 .B Note: The .CW -m 702 .R flag for .CW hjfs allocates 702 megabytes of memory to be used as a cache. This value is typically automatically calculated by the 9front installer, and may differ on your system. There is no need to change whatever default was already configured. Read: .ihtml a .I FQA 7.2.2 - How do I modify plan9.ini? .R .ihtml a Reboot the file server: .P1 fshalt -r .P2 When the system finishes booting it should now be listening for network connections to the file system. Users who have been added to the file server and the auth server should now be able to authenticate and mount the file server (tcp boot, etc.). Read: .ihtml a .CW cwfs(4) , .ihtml a .ihtml a .CW hjfs(4) , .ihtml a .ihtml a .I FQA 6.7.1 - How do I tcp boot? .R .ihtml a .html - .ihtml h3

.SH 7.3.3.1 - Stop cwfs from allowing user none to attach without authentication .R .ihtml h3 .B ACHTUNG! By default, a .CW cwfs listener allows unathenticated attaches as user .CW none . Disable it at the fsconfig(8) prompt as follows: .P1 bootargs is (tcp, local!device) [local!/dev/sdXX/fscache] local!/dev/sdXX/fscache -c config: nonone none disabled config: end .P2 .html - .ihtml h3

.SH 7.3.3.1.1 - notes on user none .R .ihtml h3 .html ul