ts-shell(1)

📦 version 2.44.1, in opensuse-leap 16.0

🌸 NAME 🌸

Okay bestie, meet ts-shell(1) — the Login shell for terminal servers over z/VM IUCV, aka the Terminal Server over IUCV manual page. It's literally the login shell for terminal server environments using the IUCV terminal applications, and it's kind of a big deal. 💅

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

Okay so ts-shell is a login shell for terminal server environments using the IUCV terminal applications. It 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. No cap. 🫶

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. Iconic behavior, honestly. ✨

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. Main character energy for real. 👑

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. That's the vibe check passing. 🌈

🎀 OPTIONS 🎀

  • -h, --help — Displays a short help text, then exits. Cute and quick.
  • -v, --version — Displays the version information, then exits. Gotta know what you're running, bestie.

🦋 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. Bye bestie! 👋

help — Display the help about terminal server shell commands.

version — Display the ts-shell version.

💖 CONFIGURATION 💖

okay so to set up a Linux system as a terminal server and to use ts-shell for Linux users, you gotta complete these configuration steps, bestie:

  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. like, it literally needs permission to talk to the other guests, no cap.

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. iykyk ✨

🎀 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 (default: /etc/iucvterm/ts-systems.conf) — specifies a file that lists z/VM guest virtual machines. ts-shell permits connections to these z/VM guest virtual machines only. See also the section “List z/VM guest virtual machines providing terminal access over IUCV”.
  • ts-authorization (default: /etc/iucvterm/ts-authorization.conf) — specifies a file containing the terminal authorization definitions for Linux users. See the section “Configure terminal authorization for Linux users” about the file format.
  • transcript-systems (default: /etc/iucvterm/ts-audit-systems.conf) — specifies a file that lists z/VM guest virtual machines for which terminal sessions are logged. See the section “Configure terminal session transcripts” for details.
  • transcript-directory (default: /var/log/ts-shell) — specifies a directory where the terminal session transcripts are saved. See the section “Configure terminal session transcripts” for details.
  • pager (default: /usr/bin/less) — specifies the path to a pager program to paginate output of ts-shell commands.

🦋 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 option 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 the 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 the 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
  1. Change the login shell of a particular Linux user using the chsh(1) program:
chsh -s $(which ts-shell) alice

📁 FILES 📁

okay bestie, here's the whole map of where this thing keeps its stuff ✨ every single one of these paths is real and load-bearing, so pay attention 💅

/etc/iucvterm/ts-shell.conf

the general terminal server shell configuration file, like the main character of the config folder 👑

/etc/iucvterm/ts-systems.conf, /etc/iucvterm/unrestricted.conf

so these two are a little duo 🫶 and they do different jobs:

  • the ts-systems.conf file lists the z/VM guest virtual machines that connections are permitted to. no cap, that's the whole list.
  • unrestricted.conf contains [*ALL*] — literally the "let her cook" setting — which permits ts-shell(1) to connect to any z/VM guest virtual machine 🌈

and fun fact: the ts-systems configuration option in the ts-shell.conf file might specify one of these files. so like, ts-shell.conf is the one picking which list you're using. iykyk 🎀

/etc/iucvterm/ts-authorization.conf

this one is the bouncer at the door 🚪✨ the ts-authorization.conf file grants Linux users or groups the ability to establish terminal connections only to particular z/VM guest virtual machines. so it's not "can you get in", it's "which specific guests can you get to". lowkey iconic gatekeeping ngl

/etc/iucvterm/ts-audit-systems.conf

the ts-audit-systems.conf file lists the z/VM guest virtual machines for which terminal sessions are logged 📝💀 so if you're on this list, bestie, everything you do is getting written down. be normal about it 🙈

/var/log/ts-shell

the directory for saving terminal session transcripts 🍓 that's where the receipts live. literally all of them.

🌸 ENVIRONMENT 🌸

just one variable here and she's important:

  • LESSSECURE — ts-shell sets this variable to run less(1) in "secure" mode 🔒✨. see the SECURITY section in the less(1) man page for the full tea, because like… it matters.
bestie please don't mess with this one, it's set for a reason 💅

👑 SEE ALSO 👑

you want more reading? bet, i have a whole stack for you 🥞 go read these, they're all part of the lore:

and the big-girl documents too, no skipping 📚:

  • Linux on System z - Device Drivers, Features, and Commands
  • z/VM CP Planning and Administration

aaaand that's the whole page, you made it to the end 🎉🦋

this gorgeous piece of documentation is from s390-tools, dated March 2009, and it's the ts-shell(1) manual page 💖 slay, go connect to some z/VM guests responsibly, and remember: read the SECURITY section. periodt 💅✨

📦 where this page comes from