usr/src/man/man1/zlogin.1

   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
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fB-e\fR \fIc\fR\fR
 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
 247 .RS 7n
 248 Successful entry.
 249 .RE
 250
 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.