1NM-SETTINGS-KEYFILE(5)           Configuration          NM-SETTINGS-KEYFILE(5)
2
3
4

NAME

6       nm-settings-keyfile - Description of keyfile settings plugin
7

DESCRIPTION

9       NetworkManager is based on the concept of connection profiles that
10       contain network configuration (see nm-settings(5) for details). The
11       profiles can be stored in various formats. NetworkManager uses plugins
12       for reading and writing the data. The plugins can be configured in
13       NetworkManager.conf(5).
14
15       The keyfile plugin is the generic plugin that supports all the
16       connection types and capabilities that NetworkManager has. The files
17       are in a .ini-style format and located in
18       /etc/NetworkManager/system-connections/,
19       /usr/lib/NetworkManager/system-connections/ and
20       /run/NetworkManager/system-connections/. This plugin is always enabled
21       and will automatically be used to store any connections that are not
22       supported by any other active plugin. For security, it will ignore
23       files that are readable or writable by any user other than 'root' since
24       private keys and passphrases may be stored in plaintext inside the
25       file.
26

FILE FORMAT

28       The keyfile config format is a simple .ini-style format. It consists of
29       sections (groups) of key-value pairs. Each section corresponds to a
30       setting name as described in the settings specification (nm-
31       settings(5)). Each configuration key/value pair in the section is one
32       of the properties listed in the settings specification. The majority of
33       properties of the specification is written in the same format into the
34       keyfile too. However some values are inconvenient for people to use.
35       These are stored in the files in more readable ways. These properties
36       are described below. An example could be IP addresses that are not
37       written as integer arrays, but more reasonably as "1.2.3.4/12
38       1.2.3.254". More information of the generic key file format can be
39       found at GLib key file format[1] (Lines beginning with a '#' are
40       comments, lists are separated by character ; etc.).
41
42       Users can create or modify the keyfile connection files manually, even
43       if that is not the recommended way of managing the profiles. However,
44       if they choose to do that, they must inform NetworkManager about their
45       changes (for example via nmcli con (re)load).
46
47       Examples of keyfile configuration.
48
49           A sample configuration for an ethernet network:
50           [connection]
51           id=Main eth0
52           uuid=27afa607-ee36-43f0-b8c3-9d245cdc4bb3
53           type=802-3-ethernet
54           autoconnect=true
55
56           [ipv4]
57           method=auto
58
59           [802-3-ethernet]
60           mac-address=00:23:5a:47:1f:71
61
62
63
64           A sample configuration for WPA-EAP (PEAP with MSCHAPv2) and always-ask secret:
65           [connection]
66           id=CompanyWIFI
67           uuid=cdac6154-a33b-4b15-9904-666772cfa5ee
68           type=wifi
69           autoconnect=false
70
71           [wifi]
72           ssid=CorpWLAN
73           mode=infrastructure
74           security=802-11-wireless-security
75
76           [wifi-security]
77           key-mgmt=wpa-eap
78
79           [ipv4]
80           method=auto
81
82           [ipv6]
83           method=auto
84
85           [802-1x]
86           eap=peap;
87           identity=joe
88           ca-cert=/home/joe/.cert/corp.crt
89           phase1-peapver=1
90           phase2-auth=mschapv2
91           password-flags=2
92
93
94
95           A sample configuration for openvpn:
96           [connection]
97           id=RedHat-openvpn
98           uuid=7f9b3356-b210-4c0e-8123-bd116c9c280f
99           type=vpn
100           timestamp=1385401165
101
102           [vpn]
103           service-type=org.freedesktop.NetworkManager.openvpn
104           connection-type=password
105           password-flags=3
106           remote=ovpn.my-company.com
107           cipher=AES-256-CBC
108           reneg-seconds=0
109           port=443
110           username=joe
111           ca=/etc/openvpn/ISCA.pem
112           tls-remote=ovpn.my-company.com
113
114           [ipv6]
115           method=auto
116
117           [ipv4]
118           method=auto
119           ignore-auto-dns=true
120           never-default=true
121
122
123
124           A sample configuration for a bridge and a bridge port:
125           [connection]                                 [connection]
126           id=MainBridge                                id=br-port-1
127           uuid=171ae855-a0ab-42b6-bd0c-60f5812eea9d    uuid=d6e8ae98-71f8-4b3d-9d2d-2e26048fe794
128           interface-name=MainBridge                    interface-name=em1
129           type=bridge                                  type=ethernet
130                                                        master=MainBridge
131           [bridge]                                     slave-type=bridge
132           interface-name=MainBridge
133
134
135
136           A sample configuration for a VLAN:
137           [connection]
138           id=VLAN for building 4A
139           uuid=8ce1c9e0-ce7a-4d2c-aa28-077dda09dd7e
140           interface-name=VLAN-4A
141           type=vlan
142
143           [vlan]
144           interface-name=VLAN-4A
145           parent=eth0
146           id=4
147
148

