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