.\" ts-shell.1
.\"
.\"
.\" Copyright IBM Corp. 2008, 2017
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\" ----------------------------------------------------------------------
.TH "ts-shell" "1" "March 2009" "s390-tools" "Terminal Server over IUCV"
.
.
.
.SH "NAME"
ts\-shell \- Login shell for terminal servers over z/VM IUCV
.
.
.
.SH "SYNOPSIS"
.B ts\-shell
.RB [ \-h | \-\-help ]
.br
.B ts\-shell
.RB [ \-v | \-\-version ]
.
.
.
.SH "DESCRIPTION"
\fBts-shell\fP is a login shell for terminal server environments using the IUCV
terminal applications.
\fBts-shell\fP authorizes Linux users based on user names and group memberships
for accessing terminals.  Linux users can list the authorizations and access
terminals.  If a user is authorized to access a terminal, \fBts-shell\fP
establishes the terminal connection using the
.BR iucvconn (1)
program.

Apart from \fBiucvconn\fP the IUCV terminal applications include \fBiucvtty\fP.
.BR iucvtty (1)
provides full-screen terminal access to a Linux instance
running as a z/VM guest operating system.

.BR iucvconn (1)
can also establish terminal connections to z/VM IUCV hypervisor console (HVC)
device drivers. The Hypervisor Console (HVC) is a generic TTY device driver for
the Linux kernel providing terminals. One of the terminals can be used as the
Linux console.

The Linux instances where \fBts-shell\fP and \fBiucvconn\fP run and the target
Linux instance must be z/VM guest operating systems of the same z/VM instance.
Because z/VM IUCV is independent from TCP/IP, you can access Linux instances
with no external network connection.
.
.
.
.
.SH "OPTIONS"
.TP
.BR \-\^h ", " \-\^\-help
Display a short help text, then exit.
.
.TP
.BR \-\^v ", " \-\^\-version
Display the version information, then exit.
.
.
.
.SH "USAGE"
.SS "Terminal server shell commands"
The terminal server shell provides the following commands:
.PP
.TP 4
.B list
The \fBlist\fP command lists z/VM guest virtual machines to which the
Linux user is authorized to connect.

The output of the \fBlist\fP command depends on the configured authorization
method which can be "list" or "regex". The available authorization
methods are explained in section "Configure terminal authorization for Linux
users".

The output for "list" authorization is a list of z/VM guest virtual machines,
for example:
.ft CW
.in +0.25i
.nf

user@ts-shell> list
guest1
guest2
guest3
guest5

.fi
.in -0.25i
.ft
The output for "regex" authorization is a list of one or more
regular expressions, for example:
.ft CW
.in +0.25i
.nf

user@ts-shell> list
Regular expressions for your authorization:
(?i-xsm:lnx\\w{5})
(?i-xsm:^palim$)

.fi
.in -0.25i
.ft
If \fBts-shell\fP is configured to connect to particular z/VM guest virtual
machines only, the output for "regex" authorization is followed by a list of
the user IDs that match at least one of the regular expressions:
.ft CW
.in +0.25i
.nf

user@ts-shell> list
Regular expressions for your authorization:
(?i-xsm:lnx\\w{5})
(?i-xsm:^palim$)

You are authorized to connect to these z/VM guest virtual machines:
LNXSYS42
LNXSYS01

.fi
.in -0.25i
.ft

.
.TP 4
.B connect \fIvm_guest\fP \fR[\fP\fIterminal_id\fP\fR]\fP
\fBconnect\fP establishes a terminal connection to a particular z/VM guest
virtual machine specified as \fIvm_guest\fP.
\fIvm_guest\fP consists of up to eight alphanumeric characters.

An optional terminal identifier can be specified with \fIterminal_id\fP.
If not specified, the default terminal identifier is used.
To change the default terminal identifier, use the \fBterminal\fP command.

In the following example, a user opens a terminal connection to the Linux
instance in z/VM guest virtual machine LNXSYS01:
.ft CW
.in +0.25i
.nf

user@ts-shell> connect LNXSYS01
ts-shell: Connecting to LNXSYS01 (terminal identifier: lnxterm)...
  ...
ts-shell: Connection ended

.fi
.in -0.25i
.ft
.
.TP 4
.B terminal \fR[\fP\fIidentifier\fP\fR]\fP
The \fBterminal\fP command displays or sets the default terminal identifier
that is used by subsequent \fBconnect\fP commands.
\fIidentifier\fP is case-sensitive and consists of up to eight alphanumeric
characters.

