1 INSTALL(1ONBLD)               illumos Build Tools              INSTALL(1ONBLD)
   2 
   3 
   4 
   5 NAME
   6        Install - install a kernel from an ON workspace
   7 
   8 SYNOPSIS
   9        Install [ -w  workspace ] [ -s  source dir ]
  10                [ -k   kernel arch ] [ -n | -t|T target ]
  11                [ -u|m|a ] [ -v|V|q ] [ -c|p ]
  12                [ -l  library file ] [ -L ] [ -3 ] [ -6 ] [ -K ]
  13                [ -o  { obj |  debug } ] [ -d  work dir ]
  14                [ -D  library dir ] [ -G  glomname ] [ module ... ]
  15 
  16        or
  17 
  18        Install -R [ options ]
  19 
  20 DESCRIPTION
  21        Install is a utility which simplifies the process of installing a 5.0
  22        system.  Install goes into a built ON workspace (or any kernel source
  23        tree), looks at the Makefiles, and figures out how to construct the
  24        /kernel and /usr/kernel directories.  It then creates a tarfile (see
  25        tar(1)) containing /kernel, /usr/kernel, and a few related /etc files.
  26        If a target ([user@]machine:/dir) is specified, the tarfile is either
  27        copied to machine:/dir (-T) or untarred on machine in /dir (-t), using
  28        the remote user id user, if specified.  With no options, Install
  29        creates a sun4c system from files in the current workspace (as
  30        indicated by $SRC) and places the tarfile in
  31        /tmp/Install.username/Install.sun4c.tar.
  32 
  33 
  34 OPTIONS
  35        -w ws               Install the system built in the ON workspace ws. ws
  36                            must be a built ON workspace -- Install will not
  37                            automatically invoke make(1).  If -w is not
  38                            specified, Install uses the current workspace (as
  39                            indicated by $CODEMGR_WS).  If there is no current
  40                            workspace, Install checks to see if you are in an
  41                            appropriate source directory, e.g. uts/sun4c; if
  42                            so, Install takes files from there.  Otherwise,
  43                            Install looks for files under $SRC/uts.
  44 
  45        -s source directory where to look for files [default: $SRC/uts].
  46 
  47        -k kernel arch      the type of kernel to install.  The default is
  48                            sun4c; however, if you invoke Install from
  49                            $SRC/uts/sun4z, Install assumes you want a sun4z
  50                            kernel.
  51 
  52        -n                  No target; just create the tarfile in
  53                            /tmp/Install.username/Install.sun4c.tar [default].
  54                            -n implies -p.
  55 
  56        -t target           Install the system on target ([user@]machine:/dir).
  57                            This means that kernel/unix is copied to
  58                            machine:/dir/kernel/unix, etc.  /dir is typically
  59                            either / or /mnt.  -t implies -c.  The default
  60                            remote user id is the same as the local one
  61                            ($LOGNAME).
  62 
  63        -T target           Copy the tarfile to target ([user@]machine:/dir).
  64                            This creates the file /dir/Install.tar on machine.
  65                            To finish the install, log on to machine as root,
  66                            and type ``cd /; tar xvf /dir/Install.tar''.  -T
  67                            implies -c.
  68 
  69        -u                  Install unix only.
  70 
  71        -m                  Install modules only.
  72 
  73        -a                  Install unix and all modules [default].
  74 
  75        -v                  Verbose mode.
  76 
  77        -V                  REALLY verbose mode.  Useful mainly for debugging.
  78 
  79        -q                  Quiet mode [default].  Only fatal messages are
  80                            printed.
  81 
  82        -c                  Clean up.  After a successful install, delete the
  83                            files created in /tmp/Install.username.  This is
  84                            the default behavior if a target is specified with
  85                            -t or -T.
  86 
  87        -p                  Preserve temp files.  This is the default behavior
  88                            when no target is specified (-n).
  89 
  90        -R                  Recover from a failed Install.  This is not
  91                            required, it's just faster than restarting.  A
  92                            typical scenario is for Install to run smoothly
  93                            right up to the very end, but then die with
  94                            "Permission denied" when it tries to rsh/rcp to the
  95                            target machine.  At this point, you log on to the
  96                            target machine, diddle the permissions, log off,
  97                            and type ``Install -R''.  Install will only have to
  98                            retry the rsh/rcp, rather than rebuild the tarfile
  99                            from scratch.
 100 
 101        -d temp directory   specifies where Install should create its temp
 102                            files [default: /tmp/Install.username].  This is
 103                            useful if you have limited space in /tmp (Install
 104                            can take as much as 100MB).  The suffix
 105                            "Install.username" is always appended.
 106 
 107        -L                  add a system to your library.  This allows you to
 108                            build a personal collection of installable systems
 109                            from various environments and for various
 110                            architectures.  When you type ``Install -w
 111                            /ws/ws_name -k arch -L'', Install creates a tarfile
 112                            called ws_name.arch.tar in your library directory
 113                            (~/LibInstall by default).  -L implies -c.
 114 
 115        -l library file     Installs the system contained in library file.  You
 116                            may omit the ``.tar'' suffix.  For example,
 117                            ``Install -l my_ws.sun4c -t machine:/'' installs a
 118                            system you previously built with -L (from sun4c
 119                            files in my_ws) on machine:/.  This is equivalent
 120                            to typing ``rsh machine '(cd /; tar xvf -)'
 121                            <~/LibInstall/my_ws.sun4c.tar'', but      it's easier to
 122                            remember.
 123 
 124        -D lib directory    specifies the library directory [default:
 125                            $HOME/LibInstall].
 126 
 127        -G glomname         gloms /kernel and /usr/kernel together into a
 128                            single /kernel directory.  Useful for development
 129                            work, e.g. use "Install -G good [...]" to create a
 130                            "/kernel.good".
 131 
 132        -o { obj | debug }  object directory. The default is "debug".
 133 
 134        -3                  32-bit modules only
 135 
 136        -6                  64-bit modules only
 137 
 138        -K                  Do not include kmdb misc module or dmods
 139 
 140        -h                  Help.  Prints a brief summary of Install's options.
 141 
 142        If you are in a directory like $SRC/uts/sun4z when you invoke Install,
 143        it will infer that you want to install a sun4z system from the current
 144        workspace.
 145 
 146        If you supply a list of modules, it overrides any of the -uma options.
 147        You only need to specify the basename of the module(s), e.g. ``Install
 148        ufs nfs le''.  ``Install unix'' is equivalent to ``Install -u'', and
 149        ``Install modules'' is equivalent to ``Install -m''.
 150 
 151        You can customize Install by creating a .Installrc file in your home
 152        directory.  .Installrc should consist of a list of command-line-style
 153        options, e.g:
 154 
 155             -w /ws/foo
 156             -t labmachine:/mnt -pv
 157 
 158        Install processes default options first, then .Installrc options, then
 159        command-line options.  In the case of conflicting options (e.g. -uma),
 160        the last one wins.
 161 
 162        In order to use the most convenient form of Install (``Install -t
 163        machine:/''), you will need to do the following on the target machine:
 164 
 165             (1) add your machine name to the /etc/hosts.equiv file
 166             (2) add your username to the /etc/{passwd,shadow} files
 167             (3) chown -R yourself /kernel /usr/kernel
 168             (4) chmod -R u+w /kernel /usr/kernel
 169 
 170 ENVIRONMENT
 171        You can set the following variables in your environment:
 172 
 173        ON_CRYPTO_BINS
 174 
 175               file containing signed cryptographic binaries.  This is only
 176               needed if you are not building the closed-source tree.
 177 
 178        INSTALL_RC [default: $HOME/.Installrc]
 179 
 180               file containing default options for Install
 181 
 182        INSTALL_STATE [default: $HOME/.Install.state]
 183 
 184               where Install keeps its state information
 185 
 186        INSTALL_DIR [default: /tmp/Install.username]
 187 
 188               where Install does its work.  This can be overridden on the
 189               command line with -d.
 190 
 191        INSTALL_LIB [default: $HOME/LibInstall]
 192 
 193               where Install gets/puts library files.  This can be overridden
 194               on the command line with -D.
 195 
 196        INSTALL_CP [default: cp -p]
 197 
 198               the command to copy files locally
 199 
 200        INSTALL_RCP [default: rcp -p]
 201 
 202               the command to copy files remotely
 203 
 204 EXAMPLES
 205        Install -w /ws/blort -t machine:/
 206 
 207               installs the system built in workspace /ws/blort on machine:/
 208 
 209        Install -w /ws/blort -T machine:/tmp
 210        rsh machine -l root "cd /; tar xvf /tmp/Install.tar"
 211 
 212               is an equivalent way to do the previous example
 213 
 214        Install
 215 
 216               makes a tarfile containing a sun4c kernel, and places it in
 217               /tmp/Install.username/Install.sun4c.tar.  However, if you are in
 218               one of the arch directories (e.g. $SRC/uts/sun4m) when you
 219               invoke Install, you will get a tarfile for that architecture
 220               instead.
 221 
 222        Install -k sun4m -w /ws/on493 -t mpbox:/ ufs
 223 
 224               installs a new sun4m ufs module from workspace /ws/on493 on
 225               mpbox:/
 226 
 227 FILES
 228        $HOME/.Installrc, $HOME/.Install.state
 229 
 230 SEE ALSO
 231        tar(1), rsh(1), rcp(1)
 232 
 233 BUGS
 234        tar(1) and rsh(1) do not have particularly useful exit codes.  To
 235        compensate, Install feeds stderr through grep -v and throws away error
 236        messages which it considers harmless.  If there's anything left,
 237        Install assumes it is fatal.  It's a hack, but it works.
 238 
 239 
 240 
 241                                January 14, 2010                INSTALL(1ONBLD)