1NETWORKMANAGER(8)         Network management daemons         NETWORKMANAGER(8)
2
3
4

NAME

6       NetworkManager - network management daemon
7

SYNOPSIS

9       NetworkManager [OPTIONS...]
10

DESCRIPTION

12       The NetworkManager daemon attempts to make networking configuration and
13       operation as painless and automatic as possible by managing the primary
14       network connection and other network interfaces, like Ethernet, Wi-Fi,
15       and Mobile Broadband devices. NetworkManager will connect any network
16       device when a connection for that device becomes available, unless that
17       behavior is disabled. Information about networking is exported via a
18       D-Bus interface to any interested application, providing a rich API
19       with which to inspect and control network settings and operation.
20

DISPATCHER SCRIPTS

22       NetworkManager will execute scripts in the
23       /etc/NetworkManager/dispatcher.d directory or subdirectories in
24       alphabetical order in response to network events. Each script should be
25       a regular executable file owned by root. Furthermore, it must not be
26       writable by group or other, and not setuid.
27
28       Each script receives two arguments, the first being the interface name
29       of the device an operation just happened on, and second the action. For
30       device actions, the interface is the name of the kernel interface
31       suitable for IP configuration. Thus it is either VPN_IP_IFACE,
32       DEVICE_IP_IFACE, or DEVICE_IFACE, as applicable. For the hostname
33       action the device name is always "none" and for connectivity-change it
34       is empty.
35
36       The actions are:
37
38       pre-up
39           The interface is connected to the network but is not yet fully
40           activated. Scripts acting on this event must be placed or symlinked
41           into the /etc/NetworkManager/dispatcher.d/pre-up.d directory, and
42           NetworkManager will wait for script execution to complete before
43           indicating to applications that the interface is fully activated.
44
45       up
46           The interface has been activated.
47
48       pre-down
49           The interface will be deactivated but has not yet been disconnected
50           from the network. Scripts acting on this event must be placed or
51           symlinked into the /etc/NetworkManager/dispatcher.d/pre-down.d
52           directory, and NetworkManager will wait for script execution to
53           complete before disconnecting the interface from its network. Note
54           that this event is not emitted for forced disconnections, like when
55           carrier is lost or a wireless signal fades. It is only emitted when
56           there is an opportunity to cleanly handle a network disconnection
57           event.
58
59       down
60           The interface has been deactivated.
61
62       vpn-pre-up
63           The VPN is connected to the network but is not yet fully activated.
64           Scripts acting on this event must be placed or symlinked into the
65           /etc/NetworkManager/dispatcher.d/pre-up.d directory, and
66           NetworkManager will wait for script execution to complete before
67           indicating to applications that the VPN is fully activated.
68
69       vpn-up
70           A VPN connection has been activated.
71
72       vpn-pre-down
73           The VPN will be deactivated but has not yet been disconnected from
74           the network. Scripts acting on this event must be placed or
75           symlinked into the /etc/NetworkManager/dispatcher.d/pre-down.d
76           directory, and NetworkManager will wait for script execution to
77           complete before disconnecting the VPN from its network. Note that
78           this event is not emitted for forced disconnections, like when the
79           VPN terminates unexpectedly or general connectivity is lost. It is
80           only emitted when there is an opportunity to cleanly handle a VPN
81           disconnection event.
82
83       vpn-down
84           A VPN connection has been deactivated.
85
86       hostname
87           The system hostname has been updated. Use gethostname(2) to
88           retrieve it. The interface name (first argument) is empty and no
89           environment variable is set for this action.
90
91       dhcp4-change
92           The DHCPv4 lease has changed (renewed, rebound, etc).
93
94       dhcp6-change
95           The DHCPv6 lease has changed (renewed, rebound, etc).
96
97       connectivity-change
98           The network connectivity state has changed (no connectivity, went
99           online, etc).
100
101       The environment contains more information about the interface and the
102       connection. The following variables are available for the use in the
103       dispatcher scripts:
104
105       NM_DISPATCHER_ACTION
106           The dispatcher action like "up" or "dhcp4-change", identical to the
107           first command line argument. Since NetworkManager 1.12.0.
108
109       CONNECTION_UUID
110           The UUID of the connection profile.
111
112       CONNECTION_ID
113           The name (ID) of the connection profile.
114
115       CONNECTION_DBUS_PATH
116           The NetworkManager D-Bus path of the connection.
117
118       CONNECTION_FILENAME
119           The backing file name of the connection profile (if any).
120
121       CONNECTION_EXTERNAL
122           If "1", this indicates that the connection describes a network
123           configuration created outside of NetworkManager.
124
125       DEVICE_IFACE
126           The interface name of the control interface of the device.
127           Depending on the device type, this differs from DEVICE_IP_IFACE.
128           For example for ADSL devices, this could be 'atm0' or for WWAN
129           devices it might be 'ttyUSB0'.
130
131       DEVICE_IP_IFACE
132           The IP interface name of the device. This is the network interface
133           on which IP addresses and routes will be configured.
134
135       IP4_ADDRESS_N
136           The IPv4 address in the format "address/prefix gateway", where N is
137           a number from 0 to (# IPv4 addresses - 1). gateway item in this
138           variable is deprecated, use IP4_GATEWAY instead.
139
140       IP4_NUM_ADDRESSES
141           The variable contains the number of IPv4 addresses the script may
142           expect.
143
144       IP4_GATEWAY
145           The gateway IPv4 address in traditional numbers-and-dots notation.
146
147       IP4_ROUTE_N
148           The IPv4 route in the format "address/prefix next-hop metric",
149           where N is a number from 0 to (# IPv4 routes - 1).
150
151       IP4_NUM_ROUTES
152           The variable contains the number of IPv4 routes the script may
153           expect.
154
155       IP4_NAMESERVERS
156           The variable contains a space-separated list of the DNS servers.
157
158       IP4_DOMAINS
159           The variable contains a space-separated list of the search domains.
160
161       DHCP4_<dhcp-option-name>
162           If the connection used DHCP for address configuration, the received
163           DHCP configuration is passed in the environment using standard DHCP
164           option names, prefixed with "DHCP4_", like
165           "DHCP4_HOST_NAME=foobar".
166
167       IP6_<name> and DHCP6_<name>
168           The same variables as for IPv4 are available for IPv6, but the
169           prefixes are IP6_ and DHCP6_ instead.
170
171       CONNECTIVITY_STATE
172           The network connectivity state, which can take the values defined
173           by the NMConnectivityState type, from the
174           org.freedesktop.NetworkManager D-Bus API: unknown, none, portal,
175           limited or full. Note: this variable will only be set for
176           connectivity-change actions.
177
178       In case of VPN, VPN_IP_IFACE is set, and IP4_*, IP6_* variables with
179       VPN prefix are exported too, like VPN_IP4_ADDRESS_0,
180       VPN_IP4_NUM_ADDRESSES.
181
182       Dispatcher scripts are run one at a time, but asynchronously from the
183       main NetworkManager process, and will be killed if they run for too
184       long. If your script might take arbitrarily long to complete, you
185       should spawn a child process and have the parent return immediately.
186       Scripts that are symbolic links pointing inside the
187       /etc/NetworkManager/dispatcher.d/no-wait.d/ directory are run
188       immediately, without waiting for the termination of previous scripts,
189       and in parallel. Also beware that once a script is queued, it will
190       always be run, even if a later event renders it obsolete. (Eg, if an
191       interface goes up, and then back down again quickly, it is possible
192       that one or more "up" scripts will be run after the interface has gone
193       down.)
194

OPTIONS

196       The following options are understood:
197
198       --version | -V
199           Print the NetworkManager software version and exit.
200
201       --help | -h
202           Print NetworkManager's available options and exit.
203
204       --no-daemon | -n
205           Do not daemonize.
206
207       --debug | -d
208           Do not daemonize, and direct log output to the controlling terminal
209           in addition to syslog.
210
211       --pid-file | -p
212           Specify location of a PID file. The PID file is used for storing
213           PID of the running process and prevents running multiple instances.
214
215       --state-file
216           Specify file for storing state of the NetworkManager persistently.
217           If not specified, the default value of
218           /var/lib/NetworkManager/NetworkManager.state is used.
219
220       --config
221           Specify configuration file to set up various settings for
222           NetworkManager. If not specified, the default value of
223           /etc/NetworkManager/NetworkManager.conf is used with a fallback to
224           the older 'nm-system-settings.conf' if located in the same
225           directory. See NetworkManager.conf(5) for more information on
226           configuration file.
227
228       --configure-and-quit [initrd]
229           Quit after all devices reach a stable state. The optional initrd
230           parameter enables mode, where no processes are left running after
231           NetworkManager stops, which is useful for running from an initial
232           ramdisk on rearly boot.
233
234       --plugins
235           List plugins used to manage system-wide connection settings. This
236           list has preference over plugins specified in the configuration
237           file. See main.plugins setting in NetworkManager.conf(5) for
238           supported options.
239
240       --log-level
241           Sets how much information NetworkManager sends to the log
242           destination (usually syslog's "daemon" facility). By default, only
243           informational, warning, and error messages are logged. See the
244           section on logging in NetworkManager.conf(5) for more information.
245
246       --log-domains
247           A comma-separated list specifying which operations are logged to
248           the log destination (usually syslog). By default, most domains are
249           logging-enabled. See the section on logging in
250           NetworkManager.conf(5) for more information.
251
252       --print-config
253           Print the NetworkManager configuration to stdout and exit.
254

UDEV PROPERTIES

256       udev(7) device manager is used for the network device discovery. The
257       following property influences how NetworkManager manages the devices:
258
259       NM_UNMANAGED
260           If set to "1" or "true", the device is configured as unmanaged by
261           NetworkManager. Note that the user still can explicitly overrule
262           this configuration via means like nmcli device set "$DEVICE"
263           managed yes or "device*.managed=1" in NetworkManager.conf.
264

SIGNALS

266       NetworkManager process handles the following signals:
267
268       SIGHUP
269           The signal causes a reload of NetworkManager's configuration. Note
270           that not all configuration parameters can be changed at runtime and
271           therefore some changes may be applied only after the next restart
272           of the daemon. A SIGHUP also involves further reloading actions,
273           like doing a DNS update and restarting the DNS plugin. The latter
274           can be useful for example when using the dnsmasq plugin and
275           changing its configuration in /etc/NetworkManager/dnsmasq.d.
276           However, it also means this will shortly interrupt name resolution.
277           In the future, there may be further actions added. A SIGHUP means
278           to update NetworkManager configuration and reload everything that
279           is supported. Note that this does not reload connections from disk.
280           For that there is a D-Bus API and nmcli's reload action
281
282       SIGUSR1
283           The signal forces a rewrite of DNS configuration. Contrary to
284           SIGHUP, this does not restart the DNS plugin and will not interrupt
285           name resolution. In the future, further actions may be added. A
286           SIGUSR1 means to write out data like resolv.conf, or refresh a
287           cache. It is a subset of what is done for SIGHUP without reloading
288           configuration from disk.
289
290       SIGUSR2
291           The signal has no effect at the moment but is reserved for future
292           use.
293
294       An alternative to a signal to reload configuration is the Reload D-Bus
295       call. It allows for more fine-grained selection of what to reload, it
296       only returns after the reload is complete, and it is guarded by
297       PolicyKit.
298

DEBUGGING

300       NetworkManager only configures your system. So when your networking
301       setup doesn't work as expected, the first step is to look at your
302       system to understand what is actually configured, and whether that is
303       correct. The second step is to find out how to tell NetworkManager to
304       do the right thing.
305
306       You can for example try to ping hosts (by IP address or DNS name), look
307       at ip link show, ip address show and ip route show, and look at
308       /etc/resolv.conf for name resolution issues. Also look at the
309       connection profiles that you have configured in NetworkManager (nmcli
310       connection and nmcli connection show "$PROFILE") and the configured
311       interfaces (nmcli device).
312
313       If that does not suffice, look at the logfiles of NetworkManager.
314       NetworkManager logs to syslog, so depending on your system
315       configuration you can call journalctl to get the logs. By default,
316       NetworkManager logs are not verbose and thus not very helpful for
317       investigating a problem in detail. You can change the logging level at
318       runtime with nmcli general logging level TRACE domains ALL. But usually
319       a better way is to collect full logs from the start, by configuring
320       level=TRACE in NetworkManager.conf. See NetworkManager.conf(5) manual.
321       Note that trace logs of NetworkManager are verbose and systemd-journald
322       might rate limit some lines. Possibly disable rate limiting first with
323       the RateLimitIntervalSec and RateLimitBurst options of journald (see
324       journald.conf(5) manual).
325

/VAR/LIB/NETWORKMANAGER/SECRET_KEY AND /ETC/MACHINE-ID

327       The identity of a machine is important as various settings depend on
328       it. For example, ipv6.addr-gen-mode=stable and
329       ethernet.cloned-mac-address=stable generate identifiers by hashing the
330       machine's identity. See also the connection.stable-id connection
331       property which is a per-profile seed that gets hashed with the machine
332       identity for generating such addresses and identifiers.
333
334       If you backup and restore a machine, the identity of the machine
335       probably should be preserved. In that case, preserve the files
336       /var/lib/NetworkManager/secret_key and /etc/machine-id. On the other
337       hand, if you clone a virtual machine, you probably want that the clone
338       has a different identity. There is already existing tooling on Linux
339       for handling /etc/machine-id (see machine-id(5)).
340
341       The identity of the machine is determined by the
342       /var/lib/NetworkManager/secret_key. If such a file does not exist,
343       NetworkManager will create a file with random content. To generate a
344       new identity just delete the file and after restart a new file will be
345       created. The file should be read-only to root and contain at least 16
346       bytes that will be used to seed the various places where a stable
347       identifier is used.
348
349       Since 1.16.0, NetworkManager supports a version 2 of secret-keys. For
350       such keys /var/lib/NetworkManager/secret_key starts with ASCII "nm-v2:"
351       followed by at least 32 bytes of random data. Also, recent versions of
352       NetworkManager always create such kinds of secret-keys, when the file
353       does not yet exist. With version 2 of the secret-key, /etc/machine-id
354       is also hashed as part of the generation for addresses and identifiers.
355       The advantage is that you can keep /var/lib/NetworkManager/secret_key
356       stable, and only regenerate /etc/machine-id when cloning a VM.
357

BUGS

359       Please report any bugs you find in NetworkManager at the NetworkManager
360       issue tracker[1].
361

SEE ALSO

363       NetworkManager home page[2], NetworkManager.conf(5), nmcli(1), nmcli-
364       examples(7), nm-online(1), nm-settings(5), nm-applet(1), nm-connection-
365       editor(1), udev(7)
366

NOTES

368        1. NetworkManager issue tracker
369           https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues
370
371        2. NetworkManager home page
372           https://wiki.gnome.org/Projects/NetworkManager
373
374
375
376NetworkManager 1.30.4                                        NETWORKMANAGER(8)
Impressum