1 .\"
   2 .\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
   3 .\" Use is subject to license terms.
   4 .\"
   5 .\" CDDL HEADER START
   6 .\"
   7 .\" The contents of this file are subject to the terms of the
   8 .\" Common Development and Distribution License (the "License").
   9 .\" You may not use this file except in compliance with the License.
  10 .\"
  11 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  12 .\" or http://www.opensolaris.org/os/licensing.
  13 .\" See the License for the specific language governing permissions
  14 .\" and limitations under the License.
  15 .\"
  16 .\" When distributing Covered Code, include this CDDL HEADER in each
  17 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  18 .\" If applicable, add the following below this CDDL HEADER, with the
  19 .\" fields enclosed by brackets "[]" replaced with your own identifying
  20 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  21 .\"
  22 .\" CDDL HEADER END
  23 .\"
  24 .TH Install 1ONBLD "14 Jan 2010"
  25 .SH NAME
  26 Install \- install a kernel from an ON workspace
  27 .SH SYNOPSIS
  28 .TP 8n
  29 .B Install
  30 .RB [ " \-w "
  31 .IR workspace " ]"
  32 .RB [ " \-s "
  33 .IR "source dir" " ]"
  34 .br
  35 .RB [ " \-k  "
  36 .IR "kernel arch" " ]"
  37 .RB "[ " \-n " | " \-t|T
  38 .IR target " ]"
  39 .br
  40 .RB [ " \-u|m|a " ]
  41 .RB [ " \-v|V|q " ]
  42 .RB [ " \-c|p " ]
  43 .br
  44 .RB [ " \-l "
  45 .IR "library file" " ]"
  46 .RB [ " \-L " ]
  47 .RB [ " \-3 " ]
  48 .RB [ " \-6 " ]
  49 .RB [ " \-K " ]
  50 .br
  51 .RB [ " \-o "
  52 {
  53 .BR obj " | "
  54 .B debug
  55 }
  56 ]
  57 .RB [ " \-d "
  58 .IR "work dir" " ]"
  59 .br
  60 .RB [ " \-D "
  61 .IR "library dir" " ]"
  62 .RB [ " \-G "
  63 .IB glomname " ]"
  64 .RI [ " module ... " ]
  65 .LP
  66 or
  67 .LP
  68 .BR "Install \-R " "[ options ]"
  69 .SH DESCRIPTION
  70 .LP
  71 .B Install
  72 is a utility which simplifies the process of installing a 5.0 system.
  73 .B Install
  74 goes into a built ON workspace (or any kernel source tree),
  75 looks at the Makefiles,
  76 and figures out how to construct the /kernel and /usr/kernel directories.
  77 It then creates a tarfile
  78 .RB "(see " tar "(1))"
  79 containing /kernel, /usr/kernel, and a few related /etc files.  If a
  80 .I target ([user@]machine:/dir)
  81 is specified, the tarfile is either copied to
  82 .IR machine:/dir " (-T) or untarred on " "machine" " in " "/dir" " (-t),"
  83 using the remote user id
  84 .IR user ,
  85 if specified.
  86 With no options,
  87 .B Install
  88 creates a sun4c system from files in the current workspace (as indicated
  89 by $SRC) and places the tarfile in /tmp/Install.username/Install.sun4c.tar.
  90 
  91 .SH OPTIONS
  92 .TP 20n
  93 .BI "-w" " ws"
  94 Install the system built in the ON workspace
  95 .I ws.  ws
  96 must be a built ON workspace \(em
  97 .B Install
  98 will not automatically invoke
  99 .BR make "(1).  If " \-w " is not specified, " Install " uses the current
 100 workspace (as indicated by $CODEMGR_WS).  If there is no current workspace,
 101 .B Install
 102 checks to see if you are in an appropriate source directory, e.g. uts/sun4c;
 103 if so,
 104 .B Install
 105 takes files from there.  Otherwise,
 106 .B Install
 107 looks for files under $SRC/uts.
 108 .TP
 109 .BI "-s" " source directory"
 110 where to look for files [default: $SRC/uts].
 111 .TP
 112 .BI "-k" " kernel arch"
 113 the type of kernel to install.  The default is sun4c; however, if you invoke
 114 .B Install
 115 from $SRC/uts/sun4z,
 116 .B Install
 117 assumes you want a sun4z kernel.
 118 .TP
 119 .B "-n"
 120 No target; just create the tarfile in
 121 /tmp/Install.username/Install.sun4c.tar [default].
 122 .BR "-n" " implies " "-p" .
 123 .TP
 124 .BI "-t" " target"
 125 Install the system on
 126 .I target ([user@]machine:/dir).
 127 This means that kernel/unix is copied to
 128 .I machine:/dir/kernel/unix,
 129 etc.
 130 .IR /dir " is typically either " / " or " /mnt.
 131 .BR "-t" " implies " "-c" .
 132 The default remote user id is the same as the local one ($LOGNAME).
 133 .TP
 134 .BI "-T" " target"
 135 Copy the tarfile to
 136 .I target ([user@]machine:/dir).
 137 This creates the file
 138 .I /dir/Install.tar
 139 on
 140 .I machine.
 141 To finish the install, log on to
 142 .I machine
 143 as root, and type
 144 .RB `` "cd /; tar xvf /dir/Install.tar" "''."
 145 .BR "-T" " implies " "-c" .
 146 .TP
 147 .B "-u"
 148 Install unix only.
 149 .TP
 150 .B "-m"
 151 Install modules only.
 152 .TP
 153 .B "-a"
 154 Install unix and all modules [default].
 155 .TP
 156 .B "-v"
 157 Verbose mode.
 158 .TP
 159 .B "-V"
 160 REALLY verbose mode.  Useful mainly for debugging.
 161 .TP
 162 .B "-q"
 163 Quiet mode [default].  Only fatal messages are printed.
 164 .TP
 165 .B "-c"
 166 Clean up.  After a successful install, delete the files created in
 167 /tmp/Install.username.  This is the default behavior if a
 168 .I target
 169 is specified with
 170 .BR "-t" " or " "-T" .
 171 .TP
 172 .B "-p"
 173 Preserve temp files.  This is the default behavior when no
 174 .I target
 175 is specified
 176 .RB ( "-n" ).
 177 .TP
 178 .B "-R"
 179 Recover from a failed
 180 .BR Install .
 181 This is not required, it's just faster than restarting.
 182 A typical scenario is for
 183 .B Install
 184 to run smoothly right up to the very end, but then die with
 185 "Permission denied" when it tries to rsh/rcp to the target machine.
 186 At this point, you log on to the target machine, diddle the permissions,
 187 log off, and type
 188 .RB `` "Install -R" "''."
 189 .B Install
 190 will only have to retry the rsh/rcp,
 191 rather than rebuild the tarfile from scratch.
 192 .TP
 193 .BI "-d" " temp directory"
 194 specifies where
 195 .B Install
 196 should create its temp files [default: /tmp/Install.username].  This is
 197 useful if you have limited space in /tmp (\fBInstall\fR can take as
 198 much as 100MB).
 199 The suffix "Install.username" is always appended.
 200 .TP
 201 .B "-L"
 202 add a system to your library.  This allows you to build a personal
 203 collection of installable systems from various environments and for
 204 various architectures.  When you type
 205 .RB `` "Install -w /ws/ws_name -k arch -L" "'', " Install
 206 creates a tarfile called
 207 .I ws_name.arch.tar
 208 in your library directory (~/LibInstall by default).
 209 .BR "-L" " implies " "-c" .
 210 .TP
 211 .BI "-l" " library file"
 212 Installs the system contained in
 213 .I library file.
 214 You may omit the ``.tar'' suffix.  For example,
 215 .RB `` "Install -l my_ws.sun4c -t machine:/" ''
 216 installs a system you previously built with
 217 .B "-L"
 218 (from sun4c files in my_ws) on 
 219 .IR machine:/ .
 220 This is equivalent to typing
 221 .RB `` "rsh machine '(cd /; tar xvf -)' <~/LibInstall/my_ws.sun4c.tar" '',
 222 but it's easier to remember.
 223 .TP
 224 .BI "-D" " lib directory"
 225 specifies the library directory [default: $HOME/LibInstall].
 226 .TP
 227 .BI "-G " glomname
 228 gloms /kernel and /usr/kernel together into a single /kernel directory.
 229 Useful for development work, e.g. use "Install -G good [...]" to create a
 230 "/kernel.good".
 231 .TP
 232 .BR "-o " "{ \fBobj\fP | \fBdebug\fP }"
 233 object directory. The default is "debug".
 234 .TP
 235 .B \-3
 236 32-bit modules only
 237 .TP
 238 .B \-6
 239 64-bit modules only
 240 .TP
 241 .B \-K
 242 Do not include kmdb misc module or dmods
 243 .TP
 244 .B "-h"
 245 Help.  Prints a brief summary of
 246 .BR Install "'s"
 247 options.
 248 .LP
 249 If you are in a directory like $SRC/uts/sun4z when you invoke
 250 .BR Install ,
 251 it will infer that you want to install a sun4z system
 252 from the current workspace.
 253 .LP
 254 If you supply a list of modules, it overrides any of the
 255 .B "-uma"
 256 options.  You only need to specify the basename of the
 257 module(s), e.g. ``\fBInstall ufs nfs le\fR''.
 258 ``\fBInstall unix\fR'' is equivalent to ``\fBInstall -u\fR'', and
 259 ``\fBInstall modules\fR'' is equivalent to ``\fBInstall -m\fR''.
 260 .LP
 261 You can customize
 262 .B Install
 263 by creating a .Installrc file in your home directory.  .Installrc
 264 should consist of a list of command-line-style options, e.g:
 265 .LP
 266 .B
 267         -w /ws/foo
 268 .br
 269 .B
 270         -t labmachine:/mnt -pv
 271 .LP
 272 .B Install
 273 processes default options first, then .Installrc
 274 options, then command-line options.  In the case of
 275 conflicting options (e.g. \fB-uma\fR), the last one wins.
 276 .LP
 277 In order to use the most convenient form of
 278 .BR Install " (``" "Install -t machine:/" "''),"
 279 you will need to do the following on the target machine:
 280 .LP
 281 .br
 282         (1) add your machine name to the /etc/hosts.equiv file
 283 .br
 284         (2) add your username to the /etc/{passwd,shadow} files
 285 .br
 286         (3) chown -R yourself /kernel /usr/kernel
 287 .br
 288         (4) chmod -R u+w /kernel /usr/kernel
 289 .SH "ENVIRONMENT"
 290 .LP
 291 You can set the following variables in your environment:
 292 .LP
 293 ON_CRYPTO_BINS
 294 .IP
 295 file containing signed cryptographic binaries.  This is only needed if
 296 you are not building the closed-source tree.
 297 .LP
 298 INSTALL_RC [default: $HOME/.Installrc]
 299 .IP
 300 file containing default options for \fBInstall\fR
 301 .LP
 302 INSTALL_STATE [default: $HOME/.Install.state]
 303 .IP
 304 where \fBInstall\fR keeps its state information
 305 .LP
 306 INSTALL_DIR [default: /tmp/Install.username]
 307 .IP
 308 where \fBInstall\fR does its work.  This can be overridden on
 309 the command line with \fB\-d\fR.
 310 .LP
 311 INSTALL_LIB [default: $HOME/LibInstall]
 312 .IP
 313 where \fBInstall\fR gets/puts library files.  This can be overridden on
 314 the command line with \fB\-D\fR.
 315 .LP
 316 INSTALL_CP [default: cp -p]
 317 .IP
 318 the command to copy files locally
 319 .LP
 320 INSTALL_RCP [default: rcp -p]
 321 .IP
 322 the command to copy files remotely
 323 .bp
 324 .SH "EXAMPLES"
 325 .LP
 326 .B
 327 Install -w /ws/blort -t machine:/
 328 .IP
 329 .RI "installs the system built in workspace " /ws/blort " on " machine:/
 330 .LP
 331 .B
 332 Install -w /ws/blort -T machine:/tmp
 333 .br
 334 .B
 335 rsh machine -l root "cd /; tar xvf /tmp/Install.tar"
 336 .IP
 337 is an equivalent way to do the previous example
 338 .LP
 339 .B Install
 340 .IP
 341 makes a tarfile containing a sun4c kernel,
 342 and places it in /tmp/Install.username/Install.sun4c.tar.  However, if you
 343 are in one of the arch directories (e.g. $SRC/uts/sun4m) when you invoke
 344 .BR Install ,
 345 you will get a tarfile for that architecture instead.
 346 .LP
 347 .B
 348 Install -k sun4m -w /ws/on493 -t mpbox:/ ufs
 349 .IP
 350 installs a new sun4m ufs module from workspace /ws/on493 on mpbox:/
 351 .SH "FILES"
 352 $HOME/.Installrc, $HOME/.Install.state
 353 .SH "SEE ALSO"
 354 .BR tar "(1), " rsh "(1), " rcp "(1)"
 355 .SH "BUGS"
 356 .BR tar "(1) and " rsh "(1)"
 357 do not have particularly useful exit codes.  To compensate,
 358 .B Install
 359 feeds stderr through grep -v and throws away error messages which it
 360 considers harmless.  If there's anything left,
 361 .B Install
 362 assumes it is fatal.  It's a hack, but it works.