-
-
Notifications
You must be signed in to change notification settings - Fork 4.1k
ssh-generator which makes VMs and containers accessible to ssh via AF_UNIX and AF_VSOCK #30777
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
78cdb9b
mkosi: also add ssh client, to make it easier to test ssh logins via …
poettering 7ceb76b
generator: optionally return resulting unit file path in generator_op…
poettering 3392079
generator: teach generator_add_symlink_full() to optionally make alia…
poettering e09c255
install: optionally return discovered unit file path in unit_file_exi…
poettering 045f7b8
iovec-util: add helper for a single NUL byte iovec
poettering 0e32206
ssh-generator: add simple new generator
poettering 0abd510
ssh-proxy: add ssh ProxyCommand tool that can connect to AF_UNIX + AF…
poettering 613fb4b
nspawn: expose a dir in the container where it can bind AF_UNIX socke…
poettering 62b3e5f
doc: document new /run/host/ inodes in container interface doc
poettering 52d863d
test: add testcase for ssh generator
poettering 9a1dc75
update TODO
poettering File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,141 @@ | ||
| <?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>AV_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>AV_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 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> | ||
DaanDeMeyer marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| </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> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,116 @@ | ||
| <?xml version='1.0'?> <!--*-nxml-*--> | ||
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | ||
| "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> | ||
| <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> | ||
|
|
||
| <refentry id="systemd-ssh-proxy" | ||
| xmlns:xi="http://www.w3.org/2001/XInclude"> | ||
|
|
||
| <refentryinfo> | ||
| <title>systemd-ssh-proxy</title> | ||
| <productname>systemd</productname> | ||
| </refentryinfo> | ||
|
|
||
| <refmeta> | ||
| <refentrytitle>systemd-ssh-proxy</refentrytitle> | ||
| <manvolnum>1</manvolnum> | ||
| </refmeta> | ||
|
|
||
| <refnamediv> | ||
| <refname>systemd-ssh-proxy</refname> | ||
| <refpurpose>SSH client plugin for connecting to <constant>AF_VSOCK</constant> and | ||
| <constant>AF_UNIX</constant> sockets</refpurpose> | ||
| </refnamediv> | ||
|
|
||
| <refsynopsisdiv> | ||
| <programlisting> | ||
| Host unix/* vsock/* | ||
| ProxyCommand /usr/lib/systemd/systemd-ssh-proxy %h %p | ||
| ProxyUseFdpass yes | ||
| </programlisting> | ||
| <cmdsynopsis> | ||
| <command>/usr/lib/systemd/systemd-ssh-proxy</command> <arg>ADDRESS</arg> <arg>PORT</arg> | ||
| </cmdsynopsis> | ||
| </refsynopsisdiv> | ||
|
|
||
|
|
||
| <refsect1> | ||
| <title>Description</title> | ||
|
|
||
| <para><command>systemd-ssh-proxy</command> is a small "proxy" plugin for the <citerefentry | ||
| project="man-pages"><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry> | ||
| tool that allows connecting to <constant>AF_UNIX</constant> and <constant>AF_VSOCK</constant> sockets. It | ||
| implements the interface defined by <filename>ssh</filename>'s <varname>ProxyCommand</varname> | ||
| configuration option. It's supposed to be used with an <citerefentry | ||
| project="man-pages"><refentrytitle>ssh_config</refentrytitle><manvolnum>5</manvolnum></citerefentry> | ||
| configuration fragment like the following:</para> | ||
|
|
||
| <programlisting> | ||
| Host unix/* vsock/* | ||
| ProxyCommand /usr/lib/systemd/systemd-ssh-proxy %h %p | ||
| ProxyUseFdpass yes | ||
| CheckHostIP no | ||
|
|
||
| Host .host | ||
| ProxyCommand /usr/lib/systemd/systemd-ssh-proxy unix/run/ssh-unix-local/socket %p | ||
| ProxyUseFdpass yes | ||
| CheckHostIP no | ||
| </programlisting> | ||
|
|
||
| <para>A configuration fragment along these lines is by default installed into | ||
| <filename>/etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf.in</filename>.</para> | ||
|
|
||
| <para>With this in place, SSH connections to host string <literal>unix/</literal> followed by an absolute | ||
| <constant>AF_UNIX</constant> file system path to a socket will be directed to the specified socket, which | ||
| must be of type <constant>SOCK_STREAM</constant>. Similar, SSH connections to <literal>vsock/</literal> | ||
| followed by an <constant>AF_VSOCK</constant> CID will result in an SSH connection made to that | ||
| CID. Moreover connecting to <literal>.host</literal> will connect to the local host via SSH, without | ||
| involving networking.</para> | ||
|
|
||
| <para>This tool is supposed to be used together with | ||
| <citerefentry><refentrytitle>systemd-ssh-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> | ||
| which when run inside a VM or container will bind SSH to suitable | ||
| addresses. <command>systemd-ssh-generator</command> is supposed to run in the container of VM guest, and | ||
| <command>systemd-ssh-proxy</command> is run on the host, in order to connect to the container or VM | ||
| guest.</para> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <title>Exit status</title> | ||
|
|
||
| <para>On success, 0 is returned, a non-zero failure code | ||
| otherwise.</para> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <title>Examples</title> | ||
|
|
||
| <example> | ||
| <title>Talk to a local VM with CID 4711</title> | ||
|
|
||
| <programlisting>ssh vsock/4711</programlisting> | ||
| </example> | ||
|
|
||
| <example> | ||
| <title>Talk to the local host via ssh</title> | ||
|
|
||
| <programlisting>ssh .host</programlisting> | ||
|
|
||
| <para>or equivalent:</para> | ||
|
|
||
| <programlisting>ssh unix/run/ssh-unix-local/socket</programlisting> | ||
| </example> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <title>See Also</title> | ||
| <para><simplelist type="inline"> | ||
| <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | ||
| <member><citerefentry><refentrytitle>systemd-ssh-generator</refentrytitle><manvolnum>8</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> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.