diff options
Diffstat (limited to 'doc/install.ms')
| -rw-r--r-- | doc/install.ms | 1423 |
1 files changed, 1423 insertions, 0 deletions
diff --git a/doc/install.ms b/doc/install.ms new file mode 100644 index 00000000..cdec392b --- /dev/null +++ b/doc/install.ms @@ -0,0 +1,1423 @@ +.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 +support@vitanuova.com +.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/timezone . +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=1.2.3.4 # 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=200.1.1.11 # 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 200.1.1.11 +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 200.1.1.89!6668 ::!0 +tcp/2 Announced inferno 200.1.1.89!6666 ::!0 +tcp/3 Announced inferno 200.1.1.89!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 fourth line shows a TCP service listening on port 6673. +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" . |