1
0
mirror of https://github.com/systemd/systemd.git synced 2024-12-23 21:35:11 +03:00
systemd/man/systemd-ssh-generator.xml
Christoph Anton Mitterer 3e98472223 man: fix typos
Closes #34199.

Signed-off-by: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
2024-08-31 13:59:02 +09:00

147 lines
7.3 KiB
XML

<?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>