If \fBterminal\fP is called with the \fIidentifier\fP being specified,
\fIidentifier\fP is set as the new default terminal identifier.
If \fIidentifier\fP is not specified, the current default terminal identifier
is displayed:

.ft CW
.in +0.25i
.nf
user@ts-shell> terminal
lnxterm
.fi
.in -0.25i
.ft
.
.TP 4
.BR quit ", " exit
Exit the terminal server shell session.
.
.TP 4
.B help
Display the help about terminal server shell commands.
.
.TP 4
.B version
Display the \fBts-shell\fP version.
.
.
.
.SH "CONFIGURATION"
To set up a Linux system as a terminal server and to use \fBts-shell\fP for
Linux users, complete the following configuration steps:
.IP "1." 4
Authorize the terminal server z/VM guest virtual machine for IUCV.
.IP "2." 4
Create a terminal server shell configuration file.
.IP "3." 4
List z/VM guest virtual machines providing terminal access over IUCV.
.IP "4." 4
Configure terminal session transcripts.
.IP "5." 4
Configure terminal authorizations for Linux users.
.IP "6." 4
Install \fBts-shell\fP as the login shell for Linux users.
.
.
.SS "Authorize the terminal server z/VM guest virtual machine for IUCV"
The z/VM guest virtual machine on which the terminal server shell runs needs
particular authorization to establish IUCV communication paths to other z/VM
guest virtual machines.

A typical \fBIUCV\fP authorization statement in the z/VM directory entry of the
terminal server z/VM guest virtual machine might be:
.PP
.ft CW
.in +0.25in
.nf
IUCV ANY
OPTION MAXCONN 256
.fi
.in -0.25in
.ft
.PP
The example allows the terminal server shell to establish IUCV communication
paths with any z/VM guest virtual machine.
The number of IUCV connections is limited to 256.

See the
.BR af_iucv (7)
manual page for further details.
.
.
.SS "Create a terminal server shell configuration file"
When \fBts-shell\fP starts, it reads its configuration from the
\fB/etc/iucvterm/ts-shell.conf\fP configuration file. The file contains
configuration options that specify further configuration files with lists
of z/VM guest virtual machines and terminal authorization definitions.
.PP
Supported configuration options (with default settings) are:
.RS 4
.TP
.BR ts-systems " = " \fI/etc/iucvterm/ts-systems.conf\fP
The \fBts-systems\fP configuration option specifies a file that
lists z/VM guest virtual machines. \fBts-shell\fP permits connections
to these z/VM guest virtual machines only.

See also section
"List z/VM guest virtual machines providing terminal access over IUCV".
.
.TP
.BR ts-authorization " = " \fI/etc/iucvterm/ts-authorization.conf\fP
The \fBts-authorization\fP option specifies a file containing
the terminal authorization definitions for Linux users.

See section "Configure terminal authorization for Linux users" about the file
format.
.
.TP
.BR transcript-systems " = " \fI/etc/iucvterm/ts-audit-systems.conf\fP
The \fBtranscript-systems\fP option specifies a file that lists
z/VM guest virtual machines for which terminal sessions are logged.

See section "Configure terminal session transcripts" for details.
.
.TP
.BR transcript-directory " = " \fI/var/log/ts-shell\fP
The \fBtranscript-directory\fP option specifies a directory where the terminal
session transcripts are saved.

See section "Configure terminal session transcripts" for details.
.
.RE
.
.
.SS "List z/VM guest virtual machines providing terminal access over IUCV"
\fBts-shell\fP establishes terminal connections only if a Linux user has been
authorized. In some cases, the administrator might want to explicitly restrict
connections to particular z/VM guest virtual machines independent of the user.

The \fBts-systems\fP configuration option specifies a file that lists z/VM
guest virtual machines to which \fBts-shell\fP is permitted to connect.
The file lists each z/VM guest virtual machine on a separate line.
If a line contains "[*ALL*]", \fBts-shell\fP is permitted to connect to any
z/VM guest virtual machine.
.
.TP
.B Note:
The \fBts-systems\fP options applies to the \fBts-shell\fP program only.
If necessary, further restrictions can be configured for the z/VM guest
virtual machine itself using the \fBIUCV\fP z/VM directory statement.
See the section about IUCV authorizations in the
.BR af_iucv (7)
manual page.
.
.
.SS "Create lists of z/VM guest virtual machines"
A convenient method for creating lists of z/VM guest virtual machines is to use
the information from the z/VM user directory, which contains all the names of
the z/VM guest virtual machines that are defined on a z/VM operating system
instance.

