1 '\" te
2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common
4 .\" Development and Distribution License (the "License"). You may not use this
5 .\" file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or
7 .\" http://www.opensolaris.org/os/licensing. See the License for the specific
8 .\" language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and
10 .\" include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable,
11 .\" add the following below this CDDL HEADER, with the fields enclosed by
12 .\" brackets "[]" replaced with your own identifying information:
13 .\" Portions Copyright [yyyy] [name of copyright owner]
14 .\" Copyright 2013 DEY Storage Systems, Inc.
15 .\" Copyright (c) 2014 Gary Mills
16 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
17 .TH ZLOGIN 1 "Mar 17, 2015"
18 .SH NAME
19 zlogin \- enter a zone
20 .SH SYNOPSIS
21 .LP
22 .nf
23 \fBzlogin\fR [\fB-dCEQ\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR
24 .fi
25
26 .LP
27 .nf
28 \fBzlogin\fR [\fB-nEQS\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR \fIutility\fR
29 [\fIargument\fR]...
30 .fi
31
32 .SH DESCRIPTION
33 .sp
34 .LP
35 The \fBzlogin\fR utility is used by the administrator to enter an operating
36 system zone. Only a superuser operating in the global system zone can use this
37 utility.
38 .sp
39 .LP
40 \fBzlogin\fR operates in one of three modes:
41 .sp
42 .ne 2
43 .na
44 \fBInteractive Mode\fR
45 .ad
46 .RS 24n
47 If no utility argument is given and the stdin file descriptor for the
48 \fBzlogin\fR process is a tty device, \fBzlogin\fR operates in \fBinteractive
49 mode\fR. In this mode, \fBzlogin\fR creates a new pseudo terminal for use
50 within the login session. Programs requiring a tty device, for example,
51 \fBvi\fR(1), work properly in this mode. In this mode, \fBzlogin\fR invokes
52 \fBlogin\fR(1) to provide a suitable login session.
53 .RE
54
55 .sp
56 .ne 2
57 .na
58 \fBNon-Interactive Mode\fR
59 .ad
60 .RS 24n
61 If a utility is specified, \fBzlogin\fR operates in \fBnon-interactive mode\fR.
62 This mode can be useful for script authors since stdin, stdout, and stderr are
63 preserved and the exit status of \fIutility\fR is returned upon termination. In
64 this mode, \fBzlogin\fR invokes \fBsu\fR(1M) in order to set up the user's
65 environment and to provide a login environment.
66 .sp
67 The specified command is passed as a string and interpreted by a shell running
68 in the non-global zone. See \fBrsh\fR(1).
69 .RE
70
71 .sp
72 .ne 2
73 .na
74 \fBConsole Mode\fR
75 .ad
76 .RS 24n
77 If the \fB-C\fR option is specified, the user is connected to the zone console
78 device and \fBzlogin\fR operates in \fBconsole mode\fR. The zone console is
79 available once the zone is in the installed state. Connections to the console
80 are persistent across reboot of the zone.
81 .RE
82
83 .SH OPTIONS
84 .sp
85 .LP
86 The following options are supported:
87 .sp
88 .ne 2
89 .na
90 \fB\fB-C\fR\fR
91 .ad
92 .RS 15n
93 Connects to the zone console.
94 .RE
95
96 .sp
97 .ne 2
98 .na
99 \fB\fB-d\fR\fR
100 .ad
101 .RS 15n
102 Disconnect from the console when the zone halts. This option may only be used
103 if the \fB-C\fR option is specified.
104 .RE
110 .ad
111 .RS 15n
112 Specifies a different escape character, \fIc\fR, for the key sequence used to
113 access extended functions and to disconnect from the login. The default escape
114 character is the tilde (\fB~\fR).
115 .RE
116
117 .sp
118 .ne 2
119 .na
120 \fB\fB-E\fR\fR
121 .ad
122 .RS 15n
123 Disables the ability to access extended functions or to disconnect from the
124 login by using the escape sequence character.
125 .RE
126
127 .sp
128 .ne 2
129 .na
130 \fB\fB-l\fR \fIusername\fR\fR
131 .ad
132 .RS 15n
133 Specifies a different \fIusername\fR for the zone login. If you do not use this
134 option, the zone username used is "root". This option is invalid if the
135 \fB-C\fR option is specified.
136 .RE
137
138 .sp
139 .ne 2
140 .na
141 \fB-n\fR
142 .ad
143 .RS 15n
144 Redirect the input of \fBzlogin\fR to \fB/dev/null\fR.
145 This option is useful when the command running in the local zone
146 and the shell which invokes \fBzlogin\fR both read from standard input.
147 .RE
148
149 .sp
150 .ne 2
151 .na
152 \fB-Q\fR
153 .ad
154 .RS 15n
155 Specifies quiet mode operation. In quiet mode, extra messages indicating the
156 the function of \fBzlogin\fR will not be displayed, giving the possibility
157 to present the appearance that the command is running locally rather than
158 in another zone.
159 .RE
160
161 .sp
162 .ne 2
163 .na
164 \fB\fB-S\fR\fR
165 .ad
166 .RS 15n
167 "Safe" login mode. \fBzlogin\fR does minimal processing and does not invoke
168 \fBlogin\fR(1) or \fBsu\fR(1M). The \fB-S\fR option can not be used if a
169 username is specified through the \fB-l\fR option, and cannot be used with
170 console logins. This mode should only be used to recover a damaged zone when
171 other forms of login have become impossible.
172 .RE
173
174 .SS "Escape Sequences"
175 .sp
176 .LP
177 Lines that you type that start with the tilde character (\fB~\fR) are "escape
178 sequences". The escape character can be changed using the \fB-e\fR option.
179 .sp
180 .ne 2
181 .na
182 \fB\fB~.\fR\fR
183 .ad
184 .RS 6n
185 Disconnects from the zone. This is not the same as a logout, because the local
186 host breaks the connection with no warning to the zone's end.
187 .RE
188
189 .SH SECURITY
190 .sp
191 .LP
192 Once a process has been placed in a zone other than the global zone, the
193 process cannot change zone again, nor can any of its children.
194 .SH OPERANDS
195 .sp
196 .LP
197 The following operands are supported:
198 .sp
199 .ne 2
200 .na
201 \fB\fIzonename\fR\fR
202 .ad
203 .RS 15n
204 The name of the zone to be entered.
205 .RE
206
207 .sp
208 .ne 2
209 .na
210 \fB\fIutility\fR\fR
211 .ad
212 .RS 15n
213 The utility to be run in the specified zone.
214 .RE
215
216 .sp
217 .ne 2
218 .na
219 \fB\fIargument...\fR\fR
220 .ad
221 .RS 15n
222 Arguments passed to the utility.
223 .RE
224
225 .SH EXIT STATUS
226 .sp
227 .LP
228 In interactive and non-interactive modes, the \fBzlogin\fR utility exits when
229 the command or shell in the non-global zone exits. In non-interactive mode, the
230 exit status of the remote program is returned as the exit status of
231 \fBzlogin\fR. In interactive mode and console login mode, the exit status is
232 not returned. \fBzlogin\fR returns a \fB0\fR exit status as long as no
233 connection-related error occurred.
234 .sp
235 .LP
236 In all modes, in the event that a connection to the zone cannot be established,
237 the connection fails unexpectedly, or the user is lacking sufficient privilege
238 to perform the requested operation, \fBzlogin\fR exits with status \fB1\fR.
239 .sp
240 .LP
241 To summarize, the following exit values are returned:
242 .sp
243 .ne 2
244 .na
245 \fB\fB0\fR\fR
246 .ad
251 .sp
252 .ne 2
253 .na
254 \fB\fB1\fR\fR
255 .ad
256 .RS 7n
257 Permission denied, or failure to enter the zone.
258 .RE
259
260 .sp
261 .ne 2
262 .na
263 \fBAny\fR
264 .ad
265 .RS 7n
266 Return code from utility, or from \fBsu\fR(1M) if operating in non-interactive
267 mode.
268 .RE
269
270 .SH ATTRIBUTES
271 .sp
272 .LP
273 See \fBattributes\fR(5) for descriptions of the following attributes:
274 .sp
275
276 .sp
277 .TS
278 box;
279 c | c
280 l | l .
281 ATTRIBUTE TYPE ATTRIBUTE VALUE
282 _
283 Interface Stability Evolving
284 .TE
285
286 .SH SEE ALSO
287 .sp
288 .LP
289 \fBlogin\fR(1), \fBrsh\fR(1), \fBvi\fR(1), \fBsu\fR(1M), \fBzoneadm\fR(1M),
290 \fBzonecfg\fR(1M), \fBattributes\fR(5), \fBzones\fR(5)
291 .SH NOTES
292 .sp
293 .LP
294 \fBzlogin\fR fails if its open files or any portion of its address space
295 corresponds to an NFS file. This includes the executable itself or the shared
296 libraries.
|
1 '\" te
2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common
4 .\" Development and Distribution License (the "License"). You may not use this
5 .\" file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or
7 .\" http://www.opensolaris.org/os/licensing. See the License for the specific
8 .\" language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and
10 .\" include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable,
11 .\" add the following below this CDDL HEADER, with the fields enclosed by
12 .\" brackets "[]" replaced with your own identifying information:
13 .\" Portions Copyright [yyyy] [name of copyright owner]
14 .\" Copyright 2013 DEY Storage Systems, Inc.
15 .\" Copyright (c) 2014 Gary Mills
16 .\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved
17 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
18 .TH ZLOGIN 1 "Mar 30, 2015"
19 .SH NAME
20 zlogin \- enter a zone
21 .SH SYNOPSIS
22 .LP
23 .nf
24 \fBzlogin\fR [\fB-dCEINQ\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR
25 .fi
26
27 .LP
28 .nf
29 \fBzlogin\fR [\fB-inEQS\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR \fIutility\fR
30 [\fIargument\fR]...
31 .fi
32
33 .SH DESCRIPTION
34 .LP
35 The \fBzlogin\fR utility is used by the administrator to enter an operating
36 system zone. Only a superuser operating in the global system zone can use this
37 utility.
38 .sp
39 .LP
40 \fBzlogin\fR operates in one of four modes:
41 .sp
42 .ne 2
43 .na
44 \fBInteractive Mode\fR
45 .ad
46 .RS 24n
47 If no utility argument is given or if the \fB-i\fR option is specified, and the
48 stdin file descriptor for the \fBzlogin\fR process is a tty device, \fBzlogin\fR
49 operates in \fBinteractive mode\fR. In this mode, \fBzlogin\fR creates a new
50 pseudo terminal for use within the login session. Programs requiring a tty
51 device, for example, \fBvi\fR(1), work properly in this mode. In this mode,
52 \fBzlogin\fR invokes \fBlogin\fR(1) to provide a suitable login session.
53 .RE
54
55 .sp
56 .ne 2
57 .na
58 \fBNon-Interactive Mode\fR
59 .ad
60 .RS 24n
61 If a utility is specified and the \fB-i\fR option is not specified, \fBzlogin\fR
62 operates in \fBnon-interactive mode\fR. This mode can be useful for script
63 authors since stdin, stdout, and stderr are preserved and the exit status of
64 \fIutility\fR is returned upon termination. In this mode, \fBzlogin\fR invokes
65 \fBsu\fR(1M) in order to set up the user's environment and to provide a login
66 environment.
67 .sp
68 The specified command is passed as a string and interpreted by a shell running
69 in the non-global zone. See \fBrsh\fR(1).
70 .RE
71
72 .sp
73 .ne 2
74 .na
75 \fBConsole Mode\fR
76 .ad
77 .RS 24n
78 If the \fB-C\fR option is specified, the user is connected to the zone console
79 device and \fBzlogin\fR operates in \fBconsole mode\fR. The zone console is
80 available once the zone is in the installed state. Connections to the console
81 are persistent across reboot of the zone.
82 .RE
83
84 .sp
85 .ne 2
86 .na
87 \fBStandalone-processs Interactive Mode\fR
88 .ad
89 .RS 24n
90 If the \fB-I\fR option is specified the user is connected to the zone's stdin,
91 stdout and stderr \fBzfd(7D)\fR devices.
92 .RE
93
94 .SH OPTIONS
95 .LP
96 The following options are supported:
97 .sp
98 .ne 2
99 .na
100 \fB\fB-C\fR\fR
101 .ad
102 .RS 15n
103 Connects to the zone console.
104 .RE
105
106 .sp
107 .ne 2
108 .na
109 \fB\fB-d\fR\fR
110 .ad
111 .RS 15n
112 Disconnect from the console when the zone halts. This option may only be used
113 if the \fB-C\fR option is specified.
114 .RE
120 .ad
121 .RS 15n
122 Specifies a different escape character, \fIc\fR, for the key sequence used to
123 access extended functions and to disconnect from the login. The default escape
124 character is the tilde (\fB~\fR).
125 .RE
126
127 .sp
128 .ne 2
129 .na
130 \fB\fB-E\fR\fR
131 .ad
132 .RS 15n
133 Disables the ability to access extended functions or to disconnect from the
134 login by using the escape sequence character.
135 .RE
136
137 .sp
138 .ne 2
139 .na
140 \fB\fB-i\fR\fR
141 .ad
142 .RS 15n
143 Forces interactive mode when a utility argument is specified.
144 .RE
145
146 .sp
147 .ne 2
148 .na
149 \fB\fB-I\fR\fR
150 .ad
151 .RS 15n
152 Connects to the zone's \fBzfd(7D)\fR devices.
153 .RE
154
155 .sp
156 .sp
157 .ne 2
158 .na
159 \fB\fB-l\fR \fIusername\fR\fR
160 .ad
161 .RS 15n
162 Specifies a different \fIusername\fR for the zone login. If you do not use this
163 option, the zone username used is "root". This option is invalid if the
164 \fB-C\fR option is specified.
165 .RE
166
167 .sp
168 .ne 2
169 .na
170 \fB-n\fR
171 .ad
172 .RS 15n
173 Redirect the input of \fBzlogin\fR to \fB/dev/null\fR.
174 This option is useful when the command running in the local zone
175 and the shell which invokes \fBzlogin\fR both read from standard input.
176 .RE
177
178 .sp
179 .ne 2
180 .na
181 \fB-N\fR
182 .ad
183 .RS 15n
184 Nohup. This may only be used with the -I option to avoid sending EOF to the zfd
185 device when zlogin's stdin receives EOF. It can also be toggled by sending
186 \fBSIGUSR1\fR to an attached zlogin process.
187 .RE
188
189 .sp
190 .ne 2
191 .na
192 \fB-Q\fR
193 .ad
194 .RS 15n
195 Specifies quiet mode operation. In quiet mode, extra messages indicating the
196 the function of \fBzlogin\fR will not be displayed, giving the possibility
197 to present the appearance that the command is running locally rather than
198 in another zone.
199 .RE
200
201 .sp
202 .ne 2
203 .na
204 \fB\fB-S\fR\fR
205 .ad
206 .RS 15n
207 "Safe" login mode. \fBzlogin\fR does minimal processing and does not invoke
208 \fBlogin\fR(1) or \fBsu\fR(1M). The \fB-S\fR option can not be used if a
209 username is specified through the \fB-l\fR option, and cannot be used with
210 console logins. This mode should only be used to recover a damaged zone when
211 other forms of login have become impossible.
212 .RE
213
214 .SS "Escape Sequences"
215 .LP
216 Lines that you type that start with the tilde character (\fB~\fR) are "escape
217 sequences". The escape character can be changed using the \fB-e\fR option.
218 .sp
219 .ne 2
220 .na
221 \fB\fB~.\fR\fR
222 .ad
223 .RS 6n
224 Disconnects from the zone. This is not the same as a logout, because the local
225 host breaks the connection with no warning to the zone's end.
226 .RE
227
228 .SH SECURITY
229 .LP
230 Once a process has been placed in a zone other than the global zone, the
231 process cannot change zone again, nor can any of its children.
232 .SH OPERANDS
233 .LP
234 The following operands are supported:
235 .sp
236 .ne 2
237 .na
238 \fB\fIzonename\fR\fR
239 .ad
240 .RS 15n
241 The name of the zone to be entered.
242 .RE
243
244 .sp
245 .ne 2
246 .na
247 \fB\fIutility\fR\fR
248 .ad
249 .RS 15n
250 The utility to be run in the specified zone.
251 .RE
252
253 .sp
254 .ne 2
255 .na
256 \fB\fIargument...\fR\fR
257 .ad
258 .RS 15n
259 Arguments passed to the utility.
260 .RE
261
262 .SH EXIT STATUS
263 .LP
264 In interactive and non-interactive modes, the \fBzlogin\fR utility exits when
265 the command or shell in the non-global zone exits. In non-interactive mode, the
266 exit status of the remote program is returned as the exit status of
267 \fBzlogin\fR. In interactive mode and console login mode, the exit status is
268 not returned. \fBzlogin\fR returns a \fB0\fR exit status as long as no
269 connection-related error occurred.
270 .sp
271 .LP
272 In all modes, in the event that a connection to the zone cannot be established,
273 the connection fails unexpectedly, or the user is lacking sufficient privilege
274 to perform the requested operation, \fBzlogin\fR exits with status \fB1\fR.
275 .sp
276 .LP
277 To summarize, the following exit values are returned:
278 .sp
279 .ne 2
280 .na
281 \fB\fB0\fR\fR
282 .ad
287 .sp
288 .ne 2
289 .na
290 \fB\fB1\fR\fR
291 .ad
292 .RS 7n
293 Permission denied, or failure to enter the zone.
294 .RE
295
296 .sp
297 .ne 2
298 .na
299 \fBAny\fR
300 .ad
301 .RS 7n
302 Return code from utility, or from \fBsu\fR(1M) if operating in non-interactive
303 mode.
304 .RE
305
306 .SH ATTRIBUTES
307 .LP
308 See \fBattributes\fR(5) for descriptions of the following attributes:
309 .sp
310
311 .sp
312 .TS
313 box;
314 c | c
315 l | l .
316 ATTRIBUTE TYPE ATTRIBUTE VALUE
317 _
318 Interface Stability Evolving
319 .TE
320
321 .SH SEE ALSO
322 .LP
323 \fBlogin\fR(1), \fBrsh\fR(1), \fBvi\fR(1), \fBsu\fR(1M), \fBzoneadm\fR(1M),
324 \fBzonecfg\fR(1M), \fBattributes\fR(5), \fBzones\fR(5)
325 .SH NOTES
326 .LP
327 \fBzlogin\fR fails if its open files or any portion of its address space
328 corresponds to an NFS file. This includes the executable itself or the shared
329 libraries.
|