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.

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:

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

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:

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:

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