@chapter Configuration Procedures @label[chapter-doc-configuration] @section Site File Overview The term ``site files'' is used loosely to refer to the source files that define the network (``site'') configuration information. To configure a network with Lambdas, the system or network administrator modifies and maintains certain files. The information in these files is compiled and then loaded into the running LISP environment, or ``world''. This process is much like maintaining a LISP program, or system, made up of multiple files. This analogy is perfectly accurate: working with site files is done in a cycle of editing, compiling, loading, testing/debugging, and (if necessary) re-editing... and so on, until the site file ``program'' is working as desired. When the changes have been tested and debugged, and a stable version of the site files is obtained, it is generally desirable to @l(disk-save) the new site information as part of a complete LISP world on disk. Otherwise, the site files must be loaded every time the system is booted. The site file changes documented below are all changes to entries in the files contained in the directory with the logical pathname ``@l(SYS:SITE;)''. The source site files are: @description @item SYS.TRANSLATIONS - defines the logical pathname @l(SYS:SITE;) @item HOSTS.TEXT - contains tabular entries to define each network host @item SITE.LISP - defines site-wide system options @item LMLOCS.LISP - defines certain attributes of each LISP machine on the network; optionally, provides for ``local'' (per-Lambda) overriding values to site options @end(description) See @ref[figure-sitefiles], for a graphic illustration of the edit/compile/load/test cycle for site files. This figure also diagrams the relationships among the various source and compiled files. @fullpagefigure @setq figure-sitefiles figure-page @tex \special{:saved-paint-image "it:keith.release-4;paint-sitefiles.qfasl"} @end tex @vskip 6in @caption Edit/Compile/Load/Test Cycle for Site Files @end(fullpagefigure) Note that @l(HOSTS.TEXT) is translated, via the @l(make-system) function, into a file called @l(HSTTBL.LISP), which is in turn compiled and loaded. The @l(HOSTS.TEXT) file is actually a data table maintained in NIC (HOSTS2) format. The entries are translated into calls to the LISP function @see[si:define-host][fun]. @b[Never modify @l(HSTTBL.LISP) directly;] all changes @i(must) be made to @l(HOSTS.TEXT) for translation by @l(make-system). @section Defining Network Hosts - HOSTS.TEXT @subsection Format of HOSTS.TEXT Each line of text in a @l(HOSTS.TEXT) file must be one of the following: @enumerate @item a comment beginning, as in LISP, with a semi-colon ``;'', or @item an entry beginning with the token ``NET'' which defines a network entity,or @item an entry beginning with the token ``HOST'' which defines a single host entity. @end(enumerate) The ``NET'' entry format is supported for historical reasons; it is not used by Lambda software. However, a @l(HOSTS.TEXT) file can begin with the ``NET'' entry or entries defining the Chaosnet subnet(s) to which the hosts are logically assigned; for example, the template site files have the following entry: @lisp NET CHAOS, 7 @end(lisp) The format of each HOST entry can best be understood in terms of the function @l(si:define-host). When @l[(make-system 'site ...)] is executed, the @l(HOSTS.TEXT) file is processed; each host entry is translated into a LISP form calling @l(si:define-host), and these forms are written out to the file @l(HSTTBL.LISP). (The translation is usually only performed if it is necessary, i.e. when the file @l(HOSTS.TEXT) is @ii(newer) than @l(HSTTBL.LISP).) @defun si:define-host name &rest options Define a host. Should only be used in SYS:SITE;HSTTBL.LISP. @end(defun) The @l(name) argument is a string specifying the primary name for the host. The other options taken by @l(si:define-host) are as follows: @table 3 @item :MACHINE-NAMES A list of host names; the last element should be the primary name, with the preceding elements sorted by increasing name length. The first machine name is used frequently as a short name where brevity is desired. @item :SYSTEM-TYPE A keyword corresponding to a known (software) system type. Known system types are discussed below. @item :MACHINE-TYPE A keyword corresponding to a known (hardware) system type. Known machine types are discussed below. @item :CHAOS A list specifying the valid Chaosnet address(es) for this host. @item :INTERNET A list specifying the valid Internet address(es) for this host. @end(table) The host entries in @l(HOSTS.TEXT) from which these parameters are generated have the following format: @example HOST , ,,,,[] @end(example) Before proceeding with a discussion of each host entry parameter, look at these two examples that illustrate the format: @example HOST UNIX-A, CHAOS 3430,USER,UNIX,NU,[UNIXA] HOST LAMBDA-A, [CHAOS 3440,INTERNET 101.0.0.1],USER,LISPM,LISPM,[LAMA,LA] @end(example) It is possible to create a host ``on the fly'', as follows: execute @l(si:define-host), then call @see[si:parse-host][fun]. For example: @lisp (si:define-host "TEMP" :HOST-NAMES '("TEMP" "TMP") :machine-type :vax :system-type :unix :chaos #o3470) (si:parse-host 'temp) @end(lisp) However, it is better to add all new host to the site files. @subsection Host Addresses Each host can be defined with one or more addresses of either type, CHAOS or INTERNET. (For example, you might provide two Internet addresses to a host that acts as a TCP/IP gateway.) If more than one host address is listed, all the addresses are enclosed in a pair of brackets. @subsubsection Internet Addresses @label[section-internet-addresses] The DOD Military Standard for the IP protocol (Ref: MIL-STD-1777, 8/12/83) defines, among other aspects of the IP protocol, how networks and network entities (hosts) are to be identified. The two network designations which are used in Lambda site files are the @b[network addresses] for each host and, if subnets are in use, the applicable @b[subnet mask(s)]. These are in turn constrained by the chosen @b[network number(s)] corresponding to the physical and/or logical network layout in use. The network addresses, network number, and applicable subnet masks are determined by the network administrator; all are represented as 32-bit numbers. These 32-bit numbers may be expressed in various ways: as large decimal, octal, or hexadecimal numbers, or (more legibly) in ``dotted-decimal'' format. In dotted decimal format, each group of 8 bits, or ``octet'', is expressed decimally, and octets are separated by periods. An octet can have a printed value from 0 (each bit is 0) to 255 (each bit is 1). If a 32-bit number has all bits set to 1, the dotted decimal representation would be "255.255.255.255". Of course, LISP can directly represent decimal, octal, and hexadecimal notations and compare them internally. But dotted decimal format is not a standard LISP type, so it is represented by strings which contain the printed form. For example, the following Internet address designations are equivalent: @itemize @bullet @item Dotted Decimal String: "101.0.0.152" @item Decimal: 1694498968 @item Octal: #o14500000230 @item Hexadecimal: #x65000098 @end(itemize) Networking functions expecting an Internet address will generally take any of these formats; the function @see[ip:parse-internet-address][fun] is used internally, and may be useful for developers. Internet functions that accept, for example, either a host name or address will interpret any number as an Internet address; strings are parsed first to see if they specify a known host name, and finally as dotted decimal numbers. To provide some flexibility in assigning @b[host addresses], the IP specification defines several ranges of address, or ``classes''. The three classes in common usage are known as classes A, B, and C. An IP host address consists of three fixed-length bit fields: @enumerate @item a bit sequence that represents a particular network class designation, @item a bit sequence for the network number, @item and a bit sequence for the local (host) address. @end(enumerate) By inspecting the high-order bits in an address, it is always possible to determine the network class designation. The offset and length of the other fields depends on the network class. @ref[figure-internet-address], shows how an IP address is composed. @figure @setq figure-internet-address figure-page @cindex[Internet addresses] @tex \special{:saved-paint-image "it:keith.release-4;paint-netbits.qfasl"} @end tex @vskip 4in @caption Internet Addresses @end(figure) A @b[subnet mask] is a bit mask applied to a network address. It contains a range of bits set to mask the network number field, as illustrated in @ref[figure-subnet-masks]. The default subnet masks shown in the figure are those that are commonly used for the appropriate class network where subnets are @ii(not) in use. @figure @setq figure-subnet-masks figure-page @cindex[subnet mask] @sp 1 @settabs 4 @columns @< @i(Network Class:) @\ -- A -- @\ -- B -- @\ -- C -- @cr @sp 1 @< Sample address: @\ 100.000.000.002 @\ 128.001.000.002 @\ 192.001.002.003 @cr @< Network number: @\ 100.000.000.000 @\ 128.001.000.000 @\ 192.001.002.000 @cr @< Default Subnet @cr @< @ @ Mask: @\ 255.000.000.000 @\ 255.255.000.000 @\ 255.255.255.000 @cr @cleartabs @sp 1 @caption Example - Network Addresses and Subnet Masks @end(figure) @subsubsection Chaos Addresses @label[section-chaos-addresses] Each host on the Chaosnet local-area network is identified by a 16-bit @b[Chaos address]. An address consists of two fields. The most-significant 8 bits identify a @i(subnet), and the least-significant 8 bits identify a host within that subnet. Both fields must be non-zero. By convention, Chaos addresses are generally specified as octal numbers. In the site file @l(HOSTS.TEXT) the octal address number is entered directly, without a prefix, but in LISP the octal representation is entered with the octal prefix; for example, @l(#o3741). The range of addresses for a particular subnet number can be calculated as follows: @lisp low address: (* 256) high address: (+ (* 256) 255) @end(lisp) Here is a partial list of address ranges, giving the high and low address for subnets 1 through 15: @display SUBNET LOW HIGH 1 400 777 2 1000 1377 3 1400 1777 4 2000 2377 5 2400 2777 6 3000 3377 7 3400 3777 8 4000 4377 9 4400 4777 10 5000 5377 11 5400 5777 12 6000 6377 13 6400 6777 14 7000 7377 15 7400 7777 @end(display) @b[Restrictions:] Lambda hosts cannot act as Chaosnet gateways or bridges, but they will co-exist on a network with Chaosnet hosts that re-route packets. The networking software does not impose restrictions on the network addresses, so it is @i(not) necessary to assign the same subnet number to Lambda hosts inter-connected on the same physical network. As described in the next section, one Chaos address is reserved for the special host named @l(AMNESIA). @subsection Special Address - Host AMNESIA @label[section-amnesia] If a Lambda host boots up and cannot obtain its own host identity, it assigns itself the host name which corresponds to the Chaos address 3412 (octal). By convention, this address is reserved for the host called @l(``AMNESIA''). Normally this happens when the host's own name cannot be found among the known hosts in the loaded site information. The sample site files include definitions for @l(AMNESIA) in both @l(HOSTS.TEXT) and @l(LMLOCS.LISP). It is important to keep these entries in your own site files. When a system boots as @l(AMNESIA), the user is reminded of this by the output from @l(print-herald) which lists the host name, e.g. ``[Unknown Chaos Address]''. To correct this condition, the user must use @see[si:set-sys-host][fun] and @see[update-site-configuration-info][fun] to point to and load a current set of site files. @subsection Host User / Server Types Each @l(HOSTS.TEXT) entry includes a field containing either ``USER'' or ``SERVER''. This is intended to indicate whether the machine provides user login capability. The Lambda networking software does not retain this information; it is entered in the site files strictly for compatibility with NIC host-table parsers on other systems. @subsection Host Machine / System Types @label[section-host-types] Two fields in each @l(HOSTS.TEXT) entry specify the type of host in terms of ``machine type'' (hardware) and ``system type'' (software). The networking software doesn't actually depend on the machine type for proper communications; it is retained as part of each host object, however, and can be used by developers. The system type is critical to networking functionality, since it is used to define the host object type, file system type, and directory line parsing. The @ii(host object type) is a flavor definition corresponding to a particular host/system type. See Section @ref[section-host-objects] for a brief discussion on host objects; consult the @LMM@ for details. The @ii(file system type) is used to determine the appropriate flavor to be used for pathname parsing. Generally this corresponds to the @ii(system type) specified in @l(HOSTS.TEXT), but there are exceptions. Directory line parsing corresponds to file system type, but is defined separately to allow for potential discrepancies among remote file servers. Directory parsing is used by TCP/FTP during file access; certain FTP operations receive a text listing of a remote directory, and the networking software parses each line received to obtain detailed information about each file, such as owner/author, permissions, and creation date (when available). It is possible for developers to extend the known system types along these lines; contact GigaMos Customer Service for assistance. @ref[appendix-systypes], describes the implemented system types, listing the associated flavors and machine types that are typically entered in @i(HOSTS.TEXT). @section Site Options The options specified in @l(SITE.LISP) are global: they are set for all Lambda hosts. Site options in @l(LMLOCS.LISP) are put into effect for a specific Lambda only. @subsection Global Site Options - SITE.LISP Most of the options described below are normally specified as global options. The only LISP form in @l(SITE.LISP) should be a call to the macro @l(SI:DEFSITE), which establishes the options. @l(defsite) takes two arguments. The first is a keyword site name, such as @l(:OUR-SITE). @cindex[site name] This site name is also specified in the @l(LMLOCS.LISP) entry for each Lambda. The second argument is a list of option lists; the @l(CAR) of each option list is the name of a keyword option, such as @l(:SYS-HOST), followed by the value of the option. @subsection Lambda Machine Locations - LMLOCS.LISP The @l(LMLOCS) file contains an entry for each LISP Machine at your site. The primary purpose of this file is to establish certain pieces of information, such as the machine location, that are specific to each LISP machine host. Optionally, global site options listed in @l(SITE.LISP) can be overriden for a particular host by listing the desired values in its @l(LMLOCS) entry. In effect, each host sees the local value for each site option, if specified; otherwise, it sees the global value. The only LISP form in @l(LMLOCS.LISP) should be a @l(defconst) that defines the variable @l(si:machine-location-alist). @defconst si:machine-location-alist A list of LISP machine location entries. @end(defconst) This variable is an association list; each member of the list is another list that defines one host. The general pattern of a host entry is @display @ii[ (host-full-name pretty-name location-string (building floor) associated-machine site-options)] @end(display) These elements of each host entry are entered as follows: @itemize @bullet @item Host-full-name: The name of the host to be defined, specified as a string. @item Pretty-name: A full description of the host. This is displayed, for example, by @l(print-herald) and @l(hostat). @item Location-string: A string describing the physical location of the host system. @item Building-floor: A list describing the site location of the host. The first element of the list is a symbol that describes the physical site; the second element can be used to distinguish a particular physical location within that site. A convention that is used at many sites is to enter the building name and floor. @item Associated-machine: This is the name of the host where users locate their personal directories. The @l(login) function, by default, looks on the associated machine for users' directories and initialiation files. The associated machine need not be the same as the local host; on a network where users share multiple machines in a terminal room, for example, it may be convenient to designate a file server with a large file capacity as the associated machine for all Lambdas. @item Site-options: This is a list of site option/value pairs that override the global options entered in @l(SITE.LISP). The overriding values are seen only by the one host defined in this machine location entry. Site options that is specified a certain way for individual convenience, such as @l(:DEFAULT-PRINTER), are commonly overriden. @end(itemize) For example, the following entry defines the host @l(COUSIN-IT); its associated machine is @l(UNCLE), and the TI855 printer attached to it is the default printer. @lisp ("COUSIN-IT" "Cousin It" "K. Corbett's office" (LOWELL 2) "UNCLE" ((:DEFAULT-PRINTER (:TI855 "COUSIN-IT")))) @end(lisp) @subsection Defining the Network / Site @table 3 @item :NETWORK-NAMES @i([list-of-network-specs]) @kmetasubindex[:network-names][site option] @setq option-network-names page This option consists of a list of network specifications; each specification consists of network name(s), number, and (optionally) IP subnet mask. In practice, the information specified by this option is only used by Lambdas situated on an IP network with subnets. However, it is recommended that you specify the option, since the Site Editor does require it, and future software may depend on it. The first element of each specification is a list of strings, names for the network. The second element of each specification is an association list describing the protocols supported on this network. Each member of this list is a list that begins with a keyword network protocol (i.e. @l[:CHAOS] or @l[:INTERNET]). Following each protocol name is the network's corresponding network number. For @l[:CHAOS], this is the subnet number; for @l[:INTERNET], this is the network number. @cindex[subnet mask] Optionally, following an Internet network number, the site manager can specify the @i(subnet mask) which is used to distinguish addresses on separate subnets within the network. If subnets are not in use, the subnet mask @i(must be NIL or absent) for Internet addressing to be handled correctly. See Section @ref[section-internet-addresses], @b(@nameref[section-internet-addresses]), for further information on Internet addresses and subnet masks. Here's an example @l(SITE.LISP) entry that pertains to a class A network which consists of two subnets; 8 bits of the local address are used to specify the subnet number. Hosts on this network have addresses of the form "100.1.x.x" or "100.2.x.x". @group @smalllisp (DEFSITE ... ... (:NETWORK-NAMES '((("A-NETWORK") ((:INTERNET "100.1.0.0" "255.255.0.0") (:CHAOS 7))) (("B-NETWORK") ((:INTERNET "100.2.0.0" "255.255.0.0"))))) ...) @end(smalllisp) @end(group) @sp 1 @item :DEFAULT-INITIAL-FORM @i[(LISP-form-to-be-EVAL'ed)] The site option @l(:DEFAULT-INITIAL-FORM), if present, specifies a LISP form to be evaluated when the Lambda boots. (It is meant as a host option for individual machines, and thus should be used in @l(LMLOCS.LISP).) When the machine is booted, after the cold-boot initializations are completed, the form is printed out and the user is asked whether to execute it. If the user answers @b(YES), or after a one-minute timeout, the form is evaluated. A good way to use this feature is to set up a LISP program on the @b(sys host) which executes the desired initializations. This way, the initialization procedures can be modified simply by editing and compiling the initialization program. For example, the following entry in @l(SITE.LISP) would execute the specified startup program after a cold-boot: @lisp (DEFSITE ... : (:default-initial-form '(catch-error(load "sys:site;startup"))) : ) @end(lisp) The @l(catch-error) form is used to avoid throwing into the error handler during startup. @item :SHORT-SITE-NAME @i[] @itemx :LONG-SITE-NAME @i[] @itemx :SITE-PRETTY-NAME @i[] These options specify various forms of the network site name. The short name should be a very short (one-word) abbreviation. The long and ``pretty'' names can include spaces. For example: @lisp (:SHORT-SITE-NAME "W.W.") (:LONG-SITE-NAME "Widget Works") (:SITE-PRETTY-NAME "++ Widget Works, North America, Inc. ++") @end(lisp) @c (:SYS-LOGIN-NAME "LISPM") @c (:SYS-LOGIN-PASSWORD "LISPM") @end(table) @subsection System Time Services @table 3 @item :STANDALONE @i([T or NIL]) If this option is @l(T), each Lambda is ``standalone'', and gets its system time from its own battery clock. If @l(NIL), each system will attempt to get its system time from another host, a ``Time Server Host'' (see below). @item :TIMEZONE @i([hours-west-of-GMT]) This option specifies the timezone location of the network. The timezone is expressed in hours west of Greenwich Mean Time. For example, the Continental USA Eastern Timezone is entered as: @lisp (:TIMEZONE 5) @end(lisp) @item :CHAOS-TIME-SERVER-HOSTS @i([list-of-Chaos-hosts]) This option specifies a list of Chaosnet hosts which can provide the time service. On system startup, non-standalone Lambdas will poll this list of hosts to get the time of day. The value is a simple list of host names; for example, @lisp (:CHAOS-TIME-SERVER-HOSTS '("OPUS" "TISH")) @end(lisp) @end(table) @subsection Chaosnet Options @table 3 @item :SERVER-MACHINE @i([T or NIL]) @kmetasubindex[:server-machine][site option] @setq option-server-machine page Normally, a Lambda's Chaosnet services (e.g. remote file access) are enabled at boot time. However, when a Lambda is used often as a server machine at a site, it may be necessary to delay access to the services until certain other initializations are performed. If the Lambda's @l(:SERVER-MACHINE) site option value is non-NIL, then its services are @l(not) enabled automatically at boot time; instead the function @see[si:enable-services][fun] must be called. Note that the @l(:server-machine) would normally be specified in @l(LMLOCS.LISP) to apply only to specific Lambdas, not all. @end(table) @subsection TCP/IP Options @table 3 @item :BROKEN-BERKELEY-UNIX-BROADCAST-ADDRESS-P @i([T or NIL]) @kmetasubindex[:broken-berkeley-unix-broadcast-address-p][site option] @setq option-broken-berkeley page This site option must be specified if there are Berkeley 4.2 Unix systems on your network. @cindex[Berkeley 4.2 Unix] Such systems have a non-standard method of doing IP broadcasting. If you set this option to @i(T) (true), TCP/IP will also use this method, and will be able to broadcast to the Unix systems. If you set the option to NIL (or omit it), TCP/IP will use the standard method, and will be able to broadcast to systems that properly use the standard method (including systems running later Berkeley Unix releases). To enable Berkeley 4.2 IP broadcasting compatibility, add the following line within the @l(DEFSITE) in the file @l(SITE.LISP): @lisp (:broken-berkeley-unix-broadcast-address-p T) @end lisp @sp 1 @end(table) @subsection Printer Options @b[steal liberally from printer software guide ???] @subsection Defining Foreign Systems Various options specify information required for dealing with foreign system types. @table 3 @item :HOST-DEFAULT-DEVICE-ALIST @i([host . device pairs]) @label[site-option-host-device] This option specifies the default device to be used for pathnames on a specific host. This is especially useful with hosts that support multiple disk devices. The option's value is an association list of dotted pairs, one per remote host. The first element of each pair is a host name; the @l(CDR) of each pair is a string specifying the device name. For example, the following specifies that pathnames on the VAX/VMS host ``MY-VAX'' should include the default disk device ``USER_DISK'' (which is presumably a logical device assignment on the VAX): @lisp (:HOST-DEFAULT-DEVICE-ALIST '(("MY-VAX" . "USER_DISK"))) @end(lisp) @item :SPECIAL-FILE-HOSTS This is an association list of file-system types and the hosts that have the particular type of file system. Most file system types are known by the system type specified in @l(HOSTS.TEXT); only exceptions need be entered in the site option. For example, the following specifies a list of Symbolics hosts with the @l(:LMFS) file system type, and a Silicon Graphics Unix workstation with the @l(:UNIX-SGI) file system type. @lisp (:SPECIAL-FILE-HOSTS '((:LMFS "SYMB-1" "SYMB-2") (:UNIX-SGI "SGI-HOST"))) @end(lisp) @end(table) @subsection @section Updating Site Files This section documents the procedure for preparing and updating site files for use with release 4. @cindex[sys host] It is recommended that the site files be modified and compiled on the @b(sys host); this is normally the file-server host on which system sources, site files, etc. have been stored. Other Lambda hosts on the network can then load the site files from the sys host. You must first establish the location of the working, or template, site files (either your 3.0 site files, or the sample files provided by GigaMos). Then you can prepare new site files and save a band with site information. The current location of the site files is specified by the logical pathname, ``@i(SYS:SITE;)'', which is established in two ways: @enumerate @item @b(From LISP), to override the current value of @l(SYS:SITE;), use the function @l(si:set-sys-host) (see below). @item @b(In the site files), by defining the logical host ``@l(SYS)'' in the site file @l(SYS.TRANSLATIONS). This file must contain a call to the function @l(fs:set-logical-pathname-host) (see below) which defines the @b(sys host). (@b[Note:] It is @i(not) a good idea to define any other logical pathnames for your site in this file.) @end(enumerate) @defun si:set-sys-host host-name &optional operating-system-type host-address site-file-directory Specify the host to read system files from. You can specify the operating system type (a keyword), host address, and the directory for finding the site files, in case the system does not know that host yet. @end(defun) Several examples are given as they are required in documenting the procedures below. @defun fs:set-logical-pathname-host logical-host &key physical-host translations @format Define a logical host named LOGICAL-HOST, which translates to PHYSICAL-HOST. TRANSLATIONS is a list of translations to use: each element looks like (logical-pattern physical-pattern), where each pattern is a file namestring with wildcards. Omitted components default to * (:WILD). @end(format) @end(defun) @subsection Using the Sample Site Files If you are installing 4.0 software on your first Lambda system, and you haven't previously loaded 3.0 site information, you will need to start with the sample set of site files provided with release 4. @csubindex[site files][sample] Follow the procedure for restoring the sample site files provided in the @i(4.0 LISP Release Notes). Then, define @l(SYS:SITE;) to point to the sample site files (temporarily). Execute, for example, @lisp (si:set-sys-host "lm" nil nil "release-4.customer-site;") @end lisp Proceed to the step in Section @ref[section-verify-site-files], @b(@nameref[section-verify-site-files]), below. @subsection Using Previously Established Site Files @csubindex[site files][working version] To use your own site file directory in place of the default (or whatever is current in a particular band), You must redefine @l(SYS:SITE;) to point to your own directory. If the site files you have modified and loaded in the past are located on the @b(local machine) (the one you are working on), execute the following: @lisp (si:set-sys-host "lm" nil nil "directory-name;") @end lisp ...where you substitute the actual site file directory name in place of @l(directory-name;). @ii[Be sure to remember] the semi-colon in the directory specification, and do not include a host prefix. If the site files are located on another Lambda Chaosnet host, you can point to them remotely. @csubindex[site files][remote] For example, assume there is a host @b(MASTER-HOST) with Chaos address 3430 (octal). It contains site files in the directory @l(OUR-SITE;) which were used with release 3. You would execute the following to point to these site files: @lisp (si:set-sys-host "master-host" :lispm #o3430 "our-site;") @end lisp @subsection Verify Access to Site Files @label[section-verify-site-files] Once you have pointed to a set of working or template site files, you should verify that you can access them: @lisp (listf "sys:site;") @end lisp @subsection Copying Site Files to a New Directory Now you should copy the working or template site files to a new directory which will be specifically for release 4 site files. Select a directory name which will indicate its purpose. If, for example, you want to establish the top-level directory @l(OUR-SITE4;) you would execute the following (make sure you are working on the @b[sys host]): @lisp ;;To copy the site files: (fs:copy-directory "sys:site;*.*#>" "lm:our-site4;") ;;To point to the new site file directory: (si:set-sys-host "lm" nil nil "our-site4;") ;;To verify that you can access the new directory: (listf "sys:site;") @end lisp Finally, you are ready to make the changes for release 4 that were described above. @subsection Edit Site Files The most direct way to make changes to your site files is to edit the files directly with ZMacs. You can bring up a directory listing by executing @lisp (dired "sys:site;*.*#>") @end lisp To edit a particular file, position the cursor on the file name and press ``@i(E)''. Make your changes in each file as described in the previous section. Be sure to save each file with @ctrl(X) @ctrl(S). Alternatively, the Site Editor program (provided on the 4.0 LISP options tape) can be used to update the files. The Site Editor is documented in the @i(Release 3.0 Site Editor Manual). See Section @ref[section-site-editor], @b(@nameref[section-site-editor]), for an example illustrating the use of the Site Editor. If you are updating a set of release 3 site files, be sure to review @ref[figure-site-files-checklist] for a check-list of changes that must be made. If you are starting with the template site files, be sure to make all the necessary changes; here is a list of the kinds of changes that are usually required: @itemize @bullet @item Add/delete/modify hosts (names, addresses, attributes) in @l(HOSTS.TEXT) @item Add/delete/modify global site options in @l(SITE.LISP) @item Add/delete/modify LISP machine locations and local site options in @l(LMLOCS.LISP) @item Modify the definition of the @l(SYS:) logical translations to point to your own site file directory and the release 4 source directories. @end(itemize) @subsection Recompile Site Files After editing and saving the files, they must be (re)compiled. @csubindex[site files][compiling] To recompile all the files, execute: @lisp ;;Recompile site files: (make-system 'site :recompile :noload :noconfirm :no-reload-system-declaration) @end lisp Later, if you make further changes in just one or two files, you can recompile just the modified files by using the option @l(:compile) instead of @l(:recompile); for example: @lisp (make-system 'site :compile :noload :noconfirm :no-reload-system-declaration) @end lisp @subsection Update Site Configuration Info To load the recompiled site files, execute @csubindex[site files][loading] @lisp (update-site-configuration-info) @end(lisp) @defun update-site-configuration-info Loads the current site files (as specified by the current translation for @l(SYS:SITE;)) into the running LISP environment. @end(defun) This is the end of the edit / compile / load cycle for the site files. @subsection Updating Site Files - Summary Use @l(si:set-sys-host) to point to a working set of site files -- either your own, or the template site files on the @i(4.0 LISP Options Tape). If you are making 4.0 site files for the first time, copy the old site files to your own directory, and @l(si:set-sys-host) to point to the new directory. Use ZMacs or the Site Editor to make the desired changes -- add hosts, printers, and the network definition. Use @l[(make-system 'site ...)] to translate the site file @l(HOSTS.TEXT), and then compile the files @l(HSTTBL.LISP), @l(SITE.LISP), and @l(LMLOCS.LISP). Every time you change one of these files, you must execute a form of @l[(make-system 'site ...)]. And whenever this compiles or updates any file(s), you must @l[(update-site-configuration-info)] to properly load the site information. If you edit @l(SYS.TRANSLATIONS), it is sufficient to run @l[(update-site-configuration-info)]. Here's a sample session which illustrates recompiling, loading, and testing the new site files: @lisp ;;Recompile site files: (make-system 'site :recompile :noload :noconfirm :no-reload-system-declaration) Generating host table from SYS: CHAOS; HOSTS TEXT > Compiling SYS: SITE; SITE LISP > Compiling SYS: SITE; LMLOCS LISP > Compiling SYS: SITE; HSTTBL LISP > ;;Load new site files: (update-site-configuration-info) NIL ;;Make sure SYS.TRANSLATIONS points to the right site files! (listf "sys:site;") : : ;;Make sure you can contact all available Chaos hosts: (hostat) Site Name/Status Subnet ... 3701 Our Lambda ... : : ;;Use a remote TCP host name - asks for an echo (icmp:ping 'myvax) 6 NIL ;;You should get a number back from @see[icmp:ping][fun]. ;;The response '6' means 6 clock ticks, or 1/10th second, ;;which is an acceptable response time. @end(lisp) @subsection Save a Band with Site Information @label[section-disk-save] Once you are satisfied that your new site files are completely accurate, you will want to save a new release 4 band with valid site information. You should copy the most up-to-date band to @ii[every Lambda system disk on your network]. The procedure below explains how to save an updated band; you should always do this on the @b[sys host]. But on a network with multiple Lambdas, you can choose between two alternative procedures for propagating the update to other systems: @enumerate @item Copy the updated band to each system, along with the microcode; or @item Save an updated band on each machine separately. @end(enumerate) This is an important choice for the Lambda system administrator. If it is important to have all users working with the same software, it is probably easier to maintain just one load band and copy it each time it changes; this provides a central point of control and ensures consistency among the Lambdas. However, if the software on every system is maintained separately, and/or various systems need different customized or optional software, it may be easier to customize a band on each machine. @sp 1 @textbox @b[Note:] if you are upgrading from release 3 to release 4, there are some restrictions that apply to copying the initial release 4 band from the @b[sys host] to other Lambdas. If you are running TCP/IP, but not Chaosnet, on the release 3 systems, you will not be able to copy the release 4 band while running release 4. Our recommendation in this case is to use release 3 on the @b[sys host] to copy the distribution (``vanilla'') release 4 band to the release 3 systems, and update them separately. Thereafter, when every system is running release 4, you can switch to the procedure of copying a master band to the other systems. @end(textbox) Use the procedure in Section @ref[section-disk-save], below, for both creating a master band and, if you are updating bands separately, to update the other systems. The procedure in Section @ref[section-remote-update] describes how to copy a master band and microcode from the @b[sys host] to a remote system. @subsubsection Save an Updated Band to Disk @label[section-disk-save] First, cold-boot the Lambda. Make sure you reboot release 4. @ii[Don't press that system key - ] You should not bring up any windows (even the editor) when you are saving a band to disk; windows will add substantially to the size of the saved band, and booting the system will take more time. All the work of disk-saving should be done in the Initial Lisp Listener window. Login without running your @l[LISPM.INIT] initialization file; for example: @lisp (login 'sitemanager t) @end(lisp) Next, run @l(si:set-sys-host) as before to point to the new @l(SYS:SITE;) directory. Here are the examples again: @itemize @bullet @item @l[(si:set-sys-host "lm" nil nil "our-site4;")] - point to site directory on local machine @item @l[(si:set-sys-host "master-host" :lispm #o3430 "our-site4;")] - point to site directory on remote Chaos host @item @l[(si:set-sys-host "master-host" :lispm "101.0.0.10" "our-site4;")] - point to site directory on remote TCP host @end(itemize) Next, run @l[(update-site-configuration-info)] to reload the new site files into the freshly-booted LISP world. @sp 1 @textbox Now is a good time to load any optional systems or other load band customizations. See the @i[4.0 LISP Release Notes] on installing optional software. @end(textbox) Finally, run @l(disk-save) to save the current world to a new disk partition. @cindex[disk-save] Before you run @l(disk-save), select a LOD band to write over. You can execute @l[(print-disk-label)] to see the available disk partitions. Here's an example session that illustrates running @l(disk-save): @lisp @ii[(disk-save 'lod2)] Do you really want to clobber partition LOD2 on unit 0 ()? (Yes or No) @ii(yes) This is now: : Additional comment for herald: @ii(site) "Sys 4.0 laser1+ site" will not fit in disk label. Please abbreviate to 16 characters: @ii(CTRL-A CTRL-K 4.0 site) Do you wish to load LAM symbols for Lambda? (Y or N) ... @ii(Y) : Flipping level 2 now will result in better paging ... ? @ii(YES) : : @ii(saves and reboots) : @end(lisp) After LISP reboots on the new band, you will want to make the new band the current default for booting in the future. @cindex[set current band] For example, if you disk-saved to the band LOD2, you would execute: @lisp (set-current-band 'lod2) @end(lisp) @subsubsection Copying an Updated Band Over the Network @label[section-remote-update] Use the function @see[si:copy-disk-partition][fun] to copy an updated master band and current microcode from the @b[sys host] to other remote Lambda hosts. For example, working on the @b(sys host), you could copy the updated release 4 band in partition ``LOD1'', and then the release 4 microcode in ``LMC1'', to the remote host @b(NOTHER) as follows: @lisp (si:copy-disk-partition 0 'lod1 "nother" 'lod1) (si:copy-disk-partition 0 'lmc1 "nother" 'lmc1) @end(lisp) Make sure you select partitions on the other hosts that you can overwrite; if necessary, make a backup of older bands before copying the new software. For each additional system, after the bands are successfully transmitted, be sure to run @l(si:set-current-band) to make the new band and microcode current. @sp 1 @textbox @b[REMINDER:] It is not possible to copy partitions between a release 3 TCP-only Lambda and a release 4 Lambda; the release 3 TCP/IP DISK server is not compatible with the TCP specification. The best way to upgrade multiple Lambdas containing only the Excelan hardware interface is as follows: 1] Restore the distribution (``vanilla'') release 4 band and microcode partitions on the @b(sys host); 2] Use release 3 TCP/IP on all systems to run @l(si:copy-disk-partition) and copy the vanilla release 4 bands to each system. @end(textbox) @c end config2