From 1b934761ae366d84feb4b601382fa11b5d775633 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Thu, 14 Sep 2017 12:13:31 +0200
Subject: [PATCH] man: add a note about Name=eth0 being bad

Fixes #2657.
---
 man/systemd.link.xml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/man/systemd.link.xml b/man/systemd.link.xml
index 1a13a22877..066bed126b 100644
--- a/man/systemd.link.xml
+++ b/man/systemd.link.xml
@@ -79,7 +79,7 @@
     how the device should be configured. The first (in lexical order)
     of the link files that matches a given device is applied. Note
     that a default file <filename>99-default.link</filename> is
-    shipped by the system, any user-supplied
+    shipped by the system. Any user-supplied
     <filename>.link</filename> should hence have a lexically earlier
     name to be considered at all.</para>
 
@@ -332,6 +332,16 @@
           <varname>NamePolicy=</varname> fail, or in case
           <varname>NamePolicy=</varname> is missing or
           disabled.</para>
+
+          <para>Note that specifying a name that the kernel might use for another
+          interface (for example <literal>eth0</literal>) is dangerous because the
+          name assignment done by udev will race with the assignment done by the
+          kernel, and only one interface may use the name. Depending on the order of
+          operations, either udev or the kernel will win, making the naming
+          unpredictable. It is best to use some different prefix, for example
+          <literal>internal0</literal>/<literal>external0</literal> or
+          <literal>lan0</literal>/<literal>lan1</literal>/<literal>lan3</literal>.
+          </para>
         </listitem>
       </varlistentry>
       <varlistentry>