Imported Upstream version 1.0.4 upstream/1.0.4

1 files changed, 202 insertions, 22 deletions

diff --git a/man/NetworkManager.conf.xml.in b/man/NetworkManager.conf.xml.in
index 7c6b9551..40fa49dd 100644
--- a/man/NetworkManager.conf.xml.in
+++ b/man/NetworkManager.conf.xml.in
@@ -62,7 +62,8 @@ Copyright 2010 - 2014 Red Hat, Inc.
     <para>
       For keys that take a list of devices as their value, you can
       specify devices by their MAC addresses or interface names, or
-      "*" to specify all devices.
+      "*" to specify all devices. See <xref linkend="device-spec"/>
+      below.
     </para>
     <para>
       Minimal system settings configuration file looks like this:
@@ -76,6 +77,7 @@ Copyright 2010 - 2014 Red Hat, Inc.
       append a value to a previously-set list-valued key by doing:
       <programlisting>
 	plugins+=another-plugin
+	plugins-=remove-me
       </programlisting>
     </para>
   </refsect1>
@@ -148,7 +150,7 @@ Copyright 2010 - 2014 Red Hat, Inc.
       </varlistentry>
       <varlistentry>
 	<term><varname>no-auto-default</varname></term>
-	<listitem><para>Comma-separated list of devices for which
+	<listitem><para>Specify devices for which
 	NetworkManager shouldn't create default wired connection
 	(Auto eth0).  By default, NetworkManager creates a temporary
 	wired connection for any Ethernet device that is managed and
@@ -162,11 +164,15 @@ Copyright 2010 - 2014 Red Hat, Inc.
 	<filename>/var/run/NetworkManager/no-auto-default.state</filename>
 	to prevent creating the default connection for that device
 	again.</para>
+	<para>See <xref linkend="device-spec"/> for the syntax how to
+	specify a device.
+	</para>
 	<para>
+	  Example:
 	  <programlisting>
-	    no-auto-default=00:22:68:5c:5d:c4,00:1e:65:ff:aa:ee
-	    no-auto-default=eth0,eth1
-	    no-auto-default=*
+no-auto-default=00:22:68:5c:5d:c4,00:1e:65:ff:aa:ee
+no-auto-default=eth0,eth1
+no-auto-default=*
 	  </programlisting>
 	</para>
 	</listitem>
@@ -176,8 +182,8 @@ Copyright 2010 - 2014 Red Hat, Inc.
 	<term><varname>ignore-carrier</varname></term>
 	<listitem>
 	  <para>
-	    Comma-separated list of devices for which NetworkManager
-	    will (partially) ignore the carrier state. Normally, for
+	    Specify devices for which NetworkManager will (partially)
+	    ignore the carrier state. Normally, for
 	    device types that support carrier-detect, such as Ethernet
 	    and InfiniBand, NetworkManager will only allow a
 	    connection to be activated on the device if carrier is
@@ -194,14 +200,27 @@ Copyright 2010 - 2014 Red Hat, Inc.
 	    the device when carrier is lost.
 	  </para>
 	  <para>
-	    May have the special value <literal>*</literal> to apply
-	    to all devices.
-	  </para>
-	  <para>
 	    Note that the "carrier" property of NMDevices and device D-Bus
 	    interfaces will still reflect the actual device state; it's just
 	    that NetworkManager will not make use of that information.
 	  </para>
+	  <para>See <xref linkend="device-spec"/> for the syntax how to
+	   specify a device.
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>assume-ipv6ll-only</varname></term>
+	<listitem>
+	  <para>
+	    Specify devices for which NetworkManager will try to
+	    generate a connection based on initial configuration when
+	    the device only has an IPv6 link-local address.
+	  </para>
+	  <para>See <xref linkend="device-spec"/> for the syntax how to
+	   specify a device.
+	  </para>
 	</listitem>
       </varlistentry>
 
@@ -287,17 +306,11 @@ Copyright 2010 - 2014 Red Hat, Inc.
 	<varlistentry>
 	  <term><varname>unmanaged-devices</varname></term>
 	  <listitem><para>Set devices that should be ignored by
-	  NetworkManager when using the <literal>keyfile</literal>
-	  plugin. Devices are specified in the following
-	  format:</para>
-	  <para><literal>mac:&lt;hwaddr&gt;</literal> or
-	  <literal>interface-name:&lt;ifname&gt;</literal>.  Here
-	  <literal>hwaddr</literal> is the MAC address of the device
-	  to be ignored, in hex-digits-and-colons notation.
-	  <literal>ifname</literal> is the interface name of the
-	  ignored device.</para>
-	  <para>Multiple entries are separated with semicolons. No
-	  spaces are allowed in the value.</para>
+	   NetworkManager.
+	  </para>
+	  <para>See <xref linkend="device-spec"/> for the syntax how to
+	   specify a device.
+	  </para>
 	  <para>
 	    Example:
 	    <programlisting>
@@ -429,6 +442,97 @@ unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth
   </refsect1>
 
   <refsect1>
