Copyright 2005 Sun Microsystems, Inc. All rights reserved.
Use is subject to license terms.

CDDL HEADER START

The contents of this file are subject to the terms of the
Common Development and Distribution License, Version 1.0 only
(the "License"). You may not use this file except in compliance
with the License.

You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.

When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]

CDDL HEADER END

ident "%Z%%M% %I% %E% SMI"

Install - install a kernel from an ON workspace

8n Install [ " -w " workspace " ]" [ " -s " "source dir" " ]"

[ " -k " "kernel arch" " ]" "[ " -n " | " -t|T target " ]"

[ " -u|m|a " ] [ " -v|V|q " ] [ " -c|p " ]

[ " -l " "library file" " ]" [ " -L " ] [ " -3 " ] [ " -6 " ] [ " -K " ]

[ " -P " ] [ " -o " { obj " | " debug } ] [ " -d " "work dir" " ]"

[ " -D " "library dir" " ]" [ " -G " glomname " ]" [ " -x|X " ] [ " module ... " ]

or

"Install -R " "[ options ]"

Install is a utility which simplifies the process of installing a 5.0 system. Install goes into a built ON workspace (or any kernel source tree), looks at the Makefiles, and figures out how to construct the /kernel and /usr/kernel directories. It then creates a tarfile "(see " tar "(1))" containing /kernel, /usr/kernel, and a few related /etc files. If a target ([user@]machine:/dir) is specified, the tarfile is either copied to machine:/dir " (-T) or untarred on " "machine" " in " "/dir" " (-t)," using the remote user id user , if specified. With no options, Install creates a sun4c system from files in the current workspace (as indicated by $SRC) and places the tarfile in /tmp/Install.username/Install.sun4c.tar.

20n "-w" " ws" Install the system built in the ON workspace ws. ws must be a built ON workspace \(em Install will not automatically invoke make "(1). If " -w " is not specified, " Install " uses the current workspace (as indicated by $CODEMGR_WS). If there is no current workspace, Install checks to see if you are in an appropriate source directory, e.g. uts/sun4c; if so, Install takes files from there. Otherwise, Install looks for files under $SRC/uts.

"-s" " source directory" where to look for files [default: $SRC/uts].

"-k" " kernel arch" the type of kernel to install. The default is sun4c; however, if you invoke Install from $SRC/uts/sun4z, Install assumes you want a sun4z kernel.

"-n" No target; just create the tarfile in /tmp/Install.username/Install.sun4c.tar [default]. "-n" " implies " "-p" .

"-t" " target" Install the system on target ([user@]machine:/dir). This means that kernel/unix is copied to machine:/dir/kernel/unix, etc. /dir " is typically either " / " or " /mnt. "-t" " implies " "-c" . The default remote user id is the same as the local one ($LOGNAME).

"-T" " target" Copy the tarfile to target ([user@]machine:/dir). This creates the file /dir/Install.tar on machine. To finish the install, log on to machine as root, and type `` "cd /; tar xvf /dir/Install.tar" "''." "-T" " implies " "-c" .

"-u" Install unix only.

"-m" Install modules only.

"-a" Install unix and all modules [default].

"-v" Verbose mode.

"-V" REALLY verbose mode. Useful mainly for debugging.

"-q" Quiet mode [default]. Only fatal messages are printed.

"-c" Clean up. After a successful install, delete the files created in /tmp/Install.username. This is the default behavior if a target is specified with "-t" " or " "-T" .

"-p" Preserve temp files. This is the default behavior when no target is specified ( "-n" ).

"-R" Recover from a failed Install . This is not required, it's just faster than restarting. A typical scenario is for Install to run smoothly right up to the very end, but then die with "Permission denied" when it tries to rsh/rcp to the target machine. At this point, you log on to the target machine, diddle the permissions, log off, and type `` "Install -R" "''." Install will only have to retry the rsh/rcp, rather than rebuild the tarfile from scratch.

"-d" " temp directory" specifies where Install should create its temp files [default: /tmp/Install.username]. This is useful if you have limited space in /tmp (Install needs about 4MB). The suffix "Install.username" is always appended.

"-L" add a system to your library. This allows you to build a personal collection of installable systems from various environments and for various architectures. When you type `` "Install -w /ws/ws_name -k arch -L" "'', " Install creates a tarfile called ws_name.arch.tar in your library directory (~/LibInstall by default). "-L" " implies " "-c" .

"-l" " library file" Installs the system contained in library file. You may omit the ``.tar'' suffix. For example, `` "Install -l my_ws.sun4c -t machine:/" '' installs a system you previously built with "-L" (from sun4c files in my_ws) on machine:/ . This is equivalent to typing `` "rsh machine '(cd /; tar xvf -)' <~/LibInstall/my_ws.sun4c.tar" '', but it's easier to remember.

"-D" " lib directory" specifies the library directory [default: $HOME/LibInstall].

"-G " glomname gloms /kernel and /usr/kernel together into a single /kernel directory. Useful for development work, e.g. use "Install -G good [...]" to create a "/kernel.good".

"-x" includes various auxiliary files along with the kernel. Currently, these include /etc/minor_perm, /etc/driver_aliases, /etc/name_to_sysnum, and /etc/name_to_major. "-x" is the default.

"-X" opposite of "-x" : do not include auxiliary files.

"-P" update /etc/path_to_inst -- generally not advisable.

"-o " "{ obj | debug }" object directory. The default is "debug".

-3 32-bit modules only

-6 64-bit modules only

-K Do not include kmdb misc module or dmods

"-h" Help. Prints a brief summary of Install "'s" options.

If you are in a directory like $SRC/uts/sun4z when you invoke Install , it will infer that you want to install a sun4z system from the current workspace.

If you supply a list of modules, it overrides any of the "-uma" options. You only need to specify the basename of the module(s), e.g. ``Install ufs nfs le''. ``Install unix'' is equivalent to ``Install -u'', and ``Install modules'' is equivalent to ``Install -m''.

You can customize Install by creating a .Installrc file in your home directory. .Installrc should consist of a list of command-line-style options, e.g:

-w /ws/foo

-t labmachine:/mnt -pv

Install processes default options first, then .Installrc options, then command-line options. In the case of conflicting options (e.g. -uma), the last one wins.

In order to use the most convenient form of Install " (``" "Install -t machine:/" "'')," you will need to do the following on the target machine:

(1) add your machine name to the /etc/hosts.equiv file

(2) add your username to the /etc/{passwd,shadow} files

(3) chown -R yourself /kernel /usr/kernel

(4) chmod -R u+w /kernel /usr/kernel

You can set the following variables in your environment:

INSTALL_RC [default: $HOME/.Installrc]

file containing default options for Install

INSTALL_STATE [default: $HOME/.Install.state]

where Install keeps its state information

INSTALL_DIR [default: /tmp/Install.username]

where Install does its work. This can be overridden on the command line with -d.

INSTALL_LIB [default: $HOME/LibInstall]

where Install gets/puts library files. This can be overridden on the command line with -D.

INSTALL_CP [default: cp -p]

the command to copy files locally

INSTALL_RCP [default: rcp -p]

the command to copy files remotely .bp

Install -w /ws/blort -t machine:/

"installs the system built in workspace " /ws/blort " on " machine:/

Install -w /ws/blort -T machine:/tmp

rsh machine -l root "cd /; tar xvf /tmp/Install.tar"

is an equivalent way to do the previous example

Install

makes a tarfile containing a sun4c kernel, and places it in /tmp/Install.username/Install.sun4c.tar. However, if you are in one of the arch directories (e.g. $SRC/uts/sun4m) when you invoke Install , you will get a tarfile for that architecture instead.

Install -k sun4m -w /ws/on493 -t mpbox:/ ufs

installs a new sun4m ufs module from workspace /ws/on493 on mpbox:/ $HOME/.Installrc, $HOME/.Install.state tar "(1), " rsh "(1), " rcp "(1)" Install may break periodically as the kernel Makefile structure changes. I will provide frequent updates to compensate.

tar "(1) and " rsh "(1)" do not have particularly useful exit codes. To compensate, Install feeds stderr through grep -v and throws away error messages which it considers harmless. If there's anything left, Install assumes it is fatal. It's a hack, but it works.