DocBook is not my favorite thing in the world, but it's <lots-of-emphasis>far</lots-of-emphasis> saner than troff. Some style parts cribbed from systemd.
This is preparatory work for actually improving the content of the man pages. --- configure.ac | 2 - man/Makefile.am | 16 ++ man/NetworkManager.8.in | 145 ----------------- man/NetworkManager.conf.5.in | 310 ------------------------------------ man/NetworkManager.conf.xml | 362 ++++++++++++++++++++++++++++++++++++++++++ man/NetworkManager.xml | 223 ++++++++++++++++++++++++++ 6 files changed, 601 insertions(+), 457 deletions(-) delete mode 100644 man/NetworkManager.8.in delete mode 100644 man/NetworkManager.conf.5.in create mode 100644 man/NetworkManager.conf.xml create mode 100644 man/NetworkManager.xml
>From d6c878114d0088ff1a313b52f08e40c011bc1e2f Mon Sep 17 00:00:00 2001 From: Colin Walters <[email protected]> Date: Tue, 9 Apr 2013 16:41:00 -0400 Subject: [PATCH] man: Rewrite NetworkManager.8 and NetworkManager.conf.5 in DocBook DocBook is not my favorite thing in the world, but it's <lots-of-emphasis>far</lots-of-emphasis> saner than troff. Some style parts cribbed from systemd. This is preparatory work for actually improving the content of the man pages. --- configure.ac | 2 - man/Makefile.am | 16 ++ man/NetworkManager.8.in | 145 ----------------- man/NetworkManager.conf.5.in | 310 ------------------------------------ man/NetworkManager.conf.xml | 362 ++++++++++++++++++++++++++++++++++++++++++ man/NetworkManager.xml | 223 ++++++++++++++++++++++++++ 6 files changed, 601 insertions(+), 457 deletions(-) delete mode 100644 man/NetworkManager.8.in delete mode 100644 man/NetworkManager.conf.5.in create mode 100644 man/NetworkManager.conf.xml create mode 100644 man/NetworkManager.xml diff --git a/configure.ac b/configure.ac index 034bd68..fb2e118 100644 --- a/configure.ac +++ b/configure.ac @@ -706,8 +706,6 @@ initscript/linexa/networkmanager introspection/Makefile introspection/all.xml man/Makefile -man/NetworkManager.8 -man/NetworkManager.conf.5 man/nm-system-settings.conf.5 man/nm-online.1 man/nmcli.1 diff --git a/man/Makefile.am b/man/Makefile.am index 7db5623..fdf2041 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -14,6 +14,22 @@ nm-settings.xml: $(top_builddir)/tools/generate-settings-spec $(top_builddir)/li $(top_builddir)/tools/generate-settings-spec refentry $(builddir)/$@ CLEANFILES += nm-settings.xml +XSLTPROC_FLAGS = \ + --nonet \ + --stringparam man.output.quietly 1 \ + --stringparam funcsynopsis.style ansi \ + --stringparam man.th.extra1.suppress 1 \ + --stringparam man.authors.section.enabled 0 \ + --stringparam man.copyright.section.enabled 0 + +XSLTPROC_MAN_FLAGS = $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl + +%.8: %.xml + $(AM_V_GEN) xsltproc $(XSLTPROC_MAN_FLAGS) $< + +%.5: %.xml + $(AM_V_GEN) xsltproc $(XSLTPROC_MAN_FLAGS) $< + man_MANS += \ NetworkManager.8 \ NetworkManager.conf.5 \ diff --git a/man/NetworkManager.8.in b/man/NetworkManager.8.in deleted file mode 100644 index 38a195f..0000000 --- a/man/NetworkManager.8.in +++ /dev/null @@ -1,145 +0,0 @@ -.\" NetworkManager(8) manual page -.\" -.\" Copyright (C) 2005 - 2013 Red Hat, Inc. -.\" Copyright (C) 2005 - 2009 Novell, Inc. -.\" Copyright (C) 2005 Robert Love -.\" -.TH NETWORKMANAGER "8" "17 January 2012" -.SH NAME -NetworkManager \- network management daemon -.SH SYNOPSIS -.B NetworkManager [\-\-version] | [\-\-help] -.PP -.B NetworkManager [\-\-no\-daemon] [\-\-pid\-file=<filename>] [\-\-state\-file=<filename>] [\-\-config=<filename>] [\-\-config-dir=<directory>] [\-\-plugins=<plugin1>,plugin2>,...] [\-\-log\-level=<level>] [\-\-log\-domains=<domain1>,<domain2>,...] -.SH DESCRIPTION -The \fINetworkManager\fP 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. -.P -NetworkManager will execute scripts in the /etc/NetworkManager/dispatcher.d -directory in alphabetical order in response to network events. Each script -should be: -.IP "(a)" 4 -a regular file -.IP "(b)" 4 -owned by root -.IP "(c)" 4 -not writable by group or other -.IP "(d)" 4 -not set-uid -.IP "(e)" 4 -and executable by the owner -.PP -Each script receives two arguments, the first being the interface name of the -device just activated, and second an action. -.PP -Actions: -.TP -.I "up" -The interface has been activated. The environment contains more information -about the interface; CONNECTION_UUID contains the UUID of the connection. Other -variables are IP4_ADDRESS_N where N is a number from 0 to (# IPv4 addresses \- 1), -in the format "address/prefix gateway". IP4_NUM_ADDRESSES contains the number -addresses the script may expect. IP4_NAMESERVERS contains a space-separated -list of the DNS servers, and IP4_DOMAINS contains a space-separated list of the -search domains. Routes use the format IP4_ROUTE_N where N is a number from 0 -to (# IPv4 routes \- 1), in the format "address/prefix next-hop metric", and -IP4_NUM_ROUTES contains the number of routes to expect. 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". -.TP -.I "down" -The interface has been deactivated. -.TP -.I "vpn\-up" -A VPN connection has been activated. The environment contains the connection -UUID in the variable CONNECTION_UUID. -.TP -.I "vpn\-down" -A VPN connection has been deactivated. -.TP -.I "hostname" -The system hostname has been updated. Use gethostname(2) to retrieve it. -.TP -.I "dhcp4\-change" -The DHCPv4 lease has changed (renewed, rebound, etc). -.TP -.I "dhcp6\-change" -The DHCPv6 lease has changed (renewed, rebound, etc). -.SH OPTIONS -The following options are supported: -.TP -.I "\-\-version" -Print the NetworkManager software version and exit. -.TP -.I "\-\-help" -Print NetworkManager's available options and exit. -.TP -.I "\-\-no\-daemon" -Do not daemonize. This is useful for debugging, and directs log output to the -controlling terminal in addition to syslog. -.TP -.I "\-\-pid\-file=<filename>" -Specify location of a PID file. The PID file is used for storing PID of the -running proccess and prevents running multiple instances. -.TP -.I "\-\-state\-file=<filename>" -Specify file for storing state of the NetworkManager persistently. If not specified, -the default value of '<LOCALSTATEDIR>/lib/NetworkManager/NetworkManager.state' is -used; where <LOCALSTATEDIR> is dependent on your distribution (usually it's /var). -.TP -.I "\-\-config=<filename>" -Specify configuration file to set up various settings for NetworkManager. If not -specified, the default value of '<SYSCONFDIR>/NetworkManager/NetworkManager.conf' -is used with a fallback to the older 'nm\-system\-settings.conf' if located in -the same directory; where <SYSCONFDIR> is dependent on your distribution (usually -it's /etc). See \fBNetworkManager.conf\fP(5) for more information on configuration -file. -.TP -.I "\-\-config-dir=<directory>" -Specify configuration directory for files that override NetworkManager.conf. If not -specified, the default value of '<SYSCONFDIR>/NetworkManager/conf.d' -is used. See \fBNetworkManager.conf\fP(5) for more information on configuration -file. -.TP -.I "\-\-plugins=<plugin1>,<plugin2>, ... -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, ifcfg\-rh, ifcfg\-suse, ifupdown. -See \fBNetworkManager.conf\fP(5) for more information on the plugins. -.TP -.I "\-\-log\-level=<level> -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 \fBNetworkManager.conf\fP(5) for more information on -log levels and domains. -.TP -.I "\-\-log\-domains=<domain1>,<domain2>, ... -Sets which operations are logged to the log destination (usually syslog). By -default, most domains are logging-enabled. See \fBNetworkManager.conf\fP(5) for -more information on log levels and domains. - -.SH DEBUGGING -The following environment variables are supported to help debugging. When used -in conjunction with the "\-\-no\-daemon" option (thus echoing PPP and DHCP helper -output to stdout) these can quickly help pinpoint the source of connection -issues. Also see the \-\-log\-level and \-\-log\-domains to enable debug logging inside -NetworkManager itself. -.TP -.I "NM_PPP_DEBUG" -When set to anything, causes NetworkManager to turn on PPP debugging in pppd, -which logs all PPP and PPTP frames and client/server exchanges. -.SH SEE ALSO -.BR nm\-online (1), -.BR nmcli (1), -.BR NetworkManager.conf (5), -.BR nm\-settings (5), -.BR nm\-applet (1), -.BR nm\-connection\-editor (1). - diff --git a/man/NetworkManager.conf.5.in b/man/NetworkManager.conf.5.in deleted file mode 100644 index 368d776..0000000 --- a/man/NetworkManager.conf.5.in +++ /dev/null @@ -1,310 +0,0 @@ -.\" NetworkManager.conf(5) manual page -.\" -.\" Copyright (C) 2010 - 2013 Red Hat, Inc. -.\" -.TH "NetworkManager.conf" "5" "14 March 2013" "" -.SH NAME -NetworkManager.conf \- NetworkManager configuration file -.SH SYNOPSIS -/etc/NetworkManager/NetworkManager.conf -.br -/etc/NetworkManager/conf.d/*.conf -.br -or -.br -\fI<SYSCONFDIR>\fP/NetworkManager/NetworkManager.conf -.br -\fI<SYSCONFDIR>\fP/NetworkManager/conf.d/*.conf -.br -where <SYSCONFDIR> depends on your distribution or build. -.SH DESCRIPTION -.P -.I NetworkManager.conf -is a configuration file for NetworkManager. It is used to set up various -aspects of NetworkManager's behavior. The location of -the file may be changed through use of the "\-\-config=" argument for -\fBNetworkManager\fP (8). -.P -If a default -.I NetworkManager.conf -is provided by your distribution's packages, you should not modify it, -since your changes may get overwritten by package updates. Instead, -you can add additional -.I .conf -files to the -.I conf.d -directory. These will be read in order, with later files overriding -earlier ones. -.SH "FILE FORMAT" -.P -The configuration file format is so-called key file (sort of ini-style format). -It consists of sections (groups) of key-value pairs. Lines beginning with a '#' and blank -lines are considered comments. Sections are started by a header line containing -the section enclosed in '[' and ']', and ended implicitly by the start of -the next section or the end of the file. Each key-value pair must be contained -in a section. -.P -For keys that take a list of devices as their value, you can specify -devices by their MAC addresses or interface names, or "*" to specify -all devices. -.P -Minimal system settings configuration file looks like this: -.P -.nf -[main] -plugins=keyfile -.fi -.P -As an extension to the normal keyfile format, you can also append a -value to a previously-set list-valued key by doing: -.P -.nf -[main] -plugins+=another-plugin -.fi -.P -Description of sections and available keys follows: -.SS [main] -This section is the only mandatory section of the configuration file. -.TP -.B plugins=\fIplugin1\fP,\fIplugin2\fP, ... -List system settings plugin names separated by ','. These plugins are used to -read/write system-wide connection. When more plugins are specified, the -connections are read from all listed plugins. When writing connections, the -plugins will be asked to save the connection in the order listed here. If the -first plugin cannot write out that connection type, or can't write out any -connections, the next plugin is tried. If none of the plugins can save the -connection, the error is returned to the user. -.P -.RS -.B "Available plugins:" -.br -.TP -.I keyfile -plugin is the generic plugin that supports all the connection types and -capabilities that NetworkManager has. It writes files out in a .ini-style format in -/etc/NetworkManager/system-connections. For security, it will ignore files -that are readable or writeable by any user or group other than -.I root -since private keys and passphrases may be stored in plaintext inside the file. -.TP -.I ifcfg\-rh -plugin is used on the Fedora and Red Hat Enterprise Linux distributions -to read and write configuration from the standard /etc/sysconfig/network-scripts/ifcfg-* files. -It currently supports reading wired, WiFi, and 802.1x connections, but does not yet support reading -or writing mobile broadband, PPPoE, or VPN connections. To allow reading and writing of these -add \fIkeyfile\fP plugin to your configuration as well. -.TP -.I ifupdown -plugin is used on the Debian and Ubuntu distributions, and reads connections from -/etc/network/interfaces. Since it cannot write connections out (that support isn't planned), -it is usually paired with the \fIkeyfile\fP plugin to enable saving and editing of new connections. -The \fIifupdown\fP plugin supports basic wired and WiFi connections, including WPA-PSK. -.TP -.I ifcfg\-suse -plugin is only provided for simple backward compatibility with SUSE and OpenSUSE configuration. -Most setups should be using the \fIkeyfile\fP plugin instead. The \fIifcfg\-suse\fP plugin supports -reading wired and WiFi connections, but does not support saving any connection types. -.RE -.TP -.B dhcp=\fIdhclient\fP | \fIdhcpcd\fP -This key sets up what DHCP client NetworkManager will use. Presently -\fIdhclient\fP and \fIdhcpcd\fP are supported. The client configured here should -be available on your system too. If this key is missing, available DHCP clients -are looked for in this order: dhclient, dhcpcd. -.TP -.B no-auto-default=\fI<device>\fP,\fI<device>\fP,... | \fI*\fP -Set devices for which NetworkManager shouldn't create default wired connection -(Auto eth0). NetworkManager creates a default wired connection for any Ethernet -device that is managed and doesn't have a connection configured. List a device -in this option to inhibit creating the default connection for the device. -.br -When the default wired connection is deleted or saved to a new persistent connection -by a plugin, the device is added to a list in the file -\fI<LOCALSTATEDIR>\fP/run/NetworkManager/no-auto-default.state -to prevent creating the default connection for that device again. -.br -Examples: -.nf -no-auto-default=00:22:68:5c:5d:c4,00:1e:65:ff:aa:ee -no-auto-default=eth0,eth1 -no-auto-default=* -.fi -.TP -.B ignore-carrier=\fI<device>\fP,\fI<device>\fP,... | \fI*\fP -Set devices for which NetworkManager should ignore device carrier state when -deciding whether to activate or deactivate connections. -.TP -.B dns=\fImode\fP -Set the DNS/resolv.conf-processing mode. -.P -.RS -.B "Supported modes:" -.br -.TP -.I default -The default if the key is not specified. NetworkManager will update -resolv.conf to reflect the nameservers provided by currently active -connections. -.TP -.I dnsmasq -NetworkManager will run dnsmasq as a local caching nameserver, using -a "split DNS" configuration if you are connected to a VPN, and then -update resolv.conf to point to the local nameserver. -.TP -.I none -NetworkManager will not modify resolv.conf. -.RE -.SS [keyfile] -This section contains keyfile-specific options and thus only has effect when using \fIkeyfile\fP plugin. -.TP -.B hostname=\fI<hostname>\fP -Set a persistent hostname when using the \fIkeyfile\fP plugin. -.TP -.B unmanaged-devices=\fImac:<hwaddr>\fP;\fIinterface\-name:<iface name>\fP;... -Set devices that should be ignored by NetworkManager when using the \fIkeyfile\fP -plugin. Devices are specified in the following format: -.br -"mac:<hwaddr>" or "interface\-name:<iface name>" -.sp -\fI<hwaddr>\fP is MAC address of the device to be ignored, in hex-digits-and-colons notation -.br -\fI<iface name>\fP is the interface name of the ignored device -.br -Multiple entries are separated with semicolons. No spaces are allowed in the value. -.sp -Examples: -.nf -unmanaged-devices=interface-name:em4 -unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2 -.fi -.SS [ifupdown] -This section contains ifupdown-specific options and thus only has effect when using \fIifupdown\fP plugin. -.TP -.B managed=\fIfalse\fP | \fItrue\fP -Controls whether interfaces listed in the 'interfaces' file are managed by NetworkManager. -If set to \fItrue\fP, then interfaces listed in /etc/network/interfaces are managed by NetworkManager. -If set to \fIfalse\fP, then any interface listed in /etc/network/interfaces will be -ignored by NetworkManager. Remember that NetworkManager controls the default route, -so because the interface is ignored, NetworkManager may assign the default route to -some other interface. -When the option is missing, \fIfalse\fP value is taken as default. -.SS [logging] -This section controls NetworkManager's logging. Any settings here are -overridden by the \-\-log\-level and \-\-log\-domains command-line options. -.TP -.B level=\fI<level>\fP -One of [ERR, WARN, INFO, DEBUG]. The ERR level logs only critical errors. WARN -logs warnings that may reflect operation. INFO logs various informational -messages that are useful for tracking state and operations. DEBUG enables -verbose logging for debugging purposes. Subsequent levels also log all messages -from earlier levels; thus setting the log level to INFO also logs error and -warning messages. -.TP -.B domains=\fI<domain1>,<domain2>, ...\fP -The following log domains are available: [HW, RFKILL, ETHER, WIFI, BT, MB, DHCP4, -DHCP6, PPP, WIFI_SCAN, IP4, IP6, AUTOIP4, DNS, VPN, SHARING, SUPPLICANT, AGENTS, -SETTINGS, SUSPEND, CORE, DEVICE, OLPC, WIMAX, INFINIBAND, FIREWALL, ADSL, BOND, -VLAN, BRIDGE]. -.br -In addition to them, these special domains can be used: [NONE, ALL, DEFAULT, DHCP, IP]. -.PP -.RS -NONE = when given by itself, logging is disabled -.br -ALL = all log domains will be switched on -.br -DEFAULT = default log domains -.br -DHCP = a shortcut for "DHCP4, DHCP6" -.br -IP = a shortcut for "IP4, IP6" -.br -.PP -HW = Hardware related operations -.br -RFKILL = RFKill subsystem operations -.br -ETHER = Ethernet device operations -.br -WIFI = Wi-Fi device operations -.br -BT = Bluetooth -.br -MB = Mobile Broadband -.br -DHCP4 = DHCP for IPv4 -.br -DHCP6 = DHCP for IPv6 -.br -PPP = Point-to-point protocol operations -.br -WIFI_SCAN = Wi-Fi scanning operations -.br -IP4 = Domain for IPv4 logging -.br -IP6 = Domain for IPv6 logging -.br -AUTOIP4 = AutoIP (avahi) operations -.br -DNS = Domain Name System related operations -.br -VPN = Virtual Private Network connections and operaions -.br -SHARING = Connection sharing -.br -SUPPLICANT = WPA supplicant related operations -.br -AGENTS = Secret agents operations and communication -.br -SETTINGS = Settings/config service operations -.br -SUSPEND = Suspend/resume -.br -CORE = Core daemon operations -.br -DEVICE = Activation and general interface operations -.br -OLPC = OLPC Mesh device operations -.br -WIMAX = Wimax device operations -.br -INFINIBAND = InfiniBand device operations -.br -FIREWALL = FirewallD related operations -.br -ADSL = ADSL device operations -.br -BOND = Bonding device operations -.br -VLAN = VLAN device operations -.br -BRIDGE = Bridging device operations -.br -.SS [connectivity] -This section controls NetworkManager's optional connectivity checking -functionality. This allows NetworkManager to detect whether or not the system -can actually access the internet or whether it is behind a captive portal. -.TP -.B uri=\fI<uri>\fP -The URI of a web page to periodically request when connectivity is being checked. -This page should return the header "X-NetworkManager-Status" with a value of -"online". Alternatively, it's body content should be set to "NetworkManager -is online". The body content check can be controlled by the \fIresponse\fP -option. If this option is blank or missing, connectivity checking is disabled. -.TP -.B interval=\fI<seconds>\fP -Controls how often connectivity is checked when a network connection exists. If -set to 0 connectivity checking is disabled. If missing, the default is 300 -seconds. -.TP -.B response=\fI<response>\fP -If set controls what body content NetworkManager checks for when requesting the -URI for connectivity checking. If missing, defaults to "NetworkManager is online" -.SH "SEE ALSO" -.BR http://live.gnome.org/NetworkManager/SystemSettings -.sp -.BR NetworkManager (8), -.BR nmcli (1), -.BR nm\-online (1), -.BR nm\-settings (5). diff --git a/man/NetworkManager.conf.xml b/man/NetworkManager.conf.xml new file mode 100644 index 0000000..23f7244 --- /dev/null +++ b/man/NetworkManager.conf.xml @@ -0,0 +1,362 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";> + +<!-- +Copyright (C) 2010 - 2013 Red Hat, Inc. +--> + +<refentry id="NetworkManager.conf"> + <refentryinfo> + <title>NetworkManager.conf</title> + </refentryinfo> + + <refmeta> + <refentrytitle>NetworkManager.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>NetworkManager.conf</refname> + <refpurpose>NetworkManager configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/NetworkManager/NetworkManager.conf</filename>, + <filename>/etc/NetworkManager/conf.d/<replaceable>name</replaceable>.conf</filename> + </para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para>This is a configuration file for NetworkManager. It is used + to set up various aspects of NetworkManager's behavior. The + location of the file may be changed through use of the + <option>--config</option> argument for NetworkManager. + </para> + <para>If a default <literal>NetworkManager.conf</literal> is + provided by your distribution's packages, you should not modify + it, since your changes may get overwritten by package + updates. Instead, you can add additional <literal>.conf</literal> + files to the <literal>conf.d</literal> directory. These will be read in order, + with later files overriding earlier ones. + </para> + + </refsect1> + + <refsect1> + <title>File Format</title> + <para> + The configuration file format is so-called key file (sort of + ini-style format). It consists of sections (groups) of + key-value pairs. Lines beginning with a '#' and blank lines are + considered comments. Sections are started by a header line + containing the section enclosed in '[' and ']', and ended + implicitly by the start of the next section or the end of the + file. Each key-value pair must be contained in a section. + </para> + <para> + For keys that take a list of devices as their value, you can + specify devices by their MAC addresses or interface names, or + "*" to specify all devices. + </para> + <para> + Minimal system settings configuration file looks like this: + <programlisting> + [main] + plugins=keyfile + </programlisting> + </para> + <para> + As an extension to the normal keyfile format, you can also + append a value to a previously-set list-valued key by doing: + <programlisting> + plugins+=another-plugin + </programlisting> + </para> + </refsect1> + + <refsect1> + <title><literal>main</literal> section (mandatory)</title> + <variablelist> + <varlistentry> + <term><varname>plugins</varname></term> + <listitem><para>List system settings plugin names separated + by ','. These plugins are used to read/write system-wide + connection. When more plugins are specified, the connections + are read from all listed plugins. When writing connections, + the plugins will be asked to save the connection in the + order listed here. If the first plugin cannot write out that + connection type, or can't write out any connections, the + next plugin is tried. If none of the plugins can save the + connection, the error is returned to the user. See below + for available plugins.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>dhcp</varname></term> + <listitem><para>This key sets up what DHCP client + NetworkManager will use. Presently + <literal>dhclient</literal> and <literal>dhcpcd</literal> + are supported. The client configured here should be + available on your system too. If this key is missing, + available DHCP clients are looked for in this order: + dhclient, dhcpcd.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>no-auto-default</varname></term> + <listitem><para>Comma-separated list of devices for which + NetworkManager shouldn't create default wired connection + (Auto eth0). By default, NetworkManager creates a temporary + wired connection for any Ethernet device that is managed and + doesn't have a connection configured. List a device in this + option to inhibit creating the default connection for the + device. May have the special value <literal>*</literal> to + apply to all devices.</para> + <para>When the default wired connection is deleted or saved + to a new persistent connection by a plugin, the device is + added to a list in the file + <filename>/var/run/NetworkManager/no-auto-default.state</filename> + to prevent creating the default connection for that device + again.</para> + <para> + <programlisting> + no-auto-default=00:22:68:5c:5d:c4,00:1e:65:ff:aa:ee + no-auto-default=eth0,eth1 + no-auto-default=* + </programlisting> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ignore-carrier</varname></term> + <listitem><para>Set devices for which NetworkManager should + ignore device carrier state when deciding whether to + activate or deactivate connections. May have the special + value <literal>*</literal> to apply to all + devices.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>dns</varname></term> + <listitem><para>Set the DNS (<filename>resolv.conf</filename>) processing mode.</para> + <para><literal>default</literal>: The default if the key is + not specified. NetworkManager will update + <filename>resolv.conf</filename> to reflect the nameservers + provided by currently active connections.</para> + <para><literal>dnsmasq</literal>NetworkManager will run + dnsmasq as a local caching nameserver, using a "split DNS" + configuration if you are connected to a VPN, and then update + <filename>resolv.conf</filename> to point to the local + nameserver.</para> + <para><literal>none</literal>: NetworkManager will not + modify resolv.conf.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title><literal>keyfile</literal> section</title> + <para>This section contains keyfile-specific options and thus only has effect when using the <literal>keyfile</literal> plugin.</para> + + <para> + <variablelist> + <varlistentry> + <term><varname>hostname</varname></term> + <listitem><para>Set a persistent hostname.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>unmanaged-devices</varname></term> + <listitem><para>Set devices that should be ignored by + NetworkManager when using the <literal>keyfile</literal> + plugin. Devices are specified in the following + format:</para> + <para><literal>mac:<hwaddr></literal> or + <literal>interface-name:<ifname></literal>. Here + <literal>hwaddr</literal> is the MAC address of the device + to be ignored, in hex-digits-and-colons notation. + <literal>ifname</literal> is the interface name of the + ignored device.</para> + <para>Multiple entries are separated with semicolons. No + spaces are allowed in the value.</para> + <para> + Example: + <programlisting> +unmanaged-devices=interface-name:em4 +unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth2 + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1> + <title><literal>ifupdown</literal> section</title> + <para>This section contains keyfile-specific options and thus only + has effect when using the <literal>ifdown</literal> plugin.</para> + + <para> + <variablelist> + <varlistentry> + <term><varname>managed</varname></term> + <listitem><para>If set to <literal>true</literal>, then + interfaces listed in + <filename>/etc/network/interfaces</filename> are managed by + NetworkManager. If set to <literal>false</literal>, then + any interface listed in + <filename>/etc/network/interfaces</filename> will be ignored + by NetworkManager. Remember that NetworkManager controls the + default route, so because the interface is ignored, + NetworkManager may assign the default route to some other + interface.</para> + <para> + The default value is <literal>false</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1> + <title><literal>logging</literal> section</title> + <para>This section controls NetworkManager's logging. Any + settings here are overridden by the <option>--log-level</option> + and <option>--log-domains</option> command-line options.</para> + + <para> + <variablelist> + <varlistentry> + <term><varname>level</varname></term> + <listitem><para>One of <literal>ERR</literal>, + <literal>WARN</literal>, <literal>INFO</literal>, + <literal>DEBUG</literal>. The ERR level logs only critical + errors. WARN logs warnings that may reflect operation. + INFO logs various informational messages that are useful for + tracking state and operations. DEBUG enables verbose + logging for debugging purposes. Subsequent levels also log + all messages from earlier levels; thus setting the log level + to INFO also logs error and warning messages.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>domains</varname></term> + <listitem><para>The following log domains are available: + HW, RFKILL, ETHER, WIFI, BT, MB, DHCP4, DHCP6, PPP, + WIFI_SCAN, IP4, IP6, AUTOIP4, DNS, VPN, SHARING, SUPPLICANT, + AGENTS, SETTINGS, SUSPEND, CORE, DEVICE, OLPC, WIMAX, + INFINIBAND, FIREWALL, ADSL, BOND, VLAN, BRIDGE.</para> + <para>In addition, these special domains can be used: NONE, + ALL, DEFAULT, DHCP, IP.</para></listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1> + <title><literal>connectivity</literal> section</title> + <para>This section controls NetworkManager's optional connectivity + checking functionality. This allows NetworkManager to detect + whether or not the system can actually access the internet or + whether it is behind a captive portal.</para> + + <para> + <variablelist> + <varlistentry> + <term><varname>uri</varname></term> + <listitem><para>The URI of a web page to periodically + request when connectivity is being checked. This page + should return the header "X-NetworkManager-Status" with a + value of "online". Alternatively, it's body content should + be set to "NetworkManager is online". The body content + check can be controlled by the <literal>response</literal> + option. If this option is blank or missing, connectivity + checking is disabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>interval</varname></term> + <listitem><para>Specified in seconds; controls how often + connectivity is checked when a network connection exists. If + set to 0 connectivity checking is disabled. If missing, the + default is 300 seconds.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>response</varname></term> + <listitem><para>If set controls what body content + NetworkManager checks for when requesting the URI for + connectivity checking. If missing, defaults to + "NetworkManager is online" </para></listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1> + <title>Plugins</title> + + <variablelist> + <varlistentry> + <term><varname>keyfile</varname></term> + <listitem><para>plugin is the generic plugin that supports + all the connection types and capabilities that + NetworkManager has. It writes files out in an .ini-style + format in /etc/NetworkManager/system-connections. For + security, it will ignore files that are readable or + writeable by any user or group other than root since + private keys and passphrases may be stored in plaintext + inside the file. </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>ifcfg-rh</varname></term> + <listitem><para>This plugin is used on the Fedora and Red + Hat Enterprise Linux distributions to read and write + configuration from the standard + <filename>/etc/sysconfig/network-scripts/ifcfg-*</filename> + files. It currently supports reading wired, WiFi, and + 802.1x connections, but does not yet support reading or + writing mobile broadband, PPPoE, or VPN connections. To + allow reading and writing of these add <literal>keyfile</literal> + plugin to your configuration as well.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ifupdown</varname></term> + <listitem><para>This plugin is used on the Debian and Ubuntu + distributions, and reads connections from + <filename>/etc/network/interfaces</filename>. Since it cannot + write connections out (that support isn't planned), it is + usually paired with the <literal>keyfile</literal> plugin to + enable saving and editing of new connections. The + <literal>ifupdown</literal> plugin supports basic wired and + WiFi connections, including WPA-PSK.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ifcfg-suse</varname></term> + <listitem><para>This plugin is only provided for simple + backward compatibility with SUSE and OpenSUSE + configuration. Most setups should be using the + <literal>keyfile</literal> plugin instead. The + <literal>ifcfg-suse</literal> plugin supports reading + wired and WiFi connections, but does not support saving + any connection types.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</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> + </para> + </refsect1> +</refentry> + diff --git a/man/NetworkManager.xml b/man/NetworkManager.xml new file mode 100644 index 0000000..df1815a --- /dev/null +++ b/man/NetworkManager.xml @@ -0,0 +1,223 @@ +<?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 (C) 2005 - 2013 Red Hat, Inc. + Copyright (C) 2005 - 2009 Novell, Inc. + Copyright (C) 2005 Robert Love + +--> + +<refentry id="NetworkManager"> + <refentryinfo> + <title>NetworkManager</title> + </refentryinfo> + <refmeta> + <refentrytitle>NetworkManager</refentrytitle> + <manvolnum>8</manvolnum> + </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> + <para> + NetworkManager will execute scripts in the + /etc/NetworkManager/dispatcher.d directory 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 just activated, and second an action. + </para> + <variablelist class="dispatcher-options"> + <varlistentry> + <term><varname>up</varname></term> + <listitem><para>The interface has been activated. The + environment contains more information about the interface; + CONNECTION_UUID contains the UUID of the connection. Other + variables are IP4_ADDRESS_N where N is a number from 0 to (# + IPv4 addresses \- 1), in the format "address/prefix gateway". + IP4_NUM_ADDRESSES contains the number addresses the script may + expect. IP4_NAMESERVERS contains a space-separated list of + the DNS servers, and IP4_DOMAINS contains a space-separated + list of the search domains. Routes use the format IP4_ROUTE_N + where N is a number from 0 to (# IPv4 routes \- 1), in the + format "address/prefix next-hop metric", and IP4_NUM_ROUTES + contains the number of routes to expect. 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>down</varname></term> + <listitem><para> + The interface has been deactivated. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>vpn-up</varname></term> + <listitem><para> + A VPN connection has been activated. The environment contains the connection + UUID in the variable CONNECTION_UUID. + </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. + </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> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--version</option></term> + <listitem><para>Print the NetworkManager software version and exit. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option></term> + <listitem><para>Print NetworkManager's available options and exit. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-daemon</option></term> + <listitem><para>Do not daemonize. This is useful for + debugging, and directs log output to the controlling terminal + in addition to syslog. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--pid-file</option></term> + <listitem><para>Specify location of a PID file. The PID file + is used for storing PID of the running proccess 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. + </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. + </para></listitem> + </varlistentry> + </variablelist> + </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>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</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> + </para> + </refsect1> +</refentry> -- 1.7.1
_______________________________________________ networkmanager-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/networkmanager-list
