man/NetworkManager.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5
   6 <!--
   7  Copyright 2005 - 2014 Red Hat, Inc.
   8  Copyright 2005 - 2009 Novell, Inc.
   9  Copyright 2005 Robert Love
  10 -->
  11
  12 <refentry id="NetworkManager">
  13   <refentryinfo>
  14     <title>NetworkManager</title>
  15     <author>NetworkManager developers</author>
  16   </refentryinfo>
  17   <refmeta>
  18     <refentrytitle>NetworkManager</refentrytitle>
  19     <manvolnum>8</manvolnum>
  20     <refmiscinfo class="source">NetworkManager</refmiscinfo>
  21     <refmiscinfo class="manual">Network management daemons</refmiscinfo>
  22     <refmiscinfo class="version">1.2</refmiscinfo>
  23   </refmeta>
  24
  25   <refnamediv>
  26     <refname>NetworkManager</refname>
  27     <refpurpose>network management daemon</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <cmdsynopsis>
  32       <command>NetworkManager <arg choice="opt" rep="repeat">OPTIONS</arg></command>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38     <para>
  39       The NetworkManager daemon attempts to make networking
  40       configuration and operation as painless and automatic as
  41       possible by managing the primary network connection and other
  42       network interfaces, like Ethernet, WiFi, and Mobile Broadband
  43       devices.  NetworkManager will connect any network device when a
  44       connection for that device becomes available, unless that
  45       behavior is disabled.  Information about networking is exported
  46       via a D-Bus interface to any interested application, providing a
  47       rich API with which to inspect and control network settings and
  48       operation.
  49     </para>
  50   </refsect1>
  51
  52   <refsect1>
  53     <title>Dispatcher scripts</title>
  54     <para>
  55       NetworkManager will execute scripts in the
  56       /etc/NetworkManager/dispatcher.d directory or subdirectories in
  57       alphabetical order in response to network events.  Each script should
  58       be a regular executable file owned by root.  Furthermore, it must not be
  59       writable by group or other, and not setuid.
  60     </para>
  61     <para>
  62       Each script receives two arguments, the first being the interface name of the
  63       device an operation just happened on, and second the action. For device actions,
  64       the interface is the name of the kernel interface suitable for IP configuration.
  65       Thus it is either VPN_IP_IFACE, DEVICE_IP_IFACE, or DEVICE_IFACE, as applicable.
  66       For the <varname>hostname</varname> action it is always "none".
  67     </para>
  68     <para>The actions are:</para>
  69     <variablelist class="dispatcher-options">
  70       <varlistentry>
  71         <term><varname>pre-up</varname></term>
  72         <listitem><para>The interface is connected to the network but is not
  73         yet fully activated.  Scripts acting on this event must be placed or
  74         symlinked into the /etc/NetworkManager/dispatcher.d/pre-up.d directory,
  75         and NetworkManager will wait for script execution to complete before
  76         indicating to applications that the interface is fully activated.
  77         </para></listitem>
  78       </varlistentry>
  79       <varlistentry>
  80         <term><varname>up</varname></term>
  81         <listitem><para>The interface has been activated.</para></listitem>
  82       </varlistentry>
  83       <varlistentry>
  84         <term><varname>pre-down</varname></term>
  85         <listitem><para>The interface will be deactivated but has not yet been
  86         disconnected from the network.  Scripts acting on this event must be
  87         placed or symlinked into the /etc/NetworkManager/dispatcher.d/pre-down.d
  88         directory, and NetworkManager will wait for script execution to complete
  89         before disconnecting the interface from its network.  Note that this
  90         event is not emitted for forced disconnections, like when carrier is
  91         lost or a wireless signal fades.  It is only emitted when there is
  92         an opportunity to cleanly handle a network disconnection event.
  93         </para></listitem>
  94       </varlistentry>
  95       <varlistentry>
  96         <term><varname>down</varname></term>
  97         <listitem><para>
  98           The interface has been deactivated.
  99         </para></listitem>
 100       </varlistentry>
 101       <varlistentry>
 102         <term><varname>vpn-pre-up</varname></term>
 103         <listitem><para>The VPN is connected to the network but is not yet
 104         fully activated.  Scripts acting on this event must be placed or
 105         symlinked into the /etc/NetworkManager/dispatcher.d/pre-up.d directory,
 106         and NetworkManager will wait for script execution to complete before
 107         indicating to applications that the VPN is fully activated.
 108         </para></listitem>
 109       </varlistentry>
 110       <varlistentry>
 111         <term><varname>vpn-up</varname></term>
 112         <listitem><para>
 113           A VPN connection has been activated.
 114         </para></listitem>
 115       </varlistentry>
 116       <varlistentry>
 117         <term><varname>vpn-pre-down</varname></term>
 118         <listitem><para>The VPN will be deactivated but has not yet been
 119         disconnected from the network.  Scripts acting on this event must be
 120         placed or symlinked into the /etc/NetworkManager/dispatcher.d/pre-down.d
 121         directory, and NetworkManager will wait for script execution to complete
 122         before disconnecting the VPN from its network.  Note that this
 123         event is not emitted for forced disconnections, like when the VPN
 124         terminates unexpectedly or general connectivity is lost.  It is only
 125         emitted when there is an opportunity to cleanly handle a VPN
 126         disconnection event.
 127         </para></listitem>
 128       </varlistentry>
 129       <varlistentry>
 130         <term><varname>vpn-down</varname></term>
 131         <listitem><para>
 132           A VPN connection has been deactivated.
 133         </para></listitem>
 134       </varlistentry>
 135       <varlistentry>
 136         <term><varname>hostname</varname></term>
 137         <listitem><para>
 138           The system hostname has been updated.  Use gethostname(2) to retrieve it.
 139           The interface name (first argument) is empty and no environment variable is
 140           set for this action.
 141         </para></listitem>
 142       </varlistentry>
 143       <varlistentry>
 144         <term><varname>dhcp4-change</varname></term>
 145         <listitem><para>
 146           The DHCPv4 lease has changed (renewed, rebound, etc).
 147         </para></listitem>
 148       </varlistentry>
 149       <varlistentry>
 150         <term><varname>dhcp6-change</varname></term>
 151         <listitem><para>
 152           The DHCPv6 lease has changed (renewed, rebound, etc).
 153         </para></listitem>
 154       </varlistentry>
 155     </variablelist>
 156     <para>
 157       The environment contains more information about the interface and the connection.
 158       The following variables are available for the use in the dispatcher scripts:
 159       <variablelist class="dispatcher-environment">
 160         <varlistentry>
 161           <term><varname>CONNECTION_UUID</varname></term>
 162           <listitem><para>
 163             The UUID of the connection profile.
 164           </para></listitem>
 165         </varlistentry>
 166         <varlistentry>
 167           <term><varname>CONNECTION_ID</varname></term>
 168           <listitem><para>
 169             The name (ID) of the connection profile.
 170           </para></listitem>
 171         </varlistentry>
 172         <varlistentry>
 173           <term><varname>CONNECTION_DBUS_PATH</varname></term>
 174           <listitem><para>
 175             The NetworkManager D-Bus path of the connection.
 176           </para></listitem>
 177         </varlistentry>
 178         <varlistentry>
 179           <term><varname>CONNECTION_FILENAME</varname></term>
 180           <listitem><para>
 181             The backing file name of the connection profile (if any).
 182           </para></listitem>
 183         </varlistentry>
 184         <varlistentry>
 185           <term><varname>CONNECTION_EXTERNAL</varname></term>
 186           <listitem><para>
 187             If "1", this indicates that the connection describes a
 188             network configuration created outside of NetworkManager.
 189           </para></listitem>
 190         </varlistentry>
 191         <varlistentry>
 192           <term><varname>DEVICE_IFACE</varname></term>
 193           <listitem><para>
 194             The interface name of the control interface of the device.
 195             Depending on the device type, this differs from
 196             <varname>DEVICE_IP_IFACE</varname>. For example for
 197             ADSL devices, this could be 'atm0' or for WWAN devices
 198             it might be 'ttyUSB0'.
 199           </para></listitem>
 200         </varlistentry>
 201         <varlistentry>
 202           <term><varname>DEVICE_IP_IFACE</varname></term>
 203           <listitem><para>
 204             The IP interface name of the device. This is the network
 205             interface on which IP addresses and routes will be configured.
 206           </para></listitem>
 207         </varlistentry>
 208         <varlistentry>
 209           <term><varname>IP4_ADDRESS_N</varname></term>
 210           <listitem><para>
 211             The IPv4 address in the format "address/prefix gateway", where N is a number
 212             from 0 to (# IPv4 addresses - 1). gateway item in this variable is deprecated,
 213             use IP4_GATEWAY instead.
 214           </para></listitem>
 215         </varlistentry>
 216         <varlistentry>
 217           <term><varname>IP4_NUM_ADDRESSES</varname></term>
 218           <listitem><para>
 219             The variable contains the number of IPv4 addresses the script may expect.
 220           </para></listitem>
 221         </varlistentry>
 222         <varlistentry>
 223           <term><varname>IP4_GATEWAY</varname></term>
 224           <listitem><para>
 225             The gateway IPv4 address in traditional numbers-and-dots notation.
 226           </para></listitem>
 227         </varlistentry>
 228         <varlistentry>
 229           <term><varname>IP4_ROUTE_N</varname></term>
 230           <listitem><para>
 231             The IPv4 route in the format "address/prefix next-hop metric", where N is a number
 232             from 0 to (# IPv4 routes - 1).
 233           </para></listitem>
 234         </varlistentry>
 235         <varlistentry>
 236           <term><varname>IP4_NUM_ROUTES</varname></term>
 237           <listitem><para>
 238             The variable contains the number of IPv4 routes the script may expect.
 239           </para></listitem>
 240         </varlistentry>
 241         <varlistentry>
 242           <term><varname>IP4_NAMESERVERS</varname></term>
 243           <listitem><para>
 244             The variable contains a space-separated list of the DNS servers.
 245           </para></listitem>
 246         </varlistentry>
 247         <varlistentry>
 248           <term><varname>IP4_DOMAINS</varname></term>
 249           <listitem><para>
 250             The variable contains a space-separated list of the search domains.
 251           </para></listitem>
 252         </varlistentry>
 253         <varlistentry>
 254           <term><varname>DHCP4_&lt;dhcp-option-name&gt;</varname></term>
 255           <listitem><para>
 256             If the connection used DHCP for address configuration, the received DHCP
 257             configuration is passed in the environment using standard DHCP
 258             option names, prefixed with "DHCP4_", like "DHCP4_HOST_NAME=foobar".
 259           </para></listitem>
 260         </varlistentry>
 261         <varlistentry>
 262           <term><varname>IP6_&lt;name&gt; and DHCP6_&lt;name&gt;</varname></term>
 263           <listitem><para>
 264             The same variables as for IPv4 are available for IPv6, but the prefixes are IP6_
 265             and DHCP6_ instead.
 266           </para></listitem>
 267         </varlistentry>
 268       </variablelist>
 269     </para>
 270     <para>
 271       In case of VPN, VPN_IP_IFACE is set, and IP4_*, IP6_* variables with VPN prefix are
 272       exported too, like VPN_IP4_ADDRESS_0, VPN_IP4_NUM_ADDRESSES.
 273     </para>
 274     <para>
 275       Dispatcher scripts are run one at a time, but asynchronously from the main
 276       NetworkManager process, and will be killed if they run for too long. If your script
 277       might take arbitrarily long to complete, you should spawn a child process and have the
 278       parent return immediately. Scripts that are symbolic links pointing inside the
 279       /etc/NetworkManager/dispatcher.d/no-wait.d/ directory are run immediately, without
 280       waiting for the termination of previous scripts, and in parallel. Also beware that
 281       once a script is queued, it will always be run, even if a later event renders it
 282       obsolete. (Eg, if an interface goes up, and then back down again quickly, it is
 283       possible that one or more "up" scripts will be run after the interface has gone down.)
 284     </para>
 285   </refsect1>
 286
 287   <refsect1>
 288     <title>Options</title>
 289
 290     <para>The following options are understood:</para>
 291
 292     <variablelist>
 293       <varlistentry>
 294         <term><option>--version</option> | <option>-V</option></term>
 295         <listitem><para>Print the NetworkManager software version and exit.
 296         </para></listitem>
 297       </varlistentry>
 298       <varlistentry>
 299         <term><option>--help</option> | <option>-h</option></term>
 300         <listitem><para>Print NetworkManager's available options and exit.
 301         </para></listitem>
 302       </varlistentry>
 303       <varlistentry>
 304         <term><option>--no-daemon</option> | <option>-n</option></term>
 305         <listitem><para>Do not daemonize.
 306         </para></listitem>
 307       </varlistentry>
 308       <varlistentry>
 309         <term><option>--debug</option> | <option>-d</option></term>
 310         <listitem><para>Do not daemonize, and direct log output to the
 311         controlling terminal in addition to syslog.
 312         </para></listitem>
 313       </varlistentry>
 314       <varlistentry>
 315         <term><option>--pid-file</option> | <option>-p</option></term>
 316         <listitem><para>Specify location of a PID file.  The PID file
 317         is used for storing PID of the running process and prevents
 318         running multiple instances.
 319         </para></listitem>
 320       </varlistentry>
 321       <varlistentry>
 322         <term><option>--state-file</option></term>
 323         <listitem><para>Specify file for storing state of the
 324         NetworkManager persistently.  If not specified, the default
 325         value of /var/lib/NetworkManager/NetworkManager.state is used.
 326         </para></listitem>
 327       </varlistentry>
 328       <varlistentry>
 329         <term><option>--config</option></term>
 330         <listitem><para> Specify configuration file to set up various
 331         settings for NetworkManager.  If not specified, the default
 332         value of /etc/NetworkManager/NetworkManager.conf is used with
 333         a fallback to the older 'nm-system-settings.conf' if located
 334         in the same directory.  See
 335         <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 336         for more information on configuration file.
 337         </para></listitem>
 338       </varlistentry>
 339       <varlistentry>
 340         <term><option>--plugins</option></term>
 341         <listitem><para>List plugins used to manage system-wide
 342         connection settings.  This list has preference over plugins
 343         specified in the configuration file.  Currently supported
 344         plugins are: keyfile, <option>ifcfg-rh</option>,
 345         <option>ifcfg-suse</option>, <option>ifupdown</option>.
 346         </para></listitem>
 347       </varlistentry>
 348       <varlistentry>
 349         <term><option>--log-level</option></term>
 350         <listitem><para>
 351           Sets how much information NetworkManager sends to the log destination (usually
 352           syslog's "daemon" facility).  By default, only informational, warning, and error
 353           messages are logged. See the section on <literal>logging</literal> in
 354           <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 355           for more information.
 356         </para></listitem>
 357       </varlistentry>
 358       <varlistentry>
 359         <term><option>--log-domains</option></term>
 360         <listitem><para>
 361           A comma-separated list specifying which operations are logged to the log
 362           destination (usually syslog). By default, most domains are logging-enabled.
 363           See the section on <literal>logging</literal> in
 364           <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 365           for more information.
 366         </para></listitem>
 367       </varlistentry>
 368       <varlistentry>
 369         <term><option>--print-config</option></term>
 370         <listitem><para>
 371           Print the NetworkManager configuration to stdout and exit.
 372         </para></listitem>
 373       </varlistentry>
 374     </variablelist>
 375   </refsect1>
 376
 377   <refsect1>
 378     <title>UDEV PROPERTIES</title>
 379
 380     <para>
 381       <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 382       device manager is used for the network device discovery. The following
 383       property influences how NetworkManager manages the devices:
 384     </para>
 385
 386     <variablelist>
 387       <varlistentry>
 388         <term><varname>NM_UNMANAGED</varname></term>
 389         <listitem><para>
 390           No default connection will be created and automatic activation
 391           will not be attempted when this property of a device is set to a
 392           true value ("1" or "true"). You will still be able to attach a
 393           connection to the device manually or observe externally added
 394           configuration such as addresses or routes.
 395         </para><para>
 396           Create an udev rule that sets this property to prevent NetworkManager
 397           from interfering with virtual Ethernet device interfaces that are
 398           managed by virtualization tools.
 399         </para></listitem>
 400       </varlistentry>
 401     </variablelist>
 402   </refsect1>
 403
 404   <refsect1>
 405     <title>SIGNALS</title>
 406     <para>
 407       NetworkManager process handles the following signals:
 408       <variablelist>
 409         <varlistentry>
 410           <term><varname>SIGHUP</varname></term>
 411           <listitem><para>
 412           The signal causes a reload of NetworkManager's configuration.
 413           Note that not all configuration parameters can be changed at
 414           runtime and therefore some changes may be applied only after
 415           the next restart of the daemon. The signal also forces a
 416           rewrite of DNS configuration.
 417           </para></listitem>
 418         </varlistentry>
 419         <varlistentry>
 420           <term><varname>SIGUSR1</varname></term>
 421           <listitem><para>
 422             The signal forces a rewrite of DNS configuration.
 423           </para></listitem>
 424         </varlistentry>
 425         <varlistentry>
 426           <term><varname>SIGUSR2</varname></term>
 427           <listitem><para>
 428             The signal has no effect at the moment.
 429           </para></listitem>
 430         </varlistentry>
 431       </variablelist>
 432     </para>
 433   </refsect1>
 434
 435   <refsect1>
 436     <title>DEBUGGING</title>
 437     <para>
 438       The following environment variables are supported to help
 439       debugging.  When used in conjunction with the
 440       <option>--no-daemon</option> option (thus echoing PPP and DHCP
 441       helper output to stdout) these can quickly help pinpoint the
 442       source of connection issues.  Also see the
 443       <option>--log-level</option> and <option>--log-domains</option>
 444       to enable debug logging inside NetworkManager itself.
 445     </para>
 446     <para>
 447       <option>NM_PPP_DEBUG</option>: When set to anything, causes
 448       NetworkManager to turn on PPP debugging in pppd, which logs
 449       all PPP and PPTP frames and client/server exchanges.
 450     </para>
 451   </refsect1>
 452
 453   <refsect1>
 454     <title>See Also</title>
 455     <para>
 456       <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 457       <citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 458       <citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 459       <citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 460       <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 461       <citerefentry><refentrytitle>nm-applet</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 462       <citerefentry><refentrytitle>nm-connection-editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 463       <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 464     </para>
 465   </refsect1>
 466 </refentry>