For example, to create a list of all z/VM guest virtual machines with names that
start with "LINUX" and are followed by digits, use:
.ft CW
.in +0.25in
.nf

vmur receive -H -t 1234 -O |grep -E "^USER LINUX[0-9]+" |cut -d" " -f2

.fi
.in -0.25in
.ft
Spool ID 1234 refers to the z/VM user directory file in the z/VM virtual
reader device.
.br
The output of the command can be saved in a file. The file can then be
specified for the
.BR ts-systems " or " transcript-systems
configuration options in the \fBts-shell.conf\fP file.
In addition, use these files to configure list authorizations.
.
.
.SS "Configure terminal session transcripts"
\fBts-shell\fP can create transcripts of terminal sessions to z/VM guest virtual
machines.

The \fBts-audit-systems.conf\fP configuration file lists z/VM guest virtual
machines for which terminal sessions are logged. If the file
contains "[*ALL*]", each terminal session is logged.
To create a list of z/VM guest virtual machines, see section
"Create lists of z/VM guest virtual machines".

For saving the terminal session transcripts, \fBts-shell\fP requires a directory
that is specified by the \fBtranscript-directory\fP option in the
\fBts-shell.conf\fP configuration file.
.TP
.B Note:
The terminal session transcript directory must be writable by all
\fBts-shell\fP users. The system administrator might use a "ts-shell" group
containing all \fBts-shell\fP users as members. The directory can be made
writable for the "ts-shell" group only.
.PP
\fBts-shell\fP uses a combination of the Linux user name, z/VM guest virtual
machine and a time stamp for creating new terminal session transcript files.

The format is as follows:
.br
.RS 4
.RI "/var/log/ts-shell/" user_name "/" VMGUEST "_" YY "-" MM "-" DD "-" HHMMSS
.RE
.PP
Terminal session transcripts consist of three different files: the raw
terminal data stream, timing data information and connection information.
See
.BR iucvconn (1)
for more details about terminal session transcripts.
.
.
.SS "Configure terminal authorizations for Linux users"
\fBts-shell\fP performs authorization checks for Linux users before connecting
to z/VM guest virtual machines.  The authorization configuration grants Linux
users or groups to establish terminal connections only to particular z/VM guest
virtual machines.  These authorization definitions are stored in the
\fBts-authorization.conf\fP configuration file.

This configuration file consists of authorization mappings where mappings can
be created for Linux users or groups.
For the specification of z/VM guest virtual machines, a list or regular
expression is used.
.br
A Linux user is referenced by the user name; a Linux group is referenced by the
group name and prefixed with "@".

Here is an example of a Linux user and group authorization:
.PP
.ft CW
.in +0.25in
.nf
alice  =  list:guest01,guest02
@users =  list:guest03,guest04
.fi
.in -0.25in
.ft
.PP
To create lists of z/VM guest virtual machines, use the following prefixes:
.RS 4
.IP "\fIlist:\fP" 8
followed by a comma-separated list of names.
.
.IP "\fIfile:\fP" 8
followed by a file path.  The file lists z/VM guest virtual machines, each
name on a separate line.
.RE
.
.PP
The following example shows the usage of the \fIfile:\fP prefix:
.PP
.ft CW
.in +0.25in
.nf
@testgrp = file:/etc/iucvterm/auth/test-systems.list
@prodgrp = file:/etc/iucvterm/auth/production-systems.list
.fi
.in -0.25in
.ft
.PP
See section "Create lists of z/VM guest virtual machines" above
about creating lists of z/VM guest virtual machines with names that
match a specific pattern.
.
.PP
Instead of listing each z/VM guest virtual machine individually, regular
expressions can be used to match names of z/VM guest virtual machines.
If naming schemes exist for z/VM guest virtual machines, using regular
expressions might be more efficient and allow for future additions.
.br
The \fIregex:\fP prefix starts the definition of a regular expression to match
the names of z/VM guest virtual machines. The regular expression must be a
Perl-compatible or an extended regular expression (ERE) as documented in POSIX.
Basic regular expressions (BRE) cannot be used. See
.BR regex (7)
for POSIX extended regular expressions; and the Perl reference manual
.BR perlre
about regular expression in Perl.

