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