NM-SETTINGS-KEYFILE(5)

📦
version 1.58.0 · 22 versions
, in centos-stream 10

💅 nm-settings-keyfile(5) — keyfile settings plugin, bestie 💅

This is the Configuration manual section, and the main character is nm-settings-keyfile(5). Buckle up, bestie. 🎀

🌸 NAME 🌸

nm-settings-keyfile — description of keyfile settings plugin. That's the name, that's the vibe, periodt. ✨

✨ DESCRIPTION ✨

okay so NetworkManager is based on the concept of connection profiles that contain network configuration (see nm-settings-nmcli(5) for details). The profiles can be stored in various formats. NetworkManager uses plugins for reading and writing the data. The plugins can be configured in NetworkManager.conf(5).

The keyfile plugin is the generic plugin that supports all the connection types and capabilities that NetworkManager has. The files are in a .ini-style format and located in /etc/NetworkManager/system-connections/, /usr/lib/NetworkManager/system-connections/, and /run/NetworkManager/system-connections/. This plugin is always enabled and will automatically be used to store any connections that are not supported by any other active plugin.

🔐 Security tea: it will ignore files that are readable or writable by any user other than 'root' since private keys and passphrases may be stored in plaintext inside the file. 😭

🎀 FILE FORMAT 🎀

The keyfile config format is a simple .ini-style format. It consists of sections (groups) of key-value pairs. More information of the generic key file format can be found at GLib key file format[1] (Lines beginning with a '#' are comments, lists are separated by character ; etc.).

Each section corresponds to a setting name as described in the settings specification (nm-settings-nmcli(5)). Each key/value pair in a section is one of the properties from the specification.

The majority of properties are written in the same format as the specification into the keyfile. However, some values are inconvenient for people to use so they are stored in the keyfile in more readable ways. These properties that differ from the specification are described below. An example could be IP addresses that are not written as integer arrays, but more reasonably as "1.2.3.4/12 1.2.3.254". Also, some lists of complex values (addresses, routes, routing-rules), instead of using a semicolon separated list, use one key-value pair per list element, with the key being the singular of the property name followed by the numeric index (i.e address1, address2, ...).

Users can create or modify the keyfile connection files manually, even if that is not the recommended way of managing the profiles. However, if they choose to do that, they must inform NetworkManager about their changes (for example via nmcli con (re)load). 🫶

Examples of keyfile configuration. 🍓

A sample configuration for an ethernet network:

[connection]
id=Main eth0
uuid=27afa607-ee36-43f0-b8c3-9d245cdc4bb3
type=802-3-ethernet
autoconnect=true

[ipv4]
method=auto

[802-3-ethernet]
mac-address=00:23:5a:47:1f:71

A sample configuration for WPA-EAP (PEAP with MSCHAPv2) and always-ask secret:

[connection]
id=CompanyWIFI
uuid=cdac6154-a33b-4b15-9904-666772cfa5ee
type=wifi
autoconnect=false

[wifi]
ssid=CorpWLAN
mode=infrastructure
security=802-11-wireless-security

[wifi-security]
key-mgmt=wpa-eap

[ipv4]
method=auto

[ipv6]
method=auto

[802-1x]
eap=peap;
identity=joe
ca-cert=/home/joe/.cert/corp.crt
phase1-peapver=1
phase2-auth=mschapv2
password-flags=2

A sample configuration for openvpn:

[connection]
id=RedHat-openvpn
uuid=7f9b3356-b210-4c0e-8123-bd116c9c280f
type=vpn
timestamp=1385401165

[vpn]
service-type=org.freedesktop.NetworkManager.openvpn
connection-type=password
password-flags=3
remote=ovpn.my-company.com
cipher=AES-256-CBC
reneg-seconds=0
port=443
username=joe
ca=/etc/openvpn/ISCA.pem
tls-remote=ovpn.my-company.com

[ipv6]
method=auto

[ipv4]
method=auto
ignore-auto-dns=true
never-default=true

A sample configuration for a bridge and a bridge port:

[connection]                                 [connection]
id=MainBridge                                id=br-port-1
uuid=171ae855-a0ab-42b6-bd0c-60f5812eea9d    uuid=d6e8ae98-71f8-4b3d-9d2d-2e26048fe794
interface-name=MainBridge                    interface-name=em1
type=bridge                                  type=ethernet
                                             controller=MainBridge
[bridge]                                     port-type=bridge
interface-name=MainBridge

A sample configuration for a VLAN:

[connection]
id=VLAN for building 4A
uuid=8ce1c9e0-ce7a-4d2c-aa28-077dda09dd7e
interface-name=VLAN-4A
type=vlan