DETAILS

150       keyfile plugin variables for the majority of NetworkManager properties
151       have one-to-one mapping. It means a NetworkManager property is stored
152       in the keyfile as a variable of the same name and in the same format.
153       There are several exceptions to this rule, mainly for making keyfile
154       syntax easier for humans. The exceptions handled specially by keyfile
155       plugin are listed below. Refer to nm-settings(5) for all available
156       settings and properties and their description.
157
158       Name aliases. Some of the NetworkManager setting names are somewhat
159       hard to type or remember. Therefore keyfile introduces aliases that can
160       be used instead of the names.
161           setting name                 keyfile alias
162           802-3-ethernet            =  ethernet
163           802-11-wireless           =  wifi
164           802-11-wireless-security  =  wifi-security
165
166       Table 1. 802-11-wireless setting (section)
167       ┌──────────────────────┬──────────────────┬───────────────────────┬─────────────────────────────────────┐
168Property              Keyfile Variable Format                Description                         
169       ├──────────────────────┼──────────────────┼───────────────────────┼─────────────────────────────────────┤
170       │ssid                  │                  │ string (or            │ SSID of Wi-Fi                       │
171       │                      │                  │ decimal-byte          │ network.                            │
172       │                      │                  │ list - obsolete)      │                                     │
173       │                      │                  │                       │ Example:                            
174       │                      │                  │                       │ ssid=Quick Net                      │
175       ├──────────────────────┼──────────────────┼───────────────────────┼─────────────────────────────────────┤
176       │mac-address           │                  │ usual                 │ MAC address in                      │
177       │                      │                  │ hex-digits-and-colons │ traditional                         │
178       │                      │                  │ notation              │ hex-digits-and-colons               │
179       │                      │                  │                       │ notation (e.g.                      │
180       │                      │                  │                       │ 00:22:68:12:79:A2),                 │
181       │                      │                  │                       │ or semicolon                        │
182       │                      │                  │                       │ separated list                      │
183       │                      │                  │                       │ of 6 bytes                          │
184       │                      │                  │                       │ (obsolete) (e.g.                    │
185       │                      │                  │                       │ 0;34;104;18;121;162).               │
186       ├──────────────────────┼──────────────────┼───────────────────────┼─────────────────────────────────────┤
187       │cloned-mac-address    │                  │ usual                 │ Cloned MAC address in               │
188       │                      │                  │ hex-digits-and-colons │ traditional                         │
189       │                      │                  │ notation              │ hex-digits-and-colons               │
190       │                      │                  │                       │ notation (e.g.                      │
191       │                      │                  │                       │ 00:22:68:12:79:B2),                 │
192       │                      │                  │                       │ or semicolon                        │
193       │                      │                  │                       │ separated list of 6                 │
194       │                      │                  │                       │ bytes (obsolete)                    │
195       │                      │                  │                       │ (e.g.                               │
196       │                      │                  │                       │ 0;34;104;18;121;178).               │
197       ├──────────────────────┼──────────────────┼───────────────────────┼─────────────────────────────────────┤
198       │mac-address-blacklist │                  │ list of MACs          │ MAC address                         │
199       │                      │                  │ (separated with       │ blacklist.                          │
200       │                      │                  │ semicolons)           │                                     │
201       │                      │                  │                       │ Example:                            
202       │                      │                  │                       │ mac-address-blacklist=              │
203       │                      │                  │                       │ 00:22:68:12:79:A6;00:22:68:12:79:78 │
204       └──────────────────────┴──────────────────┴───────────────────────┴─────────────────────────────────────┘
205
206       Table 2. 802-3-ethernet setting (section)
207       ┌──────────────────────┬──────────────────┬───────────────────────┬─────────────────────────────────────┐
208Property              Keyfile Variable Format                Description                         
209       ├──────────────────────┼──────────────────┼───────────────────────┼─────────────────────────────────────┤
210       │mac-address           │                  │ usual                 │ MAC address in                      │
211       │                      │                  │ hex-digits-and-colons │ traditional                         │
212       │                      │                  │ notation              │ hex-digits-and-colons               │
213       │                      │                  │                       │ notation (e.g.                      │
214       │                      │                  │                       │ 00:22:68:12:79:A2),                 │
215       │                      │                  │                       │ or semicolon                        │
216       │                      │                  │                       │ separated list                      │
217       │                      │                  │                       │ of 6 bytes                          │
218       │                      │                  │                       │ (obsolete) (e.g.                    │
219       │                      │                  │                       │ 0;34;104;18;121;162)                │
220       ├──────────────────────┼──────────────────┼───────────────────────┼─────────────────────────────────────┤
221       │cloned-mac-address    │                  │ usual                 │ Cloned MAC address in               │
222       │                      │                  │ hex-digits-and-colons │ traditional                         │
223       │                      │                  │ notation              │ hex-digits-and-colons               │
224       │                      │                  │                       │ notation (e.g.                      │
225       │                      │                  │                       │ 00:22:68:12:79:B2),                 │
226       │                      │                  │                       │ or semicolon                        │
227       │                      │                  │                       │ separated list of 6                 │
228       │                      │                  │                       │ bytes (obsolete)                    │
229       │                      │                  │                       │ (e.g.                               │
230       │                      │                  │                       │ 0;34;104;18;121;178).               │
231       ├──────────────────────┼──────────────────┼───────────────────────┼─────────────────────────────────────┤
232       │mac-address-blacklist │                  │ list of MACs          │ MAC address                         │
233       │                      │                  │ (separated with       │ blacklist.                          │
234       │                      │                  │ semicolons)           │                                     │
235       │                      │                  │                       │ Example:                            
236       │                      │                  │                       │ mac-address-blacklist=              │
237       │                      │                  │                       │ 00:22:68:12:79:A6;00:22:68:12:79:78 │
238       └──────────────────────┴──────────────────┴───────────────────────┴─────────────────────────────────────┘
239
240       Table 3. bridge setting (section)
241       ┌────────────┬──────────────────┬───────────────────────┬──────────────────────────────────┐
242Property    Keyfile Variable Format                Description                      
243       ├────────────┼──────────────────┼───────────────────────┼──────────────────────────────────┤
244       │mac-address │                  │ usual                 │ MAC address in                   │
245       │            │                  │ hex-digits-and-colons │ traditional                      │
246       │            │                  │ notation              │ hex-digits-and-colons            │
247       │            │                  │                       │ notation, or                     │
248       │            │                  │                       │ semicolon                        │
249       │            │                  │                       │ separated list                   │
250       │            │                  │                       │ of 6 decimal                     │
251       │            │                  │                       │ bytes (obsolete)                 │
252       │            │                  │                       │                                  │
253       │            │                  │                       │ Example:                         
254       │            │                  │                       │ mac-address=00:22:68:12:79:A2    │
255       │            │                  │                       │ mac-address=0;34;104;18;121;162; │
256       └────────────┴──────────────────┴───────────────────────┴──────────────────────────────────┘
257
258       Table 4. infiniband setting (section)
259       ┌────────────┬──────────────────┬───────────────────────┬─────────────────────────────────────────────────────────────┐
260Property    Keyfile Variable Format                Description                                                 
261       ├────────────┼──────────────────┼───────────────────────┼─────────────────────────────────────────────────────────────┤
262       │mac-address │                  │ usual                 │ MAC address in                                              │
263       │            │                  │ hex-digits-and-colons │ traditional                                                 │
264       │            │                  │ notation              │ hex-digits-and-colons                                       │
265       │            │                  │                       │ notation, or or                                             │
266       │            │                  │                       │ semicolon                                                   │
267       │            │                  │                       │ separated list                                              │
268       │            │                  │                       │ of 20 decimal                                               │
269       │            │                  │                       │ bytes (obsolete)                                            │
270       │            │                  │                       │                                                             │
271       │            │                  │                       │ Example:                                                    
272       │            │                  │                       │ mac-address=                                                │
273       │            │                  │                       │ 80:00:00:6d:fe:80:00:00:00:00:00:00:00:02:55:00:70:33:cf:01 │
274       └────────────┴──────────────────┴───────────────────────┴─────────────────────────────────────────────────────────────┘
275
276       Table 5. ipv4 setting (section)
277       ┌──────────┬──────────────────┬─────────────────────────────┬───────────────────────────────┐
278Property  Keyfile Variable Format                      Description                   
279       ├──────────┼──────────────────┼─────────────────────────────┼───────────────────────────────┤
280       │dns       │                  │ list of DNS IP              │ List of DNS                   │
281       │          │                  │ addresses                   │ servers.                      │
282       │          │                  │                             │                               │
283       │          │                  │                             │ Example:                      
284       │          │                  │                             │ dns=1.2.3.4;8.8.8.8;8.8.4.4;  │
285       ├──────────┼──────────────────┼─────────────────────────────┼───────────────────────────────┤
286       │addresses │ address1,        │ address/plen                │ List of static IP addresses.  │
287       │          │ address2, ...    │                             │                               │
288       │          │                  │                             │ Example:                      
289       │          │                  │                             │ address1=192.168.100.100/24   │
290       │          │                  │                             │ address2=10.1.1.5/24          │
291       ├──────────┼──────────────────┼─────────────────────────────┼───────────────────────────────┤
292       │gateway   │ gateway          │ string                      │ Gateway IP addresses as a     │
293       │          │                  │                             │ string.                       │
294       │          │                  │                             │                               │
295       │          │                  │                             │ Example:                      
296       │          │                  │                             │ gateway=192.168.100.1         │
297       ├──────────┼──────────────────┼─────────────────────────────┼───────────────────────────────┤
298       │routes    │ route1, route2,  │ route/plen[,gateway,metric] │ List of IP routes.            │
299       │          │ ...              │                             │                               │
300       │          │                  │                             │ Example:                      
301       │          │                  │                             │ route1=8.8.8.0/24,10.1.1.1,77 │
302       │          │                  │                             │ route2=7.7.0.0/16             │
303       └──────────┴──────────────────┴─────────────────────────────┴───────────────────────────────┘
304
305       Table 6. ipv6 setting (section)
306       ┌──────────┬──────────────────┬─────────────────────────────┬──────────────────────────────────────────────────────────────┐
307Property  Keyfile Variable Format                      Description                                                  
308       ├──────────┼──────────────────┼─────────────────────────────┼──────────────────────────────────────────────────────────────┤
309       │dns       │                  │ list of DNS IP              │ List of DNS                                                  │
310       │          │                  │ addresses                   │ servers.                                                     │
311       │          │                  │                             │                                                              │
312       │          │                  │                             │ Example:                                                     
313       │          │                  │                             │ dns=2001:4860:4860::8888;2001:4860:4860::8844;               │
314       ├──────────┼──────────────────┼─────────────────────────────┼──────────────────────────────────────────────────────────────┤
315       │addresses │ address1,        │ address/plen                │ List of static IP addresses.                                 │
316       │          │ address2, ...    │                             │                                                              │
317       │          │                  │                             │ Example: address1=abbe::cafe/96                              │
318       │          │                  │                             │ address2=2001::1234                                          │
319       ├──────────┼──────────────────┼─────────────────────────────┼──────────────────────────────────────────────────────────────┤
320       │gateway   │ gateway          │ string                      │ Gateway IP addresses as a string.                            │
321       │          │                  │                             │                                                              │
322       │          │                  │                             │ Example: gateway=abbe::1                                     │
323       ├──────────┼──────────────────┼─────────────────────────────┼──────────────────────────────────────────────────────────────┤
324       │routes    │ route1, route2,  │ route/plen[,gateway,metric] │ List of IP routes.                                           │
325       │          │ ...              │                             │                                                              │
326       │          │                  │                             │ Example:                                                     
327       │          │                  │                             │ route1=2001:4860:4860::/64,2620:52:0:2219:222:68ff:fe11:5403 │
328       └──────────┴──────────────────┴─────────────────────────────┴──────────────────────────────────────────────────────────────┘
329
330       Table 7. serial setting (section)
331       ┌─────────┬──────────────────┬──────────────────┬─────────────────┐
332Property Keyfile Variable Format           Description     
333       ├─────────┼──────────────────┼──────────────────┼─────────────────┤
334       │parity   │                  │ 'e', 'o', or 'n' │ The connection  │
335       │         │                  │                  │ parity; even,   │
336       │         │                  │                  │ odd, or none.   │
337       │         │                  │                  │ Note that older │
338       │         │                  │                  │ versions of     │
339       │         │                  │                  │ NetworkManager  │
340       │         │                  │                  │ stored this as  │
341       │         │                  │                  │ an integer: 69  │
342       │         │                  │                  │ ('E') for even, │
343       │         │                  │                  │ 111 ('o') for   │
344       │         │                  │                  │ odd, or 110     │
345       │         │                  │                  │ ('n') for none. │
346       │         │                  │                  │                 │
347       │         │                  │                  │ Example:        
348       │         │                  │                  │ parity=n        │
349       └─────────┴──────────────────┴──────────────────┴─────────────────┘
350
351       Table 8. vpn setting (section)
352       ┌─────────┬──────────────────┬────────┬───────────────────────┐
353Property Keyfile Variable Format Description           
354       ├─────────┼──────────────────┼────────┼───────────────────────┤
355       │data     │ separate         │        │ The keys of the       │
356       │         │ variables named  │        │ data dictionary       │
357       │         │ after keys of    │        │ are used as           │
358       │         │ the dictionary   │        │ variable names        │
359       │         │                  │        │ directly under        │
360       │         │                  │        │ [vpn] section.        │
361       │         │                  │        │                       │
362       │         │                  │        │ Example:              
363       │         │                  │        │ remote=ovpn.corp.com  │
364       │         │                  │        │ cipher=AES-256-CBC    │
365       │         │                  │        │ username=joe          │
366       ├─────────┼──────────────────┼────────┼───────────────────────┤
367       │secrets  │ separate         │        │ The keys of the       │
368       │         │ variables named  │        │ secrets dictionary    │
369       │         │ after keys of    │        │ are used as variable  │
370       │         │ the dictionary   │        │ names directly under  │
371       │         │                  │        │ [vpn-secrets]         │
372       │         │                  │        │ section.              │
373       │         │                  │        │                       │
374       │         │                  │        │ Example:              
375       │         │                  │        │ password=Popocatepetl │
376       └─────────┴──────────────────┴────────┴───────────────────────┘
377
378       Table 9. wifi-p2p setting (section)
379       ┌─────────┬──────────────────┬───────────────────────┬───────────────────────┐
380Property Keyfile Variable Format                Description           
381       ├─────────┼──────────────────┼───────────────────────┼───────────────────────┤
382       │peer     │                  │ usual                 │ MAC address in        │
383       │         │                  │ hex-digits-and-colons │ traditional           │
384       │         │                  │ notation              │ hex-digits-and-colons │
385       │         │                  │                       │ notation (e.g.        │
386       │         │                  │                       │ 00:22:68:12:79:A2),   │
387       │         │                  │                       │ or semicolon          │
388       │         │                  │                       │ separated list        │
389       │         │                  │                       │ of 6 bytes            │
390       │         │                  │                       │ (obsolete) (e.g.      │
391       │         │                  │                       │ 0;34;104;18;121;162). │
392       └─────────┴──────────────────┴───────────────────────┴───────────────────────┘
393
394       Table 10. wpan setting (section)
395       ┌────────────┬──────────────────┬───────────────────────┬───────────────────────────┐
396Property    Keyfile Variable Format                Description               
397       ├────────────┼──────────────────┼───────────────────────┼───────────────────────────┤
398       │mac-address │                  │ usual                 │ MAC address in            │
399       │            │                  │ hex-digits-and-colons │ hex-digits-and-colons     │
400       │            │                  │ notation              │ notation (e.g.            │
401       │            │                  │                       │ 76:d8:9b:87:66:60:84:ee). │
402       └────────────┴──────────────────┴───────────────────────┴───────────────────────────┘
403
404   Secret flags
405       Each secret property in a NetworkManager setting has an associated
406       flags property that describes how to handle that secret. In the keyfile
407       plugin, the value of -flags variable is a decimal number (0 - 7)
408       defined as a sum of the following values:
409
410       •   0 - (NM owned) - the system is responsible for providing and
411           storing this secret.
412
413       •   1 - (agent-owned) - a user-session secret agent is responsible for
414           providing and storing this secret; when it is required, agents will
415           be asked to provide it.
416
417       •   2 - (not-saved) - this secret should not be saved but should be
418           requested from the user each time it is required.
419
420       •   4 - (not-required) - in some situations it cannot be automatically
421           determined that a secret is required or not. This flag hints that
422           the secret is not required and should not be requested from the
423           user.
424

FILES

426       /etc/NetworkManager/system-connections/*
427

SEE ALSO

429       nm-settings(5), nm-settings-ifcfg-rh(5), NetworkManager(8),
430       NetworkManager.conf(5), nmcli(1), nmcli-examples(7)
431

NOTES

433        1. GLib key file format
434           https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html#glib-Key-value-file-parser.description
435
436
437
438NetworkManager 1.44.2                                   NM-SETTINGS-KEYFILE(5)
Impressum