ts-shell(1)

NAME
ts-shell - Login shell for terminal servers over z/VM IUCV

SYNOPSIS
ts-shell [-h|--help]
ts-shell [-v|--version]

DESCRIPTION
ts-shell is a login shell for terminal server environments using the IUCV terminal applications. ts-shell 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, ts-shell establishes the terminal connection using the iucvconn(1) program. Apart from iucvconn the IUCV terminal applications include iucvtty. iucvtty(1) provides full-screen terminal access to a Linux instance running as a z/VM guest operating system. 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 ts-shell and iucvconn 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.

OPTIONS

-h, --help
    Display a short help text, then exit.

-v, --version
    Display the version information, then exit.

USAGE

  Terminal server shell commands
The terminal server shell provides the following commands:

list
    The list command lists z/VM guest virtual machines to which the Linux user is authorized to connect. The output of the list 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:
    user@ts-shell> list
    guest1
    guest2
    guest3
    guest5
    The output for "regex" authorization is a list of one or more regular expressions, for example:
    user@ts-shell> list
    Regular expressions for your authorization:
    (?i-xsm:lnx\w{5})
    (?i-xsm:^palim$)
    If ts-shell 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:
    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

connect vm_guest [terminal_id]
    connect establishes a terminal connection to a particular z/VM guest virtual machine specified as vm_guest. vm_guest consists of up to eight alphanumeric characters. An optional terminal identifier can be specified with terminal_id. If not specified, the default terminal identifier is used. To change the default terminal identifier, use the terminal command. In the following example, a user opens a terminal connection to the Linux instance in z/VM guest virtual machine LNXSYS01:
    user@ts-shell> connect LNXSYS01
    ts-shell: Connecting to LNXSYS01 (terminal identifier: lnxterm)...
      ...
    ts-shell: Connection ended

terminal [identifier]
    The terminal command displays or sets the default terminal identifier that is used by subsequent connect commands. identifier is case-sensitive and consists of up to eight alphanumeric characters. If terminal is called with the identifier being specified, identifier is set as the new default terminal identifier. If identifier is not specified, the current default terminal identifier is displayed:
    user@ts-shell> terminal
    lnxterm

quit, exit
    Exit the terminal server shell session.

help
    Display the help about terminal server shell commands.

version
    Display the ts-shell version.

CONFIGURATION
To set up a Linux system as a terminal server and to use ts-shell for Linux users, complete the following configuration steps:

1.  Authorize the terminal server z/VM guest virtual machine for IUCV.

2.  Create a terminal server shell configuration file.

3.  List z/VM guest virtual machines providing terminal access over IUCV.

4.  Configure terminal session transcripts.

5.  Configure terminal authorizations for Linux users.

6.  Install ts-shell as the login shell for Linux users.

  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 IUCV authorization statement in the z/VM directory entry of the terminal server z/VM guest virtual machine might be:

IUCV ANY
OPTION MAXCONN 256

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 af_iucv(7) manual page for further details.

  Create a terminal server shell configuration file
When ts-shell starts, it reads its configuration from the /etc/iucvterm/ts-shell.conf configuration file. The file contains configuration options that specify further configuration files with lists of z/VM guest virtual machines and terminal authorization definitions.

Supported configuration options (with default settings) are:

    ts-systems = /etc/iucvterm/ts-systems.conf
        The ts-systems configuration option specifies a file that lists z/VM guest virtual machines. ts-shell permits connections to these z/VM guest virtual machines only. See also section "List z/VM guest virtual machines providing terminal access over IUCV".

    ts-authorization = /etc/iucvterm/ts-authorization.conf
        The ts-authorization option specifies a file containing the terminal authorization definitions for Linux users. See section "Configure terminal authorization for Linux users" about the file format.

    transcript-systems = /etc/iucvterm/ts-audit-systems.conf
        The transcript-systems 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.

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

  List z/VM guest virtual machines providing terminal access over IUCV
ts-shell 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 ts-systems configuration option specifies a file that lists z/VM guest virtual machines to which ts-shell is permitted to connect. The file lists each z/VM guest virtual machine on a separate line. If a line contains "[*ALL*]", ts-shell is permitted to connect to any z/VM guest virtual machine.

