'\" te
.\" Copyright (c) 2009, 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 VNTSD 1M "Mar 31, 2009"
.SH NAME
vntsd \- virtual network terminal server daemon for Logical Domains
.SH SYNOPSIS
.LP
.nf
\fB/usr/lib/ldoms/vntsd\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBvntsd\fR daemon is a server that supports connections to the Logical
Domains (LDoms) console by using \fBtelnet\fR(1). When a \fBtelnet\fR session
starts, \fBvntsd\fR sends \fBtelnet\fR options to the client indicating a
willingness to remotely echo characters and to suppress go ahead.
.sp
.LP
Consoles are organized into groups by the LDoms Manager. Each console group is
assigned a unique group name and TCP port number. \fBvntsd\fR uses the group's
port number to export access to the consoles within that group. To establish a
connection with a console or console group, a user starts a \fBtelnet\fR(1)
session with the corresponding group's port number. Depending on the number of
consoles within that group, \fBvntsd\fR does one of two things:
.RS +4
.TP
.ie t \(bu
.el o
If there is only one console in the group, \fBvntsd\fR connects a session to
that LDoms console.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If there are multiple consoles in the group, \fBvntsd\fR prompts the user to
select the console to which they would like to connect, as shown in
"Multiple-Console Options," below.
.RE
.sp
.LP
For each console, \fBvntsd\fR provides write access only to the first user
connecting to the console. Subsequent users connecting to the console are
allowed only to read from the console and wait for write access. When the first
user disconnects, write privileges are transferred to the next user waiting in
the queue. If a user who does not have write privileges attempts to write to a
console, the \fBvntsd\fR displays the following message:
.sp
.in +2
.nf
You do not have write access
.fi
.in -2

.sp
.LP
A user who has no write access can acquire write access forcibly by using the
\fB~w\fR special console command, described in "Special Console Commands,"
below.
.sp
.LP
\fBvntsd\fR can be invoked only with superuser privileges or by someone in the
Primary Administrator role.
.SH OPTIONS
.sp
.LP
The options for \fBvntsd\fR are divided into multiple-console options and
console commands.
.SS "Multiple-Console Options"
.sp
.LP
The options listed below are supported when there are multiple LDoms consoles
in a group. The syntax for the use of these options is:
.sp
.in +2
.nf
\fI<hostname>\fR-vnts-\fI<group-name>\fR: \fI<option>\fR
.fi
.in -2

.sp
.LP
For example:
.sp
.in +2
.nf
myhost-vnts-salesgroup: h
.fi
.in -2

.sp
.LP
The \fBh\fR option invokes help, as described below.
.sp
.ne 2
.na
\fB\fBh\fR\fR
.ad
.sp .6
.RS 4n
Display the following help text:
.sp
.in +2
.nf
h -- this help
l -- list of consoles
q -- quit
c{id}, n{name} -- connect to console of domain {id} or domain name
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBl\fR\fR
.ad
.sp .6
.RS 4n
List all consoles in the group. For example:
.sp
.in +2
.nf
DOMAIN ID       DOMAIN NAME     DOMAIN STATE
0               ldg1            online
1               ldg2            connected
\&...             ...             ...
.fi
.in -2

The two domain states and their meanings are:
.sp
.ne 2
.na
\fB\fBonline\fR\fR
.ad
.sp .6
.RS 4n
No one is connected to the console.
.RE

.sp
.ne 2
.na
\fB\fBconnected\fR\fR
.ad
.sp .6
.RS 4n
At least one user is already connected to the console.
.RE

.RE

.sp
.ne 2
.na
\fB\fBq\fR\fR
.ad
.sp .6
.RS 4n
Disconnect from \fBvntsd\fR.
.RE

.sp
.ne 2
.na
\fB\fBc\fI{id}\fR, n\fI{name}\fR\fR\fR
.ad
.sp .6
.RS 4n
Connect to specified console. Upon connection, the following message is
displayed:
.sp
.in +2
.nf
Connecting to console \fI<domain-name>\fR in group \fI<group-name>\fR
Press ~? for control options ....
.fi
.in -2

.RE

.SS "Special Console Commands"
.sp
.LP
A tilde (\fB~\fR) appearing as the first character of a line is an escape
signal that directs \fBvntsd\fR to perform a special console command. The
tilde-tilde (\fB~~\fR) sequence outputs a tilde. In conjunction with the
initial tilde, \fBvntsd\fR accepts the following special console commands:
.sp
.ne 2
.na
\fB\fB~.\fR\fR
.ad
.sp .6
.RS 4n
Disconnect from the console or console group.
.RE

.sp
.ne 2
.na
\fB\fB~w\fR\fR
.ad
.sp .6
.RS 4n
Force write access to the console.
.RE

.sp
.ne 2
.na
\fB\fB~p\fR\fR
.ad
.sp .6
.RS 4n
Disconnect from this console, and connect to the console that precedes this
console in the list of consoles.
.RE

.sp
.ne 2
.na
\fB\fB~n\fR\fR
.ad
.sp .6
.RS 4n
Disconnect from this console, and connect to the console that follows this
console in the list of consoles.
.RE

.sp
.ne 2
.na
\fB\fB~#\fR\fR
.ad
.sp .6
.RS 4n
Send break.
.RE

.sp
.ne 2
.na
\fB\fB~^B\fR\fR
.ad
.sp .6
.RS 4n
Send alternate break.
.RE

.sp
.ne 2
.na
\fB\fB~?\fR\fR
.ad
.sp .6
.RS 4n
Display \fBvntsd\fR help, as follows:
.sp
.in +2
.nf
~# - Send break
~^B - Send alternate break
~. - Exit from this console
~w - Force write access
~n - Console next
~p - Console previous
~? - Help
.fi
.in -2

.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/lib/ldoms/vntsd\fR\fR
.ad
.sp .6
.RS 4n
Binary executable \fBvntsd\fR file.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/ldoms/vntsd.xml\fR\fR
.ad
.sp .6
.RS 4n
Service management facility (\fBsmf\fR(5)) manifest file for \fBvntsd\fR.
.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
\fBtelnet\fR(1), \fBsvccfg\fR(1M), \fBusermod\fR(1M), \fBauth_attr\fR(4),
\fBattributes\fR(5), \fBsmf\fR(5)
.SH NOTES
.sp
.LP
The \fBvntsd\fR is managed by the service management facility, \fBsmf\fR(5),
under the service identifier:
.sp
.in +2
.nf
svc:/ldoms/vntsd
.fi
.in -2

.sp
.LP
You can change the following properties using the \fBsvccfg\fR(1M) command:
.sp
.ne 2
.na
\fB\fBvntsd/vcc_device\fR\fR
.ad
.sp .6
.RS 4n
Set an instance of the virtual console concentrator (\fBvcc\fR) driver to which
\fBvntsd\fR is connected.
.RE

.sp
.ne 2
.na
\fB\fBvntsd/listen_addr\fR\fR
.ad
.sp .6
.RS 4n
Set the IP address to which \fBvntsd\fR listens, using the following syntax:
.sp
.in +2
.nf
vntsd/listen_addr:"\fIxxx.xxx.xxx.xxx\fR"
.fi
.in -2

\&...where \fIxxx.xxx.xxx.xxx\fR is a valid IP address. The default value of
this property is to listen on IP address 127.0.0.1. Users can connect to a
guest console over a network if the value is set to the IP address of the
control domain.
.LP
Note -
.sp
.RS 2
Enabling network access to a console has security implications. Any user can
connect to a console and for this reason it is disabled by default.
.RE
.RE

.sp
.ne 2
.na
\fB\fBvntsd/timeout_minutes\fR\fR
.ad
.sp .6
.RS 4n
Set timeout in minutes. \fBvntsd\fR will timeout (close) \fBtelnet\fR
connection if there is no activity (input or output) on the console. The
default value is 0, which disables timeout.
.RE

.sp
.ne 2
.na
\fB\fBvntsd/authorization\fR\fR
.ad
.sp .6
.RS 4n
Enable the authorization checking of users and roles for the domain console or
consoles that are being accessed. The default value of this property is
\fBfalse\fR to maintain backward compatibility. To enable authorization
checking, use the \fBsvccfg\fR(1M) command to set the property value to
\fBtrue\fR. While this option is enabled, \fBvntsd\fR listens and accepts
connections on \fBlocalhost\fR. If the \fBlisten_addr\fR property specifies an
alternate IP address when this option is enabled, \fBvntsd\fR ignores the
alternate IP address and continues to listen on \fBlocalhost\fR. Connections
that are initiated from other hosts will also fail. Authorizations are
available to access all consoles or console groups, or to access specific
consoles or console groups. When the \fBvntsd\fR service is enabled, the
following authorization is added to the authorization description database,
\fBauth_attr\fR(4):
.sp
.in +2
.nf
solaris.vntsd.consoles:::Access All LDoms Guest Consoles::
.fi
.in -2
.sp

Add any fine-grained authorizations based on the name of the console group. For
example, if the name of the console group to be authorized is \fBldg1\fR, add
the following entry to the \fBauth_attr\fR(4) file:
.sp
.in +2
.nf
solaris.vntsd.console-ldg1:::Access Specific LDoms Guest Console::
.fi
.in -2
.sp

By default, the authorization to access all consoles is assigned to the root
user or role. The Primary Administrator (superuser) can use the
\fBusermod\fR(1M) command to assign the required authorization or
authorizations to other users or roles.
.sp
The following example gives user \fBuser1\fR the authorization to access all
domain consoles:
.sp
.in +2
.nf
# \fBusermod -A "solaris.vntsd.consoles" user1\fR
.fi
.in -2
.sp

The following example gives user \fBuser1\fR the authorization to access the
console group named \fBldg1\fR:
.sp
.in +2
.nf
# \fBusermod -A "solaris.vntsd.console-ldg1" user1\fR
.fi
.in -2
.sp

.RE