[vlan]
interface-name=VLAN-4A
parent=eth0
id=4

💜 DETAILS 💜

keyfile plugin variables for the majority of NetworkManager properties have one-to-one mapping. It means a NetworkManager property is stored in the keyfile as a variable of the same name and in the same format. There are several exceptions to this rule, mainly for making keyfile syntax easier for humans. The exceptions handled specially by keyfile plugin are listed below. Refer to nm-settings-nmcli(5) for all available settings and properties and their description. 👑

Name aliases. Some of the NetworkManager setting names are somewhat hard to type or remember. Therefore keyfile introduces aliases that can be used instead of the names. Here's the map, bestie:

  • 802-3-ethernet = ethernet
  • 802-11-wireless = wifi
  • 802-11-wireless-security = wifi-security

✨ Table 1. 802-11-wireless setting (section) ✨

okay bestie, this is the Wi-Fi one, the one everybody actually cares about 💖 It's a little table of properties for the 802-11-wireless section, and heads up: the Keyfile Variable column is literally empty for every single row here, so there's nothing to report there — don't come for me, I'm just the messenger 🫶 The columns are Property, Keyfile Variable, Format, and Description, and here's every row, one by one, nothing skipped:

  • ssid — format is string (or decimal-byte list — that one's obsolete 👵). This is the SSID of the Wi-Fi network. Example:
ssid=Quick Net
  • mac-address — format is the usual hex-digits-and-colons notation. It's the MAC address in traditional hex-digits-and-colons notation (e.g. 00:22:68:12:79:A2), or a semicolon separated list of 6 bytes (obsolete) (e.g. 0;34;104;18;121;162). Two flavours, one of them lowkey ancient 💀
  • cloned-mac-address — format is the usual hex-digits-and-colons notation too. This is the cloned MAC address in traditional hex-digits-and-colons notation (e.g. 00:22:68:12:79:B2), or a semicolon separated list of 6 bytes (obsolete) (e.g. 0;34;104;18;121;178). Same deal as above but with a B instead of an A in the last octet — yes, that difference matters, don't @ me 🙈
  • mac-address-blacklist — format is a list of MACs (separated with semicolons). It's the MAC address blacklist. Example:
mac-address-blacklist=00:22:68:12:79:A6;00:22:68:12:79:78
  • mac-address-denylist — format is a list of MACs (separated with semicolons). It's the MAC address denylist. Example:
mac-address-denylist=00:22:68:12:79:A6;00:22:68:12:79:78

see how blacklist and denylist take the exact same example value? 👀 yeah. anyway, that's the whole table, every row accounted for, semicolons and all — periodt 💅

💅 Table 2. 802-3-ethernet setting (section)

Okay so this section is all about MAC addresses, bestie. Four properties, and ngl they're giving "very similar but don't mix them up" energy. Heads up: in all four rows the Keyfile Variable column is blank — so no keyfile variable name is listed for any of these, k? Just the property name itself.

  • mac-address — Format: usual hex-digits-and-colons notation. Description: the MAC address written in traditional hex-digits-and-colons notation (e.g. 00:22:68:12:79:A2), or a semicolon separated list of 6 bytes — and that second form is obsolete — (e.g. 0;34;104;18;121;162).
  • cloned-mac-address — Format: usual hex-digits-and-colons notation. Description: the cloned MAC address in traditional hex-digits-and-colons notation (e.g. 00:22:68:12:79:B2), or a semicolon separated list of 6 bytes — also obsolete — (e.g. 0;34;104;18;121;178).
  • mac-address-blacklist — Format: list of MACs (separated with semicolons). Description: MAC address blacklist. Example:
mac-address-blacklist=00:22:68:12:79:A6;00:22:68:12:79:78
  • mac-address-denylist — Format: list of MACs (separated with semicolons). Description: MAC address denylist. Example:
mac-address-denylist=00:22:68:12:79:A6;00:22:68:12:79:78
🫶 Notice how mac-address-blacklist and mac-address-denylist are literally the same thing with different names? That's not me being lazy, that's the page. Both take a semicolon separated list of MACs, both have the exact same example values. Copy them character for character and you're golden. ✨

🎀 Table 3. bridge setting (section)

One single property here, and she's iconic. Same deal as before: the Keyfile Variable column is blank. 🙈

  • mac-address — Format: usual hex-digits-and-colons notation. Description: MAC address in traditional hex-digits-and-colons notation, or semicolon separated list of 6 decimal bytes (obsolete). Example:
mac-address=00:22:68:12:79:A2
mac-address=0;34;104;18;121;162;
💀 Bestie, read that carefully — the bridge one says decimal bytes in the semicolon form, not hex bytes like the ethernet table did. And yes, that trailing semicolon in the second example is literally in the page. Don't @ me, I'm just the messenger. Also the obsolete semicolon form? Obsolete. As in, don't do it. 🚩

🦋 Table 4. connection setting (section)

One property, and it's kind of a big deal because it's your profile's whole identity. 🌈

  • uuid — Keyfile Variable: uuid. Format: (blank — no format listed here, sorry bestie). Description: the UUID for the connection profile. When it's missing, NetworkManager creates the UUID by hashing the connection filename. Example:
uuid=7bdbe39a-126c-3f94-ac5e-8f156ed38383
✨ Fun fact straight from the page (not me making stuff up, promise): if you don't give a uuid, NetworkManager just makes one by hashing the connection filename. So like… your filename is lowkey your identity. Main character energy fr fr. 👑

✨ Table 5. infiniband setting (section) ✨

Okay bestie, this one's a little baby section — literally just one property in here, and honestly? She's lowkey iconic for it 🎀

  • mac-address — the keyfile variable column here is empty (no separate keyfile variable name, the property name is the thing), the format is just the usual one, and here's what it does: it's the MAC address, written in the traditional hex-digits-and-colons notation ✨ or as a semicolon separated list of 20 decimal bytes — and heads up, that second form is obsolete 💀 like, it still exists, but ngl it's giving legacy vibes.
🫶 Reminder bestie: that semicolon-separated-20-decimal-bytes form is marked obsolete in the manual — it's not gone, it's just not the moment anymore.

And here's the example, exactly as written, because I am not about to mess with a MAC address 🙈

mac-address=80:00:00:6d:fe:80:00:00:00:00:00:00:00:02:55:00:70:33:cf:01

Look at all those colons though — twenty bytes of pure hex realness 💅 count them if you want, that's the traditional notation doing its thing.

🎀 Table 6. ipv4 setting (section) 🎀

ok so this is the ipv4 table and honestly it's a whole vibe — every property, every keyfile variable, every format, all of it's here. let's go bestie 💅

🌸 dns

  • Keyfile Variable — dns
  • Format — list of DNS IP addresses
  • Description — a literal list of DNS servers. that's it, that's the whole thing.

Example, serving looks:

dns=1.2.3.4;8.8.8.8;8.8.4.4;

💖 addresses

  • Keyfile Variable — address1, address2, ...
  • Format — address/prefix-length[,gateway]
  • Description — static IPv4 addresses, and it's one address per variable, no cramming. the variables can also sneak in the gateway after a comma or a semicolon, but lowkey it's recommended to use the "gateway" variable instead. iykyk 🫶

Examples, all iconic:

address1=192.168.100.100/24
address2=10.1.1.5/16
address1=192.168.100.100/24,192.168.100.1

✨ gateway

  • Keyfile Variable — gateway
  • Format — string
  • Description — the gateway IP address, as a string, no drama.

ok so plot twist: the gateway can also be specified in one of the "address1", "address2", etc. variables after the address, separated by a comma or semicolon — like "address1=192.168.100.1/24,192.168.100.254". but heads up: the value from the "gateway" variable takes precedence over any gateway specified in one of the "address*" variables. main character energy, it wins. 👑

Example:

gateway=192.168.100.254

🦋 routes

  • Keyfile Variable — route1, route2, ...
  • Format — route/plen[,gateway,metric]
  • Description — a list of IP routes. simple as that.

Examples:

route1=8.8.8.0/24,10.1.1.1,77
route2=7.7.0.0/16

🌈 routes (attributes)

  • Keyfile Variable — route1_options, route2_options, ...
  • Format — key=val[,key=val...]
  • Description — attributes defined for the routes, if any exist. the supported attributes are explained in the ipv4.routes entry in man nm-settings-nmcli — go read that for the full tea 🍵

Example:

route1_options=mtu=1000,onlink=true

⭐ routing-rules

  • Keyfile Variable — routing-rule1, routing-rule2, ...
  • Format — routing rule string
  • Description — routing rules as defined with ip rule add, BUT with a mandatory fixed priority. and important: the "lookup" and "table" options don't support a table name, only a number. no names, bestie, numbers only. 💀

Example:

routing-rule1=priority 5 from 192.167.4.0/24 table 45

💅 the ipv6 setting (section)

Okay bestie, this is the IPv6 glow-up table — literally the whole v6 universe in one section. Let's go property by property, no skipping, no cap 🫶

  • dns — no keyfile variable, she just exists — format: list of DNS IP addresses — literally just your list of DNS servers. Simple, iconic, done. Example:
dns=2001:4860:4860::8888;2001:4860:4860::8844;
  • addresses — keyfile variables: address1, address2, ... — format: address/plen[,gateway] — these are your static IPv6 addresses, one address per variable so don't try to cram them all in one line. The variables can also hold the gateway, tacked on after a comma or a semicolon — but ngl, the manpage itself says it's recommended to use the gateway variable instead. Do with that what you will 😌 Examples:
address1=abbe::cafe/96
address2=2001::1234/56
address1=fd01::2000/64;fd01::1
  • gateway — keyfile variable: gateway — format: string — your gateway IP address, as a string, bestie. And yes, the gateway can also be specified in one of the address1, address2, etc. variables after the address, separated by a comma or semicolon (for example address1=fd01::2000/64;fd01::1). But here's the tea ☕ — the value from the gateway variable takes precedence over any gateway specified in one of the address* variables. So if you set both, gateway wins, periodt. Example:
gateway=abbe::1
  • routes — keyfile variables: route1, route2, ... — format: route/plen[,gateway,metric] — your list of IP routes. That's it, that's the vibe. Example:
route1=2001:4860:4860::/64,2620:52:0:2219:222:68ff:fe11:5403
  • routes (attributes) — keyfile variables: route1_options, route2_options, ... — format: key=val[,key=val...] — the attributes defined for those routes, if any exist. The supported attributes are explained in the ipv6.routes entry in man nm-settings-nmcli — go read that one if you're being extra ✨ Example:
route1_options=mtu=1000,onlink=true
  • routing-rules — keyfile variables: routing-rule1, routing-rule2, ... — format: routing rule string — these are routing rules as defined with ip rule add, but with a mandatory fixed priority. Yeah, priority isn't optional here, it's giving non-negotiable 💀 Example:
routing-rule1=priority 5 from 2001:4860:4860::/64 table 45

🎀 the serial setting (section)

Short and sweet, we love a minimal queen 👑

  • parity — no keyfile variable — format: 'e', 'o', or 'n' — the connection parity: even, odd, or none. But listen, this is the fun part — older versions of NetworkManager stored this as an integer: 69 ('E') for even, 111 ('o') for odd, or 110 ('n') for none. Yes, actual ASCII codes, that's the legacy lore, iykyk 🙈 Example:
parity=n

Honestly? Chef's kiss. Serial takes like five seconds to configure and that's the energy we're bringing 🦋

✨ Table 9. vpn setting (section) ✨

  • data — maps to separate variables that are literally named after the keys of the dictionary 🫶. The keys of the data dictionary get used as variable names directly under the [vpn] section. Example:
remote=ovpn.corp.com
cipher=AES-256-CBC
username=joe
  • secrets — also separate variables named after the keys of the dictionary 💅. The keys of the secrets dictionary get used as variable names directly under the [vpn-secrets] section. Example:
password=Popocatepetl

🦋 Table 10. wifi-p2p setting (section) 🦋

  • peer — no keyfile variable name of its own, and the format is the usual hex-digits-and-colons notation. It's a MAC address in traditional hex-digits-and-colons notation (e.g. 00:22:68:12:79:A2), or a semicolon separated list of 6 bytes — that one's obsolete ngl (e.g. 0;34;104;18;121;162). 💀

🌸 Table 11. wpan setting (section) 🌸

  • mac-address — no keyfile variable name, format is the usual hex-digits-and-colons notation. It's a MAC address in hex-digits-and-colons notation (e.g. 76:d8:9b:87:66:60:84:ee). 🎀

🔐 Secret flags 🔐

okay so every secret property in a NetworkManager setting has a flags property that comes with it, and that property describes how to handle that secret. In the keyfile plugin, the value of the -flags variable is a decimal number (0 - 7), defined as a sum of the following values 👇

  • 0 - (NM owned) - the system is responsible for providing and storing this secret. 👑
  • 1 - (agent-owned) - a user-session secret agent is responsible for providing and storing this secret; when it's required, agents will be asked to provide it.
  • 2 - (not-saved) - this secret should not be saved but should be requested from the user each time it's required. 🙈
  • 4 - (not-required) - in some situations it can't be automatically determined that a secret is required or not. This flag hints that the secret is not required and should not be requested from the user.

📁 FILES 📁

  • /etc/NetworkManager/system-connections/*

👀 SEE ALSO 👀

📝 NOTES 📝

  1. GLib key file format — https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html#glib-Key-value-file-parser.description

and that's the whole page bestie, you made it 🫶✨ this was NetworkManager 1.58.0, NM-SETTINGS-KEYFILE(5) — go forth and edit your keyfiles with main character energy 💅💖

📦 where this page comes from