+    <title><literal>connection</literal> section</title>
+    <para>This section allows to specify default values for
+    connections. Not all properties can be overwritten, only a selected
+    list below. You can have multiple <literal>connection</literal>
+    sections, by having different sections with a name that all start
+    with "connection".</para>
+    <para>
+        Example:
+<programlisting>
+[connection]
+ipv6.ip6-privacy=0
+connection.autoconnect-slaves=1
+
+[connection-wifi-wlan0]
+match-device=interface-name:wlan0
+ipv4.route-metric=50
+
+[connection-wifi-other]
+match-device=type:wifi
+ipv4.route-metric=55
+ipv6.ip6-privacy=1
+</programlisting>
+    </para>
+
+    <para>
+        The sections within one file are considered in order of appearance, with the
+        exception that the <literal>[connection]</literal> section is always
+        considered last. In the example above, this order is <literal>[connection-wifi-wlan0]</literal>,
+        <literal>[connection-wlan-other]</literal>, and <literal>[connection]</literal>.
+        When checking for a default configuration value, the section are searched until
+        the requested value is found.
+        In the example above, "ipv4.route-metric" for wlan0 interface is set to 50,
+        and for all other Wi-Fi typed interfaces to 55. Also, Wi-Fi devices would have
+        IPv6 private addresses enabled by default, but other devices would have it disabled.
+        Note that also "wlan0" gets "ipv6.ip6-privacy=1", because although the section
+        "[connection-wifi-wlan0]" matches the device, it does not contain that property
+        and the search continues.
+    </para>
+    <para>
+        When having different sections in multiple files, sections from files that are read
+        later have higher priority. So within one file the priority of the sections is
+        top-to-bottom. Across multiple files later definitions take precedence.
+    </para>
+
+    <para>
+      <variablelist>
+        <varlistentry>
+          <term><varname>match-device</varname></term>
+          <listitem><para>An optional device spec that restricts
+          when the section applies. See <xref linkend="device-spec"/>
+          for the possible values.
+          </para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>stop-match</varname></term>
+          <listitem><para>An optional boolean value which defaults to
+          <literal>no</literal>. If the section matches (based on
+          <literal>match-device</literal>), further sections will not be
+          considered even if the property in question is not present. In
+          the example above, if <literal>[connection-wifi-wlan0]</literal> would
+          have <literal>stop-match</literal> set to <literal>yes</literal>,
+          its <literal>ipv6.ip6-privacy</literal> value would be
+          unspecified.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </para>
+
+    <para>
+      The following properties are supported to have their default values configured:
+      <variablelist>
+        <varlistentry>
+          <term><varname>ipv4.route-metric</varname></term>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>ipv6.ip6-privacy</varname></term>
+          <listitem><para>If <literal>ipv6.ip6-privacy</literal> is unset, use the content of
+            "/proc/sys/net/ipv6/conf/default/use_tempaddr" as last fallback.
+          </para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>ipv6.route-metric</varname></term>
+        </varlistentry>
+        <varlistentry>
+          <term><varname>connection.autoconnect-slaves</varname></term>
+        </varlistentry>
+      </variablelist>
+    </para>
+  </refsect1>
+
+  <refsect1>
     <title><literal>connectivity</literal> section</title>
     <para>This section controls NetworkManager's optional connectivity
     checking functionality.  This allows NetworkManager to detect
@@ -554,6 +658,82 @@ unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth
   </refsect1>
 
   <refsect1>
+    <title>Appendix</title>
+    <refsect2 id="device-spec">
+      <title>Device List Format</title>
+      <para>
+          The configuration options <literal>main.no-auto-default</literal>, <literal>main.ignore-carrier</literal>,
+          and <literal>keyfile.unmanaged-devices</literal> select devices based on a list of matchings.
+          Devices can be specified using the following format:
+      </para>
+      <para>
+      <variablelist>
+        <varlistentry>
+          <term>*</term>
+          <listitem><para>Matches every device.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>IFNAME</term>
+          <listitem><para>Case sensitive match of interface name of the device. Globbing is not supported.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>HWADDR</term>
+          <listitem><para>Match the MAC address of the device. Globbing is not supported</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>interface-name:IFNAME</term>
+          <term>interface-name:~IFNAME</term>
+          <listitem><para>Case sensitive match of interface name of the device. Simple globbing is supported with
+             <literal>*</literal> and <literal>?</literal>. Ranges and escaping is not supported.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>interface-name:=IFNAME</term>
+          <listitem><para>Case sensitive match of interface name of the device. Globbing is disabled and <literal>IFNAME</literal>
+             is taken literally.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>mac:HWADDR</term>
+          <listitem><para>Match the MAC address of the device. Globbing is not supported</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>s390-subchannels:HWADDR</term>
+          <listitem><para>Match the device based on the subchannel address. Globbing is not supported</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>type:TYPE</term>
+          <listitem><para>Match the device type. Valid type names are as reported by "<literal>nmcli -f GENERAL.TYPE device show</literal>".
+          Globbing is not supported.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>except:SPEC</term>
+          <listitem><para>Negative match of a device. <literal>SPEC</literal> must be explicitly qualified with
+             a prefix such as <literal>interface-name:</literal>. A negative match has higher priority then the positive
+             matches above.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>SPEC[,;]SPEC</term>
+          <listitem><para>Multiple specs can be concatenated with comman or semicolon. The order does not matter as
+             matches are either positive (inclusive) or negative, with negative matches having higher priority.</para>
+            <para>Backslash is supported to escape the separators ';' and ',', and to express special
+            characters such as newline ('\n'), tabulator ('\t'), whitespace ('\s') and backslash ('\\'). The globbing of
+            interface names cannot be escaped. Whitespace is taken literally so usually the specs will be concatenated
+            without spaces.</para></listitem>
+        </varlistentry>
+      </variablelist>
+      </para>
+      <para>
+        Example:
+        <programlisting>
+interface-name:em4
+mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2
+interface-name:vboxnet*,except:interface-name:vboxnet2
+*,except:mac:00:22:68:1c:59:b1
+        </programlisting>
+      </para>
+    </refsect2>
+  </refsect1>
+
+  <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry>,