man/nss-mymachines.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="nss-mymachines" conditional='ENABLE_NSS_MYMACHINES'>
   7
   8   <refentryinfo>
   9     <title>nss-mymachines</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>nss-mymachines</refentrytitle>
  15     <manvolnum>8</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>nss-mymachines</refname>
  20     <refname>libnss_mymachines.so.2</refname>
  21     <refpurpose>Hostname resolution for local container instances</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <para><filename>libnss_mymachines.so.2</filename></para>
  26   </refsynopsisdiv>
  27
  28   <refsect1>
  29     <title>Description</title>
  30
  31     <para><command>nss-mymachines</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of
  32     the GNU C Library (<command>glibc</command>), providing hostname resolution for the names of containers running
  33     locally that are registered with
  34     <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The
  35     container names are resolved to the IP addresses of the specific container, ordered by their scope. This
  36     functionality only applies to containers using network namespacing (see the description of
  37     <option>--private-network</option> in
  38     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
  39     Note that the name that is resolved is the one registered with <command>systemd-machined</command>, which
  40     may be different than the hostname configured inside of the container.</para>
  41
  42     <para>The module also provides name resolution for user and group identifiers mapped to containers. All names from
  43     the range allocated to a given container <replaceable>container</replaceable> are exposed on the host as
  44     <literal>vu-<replaceable>container</replaceable>-<replaceable>uid</replaceable></literal> and
  45     <literal>vg-<replaceable>container</replaceable>-<replaceable>gid</replaceable></literal> (see example below). This
  46     functionality only applies to containers using user namespacing (see the description of
  47     <option>--private-users</option> in
  48     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
  49
  50     <para>To activate the NSS module, add <literal>mymachines</literal> to the lines starting with
  51     <literal>hosts:</literal>, <literal>passwd:</literal> and <literal>group:</literal> in
  52     <filename>/etc/nsswitch.conf</filename>.</para>
  53
  54     <para>It is recommended to place <literal>mymachines</literal> after the <literal>files</literal> or
  55     <literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> lines to make sure that its mappings
  56     are preferred over other resolvers such as DNS, but so that <filename>/etc/hosts</filename>,
  57     <filename>/etc/passwd</filename> and <filename>/etc/group</filename> based mappings take precedence.</para>
  58   </refsect1>
  59
  60   <refsect1>
  61     <title>Configuration in <filename>/etc/nsswitch.conf</filename></title>
  62
  63     <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
  64     <command>nss-mymachines</command> correctly:</para>
  65
  66     <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
  67     <programlisting>passwd:         compat <command>mymachines</command> systemd
  68 group:          compat <command>mymachines</command> systemd
  69 shadow:         compat
  70
  71 hosts:          <command>mymachines</command> resolve [!UNAVAIL=return] myhostname files dns
  72 networks:       files
  73
  74 protocols:      db files
  75 services:       db files
  76 ethers:         db files
  77 rpc:            db files
  78
  79 netgroup:       nis</programlisting>
  80
  81   </refsect1>
  82
  83   <refsect1>
  84     <title>Mappings provided by <filename>nss-mymachines</filename></title>
  85
  86     <para>The container <literal>rawhide</literal> is spawned using
  87     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>:
  88     </para>
  89
  90     <programlisting># systemd-nspawn -M rawhide --boot --network-veth --private-users=pick
  91 Spawning container rawhide on /var/lib/machines/rawhide.
  92 Selected user namespace base 20119552 and range 65536.
  93 ...
  94
  95 $ machinectl --max-addresses=3
  96 MACHINE CLASS     SERVICE        OS     VERSION ADDRESSES
  97 rawhide container systemd-nspawn fedora 30      169.254.40.164 fe80::94aa:3aff:fe7b:d4b9
  98
  99 $ getent passwd vu-rawhide-0 vu-rawhide-81
 100 vu-rawhide-0:*:20119552:65534:vu-rawhide-0:/:/usr/sbin/nologin
 101 vu-rawhide-81:*:20119633:65534:vu-rawhide-81:/:/usr/sbin/nologin
 102
 103 $ getent group vg-rawhide-0 vg-rawhide-81
 104 vg-rawhide-0:*:20119552:
 105 vg-rawhide-81:*:20119633:
 106
 107 $ ps -o user:15,pid,tty,command -e|grep '^vu-rawhide'
 108 vu-rawhide-0      692 ?        /usr/lib/systemd/systemd
 109 vu-rawhide-0      731 ?        /usr/lib/systemd/systemd-journald
 110 vu-rawhide-192    734 ?        /usr/lib/systemd/systemd-networkd
 111 vu-rawhide-193    738 ?        /usr/lib/systemd/systemd-resolved
 112 vu-rawhide-0      742 ?        /usr/lib/systemd/systemd-logind
 113 vu-rawhide-81     744 ?        /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only
 114 vu-rawhide-0      746 ?        /usr/sbin/sshd -D ...
 115 vu-rawhide-0      752 ?        /usr/lib/systemd/systemd --user
 116 vu-rawhide-0      753 ?        (sd-pam)
 117 vu-rawhide-0     1628 ?        login -- zbyszek
 118 vu-rawhide-1000  1630 ?        /usr/lib/systemd/systemd --user
 119 vu-rawhide-1000  1631 ?        (sd-pam)
 120 vu-rawhide-1000  1637 pts/8    -zsh
 121
 122 $ ping -c1 rawhide
 123 PING rawhide(fe80::94aa:3aff:fe7b:d4b9%ve-rawhide (fe80::94aa:3aff:fe7b:d4b9%ve-rawhide)) 56 data bytes
 124 64 bytes from fe80::94aa:3aff:fe7b:d4b9%ve-rawhide (fe80::94aa:3aff:fe7b:d4b9%ve-rawhide): icmp_seq=1 ttl=64 time=0.045 ms
 125 ...
 126 $ ping -c1 -4 rawhide
 127 PING rawhide (169.254.40.164) 56(84) bytes of data.
 128 64 bytes from 169.254.40.164 (169.254.40.164): icmp_seq=1 ttl=64 time=0.064 ms
 129 ...
 130
 131 # machinectl shell rawhide /sbin/ip a
 132 Connected to machine rawhide. Press ^] three times within 1s to exit session.
 133 1: lo: &lt;LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
 134     ...
 135 2: host0@if21: &lt;BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
 136     link/ether 96:aa:3a:7b:d4:b9 brd ff:ff:ff:ff:ff:ff link-netnsid 0
 137     inet 169.254.40.164/16 brd 169.254.255.255 scope link host0
 138        valid_lft forever preferred_lft forever
 139     inet6 fe80::94aa:3aff:fe7b:d4b9/64 scope link
 140        valid_lft forever preferred_lft forever
 141 Connection to machine rawhide terminated.
 142 </programlisting>
 143   </refsect1>
 144
 145   <refsect1>
 146     <title>See Also</title>
 147     <para>
 148       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 149       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 150       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 151       <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 152       <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 153       <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 154       <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 155       <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 156     </para>
 157   </refsect1>
 158
 159 </refentry>