'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH ZLOGIN 1 "Dec 18, 2006"
.SH NAME
zlogin \- enter a zone
.SH SYNOPSIS
.LP
.nf
\fBzlogin\fR [\fB-CE\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR
.fi

.LP
.nf
\fBzlogin\fR [\fB-ES\fR] [\fB-e\fR \fIc\fR] [\fB-l\fR \fIusername\fR] \fIzonename\fR \fIutility\fR
     [\fIargument\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBzlogin\fR utility is used by the administrator to enter an operating
system zone. Only a superuser operating in the global system zone can use this
utility.
.sp
.LP
\fBzlogin\fR operates in one of three modes:
.sp
.ne 2
.na
\fBInteractive Mode\fR
.ad
.RS 24n
If no utility argument is given and the stdin file descriptor for the
\fBzlogin\fR process is a tty device, \fBzlogin\fR operates in \fBinteractive
mode\fR. In this mode, \fBzlogin\fR creates a new pseudo terminal for use
within the login session. Programs requiring a tty device, for example,
\fBvi\fR(1), work properly in this mode. In this mode, \fBzlogin\fR invokes
\fBlogin\fR(1) to provide a suitable login session.
.RE

.sp
.ne 2
.na
\fBNon-Interactive Mode\fR
.ad
.RS 24n
If a utility is specified, \fBzlogin\fR operates in \fBnon-interactive mode\fR.
This mode can be useful for script authors since stdin, stdout, and stderr are
preserved and the exit status of \fIutility\fR is returned upon termination. In
this mode, \fBzlogin\fR invokes \fBsu\fR(1M) in order to set up the user's
environment and to provide a login environment.
.sp
The specified command is passed as a string and interpreted by a shell running
in the non-global zone. See \fBrsh\fR(1).
.RE

.sp
.ne 2
.na
\fBConsole Mode\fR
.ad
.RS 24n
If the \fB-C\fR option is specified, the user is connected to the zone console
device and \fBzlogin\fR operates in \fBconsole mode\fR. The zone console is
available once the zone is in the installed  state. Connections to the console
are persistent across reboot of the zone.
.RE

.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-C\fR\fR
.ad
.RS 15n
Connects to the zone console.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR \fIc\fR\fR
.ad
.RS 15n
Specifies a different escape character, \fIc\fR, for the key sequence used to
access extended functions and to disconnect from the login. The default escape
character is the tilde (\fB~\fR).
.RE

.sp
.ne 2
.na
\fB\fB-E\fR\fR
.ad
.RS 15n
Disables the ability to access extended functions or to disconnect from the
login by using the escape sequence character.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fIusername\fR\fR
.ad
.RS 15n
Specifies a different \fIusername\fR for the zone login. If you do not use this
option, the zone username used is "root". This option is invalid if the
\fB-C\fR option is specified.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR\fR
.ad
.RS 15n
"Safe" login mode. \fBzlogin\fR does minimal processing and does not invoke
\fBlogin\fR(1) or \fBsu\fR(1M). The \fB-S\fR option can not be used if a
username is specified through the \fB-l\fR option, and cannot be used with
console logins. This mode should only be used to recover a damaged zone when
other forms of login have become impossible.
.RE

.SS "Escape Sequences"
.sp
.LP
Lines that you type that start with the tilde character (\fB~\fR) are "escape
sequences". The escape character can be changed using the \fB-e\fR option.
.sp
.ne 2
.na
\fB\fB~.\fR\fR
.ad
.RS 6n
Disconnects from the zone. This is not the same as a logout, because the local
host breaks the connection with no warning to the zone's end.
.RE

.SH SECURITY
.sp
.LP
Once a process has been placed in a zone other than the global zone, the
process cannot change zone again, nor can any of its children.
.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIzonename\fR\fR
.ad
.RS 15n
The name of the zone to be entered.
.RE

.sp
.ne 2
.na
\fB\fIutility\fR\fR
.ad
.RS 15n
The utility to be run in the specified zone.
.RE

.sp
.ne 2
.na
\fB\fIargument...\fR\fR
.ad
.RS 15n
Arguments passed to the utility.
.RE

.SH EXIT STATUS
.sp
.LP
In interactive and non-interactive modes, the \fBzlogin\fR utility exits when
the command or shell in the non-global zone exits. In non-interactive mode, the
exit status of the remote program is returned as the exit status of
\fBzlogin\fR. In interactive mode and console login mode, the exit status is
not returned. \fBzlogin\fR returns a \fB0\fR exit status as long as no
connection-related error occurred.
.sp
.LP
In all modes, in the event that a connection to the zone cannot be established,
the connection fails unexpectedly, or the user is lacking sufficient privilege
to perform the requested operation, \fBzlogin\fR exits with status \fB1\fR.
.sp
.LP
To summarize, the following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 7n
Successful entry.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 7n
Permission denied, or failure to enter the zone.
.RE

.sp
.ne 2
.na
\fBAny\fR
.ad
.RS 7n
Return code from utility, or from \fBsu\fR(1M) if operating in non-interactive
mode.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBlogin\fR(1), \fBrsh\fR(1), \fBvi\fR(1), \fBsu\fR(1M), \fBzoneadm\fR(1M),
\fBzonecfg\fR(1M), \fBattributes\fR(5), \fBzones\fR(5)
.SH NOTES
.sp
.LP
\fBzlogin\fR fails if its open files or any portion of its address space
corresponds to an NFS file. This includes the executable itself or the shared
libraries.