mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
b627b8d8e1
This commit is based on the s390-tools-1.39.0 version. Changes on top of s390-tools-1.39.0: - Add MIT license to all source files - Add LICENSE file - Transform REAMDE to README.md (markdown) - Add AUTHORS.md file - Add CONTRIBUTING.md file - Move changelog from README to CHANGELOG.md file Reviewed-by: Stefan Haberland <sth@linux.vnet.ibm.com> Signed-off-by: Michael Holzheu <holzheu@linux.vnet.ibm.com>
575 lines
16 KiB
Groff
575 lines
16 KiB
Groff
.\" 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"
|