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