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)