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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
<?xml version="1.0"?>
<!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd-ssh-generator"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-ssh-generator</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-ssh-generator</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-ssh-generator</refname>
<refpurpose>Generator for binding a socket-activated SSH server to local <constant>AF_VSOCK</constant>
and <constant>AF_UNIX</constant> sockets</refpurpose>
</refnamediv>
<refsynopsisdiv>
<para><filename>/usr/lib/systemd/system-generators/systemd-ssh-generator</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>systemd-ssh-generator</command> binds a socket-activated SSH server to local
<constant>AF_VSOCK</constant> and <constant>AF_UNIX</constant> sockets under certain conditions. It only
has an effect if the <citerefentry
project="man-pages"><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry> binary is
installed. Specifically, it does the following:</para>
<itemizedlist>
<listitem><para>If invoked in a VM with <constant>AF_VSOCK</constant> support, a socket-activated SSH
per-connection service is bound to <constant>AF_VSOCK</constant> port 22.</para></listitem>
<listitem><para>If invoked in a container environment with a writable directory
<filename>/run/host/unix-export/</filename> pre-mounted it binds SSH to an <constant>AF_UNIX</constant>
socket <filename>/run/host/unix-export/ssh</filename>. The assumption is that this directory is bind
mounted to the host side as well, and can be used to connect to the container from there. See <ulink
url="https://systemd.io/CONTAINER_INTERFACE">Container Interface</ulink> for more information about
this interface.</para></listitem>
<listitem><para>A local <constant>AF_UNIX</constant> socket
<filename>/run/ssh-unix-local/socket</filename> is also bound, unconditionally. This may be used for
SSH communication from the host to itself, without involving networking, for example to traverse
security boundaries safely and with secure authentication.</para></listitem>
<listitem><para>Additional <constant>AF_UNIX</constant> and <constant>AF_VSOCK</constant> sockets are
optionally bound, based on the <varname>systemd.ssh_listen=</varname> kernel command line option or the
<filename>ssh.listen</filename> system credential (see below).</para></listitem>
</itemizedlist>
<para>See
<citerefentry><refentrytitle>systemd-ssh-proxy</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
details on how to connect to these sockets via the <command>ssh</command> client.</para>
<para>The <varname>ssh.authorized_keys.root</varname> credential can be used to allow specific public keys
to log in over SSH. See
<citerefentry><refentrytitle>systemd.system-credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more information.</para>
<para>The generator will use a packaged <filename>sshd@.service</filename> service template file if one
exists, and otherwise generate a suitable service template file.</para>
<para><filename>systemd-ssh-generator</filename> implements
<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
<title>Kernel Command Line</title>
<para><filename>systemd-ssh-generator</filename> understands the following
<citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>
parameters:</para>
<variablelist class='kernel-commandline-options'>
<varlistentry>
<term><varname>systemd.ssh_auto=</varname></term>
<listitem><para>This option takes an optional boolean argument, and defaults to yes. If enabled, the
automatic binding to the <constant>AF_VSOCK</constant> and <constant>AF_UNIX</constant> sockets
listed above is done. If disable, this is not done, except for those explicitly requested via
<varname>systemd.ssh_listen=</varname> on the kernel command line or via the
<varname>ssh.listen</varname> system credential.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.ssh_listen=</varname></term>
<listitem><para>This option configures an additional socket to bind SSH to. It may be used multiple
times to bind multiple sockets. The syntax should follow the one of <varname>ListenStream=</varname>,
see
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. This functionality supports all socket families systemd supports, including
<constant>AF_INET</constant> and <constant>AF_INET6</constant>.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Credentials</title>
<para><command>systemd-ssh-generator</command> supports the system credentials logic. The following
credentials are used when passed in:</para>
<variablelist class='system-credentials'>
<varlistentry>
<term><varname>ssh.listen</varname></term>
<listitem><para>This credential should be a text file, with each line referencing one additional
socket to bind SSH to. The syntax should follow the one of <varname>ListenStream=</varname>, see
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. This functionality supports all socket families systemd supports, including
<constant>AF_INET</constant> and <constant>AF_INET6</constant>.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.system-credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry project="man-pages"><refentrytitle>vsock</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry project="man-pages"><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry project="man-pages"><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project="man-pages"><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>
|
