Install(1ONBLD) illumos Build Tools Install(1ONBLD)

NAME

Install - install a kernel from an ON workspace

SYNOPSIS

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 ]
 
[ -o { obj | debug } ] [ -d work dir ]
 
[ -D library dir ] [ -G glomname ] [ module ... ]

or

Install -R [ options ]

DESCRIPTION

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.
 

OPTIONS

-w ws
Install the system built in the ON workspace ws. ws must be a built ON workspace — 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 can take as much as 100MB). 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".
-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

ENVIRONMENT

You can set the following variables in your environment:

ON_CRYPTO_BINS

file containing signed cryptographic binaries. This is only needed if you are not building the closed-source tree.

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

EXAMPLES

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:/

FILES

$HOME/.Installrc, $HOME/.Install.state

SEE ALSO

tar(1), rsh(1), rcp(1)

BUGS

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.
14 Jan 2010