To authorize user bob for all z/VM guest virtual machines with names that
start with "lnx" and are followed with at least three but not more than five
alphanumeric characters, use:
.PP
.ft CW
.in +0.25in
.nf
bob = regex:lnx\\w{3,5}
.fi
.in -0.25in
.ft
.PP
.
If a naming scheme exists for z/VM guest virtual machines belonging to the
test or production environment: authorize all users in the "testgrp" group for
all systems in the test environment; and respectively, authorize all users in
the "prodgrp" group for all systems in the production environment:
.PP
.ft CW
.in +0.25in
.nf
@testgrp = regex:test\\w+
@prodgrp = regex:prod\\w+
.fi
.in -0.25in
.ft
.
.PP
You can have multiple authorizations for the same user, either directly through
user authorizations or indirectly through authorizations for groups that the
user is a member of.  Be aware that \fBts-shell\fP accepts only one type of
authorization, list or regex, for a particular user. The first type of
authorization that is found for a user sets the authorization type for this
user. Further authorizations of the same type are accumulated.  Authorizations
of the other type are ignored.

Example:
.PP
.ft CW
.in +0.25in
.nf
@users = list:guest01,guest03,guest05
alice = list:guest02,guest04
eve = regex:guest0[7890]
.fi
.in -0.25in
.ft
.PP
If both alice and eve are members of group users, alice is authorized for
guest01, guest02, guest03, guest04, and guest05. For eve, the regular expression
is ignored and the authorizations are for guest01, guest03, guest05 as defined
for the group.
.
.
.
.SS "Install ts-shell as login shell for Linux users"
To use the \fBts-shell\fP as the login shell for Linux users, follow these steps:
.IP "1." 4
Add the path of the \fBts-shell\fP program to the \fI/etc/shells\fP file that
contains the list of valid login shells:
.PP
.ft CW
.in +0.25in
.nf
echo $(which ts-shell) >> /etc/shells
.fi
.in -0.25in
.ft
.PP
.
.IP "2." 4
Change the login shell of a particular Linux user using the
.BR chsh (1)
program:
.PP
.ft CW
.in +0.25in
.nf
chsh -s $(which ts-shell) alice
.fi
.in -0.25in
.ft
.
.
.
.SH "FILES"
.TP
.B /etc/iucvterm/ts-shell.conf
General terminal server shell configuration file.
.
.TP
.BR /etc/iucvterm/ts-systems.conf ", " /etc/iucvterm/unrestricted.conf
The \fBts-systems.conf\fP file lists z/VM guest virtual machines to which
connections are permitted.
\fBunrestricted.conf\fP contains "[*ALL*]" to permit
.BR ts-shell (1)
to connect to any z/VM guest virtual machine.

The \fBts-systems\fP configuration option in the \fBts-shell.conf\fP file
might specify one of these files.
.
.TP
.B /etc/iucvterm/ts-authorization.conf
The \fBts-authorization.conf\fP file grants Linux users or groups to establish
terminal connections only to particular z/VM guest virtual machines.
.
.TP
.B /etc/iucvterm/ts-audit-systems.conf
The \fBts-audit-systems.conf\fP file lists z/VM guest virtual machines for which
terminal sessions are logged.
.
.TP
.B /var/log/ts-shell
Directory for saving terminal session transcripts.
.
.
.
.SH "ENVIRONMENT"
.TP
.B PAGER
The \fBPAGER\fP environment variable designates a program used as pager for the
\fBlist\fP command of the terminal server shell.
If \fBPAGER\fP is not set or empty,
.BR less (1)
is used.
.
.TP
.B LESSSECURE
\fBts-shell\fP sets this variable to run
.BR less (1)
in "secure" mode. See the SECURITY section in the
.BR less (1)
man page.
.
.
.
.SH "SEE ALSO"
.BR iucvconn (1),
.BR iucvtty (1),
.BR af_iucv (7),
.BR less (1),
.BR chsh (1),
.BR shells (5),
.BR regex (7),
.BR perlre

.I "Linux on System z - Device Drivers, Features, and Commands"
.br
.I "z/VM CP Planning and Administration"