.de EX .nr x \\$1v \\!h0c n \\nx 0 .. .de FG \" start figure caption: .FG filename.ps verticalsize .KF .BP \\$1 \\$2 .sp .5v .EX \\$2v .ps -1 .vs -1 .. .de fg \" end figure caption (yes, it is clumsy) .ps .vs .br \l'1i' .KE .. \" step numbers .nr ,s 0 1 .af ,s a .am NH .nr ,s 0 1 .. .de Sn \" .Sn "step" •\ Step \\n(H1\\n+(,s: \\$1 .. .de Ss .P1 .B .Sn "\\$1" .P2 .. .TL Installing the Inferno Software .AU Vita Nuova .br firstname.lastname@example.org .br 12 June 2003 .SP 4 .LP Inferno can run as either a native operating system, in the usual way, or as a .I hosted virtual operating system, running as an application on another operating system. This paper explains how to install Inferno from the distribution media to a hosted environment and how to configure the system for basic networking. .LP Inferno can run as a hosted virtual operating system on top of Plan 9, Unix or Windows. In this paper, the term .I Unix is used to cover all supported variants, currently FreeBSD, Linux, HP/UX, Irix and Solaris, and the term .I Windows covers Microsoft Windows (98, Me, Nt, 2000, and XP). (Windows 98 might first require installation of the Unicode layer update from Microsoft.) .NH Preparation .LP You should ensure at least 150 Mbytes of free space on the filesystem. The installation program will copy files from the distribution CD to a directory on the filesystem called the .I inferno_root directory. You can choose the location of this directory. If you are installing to a multiuser filesystem outside your control a subdirectory of your home directory might be most sensible. If you plan to share the Inferno system with other users then common choices for .I inferno_root are .CW /usr/inferno on Unix and Plan 9 systems, and .CW c:\einferno on Windows systems. Where these appear in examples in this paper you should substitute your own .I inferno_root directory. .Ss "Choose the \fIinferno_root\fP directory." Ensure that the user who will run the installation program has appropriate filesystem permissions to create the .I inferno_root directory and files and subdirectories beneath it. .NH Copying Files .LP On all platforms the files will be owned by the user doing the installation, except for installation onto a FAT file system (eg, on Windows), where the files appear to be owned by .CW Everyone because FAT does not record ownership. .Ss "Insert the distribution CD into the CD drive." On Unix and Plan 9, mount the CD to a suitable location on the filesystem, call this location .I cd_path . On Windows, note the drive letter of the CD, call this drive letter .I cd_drive . The files will be copied by an Inferno hosted installation program which runs directly from the CD. The directory .CW /install on the CD contains an installation program for each supported platform \- a shell script for Unix and Plan 9 and an executable for Windows. The Plan 9 install script is called .CW Plan9.rc and determines the CPU type from the environment variable .CW cputype . The Unix install scripts all have names of the form .CW \fIhost_os\fP-\fIhost_arch\fP.sh where .I host_os will be one of: .CW FreeBSD , .CW Linux , or .CW Solaris and .I host_arch will be one of: .CW 386 , .CW mips , .CW power or .CW sparc . Most platforms offer just the one obvious combination. The Windows installation program is called .CW setup.exe ; it is used on all varieties of Windows. The next step describes how to begin the installation by running the program that corresponds to your host system. .Ss "Run the installation script." The installation program will copy files from the CD to the filesystem. The Windows installation program will also create registry entries and add an Inferno item to the Windows .I start menu. On Plan 9, run .P1 rc \fIcd_path\fP/install/Plan9.rc \fIinferno_root\fP .P2 Where .I inferno_root is the path to the chosen Inferno root directory. The CPU architecture will be inferred from the environment variable .CW cputype . On Unix, run .P1 sh \fIcd_path\fP/install/\fIhost-os\fP-\fIhost_arch\fP.sh \fIinferno_root\fP .P2 Where .I host_os is the Unix variant name .CW FreeBSD , ( .CW Irix , .CW Linux or .CW Solaris ). .I host_arch is the CPU type (eg, .CW 386 ), and .I inferno_root is the path to the chosen Inferno directory. On Windows, run .P1 \fIcd_drive\f(CW:\einstall\esetup.exe .P2 The Windows installation program will ask you to choose the location of the installation directory on the hard disk. .LP On all platforms, a copy of Inferno on the CD will install from various installation packages on the CD to the .I inferno_root subtree on the filesystem. On any platform it installs support for all. .LP Inferno is now installed, but it needs to be configured for your site. The process acts as a quick tour of parts of the system. The main tasks are to add local parameters to the network data base, and to set up the authentication system. If you are going to run Inferno standalone, for instance to experiment with Limbo and the file serving interface, most of what follows can be deferred indefinitely. It is still worthwhile skimming through it, because the first few sections tell how to start up Inferno with correct parameters (eg, root directory and graphics resolution). (A configuration program that runs under the window system would be more convenient, and fairly easy to do, but that has not yet been done.) .NH Running Inferno .LP Inferno host executables are all kept in a single directory corresponding to the combination of host operating system and CPU architecture \- the Inferno .CW bin directory. .P1 \fIinferno_root\fP/\fIhost_os\fP/\fIhost_arch\fP/bin .P2 (On Windows the path might need .CW \e not .CW / of course.) That directory can be added to the search path of the host system's command interpreter, and that process will be described first, although as discussed later one can use a script instead and that is sometimes more convenient. (Of course, the script will still need to refer to that directory.) .LP .I "Plan 9:\ \ " Plan 9 users should add a line to their .CW lib/profile file that binds this directory after their .CW /bin directory. .P1 bind -a /usr/inferno/Plan9/$cputype/bin /bin .P2 The bind is done after the existing .I bin directory to avoid hiding the existing Plan 9 compilers. If, at a later stage, you build either the hosted or native Inferno kernels for ARM or StrongARM you should ensure that the Inferno compilers are used rather than the Plan 9 compilers, since they differ in the implementation of floating-point instructions (the Plan 9 ARM suite uses a byte order that is more plausible than the order ARM dictates but therefore wrong). That difference is likely to be resolved at some point but it has not yet been done. .LP .I "Windows:\ \" The .I host_os is always .CW Nt (even for Windows 98, 2000 or XP) and .I host_arch is always .CW 386 and the installation program will create an entry on the .I "start menu" to invoke Inferno. For Unix systems or Windows systems in which Inferno will be started from a command shell, the environment variable .CW PATH should be set to include the Inferno .CW bin directory. For Windows 95 and Windows 98 this should be done in the .CW \eautoexec.bat file by adding a line like .P1 PATH=c:\einferno\eNt\e386\ebin;%PATH% .P2 You will need to reboot Windows to have the system reread the .CW \eautoexec.bat file. For Windows NT and Windows 2000 modify the .CW Path environment variable through .I "Control Panel -> System -> Environment" . .LP If you are using an MKS or Cygwin Unix-like shell environment, you might instead set: .P1 PATH="c:/inferno/Nt/386/bin;$PATH" .P2 and export it if necessary. .LP .I "Unix:\ \" For Unix systems, for .CW sh derivatives, the environment variable .CW PATH should be set to include the Inferno .CW bin directory. This might be done in your .CW .profile file by adding a line like .P1 PATH="/usr/inferno/Linux/386/bin:$PATH" .P2 Don't forget to ensure that .CW PATH is exported. You may need to log out and back in again for the changes to take effect. .KS .Ss "Start Inferno." Hosted inferno is run by invoking an executable called .I emu . .KE On Windows, select the Inferno option from the .I "start menu" . This will invoke .I emu with appropriate arguments to find its files in .I inferno_root . If you need to change any of the options passed to .I emu when invoked from the .I "start menu" you need to do this by clicking the right mouse button on the Windows task bar and choosing .I "Properties -> Start Menu Programs -> Advanced" to modify the shortcut used for Inferno. For Unix and Plan 9, you will need to tell .I emu where to find the Inferno file tree by passing it the .CW -r\fIrootpath\f(CW command line option. For example .P1 emu -r/usr/john/inferno .P2 Without the .CW -r option it will look for the file tree in .CW /usr/inferno on Plan 9 and Unix and, when invoked from the command line on WIndows, the default is .CW \einferno on the current drive. (The Windows start menu by contrast has already been set to use the right directory by the installation software.) .LP When using graphics, .I emu will use a window with a resolution of 640 x 480 pixels by default. To use a larger resolution you will need to pass .I emu an option .CW -g\fIXsize\f(CWx\fIYsize\f(CW on the command line. So, for example, to invoke .I emu as above but with a resolution of 1024 x 768 pixels the full command line would be .P1 emu -r/usr/john/inferno -g1024x768 .P2 When invoked in this way .I emu displays a command window running the Inferno shell .CW /dis/sh.dis . To avoid typing the command line options each time you invoke .I emu you can store them in the environment variable .CW EMU which is interrogated when .I emu is started and might as well be set along side the .CW PATH environment variable if the same configuration options are to be used on each invocation. .P1 set EMU="-rd:\eDocuments and Settings\ejohn\einferno -g1024x768" .P2 for Windows. .P1 EMU=(-r/usr/john/inferno -g1024x768) .P2 for Plan 9, and .P1 EMU="-r/usr/john/inferno -g1024x768" .P2 for Unix. An alternative to using the .CW EMU environment variable is to place the correct invocation in a script file (or batch file, for Windows) and invoke that instead of running .I emu directly. It is important to note that for Windows the .CW -r option also serves to indicate both the drive and directory on to which the software has been installed. Without a drive letter the system will assume the current drive and will fail if the user changes to an alternative drive. Once the environment variables or scripts are set up, as described above, invoking plain .P1 emu .P2 or the appropriate script file, should result in it starting up Inferno's command interpreter .I sh (1), which prompts with a semicolon: .P1 ; .P2 You can add a further option .CW -c1 to start up .I emu in a mode in which the system compiles a module's Dis operations to native machine instructions when a module is loaded. (See the .I emu (1) manual page.) In .I compile mode programs that do significant computation will run much faster. Whether in compiled or interpreted mode you should now have a functional hosted Inferno system. When Inferno starts the initial .CW /dis/sh.dis it reads commands from the file .CW /lib/sh/profile before becoming interactive. See the manual pages for the shell .I sh (1) to learn more about tailoring the initial environment. .LP The semicolon is the default shell prompt. From this command window you should be able to see the installed Inferno files and directories .P1 lc / .P2 The command .I lc presents the contents of its directory argument in columnar fashion to standard output in the command window. .P1 ; lc / FreeBSD/ Unixware/ icons/ libkern/ man/ prof/ Hp/ acme/ include/ libkeyring/ mkconfig prog/ Inferno/ appl/ keydb/ libmath/ mkfile services/ Irix/ asm/ legal/ libmemdraw/ mkfiles/ tmp/ LICENCE chan/ lib/ libmemlayer/ mnt/ tools/ Linux/ dev/ lib9/ libtk/ module/ usr/ MacOSX/ dis/ libbio/ licencedb/ n/ utils/ NOTICE doc/ libcrypt/ limbo/ net/ wrap/ Nt/ emu/ libdraw/ locale/ nvfs/ Plan9/ env/ libfreetype/ mail/ o/ Solaris/ fonts/ libinterp/ makemk.sh os/ ; .P2 Only the files and directories in and below the .I inferno_root directory on the host filesystem are immediately visible to an Inferno process; these files are made visible in the root of the Inferno file namespace. If you wish to import or export files from and to the host filesystem you will need to use tools on your host to move them in or out of the Inferno visible portion of your host filesystem (see the manual pages .I os (1) and .I cmd (3) for an interface to host commands). (We plan to make such access direct, but the details are still being worked out.) From this point onwards in this paper all file paths not qualified with .I inferno_root are assumed to be in the Inferno namespace. Files created in the host filesystem will be created with the user id of the user that started .I emu and on Unix systems with that user's group id. .NH Setting the site's time zone .LP Time zone settings are defined by files in the directory .CW /locale . The setting affects only how the time is displayed; the internal representation does not vary. For instance, the file .CW /locale/GMT defines Greenwich Mean Time, .CW /locale/GB-Eire defines time zones for Great Britain and the Irish Republic (GMT and British Summer Time), and .CW /locale/US_Eastern defines United States Eastern Standard Time and Eastern Daylight Time. The time zone settings used by applications are read (by .I daytime (2)) from the file .CW /locale/timezone , which is initially a copy of .CW /locale/GB-Eire . If displaying time as the time in London is adequate, you need change nothing. To set a different time zone for the whole site, copy the appropriate time zone file into .CW /locale/timezone : .P1 cp /locale/US_Eastern /locale/timezone .P2 To set a different time zone for a user or window, .I bind (1) the file containing the time zone setting over .CW /locale/timezone , either in the user's profile or in a name space description file: .P1 bind /locale/US_Eastern /locale/timezone .P2 .NH Running the Window Manager .I wm .LP Graphical Inferno programs normally run under the window manager .I wm (1). Inferno has a simple editor, .I wm/edit , that can be used to edit the inferno configuration files. The `power environment' for editing and program development is .I acme (1), but rather that throwing you in at the deep end, we shall stick to the simpler one for now. If you already know Acme from Plan 9, however, or perhaps Wily from Unix, feel free to use Inferno's .I acme instead of .I edit . .Ss "Start the window manager." Invoke .I wm by typing .P1 wm/wm .P2 You should see a new window open with a blue-grey background and a small .I "Vita Nuova" logo in the bottom left hand corner. Click on the logo with mouse button 1 to reveal a small menu. Selecting the .I Edit entry will start .I wm/edit . In common with most .I wm programs the editor has three small buttons in a line at its top right hand corner. Clicking on the X button, the rightmost button, will close the program down. The leftmost of the three buttons will allow the window to be resized \- after clicking it drag the window from a point near to either one of its edges or one of its corners. The middle button will minimise the window, creating an entry for it in the application bar along the bottom of the main .I wm window. You can restore a minimised window by clicking on its entry in the application bar. The initial .I wm configuration is determined by the contents of the shell script .CW /lib/wmsetup (see .I toolbar (1) and .I sh (1)). .Ss "Open a shell window." Choose the .I shell option from the menu to open up a shell window. The configuration of Inferno will be done from this shell window. .NH Manual Pages .LP Manual pages for all of the system commands are available from a shell window. Use the .I man or .I wm/man commands. For example, .P1 man wm .P2 will give information about .I wm . And .P1 man man .P2 will give information about using .I man . .I Wm/man makes use of the Tk text widget to produce slightly more attractive output than the plain command .I man . Here, and in other Inferno documentation you will see references to manual page entries of the form \fIcommand\f(CW(\fIsection\f(CW)\fR. You can display the manual page for the command by running .P1 man \fIcommand\fP .P2 or .P1 man \fIsection\fP \fIcommand\fP .P2 if the manual page appears in more than one section. .NH Initial Namespace .LP The initial Inferno namespace is built by placing the root device '#/' (see .I root (3)) at the root of the namespace and binding .nr ,i 0 1 .af ,i i .IP \n+(,i) the host filesystem device '#U' (see .I fs (3)) containing the .I inferno_root subtree of the host filesystem at the root of the Inferno filesystem, .IP \n+(,i) the console device '#c' (see .I cons (3)) in .CW /dev , .IP \n+(,i) the prog device '#p' (see .I prog (3)) onto .CW /prog , .IP \n+(,i) the IP device '#I' (see .I ip (3)) in .CW /net , and .IP \n+(,i) the environment device '#e' (see .I env (3)) at .CW /dev/env . .rr ,i .LP You can see the sequence of commands required to construct the current namespace by running .P1 ns .P2 .NH Inferno's network .LP If you are just going to use Inferno for local Limbo programming, and not use its networking interface, you can skip to the section ``Adding new users'' at the end of this document. You can always come back to this step later. .LP To use IP networking, the IP device .I ip (3)) ( must have been bound into .CW /net . Typing .P1 ls -l /net .P2 (see .I ls (1)) should result in something like .P1 --rw-rw-r-- I 0 network john 0 May 31 07:11 /net/arp --rw-rw-r-- I 0 network john 0 May 31 07:11 /net/ndb d-r-xr-xr-x I 0 network john 0 May 31 07:11 /net/tcp d-r-xr-xr-x I 0 network john 0 May 31 07:11 /net/udp .P2 There might be many more names on some systems. .LP A system running Inferno, whether native or hosted, can by agreement attach to any or all resources that are in the name space of another Inferno system (or even its own). That requires: .IP • the importing system must know where to find them .IP • the exporting system must agree to export them .IP • the two systems must authenticate the access (not all resources will be permitted to all systems or users) .IP • the conversation can be encrypted to keep it safe from prying eyes and interference .LP On an Inferno network, there is usually one secure machine that acts as authentication server. All other systems variously play the rôles of server and client as required: any system can import some resources (or none) and export others (or none), simultaneously, and differently in different name spaces. In following sections, we shall write as though there were three distinct machines: authentication server (signer); server (exporting resources); and client (importing resources). With Inferno, you can achieve a similar effect on a single machine by starting up distinct instances of .I emu instead. That is the easiest way to become familiar with the process (and also avoids having to install the system on several machines to start). It is still worthwhile setting up a secured authentication server later, especially if you are using Windows on a FAT file system where the host system's file protections are limited. .LP We shall now configure Inferno to allow each of the functions listed above: .IP • change the network database to tell where to find local network resources .IP • set up the authentication system, specifically the authentication server or `signer' .IP • start network services (two distinct sets: one for the authentication services and the other for all other network services) .NH Network database files .LP In both hosted and native modes, Inferno uses a collection of text files of a particular form to store all details of network and service configuration. When running hosted, Inferno typically gets most of its data from the host operating system, and the database contains mainly Inferno-specific data. .LP The file .CW /lib/ndb/local is the root of the collection of network database files. The format is defined by .I ndb (6), but essentially it is a collection of groups of attribute/value pairs of the form \fIattribute\fP\f(CW=\fP\fIvalue\fP. Attribute names and most values are case-sensitive. .LP Related attribute/value pairs are grouped into database `entries'. An entry can span one or more lines: the first line starts with a non-blank character, and any subsequent lines in that entry start with white space (blank or tab). .NH 2 Site parameters .LP The version of .CW /lib/ndb/local at time of writing looks like this: .P1 database= file=/lib/ndb/local file=/lib/ndb/dns file=/lib/ndb/inferno file=/lib/ndb/common infernosite= #dnsdomain=your.domain.com #dns=220.127.116.11 # resolver SIGNER=your_Inferno_signer_here FILESERVER=your_Inferno_fileserver_here smtp=your_smtpserver_here pop3=your_pop3server_here registry=your_registry_server .P2 The individual files forming the data base are listed in order in the .CW database entry. They can be ignored for the moment. The entry labelled .CW infernosite= defines a mapping from symbolic host names of the form .CW $\fIservice\f(CW to a host name, domain name, or a numeric Internet address. For instance, an application that needs an authentication service will refer to .CW $SIGNER and an Inferno naming service will translate that at run-time to the appropriate network name for that environment. Consequently, the entries above need to be customised for a given site. (The items that are commented out are not needed when the host's own DNS resolver is used instead of Inferno's own .I dns (8).) For example, our .CW infernosite entry in the .CW local file might look something like this .P1 infernosite= dnsdomain=vitanuova.com dns=18.104.22.168 # resolver SIGNER=doppio FILESERVER=doppio smtp=doppio pop3=doppio registry=doppio .P2 where .CW doppio is the host name of a machine that is offering the given services to Inferno, and .CW 22.214.171.124 is the Internet address of a local DNS resolver. .Ss "Enter defaults for your site" .LP The only important names initially are: .IP \f(CWSIGNER\fP 20 the host or domain name, or address of the machine that will act as signer .IP \f(CWregistry\fP the name or address of a machine that provides the local dynamic service .I registry (4) .IP \f(CWFILESERVER\fP the primary file server (actually needed only by clients with no storage of their own) .LP All others are used by specific applications such as .I acme (1) mail or .I ftpfs (4). .LP If you are using a single machine for signer and server/client, put its name in those three entries. .NH 2 Connection server .I cs (8) and name translation .LP The connection server .I cs (8) uses the network database and other data (such as that provided by the host system and the Internet DNS servers) to translate symbolic network names and services into instructions for connecting to a given service. In hosted mode, network and service names are passed through to the host for conversion to numeric IP addresses and port numbers. If the host is unable to convert a service name the connection server will attempt to convert the name using mappings of service and protocol names to Internet port numbers in the file .CW /lib/ndb/inferno : .P1 tcp=infgamelogin port=6660 # inferno games login service tcp=styx port=6666 # main file service tcp=mpeg port=6667 # mpeg stream tcp=rstyx port=6668 # remote invocation tcp=infdb port=6669 # database server tcp=infweb port=6670 # inferno web server tcp=infsigner port=6671 # inferno signing services tcp=infcsigner port=6672 # inferno countersigner tcp=inflogin port=6673 # inferno credential service tcp=infsds port=6674 # software download tcp=registry port=6675 # registry(4) udp=virgil port=2202 # naming service .P2 For the moment, leave that file as it is. You will only need to modify this file if in future you add new statically-configured services to Inferno. (Services that come and go dynamically might use .I registry (4) instead, a registry manager that allows a service to be found using a description of it.) .NH Configuring a Signer .LP Before an Inferno machine can authenticate establish a secure connection to an Inferno service on another machine, each system needs to obtain a certificate from a common signer.† We talk here as though there is only one `signer' per site but in fact there can be application- or group-specific ones. For instance, a version of the Inferno games server automatically starts its own signing service to keep the identities and keys used for game service separate from those of the primary system, allowing users to set up their own gaming groups without fuss. .FS .FA †The authentication system will shortly expand to a rôle-based one allowing a chain of certificates to be used, from several signers, with delegation etc. .FE To use authenticated connections for the primary file services we need to set up a signer to generate certificates for users (see .I createsignerkey (8) and .I logind (8)). .LP Choose an Inferno machine to become the signer. If this is the first or only Inferno machine on your network then make this machine the signer. (It is more realistic if you start up a separate copy of .I emu and leave it in `console' mode without starting the window system.) You can always move the function elsewhere later. .Ss "Empty the secret file of secrets." The authentication server verifies a user's identity by checking that the user knows a shared secret. (In fact the secret is not used directly, but instead a scrambled value that was derived from it.) The file .CW /keydb/keys holds those secrets; it is encrypted using a secret password or phrase known only to the manager of the authentication server. Having just installed Inferno, the file should exist and be readable only by you (or the user as which the authentication service will run). On the signer machine, type .P1 ls -l /keydb/keys .P2 You should see something like: .P1 --rw------- M 7772 yourname inf 0 Jun 12 03:08 /keydb/keys .P2 You should see something like the above. If the file does not exist or is not empty or has the wrong mode, use: .P1 cp /dev/null /keydb/keys; chmod 600 /keydb/keys .P2 to set it right. .Ss "Generate a signer key." Next on the signer machine, run .P1 auth/createsignerkey \fIname\fP .P2 In place of .I name enter the network name of the signer. A fully-qualified domain name of a host or individual is fine. This value will appear as the signer name in each certificate generated by the signer. .I Createsignerkey creates public and private keys that are used by the signer when generating certificates. They are stored in .CW /keydb/signerkey ; check that it has permissions that limit access to the user that will run the authentication services: .P1 ; ls -l /keydb/signerkey --rw------- M 32685 secrets inf 1010 Jul 07 2000 /keydb/signerkey .P2 Use .I chmod (1) to set the mode to read/write only for the owner if necessary: .P1 chmod 600 /keydb/signerkey .P2 .Ss "Start the authentication network services" Still at the signer console, type .P1 svc/auth .P2 That script (see .I svc (8)) will check that the .CW /keydb/keys and .CW /keydb/signerkey files exist, and then start the program .I keyfs (4), which manages the .CW keys file. It will prompt for the password (pass phrase) you wish to use to protect the .CW keys file, now and on subsequent runs: .P1 ; svc/auth Key: Confirm key: .P2 It prompts twice to confirm it. If successfully confirmed, it will then start the network services used by Inferno to authenticate local and remote users and hosts. (If confirmation fails, retry by running .CW svc/auth again.) .LP You can check that they are running by typing: .P1 ps .P2 which should show something like the following: .P1 1 1 john release 74K Sh[$Sys] 3 2 john alt 15K Cs 10 9 john recv 25K Keyfs 11 9 john release 44K Styx[$Sys] 12 9 john recv 25K Keyfs 14 1 john alt 8K Listen 16 1 john release 8K Listen[$Sys] 18 1 john alt 9K Listen 20 1 john release 9K Listen[$Sys] 22 1 john alt 9K Listen 24 1 john release 9K Listen[$Sys] 26 1 john alt 8K Listen 28 1 john release 8K Listen[$Sys] 29 1 john ready 73K Ps[$Sys] .P2 There should be .CW Keyfs and .CW Listen processes. .Ss "Enter user names and secrets." For each user to be authenticated by the signer run .P1 auth/changelogin \fIusername\fP .P2 You will be prompted to supply a secret (ie, password or pass phrase) and expiration date. The expiration date will be used as the maximum expiration date of authentication certificates granted to that user. .I Changelogin (see .I changelogin (8)) accesses the name space generated by .I keyfs (4), which has just been started above by .CW svc/auth . A user can later change the stored secret using the .I passwd (1) command. For the signer to generate a certificate there must be at least one entry in the password file. If you are not sure at this stage of the names of the users that you want to authenticate then create an entry for the user .CW inferno and yourself. .NH Establishing a Secure Connection .LP To establish a secure connection between two Inferno machines, each needs to present a public key with a certificate signed by a common signer. We shall make two public/private key sets, one for the server and one for a client (they differ only in where they are stored). We shall do the server first, because the usual network services require the server possess some keys before they can start. We shall then start those services, and finally sort out the client. .Ss "Start the connection service." The server still needs to make contact with the signer, so we need to start the basic connection service .I cs (8). If you are using the same instance of .I emu in which you invoked .CW svc/auth above, you should skip this step. To check, you should see a new file in the .CW /net directory called .CW cs . Run the command .P1 ls /net .P2 You should see at least the following names in the output: .P1 /net/cs /net/ndb /net/tcp /net/udp .P2 Otherwise, type .P1 ndb/cs .P2 That starts .I cs (8). Try the .CW "ls /net" again to check that the .CW cs file has appeared. .LP .Ss "Generate a server key set." On the server machine (or in the `server' window), use .I getauthinfo (8) to obtain a certificate and save it in a file named .CW default by running .P1 getauthinfo default .P2 .I Getauthinfo will prompt for the address of your signer (you can often just use its host name or even .CW localhost ) and for a remote username and password combination. .I Getauthinfo will connect to the .I inflogin service on the signer and authenticate you against its user and password database, .CW /keydb/keys , using the username and password that you entered above. Answer .CW yes to the question that asks if you want to save the certificate in a file. .I Getauthinfo will save a certificate in the file .CW /usr/\fIuser\f(CW/keyring/default where .I user is the name in .CW /dev/user . .NH Network Services .LP As mentioned above, in a full Inferno network the authentication services will usually be run on a secured machine of their own (the signer), and the ordinary network services such as file service are not run on a signer. If you are, however, using one machine for all functions, you can get the right effect by starting another instance of .I emu , to act as an Inferno host that is not a signer. This one will run the services of a primary file server and the site .I registry (4). .LP Commands described in .I svc (8) start listeners for various local network services. (The commands are actually shell scripts.) As we saw above, .CW svc/auth starts the services on a signer. .LP Here we shall start the usual set of services. .KS .Ss "Start the network listener services." Type .P1 svc/net .P2 .KE Various network services will (should!) now be running. To confirm this type .P1 ps .P2 which should show something like the following: .P1 ; ps 1 1 inferno release 74K Sh[$Sys] 7 6 inferno alt 15K Cs 13 1 inferno recv 15K Registry 14 1 inferno release 44K Styx[$Sys] 15 1 inferno recv 15K Registry 17 1 inferno alt 8K Listen 19 1 inferno release 8K Listen[$Sys] 22 1 inferno alt 8K Listen 24 1 inferno release 8K Listen[$Sys] 25 1 inferno ready 74K Ps[$Sys] .P2 There should be a few .CW Listen processes and perhaps a .CW Registry . .LP You can also try .P1 netstat .P2 .I Netstat prints information about network connections. You should see several lines of output, each one describing an announced TCP or UDP service. Depending upon the contents of the network configuration files we included on the CD, you might see output something like this: .P1 tcp/1 Announced inferno 126.96.36.199!6668 ::!0 tcp/2 Announced inferno 188.8.131.52!6666 ::!0 tcp/3 Announced inferno 184.108.40.206!6675 ::!0 .P2 Each line corresponds to a network connection: the connection name, the name of the user running the server, the address of the local end of the connection, the address of the remote end of the connection, and the connection status. The connection name is actually the protocol and conversation directory in .CW /net . The connection addresses are all of the form \fIhost\f(CW!\fIport\fR for these IP based services, and the remote addresses are not filled in because they all represent listening services that are in the .CW Announced state. In this example the third line shows a TCP service listening on port 6675. Examining .CW /lib/ndb/inferno with .CW grep (see .I grep (1)) shows that the listener on port 6675 is the Inferno registry service .P1 grep 6675 /lib/ndb/inferno .P2 gives .P1 tcp=registry port=6675 # default registry .P2 .LP Now the server is ready but we need a client. .LP Either use a third machine or (more likely at first) simply start another .I emu instance in a new window. Start its connection server, again by typing .P1 ndb/cs .P2 The connection server is fundamental to the Inferno network. Once networking is set up, when subsequently starting up a client you should start .I cs before starting the window system. Note that if you are running the Inferno instance as a server, or combined server and client, the .CW svc/net that starts the network services automatically starts .I cs , and you need not do so explicitly. .LP .Ss "Generate a client certificate." Obtain a certificate for the client in the same way as on the server. We shall obtain a certificate for use with a specific server by storing it in a file whose name exactly matches the network address of the server .P1 getauthinfo tcp!\fIhostname\fP .P2 Use the current machine's .I hostname . .I Getauthinfo stores the certificate in the file .CW /usr/\fIuser\fP/keyring/\fIkeyname\fP where .I user is the name in .CW /dev/user and .I keyname is the argument given to .I getauthinfo . Again, answer .CW yes to the question that asks if you want to save the certificate in a file. .LP Now that both client and server have a certificate obtained from the same signer it is possible to establish a secure connection between them. Note that getting keys and certificates with .I getauthinfo is normally done just once (or at most once per server when the .CW default key is not used). In short, all the work done up to now need not be repeated. After this, provided the keys were saved to a keyring file, as many authenticated connections can be made as desired until the certificate expires (which by default is whenever the password entry was set to expire). Also note that the certificates for different machines can have different signers, and one can even use different certificates for the same machine when the remote user name is to differ (the .CW -f option of .I getauthinfo can then be useful to force an appropriate keyring name). .Ss "Make an authenticated connection." The script .CW svc/net on the server started fundamental name services and also a Styx file service. That can also be started separately using .CW svc/styx . In either case the namespace that is served is the one in which the command was invoked. Now you can test the service. .LP Confirm that .CW /n/remote is an empty directory by typing .P1 lc /n/remote .P2 You can now mount the server's name space onto the client's directory .CW /n/remote by typing .P1 mount \fIserveraddr\fP /n/remote .P2 Where .I serveraddr is the IP address of the server or a name that the host can resolve to the IP address of the server. Now .P1 lc /n/remote .P2 should reveal the files and directories in the namespace being served by the server. Those files are now also visible in the namespace of your shell. You will notice that these changes only affect the shell in which you ran the .I mount command \- other windows are unaffected. You can create, remove or modify files and directories in and under .CW /n/remote much as you can any other file or directory in your namespace. In fact, in general, a process does not need to know whether a file actually resides locally or remotely. You can unmount the mounted directory with .I unmount . Type .P1 unmount /n/remote .P2 You can confirm that it has gone by running .P1 ls /n/remote .P2 All connections made by Inferno are authenticated. The default connection made by .I mount is authenticated but uses neither encryption nor secure digests. You can pass an argument to .I mount to specify a more secure connection: its .CW -C option gives it a hashing and an encryption algorithm to be applied to the connection. .KS .Ss "Make a secure authenticated connection." For example, .P1 mount -C sha1/rc4_256 \fIserveraddr\fP /n/remote .P2 makes an authenticated connection to the machine given by .I serveraddr , then engages SHA1 hashing for message digesting and 256-bit RC4 for encryption. .KE It mounts the namespace served by .I serveraddr 's Styx service on the local Inferno directory .CW /n/remote . .NH Adding new users .LP Every inferno process has an associated .I "user name" . At boot time the user name is set equal to your login name on the host operating system. The user name is used by .I wm/logon to select the home directory, and by other programs like .I mount when it searches for certificates. (It can also control permission for file access on the local system in native Inferno and some hosted Inferno configurations.) When you attach to a server on another system the user name in the authenticating certificate can be used by the remote file service to set the user name appropriately there.† .FS .FA †The details are system-dependent and currently subject to change. .FE .LP To create a new user, copy the directory .CW /usr/inferno into \f(CW/usr/\fP\fIusername\fP. If the user is to have access to services on the network, make an authentication server entry using .I changelogin (8). The user can change the stored secret using .I passwd (1), if desired. Having logged in for the first time, the user should generate a default public/private key set using .I getauthinfo (8). (The authentication services must be running somewhere.) .LP The .I wm window manager program .I wm/logon allows a user to login to the local Inferno system as an Inferno user (different from the host user name). Its use is shown next. .Ss "Re-start Inferno." You should now close down any instances of .I emu that you are currently running. The quickest way to do this is to type .I control-c in the emu window in which you ran .I wm/wm . Start a new .I emu , as before, by either running .P1 emu .P2 or by choosing the appropriate entry from your start menu on Windows machines. This time, start network services .P1 svc/net .P2 and then run .P1 wm/wm wm/logon .P2 and log in as user .I inferno . When you log in, .I wm/logon will change directory to .CW /usr/inferno and then write the name .CW inferno to .CW /dev/user . If the file .CW /usr/inferno/namespace exists it will be used to construct a new namespace for the user based on the commands that it contains (see .I newns (2)). .NH What next .LP You should now have a fully functional Inferno system. You will need to have a three button mouse to use .I acme , .I wm , or .I plumbing . .LP To learn more you could start with the manual pages for: .I intro (1), .I emu (1), .I wm (1), .I wm-misc (1), .I sh (1), .I acme (1), and .I limbo (1) and also the papers in sections 1, 2 and 3 of Volume 2 of .I "The Inferno Programmer's Manual" .