diff options
Diffstat (limited to 'man/NetworkManager.xml')
| -rw-r--r-- | man/NetworkManager.xml | 461 |
1 files changed, 461 insertions, 0 deletions
diff --git a/man/NetworkManager.xml b/man/NetworkManager.xml new file mode 100644 index 00000000..2df37d9a --- /dev/null +++ b/man/NetworkManager.xml @@ -0,0 +1,461 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + Copyright 2005 - 2014 Red Hat, Inc. + Copyright 2005 - 2009 Novell, Inc. + Copyright 2005 Robert Love +--> + +<refentry id="NetworkManager"> + <refentryinfo> + <title>NetworkManager</title> + <author>NetworkManager developers</author> + </refentryinfo> + <refmeta> + <refentrytitle>NetworkManager</refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="source">NetworkManager</refmiscinfo> + <refmiscinfo class="manual">Network management daemons</refmiscinfo> + <refmiscinfo class="version">1.0</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>NetworkManager</refname> + <refpurpose>network management daemon</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>NetworkManager <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The NetworkManager daemon attempts to make networking + configuration and operation as painless and automatic as + possible by managing the primary network connection and other + network interfaces, like Ethernet, WiFi, and Mobile Broadband + devices. NetworkManager will connect any network device when a + connection for that device becomes available, unless that + behavior is disabled. Information about networking is exported + via a D-Bus interface to any interested application, providing a + rich API with which to inspect and control network settings and + operation. + </para> + </refsect1> + + <refsect1> + <title>Dispatcher scripts</title> + <para> + NetworkManager will execute scripts in the + /etc/NetworkManager/dispatcher.d directory or subdirectories in + alphabetical order in response to network events. Each script should + be a regular executable file owned by root. Furthermore, it must not be + writable by group or other, and not setuid. + </para> + <para> + Each script receives two arguments, the first being the interface name of the + device an operation just happened on, and second the action. For device actions, + the interface is the name of the kernel interface suitable for IP configuration. + Thus it is either VPN_IP_IFACE, DEVICE_IP_IFACE, or DEVICE_IFACE, as applicable. + For the <varname>hostname</varname> action it is always "none". + </para> + <para>The actions are:</para> + <variablelist class="dispatcher-options"> + <varlistentry> + <term><varname>pre-up</varname></term> + <listitem><para>The interface is connected to the network but is not + yet fully activated. Scripts acting on this event must be placed or + symlinked into the /etc/NetworkManager/dispatcher.d/pre-up.d directory, + and NetworkManager will wait for script execution to complete before + indicating to applications that the interface is fully activated. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>up</varname></term> + <listitem><para>The interface has been activated.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>pre-down</varname></term> + <listitem><para>The interface will be deactivated but has not yet been + disconnected from the network. Scripts acting on this event must be + placed or symlinked into the /etc/NetworkManager/dispatcher.d/pre-down.d + directory, and NetworkManager will wait for script execution to complete + before disconnecting the interface from its network. Note that this + event is not emitted for forced disconnections, like when carrier is + lost or a wireless signal fades. It is only emitted when there is + an opportunity to cleanly handle a network disconnection event. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>down</varname></term> + <listitem><para> + The interface has been deactivated. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>vpn-pre-up</varname></term> + <listitem><para>The VPN is connected to the network but is not yet + fully activated. Scripts acting on this event must be placed or + symlinked into the /etc/NetworkManager/dispatcher.d/pre-up.d directory, + and NetworkManager will wait for script execution to complete before + indicating to applications that the VPN is fully activated. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>vpn-up</varname></term> + <listitem><para> + A VPN connection has been activated. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>vpn-pre-down</varname></term> + <listitem><para>The VPN will be deactivated but has not yet been + disconnected from the network. Scripts acting on this event must be + placed or symlinked into the /etc/NetworkManager/dispatcher.d/pre-down.d + directory, and NetworkManager will wait for script execution to complete + before disconnecting the VPN from its network. Note that this + event is not emitted for forced disconnections, like when the VPN + terminates unexpectedly or general connectivity is lost. It is only + emitted when there is an opportunity to cleanly handle a VPN + disconnection event. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>vpn-down</varname></term> + <listitem><para> + A VPN connection has been deactivated. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>hostname</varname></term> + <listitem><para> + The system hostname has been updated. Use gethostname(2) to retrieve it. + The interface name (first argument) is empty and no environment variable is + set for this action. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>dhcp4-change</varname></term> + <listitem><para> + The DHCPv4 lease has changed (renewed, rebound, etc). + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>dhcp6-change</varname></term> + <listitem><para> + The DHCPv6 lease has changed (renewed, rebound, etc). + </para></listitem> + </varlistentry> + </variablelist> + <para> + The environment contains more information about the interface and the connection. + The following variables are available for the use in the dispatcher scripts: + <variablelist class="dispatcher-environment"> + <varlistentry> + <term><varname>CONNECTION_UUID</varname></term> + <listitem><para> + The UUID of the connection profile. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>CONNECTION_ID</varname></term> + <listitem><para> + The name (ID) of the connection profile. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>CONNECTION_DBUS_PATH</varname></term> + <listitem><para> + The NetworkManager D-Bus path of the connection. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>CONNECTION_FILENAME</varname></term> + <listitem><para> + The backing file name of the connection profile (if any). + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>CONNECTION_EXTERNAL</varname></term> + <listitem><para> + If "1", this indicates that the connection describes a + network configuration created outside of NetworkManager. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>DEVICE_IFACE</varname></term> + <listitem><para> + The interface name of the device. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>DEVICE_IP_IFACE</varname></term> + <listitem><para> + The IP interface name of the device. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IP4_ADDRESS_N</varname></term> + <listitem><para> + The IPv4 address in the format "address/prefix gateway", where N is a number + from 0 to (# IPv4 addresses - 1). gateway item in this variable is deprecated, + use IP4_GATEWAY instead. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IP4_NUM_ADDRESSES</varname></term> + <listitem><para> + The variable contains the number of IPv4 addresses the script may expect. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IP4_GATEWAY</varname></term> + <listitem><para> + The gateway IPv4 address in traditional numbers-and-dots notation. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IP4_ROUTE_N</varname></term> + <listitem><para> + The IPv4 route in the format "address/prefix next-hop metric", where N is a number + from 0 to (# IPv4 routes - 1). + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IP4_NUM_ROUTES</varname></term> + <listitem><para> + The variable contains the number of IPv4 routes the script may expect. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IP4_NAMESERVERS</varname></term> + <listitem><para> + The variable contains a space-separated list of the DNS servers. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IP4_DOMAINS</varname></term> + <listitem><para> + The variable contains a space-separated list of the search domains. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>DHCP4_<dhcp-option-name></varname></term> + <listitem><para> + If the connection used DHCP for address configuration, the received DHCP + configuration is passed in the environment using standard DHCP + option names, prefixed with "DHCP4_", like "DHCP4_HOST_NAME=foobar". + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IP6_<name> and DHCP6_<name></varname></term> + <listitem><para> + The same variables as for IPv4 are available for IPv6, but the prefixes are IP6_ + and DHCP6_ instead. + </para></listitem> + </varlistentry> + </variablelist> + </para> + <para> + In case of VPN, VPN_IP_IFACE is set, and IP4_*, IP6_* variables with VPN prefix are + exported too, like VPN_IP4_ADDRESS_0, VPN_IP4_NUM_ADDRESSES. + </para> + <para> + Dispatcher scripts are run one at a time, but asynchronously from the main + NetworkManager process, and will be killed if they run for too long. If your script + might take arbitrarily long to complete, you should spawn a child process and have the + parent return immediately. Scripts that are symbolic links pointing inside the + /etc/NetworkManager/dispatcher.d/no-wait.d/ directory are run immediately, without + waiting for the termination of previous scripts, and in parallel. Also beware that + once a script is queued, it will always be run, even if a later event renders it + obsolete. (Eg, if an interface goes up, and then back down again quickly, it is + possible that one or more "up" scripts will be run after the interface has gone down.) + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--version</option> | <option>-V</option></term> + <listitem><para>Print the NetworkManager software version and exit. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option> | <option>-h</option></term> + <listitem><para>Print NetworkManager's available options and exit. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-daemon</option> | <option>-n</option></term> + <listitem><para>Do not daemonize. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--debug</option> | <option>-d</option></term> + <listitem><para>Do not daemonize, and direct log output to the + controlling terminal in addition to syslog. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--pid-file</option> | <option>-p</option></term> + <listitem><para>Specify location of a PID file. The PID file + is used for storing PID of the running process and prevents + running multiple instances. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--state-file</option></term> + <listitem><para>Specify file for storing state of the + NetworkManager persistently. If not specified, the default + value of /var/lib/NetworkManager/NetworkManager.state is used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--config</option></term> + <listitem><para> Specify configuration file to set up various + settings for NetworkManager. If not specified, the default + value of /etc/NetworkManager/NetworkManager.conf is used with + a fallback to the older 'nm-system-settings.conf' if located + in the same directory. See + <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on configuration file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--plugins</option></term> + <listitem><para>List plugins used to manage system-wide + connection settings. This list has preference over plugins + specified in the configuration file. Currently supported + plugins are: keyfile, <option>ifcfg-rh</option>, + <option>ifcfg-suse</option>, <option>ifupdown</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-level</option></term> + <listitem><para> + Sets how much information NetworkManager sends to the log destination (usually + syslog's "daemon" facility). By default, only informational, warning, and error + messages are logged. See the section on <literal>logging</literal> in + <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-domains</option></term> + <listitem><para> + A comma-separated list specifying which operations are logged to the log + destination (usually syslog). By default, most domains are logging-enabled. + See the section on <literal>logging</literal> in + <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--print-config</option></term> + <listitem><para> + Print the NetworkManager configuration to stdout and exit. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>UDEV PROPERTIES</title> + + <para> + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + device manager is used for the network device discovery. The following + property influences how NetworkManager manages the devices: + </para> + + <variablelist> + <varlistentry> + <term><varname>NM_UNMANAGED</varname></term> + <listitem><para> + No default connection will be created and automatic activation + will not be attempted when this property of a device is set to a + true value ("1" or "true"). You will still be able to attach a + connection to the device manually or observe externally added + configuration such as addresses or routes. + </para><para> + Create an udev rule that sets this property to prevent NetworkManager + from interfering with virtual Ethernet device interfaces that are + managed by virtualization tools. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>SIGNALS</title> + <para> + NetworkManager process handles the following signals: + <variablelist> + <varlistentry> + <term><varname>SIGHUP</varname></term> + <listitem><para> + The signal causes a reload of NetworkManager's configuration. + Note that not all configuration parameters can be changed at + runtime and therefore some changes may be applied only after + the next restart of the daemon. The signal also forces a + rewrite of DNS configuration. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SIGUSR1</varname></term> + <listitem><para> + The signal forces a rewrite of DNS configuration. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SIGUSR2</varname></term> + <listitem><para> + The signal has no effect at the moment. + </para></listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1> + <title>DEBUGGING</title> + <para> + The following environment variables are supported to help + debugging. When used in conjunction with the + <option>--no-daemon</option> option (thus echoing PPP and DHCP + helper output to stdout) these can quickly help pinpoint the + source of connection issues. Also see the + <option>--log-level</option> and <option>--log-domains</option> + to enable debug logging inside NetworkManager itself. + </para> + <para> + <option>NM_PPP_DEBUG</option>: When set to anything, causes + NetworkManager to turn on PPP debugging in pppd, which logs + all PPP and PPTP frames and client/server exchanges. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nm-applet</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nm-connection-editor</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> |