.\" Open Infrastructure: compute-tools
.\"
.\" Copyright (C) 2014-2022 Daniel Baumann <daniel.baumann@open-infrastructure.net>
.\"
.\" SPDX-License-Identifier: GPL-3.0+
.\"
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
.\"
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "CONTAINER-SHELL" 1  compute-tools "Open Infrastructure"
.SH NAME
container-shell \- Manage systemd-nspawn containers (shell)
.SH SYNOPSIS
.nf
\fBcontainer\-shell\fP [\(aqOPTIONS\(aq]
\fBcntsh\fP [\(aqOPTIONS\(aq]
.fi
.sp
.SH DESCRIPTION
.sp
compute\-tools provides the system integration for managing containers using
systemd\-nspawn.
.SS Usage
.sp
Although the \fBcontainer\-shell\fP can be started from a running system like any
other program, the main intend is to use the \fBcontainer\-shell\fP via SSH. That
way otherwise unprivileged users have possibility to manage containers without
needing a regular shell login on the container server.
.sp
For usage over SSH a unprivileged user should be created:
.nf

.in +2
sudo adduser \-\-gecos \(dqcompute\-tools,,,\(dq \e
.in +2
\-\-home /var/lib/open\-infrastructure/container\-shell \e
\-\-shell /usr/bin/container\-shell
.in -2
.in -2
.fi
.sp
.sp
The container\-shell can then be allowed for specific SSH keys via
/var/lib/compute\-tools/container\-shell/.ssh/authorized_keys like so:
.nf

.in +2
command=\(dq/usr/bin/container\-shell\(dq,no\-port\-forwarding,no\-X11\-forwarding,\e
.in +2
no\-agent\-forwarding,no\-pty ssh\-ed25519 [...]
.in -2
.in -2
.fi
.sp
.SS Restricted shell
.sp
The container\-shell by default grants any user that has access to it to use all available container commands.
.sp
Through two corresponding environment variables users can be allowed or disallowed to use specific container commands.
In connection with SSH this makes it possible to grant certain SSH keys (and by that, users) privileges to operate container
servers without having to give them root access, a login shell at all and prevents them from doing things they are not trusted to do.
.SS Example (blacklisting)
.sp
In order to allow all commands except for removing and stopping containers, the
following variable can be used:
.nf

.in +2
command=\(dqCONTAINER_COMMANDS_DISABLE=\(aqremove stop\(aq \e
.in +2
/usr/bin/container\-shell\(dq,no\-port\-forwarding,no\-X11\-forwarding,\e
no\-agent\-forwarding,no\-pty ssh\-ed25519 [...]
.in -2
.in -2
.fi
.sp
.SS Example (whitelisting)
.sp
The other way around works too. To disallow all commands except for listing
containers and showing the compute\-tools version, the following variable can be
used:
.nf

.in +2
command=\(dqCONTAINER_COMMANDS_ENABLE=\(aqlist version\(aq \e
.in +2
/usr/bin/container\-shell\(dq,no\-port\-forwarding,no\-X11\-forwarding,\e
no\-agent\-forwarding,no\-pty ssh\-ed25519 [...]
.in -2
.in -2
.fi
.sp
.SH COMMANDS
.sp
All container commands are available, see container(1). Additionally, the
following commands are specific to container\-shell:
.INDENT 0.0
.TP
.B about:
Shows introduction (manpage).
.TP
.B help:
Shows available commands within the container\-shell.
.TP
.B help COMMAND:
Shows help (manpage) for a specific container command.
.TP
.B logout, exit:
Exits container\-shell.
.UNINDENT
.SH SEE ALSO
.nf
compute\-tools(7),
container(1).
.fi
.sp
.SH HOMEPAGE
.sp
More information about compute\-tools and the Open Infrastructure project can be
found on the homepage (\fI\%https://open\-infrastructure.net\fP).
.SH CONTACT
.sp
Bug reports, feature requests, help, patches, support and everything else are
welcome on the Open Infrastructure Software Mailing List
<\fI\%software@lists.open\-infrastructure.net\fP>.
.sp
Debian specific bugs can also be reported in the Debian Bug Tracking System
(\fI\%https://bugs.debian.org\fP).
.SH AUTHORS
.sp
compute\-tools were written by Daniel Baumann
<\fI\%daniel.baumann@open\-infrastructure.net\fP> and others.
.