Note:
    The ts-systems options applies to the ts-shell program only. If necessary, further restrictions can be configured for the z/VM guest virtual machine itself using the IUCV z/VM directory statement. See the section about IUCV authorizations in the af_iucv(7) manual page.

  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:
vmur receive -H -t 1234 -O |grep -E "^USER LINUX[0-9]+" |cut -d" " -f2
Spool ID 1234 refers to the z/VM user directory file in the z/VM virtual reader device.
The output of the command can be saved in a file. The file can then be specified for the ts-systems or transcript-systems configuration options in the ts-shell.conf file. In addition, use these files to configure list authorizations.

  Configure terminal session transcripts
ts-shell can create transcripts of terminal sessions to z/VM guest virtual machines. The ts-audit-systems.conf 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, ts-shell requires a directory that is specified by the transcript-directory option in the ts-shell.conf configuration file.

Note:
    The terminal session transcript directory must be writable by all ts-shell users. The system administrator might use a "ts-shell" group containing all ts-shell users as members. The directory can be made writable for the "ts-shell" group only.

ts-shell 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:
    /var/log/ts-shell/user_name/VMGUEST_YY-MM-DD-HHMMSS

Terminal session transcripts consist of three different files: the raw terminal data stream, timing data information and connection information. See iucvconn(1) for more details about terminal session transcripts.

  Configure terminal authorizations for Linux users
ts-shell 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 ts-authorization.conf 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.
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:

alice  =  list:guest01,guest02
@users =  list:guest03,guest04

To create lists of z/VM guest virtual machines, use the following prefixes:

    list:
        followed by a comma-separated list of names.

    file:
        followed by a file path. The file lists z/VM guest virtual machines, each name on a separate line.

The following example shows the usage of the file: prefix:

@testgrp = file:/etc/iucvterm/auth/test-systems.list
@prodgrp = file:/etc/iucvterm/auth/production-systems.list

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.

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.
The regex: 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 regex(7) for POSIX extended regular expressions; and the Perl reference manual 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:

bob = regex:lnx\w{3,5}

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:

@testgrp = regex:test\w+
@prodgrp = regex:prod\w+

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 ts-shell 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:

@users = list:guest01,guest03,guest05
alice = list:guest02,guest04
eve = regex:guest0[7890]

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.

  Install ts-shell as login shell for Linux users
To use the ts-shell as the login shell for Linux users, follow these steps:

1.  Add the path of the ts-shell program to the /etc/shells file that contains the list of valid login shells:

echo $(which ts-shell) >> /etc/shells

2.  Change the login shell of a particular Linux user using the chsh(1) program:

chsh -s $(which ts-shell) alice

FILES

/etc/iucvterm/ts-shell.conf
    General terminal server shell configuration file.

/etc/iucvterm/ts-systems.conf, /etc/iucvterm/unrestricted.conf
    The ts-systems.conf file lists z/VM guest virtual machines to which connections are permitted. unrestricted.conf contains "[*ALL*]" to permit ts-shell(1) to connect to any z/VM guest virtual machine. The ts-systems configuration option in the ts-shell.conf file might specify one of these files.

/etc/iucvterm/ts-authorization.conf
    The ts-authorization.conf file grants Linux users or groups to establish terminal connections only to particular z/VM guest virtual machines.

/etc/iucvterm/ts-audit-systems.conf
    The ts-audit-systems.conf file lists z/VM guest virtual machines for which terminal sessions are logged.

/var/log/ts-shell
    Directory for saving terminal session transcripts.

ENVIRONMENT

PAGER
    The PAGER environment variable designates a program used as pager for the list command of the terminal server shell. If PAGER is not set or empty, less(1) is used.

LESSSECURE
    ts-shell sets this variable to run less(1) in "secure" mode. See the SECURITY section in the less(1) man page.

SEE ALSO
iucvconn(1), iucvtty(1), af_iucv(7), less(1), chsh(1), shells(5), regex(7), perlre Linux on System z - Device Drivers, Features, and Commands
z/VM CP Planning and Administration