man/nss-mymachines.xml

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