restrict-shell(8)

NAME

restrict-shell - login shell giving a user the console of their own zone only

SYNOPSIS

/opt/omnicube/sbin/restrict-shell

DESCRIPTION

restrict-shell is a login shell, not an interactive one. It is meant to be the shell of an unprivileged account that must be able to reach the console of exactly one zone - the zone whose name is the account's own login name - and nothing else on the host. The account owner never obtains a command prompt on the global zone: when the console session ends, the shell logs out.

On invocation it performs, in order:

1.: Validates LOGNAME against ^[a-zA-Z_][a-zA-Z0-9._-]*$. LOGNAME is used both in a process-table match and in the privileged kill-target chain, so an unusual login name containing regular-expression metacharacters, whitespace or shell escapes is refused immediately.
2.: Echoes the login name, so the operator can see which zone is about to be entered.
3.: Looks for a stale console session for this user's zone by scanning ps -eo pid= -o args= for a zlogin process whose argument list contains -C LOGNAME (the match is done with awk index(), so the zone name is compared literally and no metacharacter can widen it). Every pid found is passed to pfexec /opt/omnicube/sbin/restrict-shell-cmd kill pid, which re-validates the target before signalling it. Ownership cannot be used for this match, because the console process runs as root.
4.: Prints the hint Use #~ to exit.
5.: Runs pfexec /opt/omnicube/sbin/restrict-shell-cmd zlogin LOGNAME, which is the only way this shell can start anything.
6.: Runs the logout builtin and exits 0 when the console session ends.

All privileged work is delegated to restrict-shell-cmd(8); restrict-shell itself runs entirely with the calling user's identity and holds no privilege. The pair is deliberately split this way so that only the small helper that validates its own arguments carries an exec_attr entry.

The shell sets its own PATH to /usr/bin:/usr/sbin:/sbin:/opt/ooce/bin:/usr/gnu/bin and does not source /opt/omnicube/lib/common/utils.sh, so none of the usual OmniCube SMF configuration, locking or run-level guard applies to it.

OPERANDS

This command takes no options and no operands. Anything passed on the command line is ignored; the zone to enter is determined solely by LOGNAME.

USAGE

Example 1: create a console account for zone win2022

The login name must equal the zone name, and the account needs the RBAC profile that allows it to run the privileged helper:

useradd -s /opt/omnicube/sbin/restrict-shell -m win2022
usermod -P 'OmniCube Restricted Shell' win2022
passwd win2022

usermod -P replaces the profiles= list in user_attr(5) — illumos has no + modifier — so on an account that already holds profiles, pass the whole comma-separated list. Verify with profiles -l win2022.

Example 2: restrict an ssh key to the zone console

Wiring the same shell in as a forced command keeps the restriction in place even for a key on an account whose shell is something else. In sshd_config:

Match User win2022
    ForceCommand /opt/omnicube/sbin/restrict-shell
    PermitTTY yes
    AllowTcpForwarding no
    X11Forwarding no
    PermitTunnel no

Per-key equivalent in authorized_keys:

command="/opt/omnicube/sbin/restrict-shell",no-port-forwarding,\\
no-agent-forwarding,no-X11-forwarding ssh-ed25519 AAAA... op@ws

Example 3: what the session looks like

$ ssh win2022@node1
win2022
Use #~ to exit
[Connected to zone 'win2022' console]

EXIT STATUS

0: The console session ran and ended normally. This is also returned when restrict-shell-cmd refuses the request, since its status is not propagated.
1: LOGNAME is unset or not a valid login name; nothing was attempted.

FILES

/opt/omnicube/sbin/restrict-shell: This shell.
/opt/omnicube/sbin/restrict-shell-cmd: The privileged helper that performs the zlogin and the kill on its behalf.
/etc/security/prof_attr.d/omnicube: Defines the OmniCube Restricted Shell profile, described as "Console access to the zone matching the login name".
/etc/security/exec_attr.d/omnicube: Grants that profile euid=0 execution of restrict-shell-cmd and nothing else.

ENVIRONMENT

LOGNAME: The login name, which is also the name of the zone whose console will be opened. Validated as described above; there is no option to override it.
PATH: Ignored on entry and reset by the shell.

SECURITY

The intent is containment by construction: the account has no shell, no argument it supplies is used, and the single privileged operation it can reach is parameterised only by its own login name.

LOGNAME is attacker-controlled in principle, but spoofing it buys nothing: restrict-shell-cmd(8) independently re-derives the caller from the real uid, which is preserved because its exec_attr entry uses euid=0 rather than uid=0. The validation here only fails fast with a clear message. Likewise, a wrong pid discovered by the ps scan is rejected by the helper rather than acted upon.

The account must hold the OmniCube Restricted Shell profile only. It must not hold OmniCube Administration, which is root-equivalent.

NOTES

The console is spawned by the helper as zlogin -e '#' -C zone, so the escape character is # and the sequence that disconnects the console is #.amp;. The hint printed by this shell says Use #~ to exit, which does not match that escape sequence; use #. to leave the console.

Because the exit status of the helper is not propagated, a refused or failed console attempt is indistinguishable from a normal logout for anything that inspects the shell's status. The refusal message itself is printed on standard error.

The shell assumes the convention that a zone's console account is named after the zone. An account whose name does not match a configured zone gets a refusal from the helper and an immediate logout.