summaryrefslogtreecommitdiffstats
path: root/share/man/container-shell.1
blob: 278ea0bb5cd9d4f0ab8b6b96dd0acac22752a5f1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
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>\&.