| blob | f5600914270338e816e0f44d56162d911c97556e |
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.
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.