Merging upstream version 20170722.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 132 insertions, 0 deletions

diff --git a/share/man/container-shell.1 b/share/man/container-shell.1
new file mode 100644
index 0000000..278ea0b
--- /dev/null
+++ b/share/man/container-shell.1
@@ -0,0 +1,132 @@
+'\" t
+.\"     Title: container
+.\"    Author: [see the "AUTHORS" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 20170701
+.\"    Manual: Open Infrastructure
+.\"    Source: container-tools
+.\"  Language: English
+.\"
+.TH "CONTAINER" "1" "20170701" "container\-tools" "Open Infrastructure"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+container-shell \- Manage systemd\-nspawn containers (shell)
+.SH "SYNOPSIS"
+.sp
+\fBcontainer\-shell\fR
+.SH "DESCRIPTION"
+.sp
+container\-tools provides the system integration for managing containers using systemd\-nspawn\&.
+.SH "COMMANDS"
+.sp
+All container commands are available, see container(1)\&. Additionally, the following commands are specific to container\-shell:
+.PP
+\fBabout:\fR
+.RS 4
+shows introduction (manpage)\&.
+.RE
+.PP
+\fBhelp:\fR
+.RS 4
+shows available commands within the container\-shell\&.
+.RE
+.PP
+\fBhelp COMMAND:\fR
+.RS 4
+shows help (manpage) for a specific container command\&.
+.RE
+.PP
+\fBlogout\fR, \fBexit:\fR
+.RS 4
+exits container\-shell\&.
+.RE
+.SH "USAGE"
+.sp
+Although the container\-shell can be started from a running system like any other program, the main intend is to use the container\-shell 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:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+sudo adduser \-\-gecos "container\-tools,,," \e
+      \-\-home /var/lib/container\-tools/container\-shell \e
+      \-\-shell /usr/bin/container\-shell
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The container\-shell can then be allowed for specific SSH keys via /var/ib/container\-tools/container\-shell/\&.ssh/authorized_keys like so:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+command="/usr/bin/container\-shell",no\-port\-forwarding,no\-X11\-forwarding,no\-agent\-forwarding,no\-pty ssh\-rsa [\&.\&.\&.]
+.fi
+.if n \{\
+.RE
+.\}
+.SH "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\&.
+.sp
+Example (blacklisting): In order to allow all commands except for removing and stopping containers, the following variable can be used:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+command="CONTAINER_COMMANDS_DISABLE=\*(Aqremove stop\*(Aq /usr/bin/container\-shell",no\-port\-forwarding,no\-X11\-forwarding,no\-agent\-forwarding,no\-pty ssh\-rsa [\&.\&.\&.]
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Example (whitelisting): The other way around works too\&. To disallow all commands except for listing containers and showing the container\-tools version, the following variable can be used:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+command="CONTAINER_COMMANDS_ENABLE=\*(Aqlist version\*(Aq /usr/bin/container\-shell",no\-port\-forwarding,no\-X11\-forwarding,no\-agent\-forwarding,no\-pty ssh\-rsa [\&.\&.\&.]
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.sp
+machinectl(1), systemd\-nspawn(1)\&.
+.SH "HOMEPAGE"
+.sp
+More information about container\-tools and the Open Infrastructure project can be found on the homepage at https://open\-infrastructure\&.net\&.
+.SH "CONTACT"
+.sp
+Bug reports, feature requests, help, patches, support and everything else are welcome on the Open Infrastructure Software Mailing List <software@lists\&.open\-infrastructure\&.net>\&.
+.sp
+Debian specific bugs can also be reported in the Debian Bug Tracking System at https://bugs\&.debian\&.org\&.
+.SH "AUTHORS"
+.sp
+container\-tools was written by Daniel Baumann <daniel\&.baumann@open\-infrastructure\&.net>\&.