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 .TH ZLOGIN 1 "Sep 8, 2013"
  16 .SH NAME
  17 zlogin \- enter a zone
  18 .SH SYNOPSIS
  19 .LP
  20 .nf
  21 \fBzlogin\fR [\fB-CEQ\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR
  22 .fi
  23 
  24 .LP
  25 .nf
  26 \fBzlogin\fR [\fB-EQS\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR \fIutility\fR
  27      [\fIargument\fR]...
  28 .fi
  29 
  30 .SH DESCRIPTION
  31 .sp
  32 .LP
  33 The \fBzlogin\fR utility is used by the administrator to enter an operating
  34 system zone. Only a superuser operating in the global system zone can use this
  35 utility.
  36 .sp
  37 .LP
  38 \fBzlogin\fR operates in one of three modes:
  39 .sp
  40 .ne 2
  41 .na
  42 \fBInteractive Mode\fR
  43 .ad
  44 .RS 24n
  45 If no utility argument is given and the stdin file descriptor for the
  46 \fBzlogin\fR process is a tty device, \fBzlogin\fR operates in \fBinteractive
  47 mode\fR. In this mode, \fBzlogin\fR creates a new pseudo terminal for use
  48 within the login session. Programs requiring a tty device, for example,
  49 \fBvi\fR(1), work properly in this mode. In this mode, \fBzlogin\fR invokes
  50 \fBlogin\fR(1) to provide a suitable login session.
  51 .RE
  52 
  53 .sp
  54 .ne 2
  55 .na
  56 \fBNon-Interactive Mode\fR
  57 .ad
  58 .RS 24n
  59 If a utility is specified, \fBzlogin\fR operates in \fBnon-interactive mode\fR.
  60 This mode can be useful for script authors since stdin, stdout, and stderr are
  61 preserved and the exit status of \fIutility\fR is returned upon termination. In
  62 this mode, \fBzlogin\fR invokes \fBsu\fR(1M) in order to set up the user's
  63 environment and to provide a login environment.
  64 .sp
  65 The specified command is passed as a string and interpreted by a shell running
  66 in the non-global zone. See \fBrsh\fR(1).
  67 .RE
  68 
  69 .sp
  70 .ne 2
  71 .na
  72 \fBConsole Mode\fR
  73 .ad
  74 .RS 24n
  75 If the \fB-C\fR option is specified, the user is connected to the zone console
  76 device and \fBzlogin\fR operates in \fBconsole mode\fR. The zone console is
  77 available once the zone is in the installed  state. Connections to the console
  78 are persistent across reboot of the zone.
  79 .RE
  80 
  81 .SH OPTIONS
  82 .sp
  83 .LP
  84 The following options are supported:
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fB-C\fR\fR
  89 .ad
  90 .RS 15n
  91 Connects to the zone console.
  92 .RE
  93 
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fB-e\fR \fIc\fR\fR
  98 .ad
  99 .RS 15n
 100 Specifies a different escape character, \fIc\fR, for the key sequence used to
 101 access extended functions and to disconnect from the login. The default escape
 102 character is the tilde (\fB~\fR).
 103 .RE
 104 
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fB-E\fR\fR
 109 .ad
 110 .RS 15n
 111 Disables the ability to access extended functions or to disconnect from the
 112 login by using the escape sequence character.
 113 .RE
 114 
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fB-l\fR \fIusername\fR\fR
 119 .ad
 120 .RS 15n
 121 Specifies a different \fIusername\fR for the zone login. If you do not use this
 122 option, the zone username used is "root". This option is invalid if the
 123 \fB-C\fR option is specified.
 124 .RE
 125 
 126 .sp
 127 .ne 2
 128 .na
 129 \fB-Q\fR
 130 .ad
 131 .RS 15n
 132 Specifies quiet mode operation.  In quiet mode, extra messages indicating the
 133 the function of \fBzlogin\fR will not be displayed, giving the possibility
 134 to present the appearance that the command is running locally rather than
 135 in another zone.
 136 .RE
 137 
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fB-S\fR\fR
 142 .ad
 143 .RS 15n
 144 "Safe" login mode. \fBzlogin\fR does minimal processing and does not invoke
 145 \fBlogin\fR(1) or \fBsu\fR(1M). The \fB-S\fR option can not be used if a
 146 username is specified through the \fB-l\fR option, and cannot be used with
 147 console logins. This mode should only be used to recover a damaged zone when
 148 other forms of login have become impossible.
 149 .RE
 150 
 151 .SS "Escape Sequences"
 152 .sp
 153 .LP
 154 Lines that you type that start with the tilde character (\fB~\fR) are "escape
 155 sequences". The escape character can be changed using the \fB-e\fR option.
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fB~.\fR\fR
 160 .ad
 161 .RS 6n
 162 Disconnects from the zone. This is not the same as a logout, because the local
 163 host breaks the connection with no warning to the zone's end.
 164 .RE
 165 
 166 .SH SECURITY
 167 .sp
 168 .LP
 169 Once a process has been placed in a zone other than the global zone, the
 170 process cannot change zone again, nor can any of its children.
 171 .SH OPERANDS
 172 .sp
 173 .LP
 174 The following operands are supported:
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fIzonename\fR\fR
 179 .ad
 180 .RS 15n
 181 The name of the zone to be entered.
 182 .RE
 183 
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fIutility\fR\fR
 188 .ad
 189 .RS 15n
 190 The utility to be run in the specified zone.
 191 .RE
 192 
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fIargument...\fR\fR
 197 .ad
 198 .RS 15n
 199 Arguments passed to the utility.
 200 .RE
 201 
 202 .SH EXIT STATUS
 203 .sp
 204 .LP
 205 In interactive and non-interactive modes, the \fBzlogin\fR utility exits when
 206 the command or shell in the non-global zone exits. In non-interactive mode, the
 207 exit status of the remote program is returned as the exit status of
 208 \fBzlogin\fR. In interactive mode and console login mode, the exit status is
 209 not returned. \fBzlogin\fR returns a \fB0\fR exit status as long as no
 210 connection-related error occurred.
 211 .sp
 212 .LP
 213 In all modes, in the event that a connection to the zone cannot be established,
 214 the connection fails unexpectedly, or the user is lacking sufficient privilege
 215 to perform the requested operation, \fBzlogin\fR exits with status \fB1\fR.
 216 .sp
 217 .LP
 218 To summarize, the following exit values are returned:
 219 .sp
 220 .ne 2
 221 .na
 222 \fB\fB0\fR\fR
 223 .ad
 224 .RS 7n
 225 Successful entry.
 226 .RE
 227 
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fB1\fR\fR
 232 .ad
 233 .RS 7n
 234 Permission denied, or failure to enter the zone.
 235 .RE
 236 
 237 .sp
 238 .ne 2
 239 .na
 240 \fBAny\fR
 241 .ad
 242 .RS 7n
 243 Return code from utility, or from \fBsu\fR(1M) if operating in non-interactive
 244 mode.
 245 .RE
 246 
 247 .SH ATTRIBUTES
 248 .sp
 249 .LP
 250 See \fBattributes\fR(5) for descriptions of the following attributes:
 251 .sp
 252 
 253 .sp
 254 .TS
 255 box;
 256 c | c
 257 l | l .
 258 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 259 _
 260 Interface Stability     Evolving
 261 .TE
 262 
 263 .SH SEE ALSO
 264 .sp
 265 .LP
 266 \fBlogin\fR(1), \fBrsh\fR(1), \fBvi\fR(1), \fBsu\fR(1M), \fBzoneadm\fR(1M),
 267 \fBzonecfg\fR(1M), \fBattributes\fR(5), \fBzones\fR(5)
 268 .SH NOTES
 269 .sp
 270 .LP
 271 \fBzlogin\fR fails if its open files or any portion of its address space
 272 corresponds to an NFS file. This includes the executable itself or the shared
 273 libraries.