2 Help on the GUI Installer
3 ==========================
18 Multiple installations
20 Finding the AFS distribution
21 Finding the AFS sysname
23 Setting default path from command line
25 Default vs Custom installation
26 List of available packages and where it comes from
27 Command line list of packages
28 Adding new packages to the list
32 Setting default values from command line
38 Seeing the command output
39 Finishing up the installation
40 Why those two buttons are disabled
48 This program is designed to install AFS on a machine from a
49 standard AFS distribution directory. The AFS distribution is
50 logically divided into sections called "packages", and one or more
51 packages can be installed at a time. AFS can be installed on the
52 local machine or to one or more remote machines on which AFS aware
57 The installation of packages is controlled by perl subscripts
58 called Install Guides. The complete set of Install Guides is kept
59 under the lib/InstallGuides directory. There is one Install Guide
60 per package, and it provides all of the Perl code that is necessary
61 to install that package. Because different systems have different
62 requirements for installation, the InstallGuides/ directory has in
63 it different subdirectories for different systems. The
64 subdirectories match the AFS sysnames, such as "sgi_64". Inside
65 each system name subdirectory are package files that are specific
67 There are also wildcard subdirectories, such as SGI_x, which can
68 be searched if a desired package is NOT in its sysname
69 subdirectory. The wildcarding consists of capitalizing the letters
70 in the sysname, and using the letter "x" to match one or more
71 characters. In the case of multiple wildcard directories matching a
72 sysname, the longest wildcard directory wins.
73 As a catchall wildcard, there is also a subdirectory "GENERIC"
74 that can be searched if all other matches fail.
75 If a file exists whose name is a package name with ".skip"
76 appended, that package will not be installed on machines of that
77 system type. This is useful to prevent GENERIC Installation Guides
78 from being used, such as "bldkernel" on Solaris machines or "vfsck"
83 This installer program uses an rc script named "afsinstall.rc"
84 located in the InstallGuides/ subdirectories. Locating the right one
85 follows the same rules as locating an InstallGuide: look in the
86 sysname subdirectory, then look in the wildcard directories, and
87 lastly look in GENERIC.
88 The GENERIC afsinstall.rc file is always read in, followed by the
89 most system specific one available, if any. There can also be an
90 afsinstall.rc file in the user's home directory given by the
91 environment variable "HOME", and if it exists it will be read in
92 last. If more than one of these afsinstall.rc files are read in, the
93 files read later will merge with and overwrite the values and options
94 from the earlier files.
95 The rc file consists of three sections separated by a blank
96 line. The first section sets up Path accelerator buttons, the second
97 describes available packages. Both are described in the appropriate
98 sections below. The third section sets configuration options similar
99 to environment variables. Each line is of the form
103 The InstallGuide files can then access the VALUE by referencing the
104 key NAME in the hash Configuration. This is intended for use as
105 options such as use of NFS aware kernel libraries, default cache size,
106 etc. The VALUE can be omitted after the equals sign to signify a NULL
109 The personal afsinstall.rc file in the user's home directory is
110 intended to let the user select default packages to install and
111 default options such as usage of NFS libraries. Because the user may
112 want to set different options for different system types, system
113 specific options can be put into an afsinstall.rc file. To make a
114 given line in the file apply only to certain system types, the line
115 can be prepended with an AFS system name followed by a colon, such as:
117 sun4x_56 :modkernel 1 Dynamic kernel libraries and afsd
118 ALPHA_x :modkernel 0 Dynamic kernel libraries and afsd
120 The first line shows that Solaris 2.6 systems should have the
121 "modkernel" package installed by default, while the wildcarded second
122 line shows the same option should be off by default on all Alpha
123 platforms. All systems that were not running Solaris 2.6 would
124 completely skip the first line, such that the determination of
125 installing the "modkernel" package by default would have to be
126 resolved by one of the other afsinstall.rc files that was read in.
127 The same applies for the second line in the example above for non
133 The install window is divided into four sections. From top to
134 bottom, these sections select the host or hosts on which to
135 install, locate the AFS distribution, select the packages to
136 install, and set certain options.
141 The top section first appears as an entry box labelled "Hostname"
142 with the local hostname filled in. The local hostname was taken
143 from the HOST environment variable. If an install is begun by
144 pressing the "INSTALL" button, AFS will be installed on the local
145 machine using the same user identity by which this program was run.
146 If a new value is typed in and entered with the RETURN key, a
147 second entry box will appear labelled "rsh as username:", and a
148 default username is filled in. This value came from the RSHas
149 variable set at the top of this program. When an installation is
150 started, the program will attempt to make an rsh connection to the
151 hostname entered under the identity given in the "rsh as username:"
152 box. Note that rsh will still be used if the hostname entered does
153 not match the HOST environment variable but still refers to the
154 local host (eg entering "localhost" or the FQDN). Also note that
155 setting up an AFS aware inetd on the remote machine requires that
156 the AFS client is already running, so this feature is primarily
157 intended for AFS upgrades and not first time installs.
158 If the value entered into the "Hostname" box is a filename, the
159 label for that box becomes "Filename". If an install is then
160 started by pressing the "INSTALL" button, the entered file is read
161 and each line of the file is used as a remote hostname on which to
162 install AFS using rsh.
166 The Path section is divided into two parts. The upper part is an
167 entry box and the lower half is several default value buttons. The
168 path to the distribution of AFS is entered into the upper entry
169 box. When an install is started by pressing the "INSTALL" button,
170 the path given is inspected, searching for signs of an AFS
171 distribution. Namely, the existence of a "root.client" directory is
172 used to determine if there is an AFS distribution. If the path
173 given does not have an AFS distribution, the installer will also
174 look for one under a directory matching the host's AFS sysname (eg
175 sun4x_55) and a directory under that named "dest". If no AFS
176 distribution can be found, the installation exits with an error.
177 The AFS sysname is determined automatically using the output of
178 /bin/uname and NOT via "fs sysname". If an installation is being
179 done on a remote machine, the remote machine's AFS sysname is used,
180 allowing installations on heterogeneous networks.
181 The buttons in the lower half of the Path section will enter in
182 path names for you into the upper entry box. By clicking on any of
183 the buttons, the entry box is cleared and a new value is
184 inserted. A special button "CLEAR" is automatically provided which
185 simply clears the entry box. The other buttons are taken from the
186 top half of the installer rc script. The lines from that file
187 consist of a key word to put into the button, followed by a pathname. If
188 one of the accelerator buttons has the key word "default", the
189 pathname given will be entered into the entry box when the program
190 starts, and no button is rendered for it.
191 If the "-path" flag was given on the command line, whatever
192 string followed that flag will be filled in as the default install
197 The Packages area is also divided into two halves. The upper half
198 consists of two radio buttons which allow you to install either a
199 default set of packages or a hand selected set of packages. The
200 lower half lists the packages that can be hand selected, and is
201 only used if the "Custom installation:" radio button is selected.
202 The list of packages available is read from the lower section of
203 the afsinstall.rc file. Each line consists of three parts: the
204 package name (and, therefore, matching InstallGuide filename), the
205 default mode for that package, and a brief explanation of the
206 package. If the "Default Installation" radio button is selected,
207 all those packages with a "mode" of "1" will be installed. These
208 default packages are also initially selected in the "custom"
209 packages area when the program starts.
210 Note that the list of default packages can change from system to
211 sytem, depending on which afsinstall.rc file in the
212 lib/InstallGuides/ directories matches the system name on which AFS
213 is being installed. Thus the default packages on the local machine
214 may be different from those on remote machines if the remote
215 machines are of different system types.
216 If the "-pkg" flag was given on the command line when the
217 installer was invoked, the list of package names provided will be
218 selected and the "Custom installation" radio button will select
220 See the "INFO ONLY" button (below) for details about what each
222 New packages can be added by creating Perl subscripts in the
223 InstallGuides/ directories and appending an entry to the
224 afsinstall.rc file. The Install Guide subscript file is given the
225 same name as the package name. Within the file is a function also
226 with the same name as the package. Whatever code is within that
227 function will be loaded in and executed when that package is
228 installed. Several "smart" functions are available in the body of
229 the installer program itself, such as &Copy(), &Symlink(), and
230 &CreateDir(). Following the code of other existing Install Guides
231 will show how these functions can be used.
236 There are two option buttons. The first option, labelled "Verbose"
237 turns on verbose output. When selected, the installations will provide
238 more output about what they are doing. Without this option, only the
239 package names and error messages are output during the install. The
240 second option button, "Don't keep backup files", instructs the
241 installer to not keep a backup of files being overwritten. When the
242 option is off, a file that is about to be overwritten will be moved
243 aside by appending .old to the filename.
244 Both options are off by default. The "-v" flag can be given on the
245 command line to turn on the Verbose option, and the "-nobackup" flag
246 will disable backup file creation.
255 If this button is pressed, no installation of AFS will actually
256 occur. Instead, a window appears and gives details about what each
257 selected package does. The information is derived from the "info"
258 subdirectory in the InstallGuides/ area. The window has a "DISMISS"
259 button for when you are finished reading.
260 This help guide is actually the info guide named "gui".
264 This button begins the actual installation. When pressed, a new
265 window will appear, called the Progress window. The window will
266 contain a column of boxes for each machine on which an
267 installation is running. Note that multiple installations is only
268 available by entering a filename in the "Hostname:" box (see
269 above). At the top of the column(s) will be a button labelled with
270 the hostname on which the installation is running. Under the
271 hostname(s) there will be a box for each package that has been
272 selected. When the machine begins installation of a package, the
273 box contains the word "WORKING". If an error occurs with the
274 installation of that package, the box says "ERROR". Installation of
275 later packages will still occur despite errors in previous
276 packages. When a package completes without errors the box will
277 say "SUCCESS". When the installation finishes, the last box in the
278 column, labelled "done" will turn to either "SUCCESS" or "ERRORS"
279 depending on the outcome of all the packages.
280 Note that if the "Default installation" radio button in the
281 Packages area is selected, a row of boxes will be created for ALL
282 available packages. If an available package is not a default
283 package for a particular machine, that box will never be filled in for
284 that machine. This was done because the set of default packages can
285 vary if multiple installations are in progress.
286 To see the full text output of a machine's installation, press
287 the hostname button at the top of the column of boxes. A window
288 will appear with all of the output. A scrollbar is attached for
289 when the output exceeds the height of the window. The window size
290 can be changed by using the window manager. At the bottom of the
291 output window will be two buttons, named "STOP INSTALL" and
292 "DISMISS". The first will kill the install job on that machine,
293 whether it is the local host or a remote host. this is for use when
294 you see things going very wrong. The second button closes the
295 output window but leaves the installation running. When the
296 installation is complete the "STOP INSTALL" button is removed. If
297 the output window is closed, it can be reopened again by pressing
298 the hostname button again in the Progress window.
299 The Progress window also has a "DISMISS" button, and if this button
300 is pressed the Progress window will close itself. If there are
301 installations still in progress they will be terminated, and all
302 output from the installs is deleted from memory. Use this button
303 only when you are satisfied with the completion of the
305 While the Progress window is still open the "INSTALL" and "INFO
306 ONLY" buttons in the main window are disabled. This is a safety
307 feature to prevent simultaneous installation processes on the same
308 machine. Closing the Progress window will reenable the two buttons.
313 The EXIT button at the bottom closes all windows and exits the
319 There are a few errors that are checked for and are handled in
320 the installation process. Error windows will appear for a certain
322 If an installation is to be performed on a
323 remoted machine, and that machine does not have an AFS aware inetd
324 running the rsh daemon, an error window will appear telling you
326 The installation program is a Perl script that requires Perl
327 5. The path to the perl program is the very first line of the
328 install program. If that path is to a Version 4 copy of Perl, an
329 error window will appear telling you so. This can be fixed either
330 by changing the first line of the installer or by upgrading the
331 copy of Perl to at least Version 5.00.
HCoop / hcoop / debian / openafs.git / blob