man/NetworkManager.conf.xml.in

   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 Copyright 2010 - 2014 Red Hat, Inc.
   7 -->
   8
   9 <refentry id="NetworkManager.conf">
  10   <refentryinfo>
  11     <title>NetworkManager.conf</title>
  12     <author>NetworkManager developers</author>
  13   </refentryinfo>
  14
  15   <refmeta>
  16     <refentrytitle>NetworkManager.conf</refentrytitle>
  17     <manvolnum>5</manvolnum>
  18     <refmiscinfo class="source">NetworkManager</refmiscinfo>
  19     <refmiscinfo class="manual">Configuration</refmiscinfo>
  20     <refmiscinfo class="version">1.2</refmiscinfo>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>NetworkManager.conf</refname>
  25     <refpurpose>NetworkManager configuration file</refpurpose>
  26   </refnamediv>
  27
  28   <refsynopsisdiv>
  29     <para><filename>/etc/NetworkManager/NetworkManager.conf</filename>,
  30     <filename>/etc/NetworkManager/conf.d/<replaceable>name</replaceable>.conf</filename>,
  31     <filename>/usr/lib/NetworkManager/conf.d/<replaceable>name</replaceable>.conf</filename>,
  32     <filename>/var/lib/NetworkManager/NetworkManager-intern.conf</filename>
  33     </para>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38     <para><literal>NetworkManager.conf</literal> is the configuration file for NetworkManager. It is used
  39     to set up various aspects of NetworkManager's behavior. The
  40     location of the main file and configuration directories may be changed
  41     through use of the <option>--config</option>, <option>--config-dir</option>,
  42     <option>--system-config-dir</option>, and <option>--intern-config</option>
  43     argument for NetworkManager, respectively.
  44     </para>
  45     <para>If a default <literal>NetworkManager.conf</literal> is
  46     provided by your distribution's packages, you should not modify
  47     it, since your changes may get overwritten by package
  48     updates. Instead, you can add additional <literal>.conf</literal>
  49     files to the <literal>/etc/NetworkManager/conf.d</literal> directory.
  50     These will be read in order, with later files overriding earlier ones.
  51     Packages might install further configuration snippets to <literal>/usr/lib/NetworkManager/conf.d</literal>.
  52     This directory is parsed first, even before <literal>NetworkManager.conf</literal>.
  53     The loading of a file <literal>/usr/lib/NetworkManager/conf.d/<replaceable>name</replaceable>.conf</literal>
  54     can be prevented by adding a file <literal>/etc/NetworkManager/conf.d/<replaceable>name</replaceable>.conf</literal>.
  55     In this case, the file from the etc configuration shadows the file from the
  56     system configuration directory.
  57     </para>
  58     <para>
  59     NetworkManager can overwrite certain user configuration options via D-Bus or other internal
  60     operations. In this case it writes those changes to <literal>/var/lib/NetworkManager/NetworkManager-intern.conf</literal>.
  61     This file is not intended to be modified by the user, but it is read last and can shadow
  62     user configuration from <literal>NetworkManager.conf</literal>.
  63     </para>
  64
  65   </refsect1>
  66
  67   <refsect1>
  68     <title>File Format</title>
  69     <para>
  70       The configuration file format is so-called key file (sort of
  71       ini-style format).  It consists of sections (groups) of
  72       key-value pairs. Lines beginning with a '#' and blank lines are
  73       considered comments. Sections are started by a header line
  74       containing the section enclosed in '[' and ']', and ended
  75       implicitly by the start of the next section or the end of the
  76       file. Each key-value pair must be contained in a section.
  77     </para>
  78     <para>
  79       For keys that take a list of devices as their value, you can
  80       specify devices by their MAC addresses or interface names, or
  81       "*" to specify all devices. See <xref linkend="device-spec"/>
  82       below.
  83     </para>
  84     <para>
  85       Minimal system settings configuration file looks like this:
  86       <programlisting>
  87 [main]
  88 plugins=keyfile
  89 </programlisting>
  90     </para>
  91     <para>
  92       As an extension to the normal keyfile format, you can also
  93       append a value to a previously-set list-valued key by doing:
  94       <programlisting>
  95 plugins+=another-plugin
  96 plugins-=remove-me
  97 </programlisting>
  98     </para>
  99   </refsect1>
 100
 101   <refsect1>
 102     <title><literal>main</literal> section</title>
 103     <variablelist>
 104       <varlistentry>
 105         <term><varname>plugins</varname></term>
 106         <listitem>
 107           <para>
 108             Lists system settings plugin names separated by ','. These
 109             plugins are used to read and write system-wide
 110             connections. When multiple plugins are specified, the
 111             connections are read from all listed plugins. When writing
 112             connections, the plugins will be asked to save the
 113             connection in the order listed here; if the first plugin
 114             cannot write out that connection type (or can't write out
 115             any connections) the next plugin is tried, etc. If none of
 116             the plugins can save the connection, an error is returned
 117             to the user.
 118           </para>
 119           <para>
 120             If NetworkManager defines a distro-specific
 121             network-configuration plugin for your system, then that
 122             will normally be listed here. (See below for the available
 123             plugins.) Note that the <literal>keyfile</literal> plugin
 124             is always appended to the end of this list (if it doesn't
 125             already appear earlier in the list), so if there is no
 126             distro-specific plugin for your system then you can leave
 127             this key unset and NetworkManager will fall back to using
 128             <literal>keyfile</literal>.
 129           </para>
 130         </listitem>
 131       </varlistentry>
 132       <varlistentry>
 133         <term><varname>monitor-connection-files</varname></term>
 134         <listitem><para>Whether the configured settings plugin(s)
 135         should set up file monitors and immediately pick up changes
 136         made to connection files while NetworkManager is running. This
 137         is disabled by default; NetworkManager will only read
 138         the connection files at startup, and when explicitly requested
 139         via the ReloadConnections D-Bus call. If this key is set to
 140         '<literal>true</literal>', then NetworkManager will reload
 141         connection files any time they changed.
 142         Automatic reloading is not adviced because there are race conditions
 143         involved and it depends on the way how the editor updates the file.
 144         In some situations, NetworkManager might first delete and add the
 145         connection anew, instead of updating the existing one. Also, NetworkManager
 146         might pick up incomplete settings while the user is still editing the files.
 147         </para></listitem>
 148       </varlistentry>
 149       <varlistentry>
 150         <term><varname>auth-polkit</varname></term>
 151         <listitem><para>Whether the system uses PolicyKit for authorization.
 152         If <literal>false</literal>, all requests will be allowed. If
 153         <literal>true</literal>, non-root requests are authorized using PolicyKit.
 154         The default value is <literal>@NM_CONFIG_DEFAULT_AUTH_POLKIT_TEXT@</literal>.
 155         </para></listitem>
 156       </varlistentry>
 157       <varlistentry>
 158         <term><varname>dhcp</varname></term>
 159         <listitem><para>This key sets up what DHCP client
 160         NetworkManager will use. Allowed values are
 161         <literal>dhclient</literal>, <literal>dhcpcd</literal>, and
 162         <literal>internal</literal>. The <literal>dhclient</literal>
 163         and <literal>dhcpcd</literal> options require the indicated
 164         clients to be installed. The <literal>internal</literal>
 165         option uses a built-in DHCP client which is not currently as
 166         featureful as the external clients.</para>
 167         <para>If this key is missing, available DHCP clients are
 168         looked for in this order: <literal>dhclient</literal>,
 169         <literal>dhcpcd</literal>,
 170         <literal>internal</literal>.</para></listitem>
 171       </varlistentry>
 172       <varlistentry>
 173         <term><varname>no-auto-default</varname></term>
 174         <listitem><para>Specify devices for which
 175         NetworkManager shouldn't create default wired connection
 176         (Auto eth0).  By default, NetworkManager creates a temporary
 177         wired connection for any Ethernet device that is managed and
 178         doesn't have a connection configured. List a device in this
 179         option to inhibit creating the default connection for the
 180         device. May have the special value <literal>*</literal> to
 181         apply to all devices.</para>
 182         <para>When the default wired connection is deleted or saved
 183         to a new persistent connection by a plugin, the device is
 184         added to a list in the file
 185         <filename>/var/run/NetworkManager/no-auto-default.state</filename>
 186         to prevent creating the default connection for that device
 187         again.</para>
 188         <para>See <xref linkend="device-spec"/> for the syntax how to
 189         specify a device.
 190         </para>
 191         <para>
 192           Example:
 193           <programlisting>
 194 no-auto-default=00:22:68:5c:5d:c4,00:1e:65:ff:aa:ee
 195 no-auto-default=eth0,eth1
 196 no-auto-default=*
 197 </programlisting>
 198         </para>
 199         </listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term><varname>ignore-carrier</varname></term>
 204         <listitem>
 205           <para>
 206             Specify devices for which NetworkManager will (partially)
 207             ignore the carrier state. Normally, for
 208             device types that support carrier-detect, such as Ethernet
 209             and InfiniBand, NetworkManager will only allow a
 210             connection to be activated on the device if carrier is
 211             present (ie, a cable is plugged in), and it will
 212             deactivate the device if carrier drops for more than a few
 213             seconds.
 214           </para>
 215           <para>
 216             Listing a device here will allow activating connections on
 217             that device even when it does not have carrier, provided
 218             that the connection uses only statically-configured IP
 219             addresses. Additionally, it will allow any active
 220             connection (whether static or dynamic) to remain active on
 221             the device when carrier is lost.
 222           </para>
 223           <para>
 224             Note that the "carrier" property of NMDevices and device D-Bus
 225             interfaces will still reflect the actual device state; it's just
 226             that NetworkManager will not make use of that information.
 227           </para>
 228           <para>See <xref linkend="device-spec"/> for the syntax how to
 229            specify a device.
 230           </para>
 231         </listitem>
 232       </varlistentry>
 233
 234       <varlistentry>
 235         <term><varname>assume-ipv6ll-only</varname></term>
 236         <listitem>
 237           <para>
 238             Specify devices for which NetworkManager will try to
 239             generate a connection based on initial configuration when
 240             the device only has an IPv6 link-local address.
 241           </para>
 242           <para>See <xref linkend="device-spec"/> for the syntax how to
 243            specify a device.
 244           </para>
 245         </listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term><varname>configure-and-quit</varname></term>
 250         <listitem>
 251           <para>
 252             When set to '<literal>true</literal>', NetworkManager quits after
 253             performing initial network configuration but spawns small helpers
 254             to preserve DHCP leases and IPv6 addresses.  This is useful in
 255             environments where network setup is more or less static or it is
 256             desirable to save process time but still handle some dynamic
 257             configurations.  When this option is <literal>true</literal>,
 258             network configuration for WiFi, WWAN, Bluetooth, ADSL, and PPPoE
 259             interfaces cannot be preserved due to their use of external
 260             services, and these devices will be deconfigured when NetworkManager
 261             quits even though other interface's configuration may be preserved.
 262             Also, to preserve DHCP addresses the '<literal>dhcp</literal>' option
 263             must be set to '<literal>internal</literal>'. The default value of
 264             the '<literal>configure-and-quit</literal>' option is
 265             '<literal>false</literal>', meaning that NetworkManager will continue
 266             running after initial network configuration and continue responding
 267             to system and hardware events, D-Bus requests, and user commands.
 268           </para>
 269         </listitem>
 270       </varlistentry>
 271
 272       <varlistentry>
 273         <term><varname>dns</varname></term>
 274         <listitem><para>Set the DNS (<filename>resolv.conf</filename>) processing mode.</para>
 275         <para><literal>default</literal>: The default if the key is
 276         not specified. NetworkManager will update
 277         <filename>resolv.conf</filename> to reflect the nameservers
 278         provided by currently active connections.</para>
 279         <para><literal>dnsmasq</literal>: NetworkManager will run
 280         dnsmasq as a local caching nameserver, using a "split DNS"
 281         configuration if you are connected to a VPN, and then update
 282         <filename>resolv.conf</filename> to point to the local
 283         nameserver.</para>
 284         <para><literal>unbound</literal>: NetworkManager will talk
 285         to unbound and dnssec-triggerd, providing a "split DNS"
 286         configuration with DNSSEC support. The /etc/resolv.conf
 287         will be managed by dnssec-trigger daemon.</para>
 288         <para><literal>none</literal>: NetworkManager will not
 289         modify resolv.conf.</para>
 290         </listitem>
 291       </varlistentry>
 292
 293       <varlistentry>
 294         <term><varname>rc-manager</varname></term>
 295         <listitem><para>Set the <filename>resolv.conf</filename>
 296         management mode. The default value depends on how NetworkManager
 297         was built. Regardless of this setting, NetworkManager will
 298         always write resolv.conf to its runtime state directory.</para>
 299         <para><literal>none</literal>: NetworkManager will symlink
 300         <filename>/etc/resolv.conf</filename> to its private
 301         resolv.conf file in the runtime state directory.</para>
 302         <para><literal>file</literal>: NetworkManager will write
 303         <filename>/etc/resolv.conf</filename> as file.</para>
 304         <para><literal>resolvconf</literal>: NetworkManager will run
 305         resolvconf to update the DNS configuration.</para>
 306         <para><literal>netconfig</literal>: NetworkManager will run
 307         netconfig to update the DNS configuration.</para>
 308         </listitem>
 309       </varlistentry>
 310
 311       <varlistentry>
 312         <term><varname>debug</varname></term>
 313         <listitem><para>Comma separated list of options to aid
 314         debugging. This value will be combined with the environment
 315         variable <literal>NM_DEBUG</literal>. Currently the following
 316         values are supported:</para>
 317         <para>
 318           <literal>RLIMIT_CORE</literal>: set ulimit -c unlimited
 319           to write out core dumps. Beware, that a core dump can contain
 320           sensitive information such as passwords or configuration settings.
 321         </para>
 322         <para>
 323           <literal>fatal-warnings</literal>: set g_log_set_always_fatal()
 324           to core dump on warning messages from glib. This is equivalent
 325           to the --g-fatal-warnings command line option.
 326         </para>
 327         </listitem>
 328       </varlistentry>
 329
 330     </variablelist>
 331   </refsect1>
 332
 333   <refsect1>
 334     <title><literal>keyfile</literal> section</title>
 335     <para>This section contains keyfile-plugin-specific options, and
 336     is normally only used when you are not using any other
 337     distro-specific plugin.</para>
 338
 339     <para>
 340       <variablelist>
 341         <varlistentry>
 342           <term><varname>hostname</varname></term>
 343           <listitem><para>This key is deprecated and has no effect
 344           since the hostname is now stored in /etc/hostname or other
 345           system configuration files according to build options.
 346           </para></listitem>
 347         </varlistentry>
 348         <varlistentry>
 349           <term><varname>path</varname></term>
 350           <listitem>
 351             <para>The location where keyfiles are read and stored.
 352             This defaults to "<literal>@NM_CONFIG_KEYFILE_PATH_DEFAULT@</literal>".
 353             </para>
 354           </listitem>
 355         </varlistentry>
 356         <varlistentry>
 357           <term><varname>unmanaged-devices</varname></term>
 358           <listitem><para>Set devices that should be ignored by
 359            NetworkManager.
 360           </para>
 361           <para>See <xref linkend="device-spec"/> for the syntax how to
 362            specify a device.
 363           </para>
 364           <para>
 365             Example:
 366             <programlisting>
 367 unmanaged-devices=interface-name:em4
 368 unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2
 369 </programlisting>
 370           </para>
 371           </listitem>
 372         </varlistentry>
 373       </variablelist>
 374     </para>
 375   </refsect1>
 376
 377   <refsect1>
 378     <title><literal>ifupdown</literal> section</title>
 379     <para>This section contains ifupdown-specific options and thus only
 380     has effect when using the <literal>ifupdown</literal> plugin.</para>
 381
 382     <para>
 383       <variablelist>
 384         <varlistentry>
 385           <term><varname>managed</varname></term>
 386           <listitem><para>If set to <literal>true</literal>, then
 387           interfaces listed in
 388           <filename>/etc/network/interfaces</filename> are managed by
 389           NetworkManager.  If set to <literal>false</literal>, then
 390           any interface listed in
 391           <filename>/etc/network/interfaces</filename> will be ignored
 392           by NetworkManager. Remember that NetworkManager controls the
 393           default route, so because the interface is ignored,
 394           NetworkManager may assign the default route to some other
 395           interface.</para>
 396           <para>
 397             The default value is <literal>false</literal>.
 398           </para>
 399           </listitem>
 400         </varlistentry>
 401       </variablelist>
 402     </para>
 403   </refsect1>
 404
 405   <refsect1>
 406     <title><literal>logging</literal> section</title>
 407     <para>This section controls NetworkManager's logging.  Any
 408     settings here are overridden by the <option>--log-level</option>
 409     and <option>--log-domains</option> command-line options.</para>
 410
 411     <para>
 412       <variablelist>
 413         <varlistentry>
 414           <term><varname>level</varname></term>
 415           <listitem><para>The default logging verbosity level.
 416           One of <literal>OFF</literal>, <literal>ERR</literal>,
 417           <literal>WARN</literal>, <literal>INFO</literal>,
 418           <literal>DEBUG</literal>, <literal>TRACE</literal>.  The ERR
 419           level logs only critical errors.  WARN logs warnings that may
 420           reflect operation. INFO logs various informational messages that
 421           are useful for tracking state and operations.  DEBUG enables
 422           verbose logging for debugging purposes. TRACE enables even more
 423           verbose logging then DEBUG level.  Subsequent levels also log
 424           all messages from earlier levels; thus setting the log level
 425           to INFO also logs error and warning messages.</para></listitem>
 426         </varlistentry>
 427         <varlistentry>
 428           <term><varname>domains</varname></term>
 429           <listitem><para>The following log domains are available:
 430           PLATFORM, RFKILL, ETHER, WIFI, BT, MB, DHCP4, DHCP6, PPP,
 431           WIFI_SCAN, IP4, IP6, AUTOIP4, DNS, VPN, SHARING, SUPPLICANT,
 432           AGENTS, SETTINGS, SUSPEND, CORE, DEVICE, OLPC, WIMAX,
 433           INFINIBAND, FIREWALL, ADSL, BOND, VLAN, BRIDGE, DBUS_PROPS,
 434           TEAM, CONCHECK, DCB, DISPATCH, AUDIT.</para>
 435           <para>In addition, these special domains can be used: NONE,
 436           ALL, DEFAULT, DHCP, IP.</para>
 437           <para>You can specify per-domain log level overrides by
 438           adding a colon and a log level to any domain. E.g.,
 439           "<literal>WIFI:DEBUG,WIFI_SCAN:OFF</literal>".</para></listitem>
 440         </varlistentry>
 441         <varlistentry>
 442           <para>Domain descriptions:
 443           <simplelist type="horiz" columns="1">
 444           <member>PLATFORM    : OS (platform) operations</member>
 445           <member>RFKILL      : RFKill subsystem operations</member>
 446           <member>ETHER       : Ethernet device operations</member>
 447           <member>WIFI        : Wi-Fi device operations</member>
 448           <member>BT          : Bluetooth operations</member>
 449           <member>MB          : Mobile broadband operations</member>
 450           <member>DHCP4       : DHCP for IPv4</member>
 451           <member>DHCP6       : DHCP for IPv6</member>
 452           <member>PPP         : Point-to-point protocol operations</member>
 453           <member>WIFI_SCAN   : Wi-Fi scanning operations</member>
 454           <member>IP4         : IPv4-related operations</member>
 455           <member>IP6         : IPv6-related operations</member>
 456           <member>AUTOIP4     : AutoIP operations</member>
 457           <member>DNS         : Domain Name System related operations</member>
 458           <member>VPN         : Virtual Private Network connections and operations</member>
 459           <member>SHARING     : Connection sharing</member>
 460           <member>SUPPLICANT  : WPA supplicant related operations</member>
 461           <member>AGENTS      : Secret agents operations and communication</member>
 462           <member>SETTINGS    : Settings/config service operations</member>
 463           <member>SUSPEND     : Suspend/resume</member>
 464           <member>CORE        : Core daemon and policy operations</member>
 465           <member>DEVICE      : Activation and general interface operations</member>
 466           <member>OLPC        : OLPC Mesh device operations</member>
 467           <member>WIMAX       : WiMAX device operations</member>
 468           <member>INFINIBAND  : InfiniBand device operations</member>
 469           <member>FIREWALL    : FirewallD related operations</member>
 470           <member>ADSL        : ADSL device operations</member>
 471           <member>BOND        : Bonding operations</member>
 472           <member>VLAN        : VLAN operations</member>
 473           <member>BRIDGE      : Bridging operations</member>
 474           <member>DBUS_PROPS  : D-Bus property changes</member>
 475           <member>TEAM        : Teaming operations</member>
 476           <member>CONCHECK    : Connectivity check</member>
 477           <member>DCB         : Data Center Bridging (DCB) operations</member>
 478           <member>DISPATCH    : Dispatcher scripts</member>
 479           <member>AUDIT       : Audit records</member>
 480           <member> </member>
 481           <member>NONE        : when given by itself logging is disabled</member>
 482           <member>ALL         : all log domains</member>
 483           <member>DEFAULT     : default log domains</member>
 484           <member>DHCP        : shortcut for "DHCP4,DHCP6"</member>
 485           <member>IP          : shortcut for "IP4,IP6"</member>
 486           <member> </member>
 487           <member>HW          : deprecated alias for "PLATFORM"</member>
 488           </simplelist>
 489           </para>
 490         </varlistentry>
 491         <varlistentry>
 492           <term><varname>backend</varname></term>
 493           <listitem><para>The logging backend. Supported values
 494           are "<literal>debug</literal>", "<literal>syslog</literal>",
 495           "<literal>journal</literal>".
 496           "<literal>debug</literal>" uses syslog and logs to standard error.
 497           If NetworkManager is started in debug mode (<literal>--debug</literal>)
 498           this option is ignored and "<literal>debug</literal>" is always used.
 499           Otherwise, the default is "<literal>@NM_CONFIG_LOGGING_BACKEND_DEFAULT_TEXT@</literal>".
 500           </para></listitem>
 501         </varlistentry>
 502         <varlistentry>
 503           <term><varname>audit</varname></term>
 504           <listitem><para>Whether the audit records are delivered to
 505           auditd, the audit daemon.  If <literal>false</literal>, audit
 506           records will be sent only to the NetworkManager logging
 507           system. If set to <literal>true</literal>, they will be also
 508           sent to auditd.  The default value is <literal>@NM_CONFIG_DEFAULT_LOGGING_AUDIT_TEXT@</literal>.
 509           </para></listitem>
 510         </varlistentry>
 511       </variablelist>
 512     </para>
 513   </refsect1>
 514
 515   <refsect1>
 516     <title><literal>connection</literal> section</title>
 517     <para>Specify default values for connections.
 518     </para>
 519     <para>
 520       Example:
 521 <programlisting>
 522 [connection]
 523 ipv6.ip6-privacy=0
 524 </programlisting>
 525     </para>
 526     <refsect2>
 527     <title>Supported Properties</title>
 528     <para>
 529       Not all properties can be overwritten, only the following
 530       properties are supported to have their default values configured
 531       (see <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details).
 532       A default value is only consulted if the corresponding per-connection value
 533       explicitly allows for that.
 534       <variablelist>
 535         <varlistentry>
 536           <term><varname>connection.autoconnect-slaves</varname></term>
 537         </varlistentry>
 538         <varlistentry>
 539           <term><varname>connection.lldp</varname></term>
 540         </varlistentry>
 541         <varlistentry>
 542           <term><varname>ethernet.wake-on-lan</varname></term>
 543         </varlistentry>
 544         <varlistentry>
 545           <term><varname>ipv4.dad-timeout</varname></term>
 546         </varlistentry>
 547         <varlistentry>
 548           <term><varname>ipv4.dhcp-timeout</varname></term>
 549           <listitem><para>If left unspecified, the default value for
 550            the interface type is used.</para></listitem>
 551         </varlistentry>
 552         <varlistentry>
 553           <term><varname>ipv4.route-metric</varname></term>
 554         </varlistentry>
 555         <varlistentry>
 556           <term><varname>ipv6.ip6-privacy</varname></term>
 557           <listitem><para>If <literal>ipv6.ip6-privacy</literal> is unset, use the content of
 558             "/proc/sys/net/ipv6/conf/default/use_tempaddr" as last fallback.
 559           </para></listitem>
 560         </varlistentry>
 561         <varlistentry>
 562           <term><varname>ipv6.route-metric</varname></term>
 563         </varlistentry>
 564         <varlistentry>
 565           <term><varname>vpn.timeout</varname></term>
 566           <listitem><para>If left unspecified, default value of 60 seconds is used.</para></listitem>
 567         </varlistentry>
 568         <varlistentry>
 569           <term><varname>wifi.mac-address-randomization</varname></term>
 570           <listitem><para>If left unspecified, MAC address randomization is disabled.</para></listitem>
 571         </varlistentry>
 572         <varlistentry>
 573           <term><varname>wifi.powersave</varname></term>
 574           <listitem><para>If left unspecified, the default value
 575           "<literal>ignore</literal>" will be used.</para></listitem>
 576         </varlistentry>
 577       </variablelist>
 578     </para>
 579     </refsect2>
 580
 581     <refsect2>
 582     <title>Sections</title>
 583     <para>
 584         You can configure multiple <literal>connection</literal>
 585         sections, by having different sections with a name that all start
 586         with "connection".
 587         Example:
 588 <programlisting>
 589 [connection]
 590 ipv6.ip6-privacy=0
 591 connection.autoconnect-slaves=1
 592 vpn.timeout=120
 593
 594 [connection-wifi-wlan0]
 595 match-device=interface-name:wlan0
 596 ipv4.route-metric=50
 597
 598 [connection-wifi-other]
 599 match-device=type:wifi
 600 ipv4.route-metric=55
 601 ipv6.ip6-privacy=1
 602 </programlisting>
 603     </para>
 604
 605     <para>
 606         The sections within one file are considered in order of appearance, with the
 607         exception that the <literal>[connection]</literal> section is always
 608         considered last. In the example above, this order is <literal>[connection-wifi-wlan0]</literal>,
 609         <literal>[connection-wlan-other]</literal>, and <literal>[connection]</literal>.
 610         When checking for a default configuration value, the sections are searched until
 611         the requested value is found.
 612         In the example above, "ipv4.route-metric" for wlan0 interface is set to 50,
 613         and for all other Wi-Fi typed interfaces to 55. Also, Wi-Fi devices would have
 614         IPv6 private addresses enabled by default, but other devices would have it disabled.
 615         Note that also "wlan0" gets "ipv6.ip6-privacy=1", because although the section
 616         "[connection-wifi-wlan0]" matches the device, it does not contain that property
 617         and the search continues.
 618     </para>
 619     <para>
 620         When having different sections in multiple files, sections from files that are read
 621         later have higher priority. So within one file the priority of the sections is
 622         top-to-bottom. Across multiple files later definitions take precedence.
 623     </para>
 624
 625     <para>
 626       The following properties further control how a connection section applies.
 627       <variablelist>
 628         <varlistentry>
 629           <term><varname>match-device</varname></term>
 630           <listitem><para>An optional device spec that restricts
 631           when the section applies. See <xref linkend="device-spec"/>
 632           for the possible values.
 633           </para></listitem>
 634         </varlistentry>
 635         <varlistentry>
 636           <term><varname>stop-match</varname></term>
 637           <listitem><para>An optional boolean value which defaults to
 638           <literal>no</literal>. If the section matches (based on
 639           <literal>match-device</literal>), further sections will not be
 640           considered even if the property in question is not present. In
 641           the example above, if <literal>[connection-wifi-wlan0]</literal> would
 642           have <literal>stop-match</literal> set to <literal>yes</literal>,
 643           its <literal>ipv6.ip6-privacy</literal> value would be
 644           unspecified.
 645           </para></listitem>
 646         </varlistentry>
 647       </variablelist>
 648     </para>
 649     </refsect2>
 650   </refsect1>
 651
 652   <refsect1>
 653     <title><literal>connectivity</literal> section</title>
 654     <para>This section controls NetworkManager's optional connectivity
 655     checking functionality.  This allows NetworkManager to detect
 656     whether or not the system can actually access the internet or
 657     whether it is behind a captive portal.</para>
 658
 659     <para>
 660       <variablelist>
 661         <varlistentry>
 662           <term><varname>uri</varname></term>
 663           <listitem><para>The URI of a web page to periodically
 664           request when connectivity is being checked.  This page
 665           should return the header "X-NetworkManager-Status" with a
 666           value of "online".  Alternatively, it's body content should
 667           be set to "NetworkManager is online".  The body content
 668           check can be controlled by the <literal>response</literal>
 669           option.  If this option is blank or missing, connectivity
 670           checking is disabled.
 671           </para></listitem>
 672         </varlistentry>
 673         <varlistentry>
 674           <term><varname>interval</varname></term>
 675           <listitem><para>Specified in seconds; controls how often
 676           connectivity is checked when a network connection exists. If
 677           set to 0 connectivity checking is disabled.  If missing, the
 678           default is 300 seconds.</para></listitem>
 679         </varlistentry>
 680         <varlistentry>
 681           <term><varname>response</varname></term>
 682           <listitem><para>If set controls what body content
 683           NetworkManager checks for when requesting the URI for
 684           connectivity checking.  If missing, defaults to
 685           "NetworkManager is online" </para></listitem>
 686         </varlistentry>
 687       </variablelist>
 688     </para>
 689   </refsect1>
 690
 691   <refsect1>
 692     <title><literal>global-dns</literal> section</title>
 693     <para>This section specifies global DNS settings that override
 694     connection-specific configuration.</para>
 695     <para>
 696       <variablelist>
 697         <varlistentry>
 698           <term><varname>searches</varname></term>
 699           <listitem>
 700             <para>
 701              A list of search domains to be used during hostname lookup.
 702            </para>
 703           </listitem>
 704         </varlistentry>
 705         <varlistentry>
 706           <term><varname>options</varname></term>
 707           <listitem>
 708             <para>
 709              A list of of options to be passed to the hostname resolver.
 710            </para>
 711           </listitem>
 712         </varlistentry>
 713       </variablelist>
 714     </para>
 715   </refsect1>
 716
 717   <refsect1>
 718     <title><literal>global-dns-domain</literal> sections</title>
 719     <para>Sections with a name starting with the "global-dns-domain-"
 720     prefix allow to define global DNS configuration for specific
 721     domains.  The part of section name after "global-dns-domain-"
 722     specifies the domain name a section applies to.  More specific
 723     domains have the precedence over less specific ones and the
 724     default domain is represented by the wildcard "*".  A default
 725     domain section is mandatory.
 726     </para>
 727     <para>
 728       <variablelist>
 729         <varlistentry>
 730           <term><varname>servers</varname></term>
 731           <listitem>
 732             <para>
 733              A list of addresses of DNS servers to be used for the given domain.
 734            </para>
 735           </listitem>
 736         </varlistentry>
 737         <varlistentry>
 738           <term><varname>options</varname></term>
 739           <listitem>
 740             <para>
 741              A list of domain-specific DNS options. Not used at the moment.
 742            </para>
 743           </listitem>
 744         </varlistentry>
 745       </variablelist>
 746     </para>
 747   </refsect1>
 748
 749   <refsect1>
 750     <title><literal>.config</literal> sections</title>
 751       <para>This is a special section that contains options which apply
 752       to the configuration file that contains the option.
 753     </para>
 754     <para>
 755       <variablelist>
 756         <varlistentry>
 757           <term><varname>enable</varname></term>
 758           <listitem>
 759             <para>
 760               Defaults to "<literal>true</literal>". If "<literal>false</literal>",
 761               the configuration file will be skipped during loading.
 762               Note that the main configuration file <literal>NetworkManager.conf</literal>
 763               cannot be disabled.
 764 <programlisting>
 765 # always skip loading the config file
 766 [.config]
 767 enable=false
 768 </programlisting>
 769             </para>
 770             <para>
 771               You can also match against the version of NetworkManager. For example
 772               the following are valid configurations:
 773 <programlisting>
 774 # only load on version 1.0.6
 775 [.config]
 776 enable=nm-version:1.0.6
 777
 778 # load on all versions 1.0.x, but not 1.2.x
 779 [.config]
 780 enable=nm-version:1.0
 781
 782 # only load on versions &gt;= 1.1.6. This does not match
 783 # with version 1.2.0 or 1.4.4. Only the last digit is considered.
 784 [.config]
 785 enable=nm-version-min:1.1.6
 786
 787 # only load on versions &gt;= 1.2. Contrary to the previous
 788 # example, this also matches with 1.2.0, 1.2.10, 1.4.4, etc.
 789 [.config]
 790 enable=nm-version-min:1.2
 791
 792 # Match against the maximum allowed version. The example matches
 793 # versions 1.2.0, 1.2.2, 1.2.4. Again, only the last version digit
 794 # is allowed to be smaller. So this would not match match on 1.1.10.
 795 [.config]
 796 enable=nm-version-max:1.2.6
 797 </programlisting>
 798             </para>
 799             <para>
 800               You can also match against the value of the environment variable
 801               <literal>NM_CONFIG_ENABLE_TAG</literal>, like:
 802 <programlisting>
 803 # always skip loading the file when running NetworkManager with
 804 # environment variable "NM_CONFIG_ENABLE_TAG=TAG1"
 805 [.config]
 806 enable=env:TAG1
 807 </programlisting>
 808             </para>
 809             <para>
 810               More then one match can be specified. The configuration will be
 811               enabled if one of the predicates matches ("or"). The special prefix "except:" can
 812               be used to negate the match. Note that if one except-predicate
 813               matches, the entire configuration will be disabled.
 814               In other words, a except predicate always wins over other predicates.
 815 <programlisting>
 816 # enable the configuration either when the environment variable
 817 # is present or the version is at least 1.2.0.
 818 [.config]
 819 enable=env:TAG2,nm-version-min:1.2
 820
 821 # enable the configuration for version &gt;= 1.2.0, but disable
 822 # it when the environment variable is set to "TAG3"
 823 [.config]
 824 enable=except:env:TAG3,nm-version-min:1.2
 825
 826 # enable the configuration on &gt;= 1.3, &gt;= 1.2.6, and &gt;= 1.0.16.
 827 # Useful if a certain feature is only present since those releases.
 828 [.config]
 829 enable=nm-version-min:1.3,nm-version-min:1.2.6,nm-version-min:1.0.16
 830 </programlisting>
 831             </para>
 832           </listitem>
 833         </varlistentry>
 834       </variablelist>
 835     </para>
 836   </refsect1>
 837
 838   <refsect1>
 839     <title>Plugins</title>
 840
 841     <variablelist>
 842       <varlistentry>
 843         <term><varname>keyfile</varname></term>
 844         <listitem>
 845           <para>
 846             The <literal>keyfile</literal> plugin is the generic
 847             plugin that supports all the connection types and
 848             capabilities that NetworkManager has. It writes files out
 849             in an .ini-style format in
 850             /etc/NetworkManager/system-connections.
 851           </para>
 852           <para>
 853             The stored connection file may contain passwords and
 854             private keys, so it will be made readable only to root,
 855             and the plugin will ignore files that are readable or
 856             writable by any user or group other than root.
 857           </para>
 858           <para>
 859             This plugin is always active, and will automatically be
 860             used to store any connections that aren't supported by any
 861             other active plugin.
 862           </para>
 863         </listitem>
 864       </varlistentry>
 865       <varlistentry>
 866         <term><varname>ifcfg-rh</varname></term>
 867         <listitem>
 868           <para>
 869             This plugin is used on the Fedora and Red Hat Enterprise
 870             Linux distributions to read and write configuration from
 871             the standard
 872             <filename>/etc/sysconfig/network-scripts/ifcfg-*</filename>
 873             files. It currently supports reading Ethernet, Wi-Fi,
 874             InfiniBand, VLAN, Bond, Bridge, and Team connections.
 875             Enabling <literal>ifcfg-rh</literal> implicitly enables
 876             <literal>ibft</literal> plugin, if it is available.
 877             This can be disabled by adding <literal>no-ibft</literal>.
 878           </para>
 879         </listitem>
 880       </varlistentry>
 881
 882       <varlistentry>
 883         <term><varname>ifcfg-suse</varname></term>
 884         <listitem>
 885           <para>
 886             This plugin is deprecated and its selection has no effect.
 887             The <literal>keyfile</literal> plugin should be used
 888             instead.
 889           </para>
 890         </listitem>
 891       </varlistentry>
 892
 893       <varlistentry>
 894         <term><varname>ifupdown</varname></term>
 895         <listitem>
 896           <para>
 897             This plugin is used on the Debian and Ubuntu
 898             distributions, and reads Ethernet and Wi-Fi connections
 899             from <filename>/etc/network/interfaces</filename>.
 900           </para>
 901           <para>
 902             This plugin is read-only; any connections (of any type)
 903             added from within NetworkManager when you are using this
 904             plugin will be saved using the <literal>keyfile</literal>
 905             plugin instead.
 906           </para>
 907         </listitem>
 908       </varlistentry>
 909
 910       <varlistentry>
 911         <term><varname>ibft</varname>, <varname>no-ibft</varname></term>
 912         <listitem>
 913           <para>
 914             This plugin allows to read iBFT configuration (iSCSI Boot Firmware Table).
 915             The configuration is read using /sbin/iscsiadm. Users are expected to
 916             configure iBFT connections via the firmware interfaces.
 917             If ibft support is available, it is automatically enabled after
 918             <literal>ifcfg-rh</literal>. This can be disabled by <literal>no-ibft</literal>.
 919             You can also explicitly specify <literal>ibft</literal> to load the
 920             plugin without <literal>ifcfg-rh</literal> or to change the plugin order.
 921           </para>
 922         </listitem>
 923       </varlistentry>
 924
 925     </variablelist>
 926   </refsect1>
 927
 928   <refsect1>
 929     <title>Appendix</title>
 930     <refsect2 id="device-spec">
 931       <title>Device List Format</title>
 932       <para>
 933           The configuration options <literal>main.no-auto-default</literal>, <literal>main.ignore-carrier</literal>,
 934           and <literal>keyfile.unmanaged-devices</literal> select devices based on a list of matchings.
 935           Devices can be specified using the following format:
 936       </para>
 937       <para>
 938       <variablelist>
 939         <varlistentry>
 940           <term>*</term>
 941           <listitem><para>Matches every device.</para></listitem>
 942         </varlistentry>
 943         <varlistentry>
 944           <term>IFNAME</term>
 945           <listitem><para>Case sensitive match of interface name of the device. Globbing is not supported.</para></listitem>
 946         </varlistentry>
 947         <varlistentry>
 948           <term>HWADDR</term>
 949           <listitem><para>Match the MAC address of the device. Globbing is not supported</para></listitem>
 950         </varlistentry>
 951         <varlistentry>
 952           <term>interface-name:IFNAME</term>
 953           <term>interface-name:~IFNAME</term>
 954           <listitem><para>Case sensitive match of interface name of the device. Simple globbing is supported with
 955              <literal>*</literal> and <literal>?</literal>. Ranges and escaping is not supported.</para></listitem>
 956         </varlistentry>
 957         <varlistentry>
 958           <term>interface-name:=IFNAME</term>
 959           <listitem><para>Case sensitive match of interface name of the device. Globbing is disabled and <literal>IFNAME</literal>
 960              is taken literally.</para></listitem>
 961         </varlistentry>
 962         <varlistentry>
 963           <term>mac:HWADDR</term>
 964           <listitem><para>Match the MAC address of the device. Globbing is not supported</para></listitem>
 965         </varlistentry>
 966         <varlistentry>
 967           <term>s390-subchannels:HWADDR</term>
 968           <listitem><para>Match the device based on the subchannel address. Globbing is not supported</para></listitem>
 969         </varlistentry>
 970         <varlistentry>
 971           <term>type:TYPE</term>
 972           <listitem><para>Match the device type. Valid type names are as reported by "<literal>nmcli -f GENERAL.TYPE device show</literal>".
 973           Globbing is not supported.</para></listitem>
 974         </varlistentry>
 975         <varlistentry>
 976           <term>except:SPEC</term>
 977           <listitem><para>Negative match of a device. <literal>SPEC</literal> must be explicitly qualified with
 978              a prefix such as <literal>interface-name:</literal>. A negative match has higher priority then the positive
 979              matches above.</para></listitem>
 980         </varlistentry>
 981         <varlistentry>
 982           <term>SPEC[,;]SPEC</term>
 983           <listitem><para>Multiple specs can be concatenated with commas or semicolons. The order does not matter as
 984             matches are either inclusive or negative (<literal>except:</literal>), with negative matches having higher
 985             priority.
 986             </para>
 987             <para>Backslash is supported to escape the separators ';' and ',', and to express special
 988             characters such as newline ('\n'), tabulator ('\t'), whitespace ('\s') and backslash ('\\'). The globbing of
 989             interface names cannot be escaped. Whitespace is not a separator but will be trimmed between
 990             two specs (unless escaped as '\s').
 991             </para>
 992           </listitem>
 993         </varlistentry>
 994       </variablelist>
 995       </para>
 996       <para>
 997         Example:
 998         <programlisting>
 999 interface-name:em4
1000 mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2
1001 interface-name:vboxnet*,except:interface-name:vboxnet2
1002 *,except:mac:00:22:68:1c:59:b1
1003 </programlisting>
1004       </para>
1005     </refsect2>
1006   </refsect1>
1007
1008   <refsect1>
1009     <title>See Also</title>
1010     <para>
1011       <citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1012       <citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1013       <citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1014       <citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1015       <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1016       <citerefentry><refentrytitle>nm-applet</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1017       <citerefentry><refentrytitle>nm-connection-editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1018     </para>
1019   </refsect1>
1020 </refentry>