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