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 "Jan 14, 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) .
 100 If \-w is not specified,
 101 .B Install
 102 uses the current
 103 workspace (as indicated by $CODEMGR_WS).  If there is no current workspace,
 104 .B Install
 105 checks to see if you are in an appropriate source directory, e.g. uts/sun4c;
 106 if so,
 107 .B Install
 108 takes files from there.  Otherwise,
 109 .B Install
 110 looks for files under $SRC/uts.
 111 .TP
 112 .BI "-s" " source directory"
 113 where to look for files [default: $SRC/uts].
 114 .TP
 115 .BI "-k" " kernel arch"
 116 the type of kernel to install.  The default is sun4c; however, if you invoke
 117 .B Install
 118 from $SRC/uts/sun4z,
 119 .B Install
 120 assumes you want a sun4z kernel.
 121 .TP
 122 .B "-n"
 123 No target; just create the tarfile in
 124 /tmp/Install.username/Install.sun4c.tar [default].
 125 .BR "-n" " implies " "-p" .
 126 .TP
 127 .BI "-t" " target"
 128 Install the system on
 129 .I target ([user@]machine:/dir).
 130 This means that kernel/unix is copied to
 131 .I machine:/dir/kernel/unix,
 132 etc.
 133 .IR /dir " is typically either " / " or " /mnt.
 134 .BR "-t" " implies " "-c" .
 135 The default remote user id is the same as the local one ($LOGNAME).
 136 .TP
 137 .BI "-T" " target"
 138 Copy the tarfile to
 139 .I target ([user@]machine:/dir).
 140 This creates the file
 141 .I /dir/Install.tar
 142 on
 143 .I machine.
 144 To finish the install, log on to
 145 .I machine
 146 as root, and type
 147 .RB `` "cd /; tar xvf /dir/Install.tar" "''."
 148 .BR "-T" " implies " "-c" .
 149 .TP
 150 .B "-u"
 151 Install unix only.
 152 .TP
 153 .B "-m"
 154 Install modules only.
 155 .TP
 156 .B "-a"
 157 Install unix and all modules [default].
 158 .TP
 159 .B "-v"
 160 Verbose mode.
 161 .TP
 162 .B "-V"
 163 REALLY verbose mode.  Useful mainly for debugging.
 164 .TP
 165 .B "-q"
 166 Quiet mode [default].  Only fatal messages are printed.
 167 .TP
 168 .B "-c"
 169 Clean up.  After a successful install, delete the files created in
 170 /tmp/Install.username.  This is the default behavior if a
 171 .I target
 172 is specified with
 173 .BR "-t" " or " "-T" .
 174 .TP
 175 .B "-p"
 176 Preserve temp files.  This is the default behavior when no
 177 .I target
 178 is specified
 179 .RB ( "-n" ).
 180 .TP
 181 .B "-R"
 182 Recover from a failed
 183 .BR Install .
 184 This is not required, it's just faster than restarting.
 185 A typical scenario is for
 186 .B Install
 187 to run smoothly right up to the very end, but then die with
 188 "Permission denied" when it tries to rsh/rcp to the target machine.
 189 At this point, you log on to the target machine, diddle the permissions,
 190 log off, and type
 191 .RB `` "Install -R" "''."
 192 .B Install
 193 will only have to retry the rsh/rcp,
 194 rather than rebuild the tarfile from scratch.
 195 .TP
 196 .BI "-d" " temp directory"
 197 specifies where
 198 .B Install
 199 should create its temp files [default: /tmp/Install.username].  This is
 200 useful if you have limited space in /tmp (\fBInstall\fR can take as
 201 much as 100MB).
 202 The suffix "Install.username" is always appended.
 203 .TP
 204 .B "-L"
 205 add a system to your library.  This allows you to build a personal
 206 collection of installable systems from various environments and for
 207 various architectures.  When you type
 208 .RB `` "Install -w /ws/ws_name -k arch -L" "'', " Install
 209 creates a tarfile called
 210 .I ws_name.arch.tar
 211 in your library directory (~/LibInstall by default).
 212 .BR "-L" " implies " "-c" .
 213 .TP
 214 .BI "-l" " library file"
 215 Installs the system contained in
 216 .I library file.
 217 You may omit the ``.tar'' suffix.  For example,
 218 .RB `` "Install -l my_ws.sun4c -t machine:/" ''
 219 installs a system you previously built with
 220 .B "-L"
 221 (from sun4c files in my_ws) on
 222 .IR machine:/ .
 223 This is equivalent to typing
 224 .RB `` "rsh machine '(cd /; tar xvf -)' <~/LibInstall/my_ws.sun4c.tar" '',
 225 but it's easier to remember.
 226 .TP
 227 .BI "-D" " lib directory"
 228 specifies the library directory [default: $HOME/LibInstall].
 229 .TP
 230 .BI "-G " glomname
 231 gloms /kernel and /usr/kernel together into a single /kernel directory.
 232 Useful for development work, e.g. use "Install -G good [...]" to create a
 233 "/kernel.good".
 234 .TP
 235 .BR "-o " "{ \fBobj\fP | \fBdebug\fP }"
 236 object directory. The default is "debug".
 237 .TP
 238 .B \-3
 239 32-bit modules only
 240 .TP
 241 .B \-6
 242 64-bit modules only
 243 .TP
 244 .B \-K
 245 Do not include kmdb misc module or dmods
 246 .TP
 247 .B "-h"
 248 Help.  Prints a brief summary of
 249 .BR Install "'s"
 250 options.
 251 .LP
 252 If you are in a directory like $SRC/uts/sun4z when you invoke
 253 .BR Install ,
 254 it will infer that you want to install a sun4z system
 255 from the current workspace.
 256 .LP
 257 If you supply a list of modules, it overrides any of the
 258 .B "-uma"
 259 options.  You only need to specify the basename of the
 260 module(s), e.g. ``\fBInstall ufs nfs le\fR''.
 261 ``\fBInstall unix\fR'' is equivalent to ``\fBInstall -u\fR'', and
 262 ``\fBInstall modules\fR'' is equivalent to ``\fBInstall -m\fR''.
 263 .LP
 264 You can customize
 265 .B Install
 266 by creating a .Installrc file in your home directory.  .Installrc
 267 should consist of a list of command-line-style options, e.g:
 268 .LP
 269 .nf
 270 .B
 271         -w /ws/foo
 272 .fi
 273 .br
 274 .nf
 275 .B
 276         -t labmachine:/mnt -pv
 277 .fi
 278 .LP
 279 .B Install
 280 processes default options first, then .Installrc
 281 options, then command-line options.  In the case of
 282 conflicting options (e.g. \fB-uma\fR), the last one wins.
 283 .LP
 284 In order to use the most convenient form of
 285 .BR Install " (``" "Install -t machine:/" "''),"
 286 you will need to do the following on the target machine:
 287 .LP
 288 .br
 289 .nf
 290         (1) add your machine name to the /etc/hosts.equiv file
 291 .fi
 292 .br
 293 .nf
 294         (2) add your username to the /etc/{passwd,shadow} files
 295 .fi
 296 .br
 297 .nf
 298         (3) chown -R yourself /kernel /usr/kernel
 299 .fi
 300 .br
 301 .nf
 302         (4) chmod -R u+w /kernel /usr/kernel
 303 .fi
 304 .SH "ENVIRONMENT"
 305 .LP
 306 You can set the following variables in your environment:
 307 .LP
 308 INSTALL_RC [default: $HOME/.Installrc]
 309 .IP
 310 file containing default options for \fBInstall\fR
 311 .LP
 312 INSTALL_STATE [default: $HOME/.Install.state]
 313 .IP
 314 where \fBInstall\fR keeps its state information
 315 .LP
 316 INSTALL_DIR [default: /tmp/Install.username]
 317 .IP
 318 where \fBInstall\fR does its work.  This can be overridden on
 319 the command line with \fB\-d\fR.
 320 .LP
 321 INSTALL_LIB [default: $HOME/LibInstall]
 322 .IP
 323 where \fBInstall\fR gets/puts library files.  This can be overridden on
 324 the command line with \fB\-D\fR.
 325 .LP
 326 INSTALL_CP [default: cp -p]
 327 .IP
 328 the command to copy files locally
 329 .LP
 330 INSTALL_RCP [default: rcp -p]
 331 .IP
 332 the command to copy files remotely
 333 .SH "EXAMPLES"
 334 .LP
 335 .B
 336 Install -w /ws/blort -t machine:/
 337 .IP
 338 .RI "installs the system built in workspace " /ws/blort " on " machine:/
 339 .LP
 340 .B
 341 Install -w /ws/blort -T machine:/tmp
 342 .br
 343 .B
 344 rsh machine -l root "cd /; tar xvf /tmp/Install.tar"
 345 .IP
 346 is an equivalent way to do the previous example
 347 .LP
 348 .B Install
 349 .IP
 350 makes a tarfile containing a sun4c kernel,
 351 and places it in /tmp/Install.username/Install.sun4c.tar.  However, if you
 352 are in one of the arch directories (e.g. $SRC/uts/sun4m) when you invoke
 353 .BR Install ,
 354 you will get a tarfile for that architecture instead.
 355 .LP
 356 .B
 357 Install -k sun4m -w /ws/on493 -t mpbox:/ ufs
 358 .IP
 359 installs a new sun4m ufs module from workspace /ws/on493 on mpbox:/
 360 .SH "FILES"
 361 $HOME/.Installrc, $HOME/.Install.state
 362 .SH "SEE ALSO"
 363 .BR tar "(1), " rsh "(1), " rcp "(1)"
 364 .SH "BUGS"
 365 .BR tar "(1) and " rsh "(1)"
 366 do not have particularly useful exit codes.  To compensate,
 367 .B Install
 368 feeds stderr through grep -v and throws away error messages which it
 369 considers harmless.  If there's anything left,
 370 .B Install
 371 assumes it is fatal.  It's a hack, but it works.