'\" t

.\"     Title: nm-settings-keyfile

.\"    Author: 

.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>

.\"      Date: 07/13/2020

.\"    Manual: Configuration

.\"    Source: NetworkManager 1.26.0

.\"  Language: English

.\"

.TH "NM\-SETTINGS\-KEYFILE" "5" "" "NetworkManager 1\&.26\&.0" "Configuration"

.\" -----------------------------------------------------------------

.\" * Define some portability stuff

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" http://bugs.debian.org/507673

.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.\" -----------------------------------------------------------------

.\" * set default formatting

.\" -----------------------------------------------------------------

.\" disable hyphenation

.nh

.\" disable justification (adjust text to left margin only)

.ad l

.\" -----------------------------------------------------------------

.\" * MAIN CONTENT STARTS HERE *

.\" -----------------------------------------------------------------

.SH "NAME"

nm-settings-keyfile \- Description of \fIkeyfile\fR settings plugin

.SH "DESCRIPTION"

.PP

NetworkManager is based on the concept of connection profiles that contain network configuration (see

\fBnm-settings\fR(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

\fBNetworkManager.conf\fR(5)\&.

.PP

The

\fIkeyfile\fR

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\&. For security, it will ignore files that are readable or writable by any user other than \*(Aqroot\*(Aq since private keys and passphrases may be stored in plaintext inside the file\&.

.SH "FILE FORMAT"

.PP

The

\fIkeyfile\fR

config format is a simple \&.ini\-style format\&. It consists of sections (groups) of key\-value pairs\&. Each section corresponds to a setting name as described in the settings specification (\fBnm-settings\fR(5))\&. Each configuration key/value pair in the section is one of the properties listed in the settings specification\&. The majority of properties of the specification is written in the same format into the

\fIkeyfile\fR

too\&. However some values are inconvenient for people to use\&. These are stored in the files in more readable ways\&. These properties 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"\&. More information of the generic key file format can be found at

\m[blue]\fBGLib key file format\fR\m[]\&\s-2\u[1]\d\s+2

(Lines beginning with a \*(Aq#\*(Aq are comments, lists are separated by character

;

etc\&.)\&.

.PP

Users can create or modify the

\fIkeyfile\fR

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

\fInmcli con (re)load\fR)\&.

.PP

\fBExamples of keyfile configuration\fR. 

.sp

.if n \{\

.RS 4

.\}

.nf

\fBA sample configuration for an ethernet network:\fR

[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

.fi

.if n \{\

.RE

.\}

.sp

.if n \{\

.RS 4

.\}

.nf

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

[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

.fi

.if n \{\

.RE

.\}

.sp

.if n \{\

.RS 4

.\}

.nf

\fBA sample configuration for openvpn:\fR

[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

.fi

.if n \{\

.RE

.\}

.sp

.if n \{\

.RS 4

.\}

.nf

\fBA sample configuration for a bridge and a bridge port:\fR

[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

                                             master=MainBridge

[bridge]                                     slave\-type=bridge

interface\-name=MainBridge

.fi

.if n \{\

.RE

.\}

.sp

.if n \{\

.RS 4

.\}

.nf

\fBA sample configuration for a VLAN:\fR

[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

.fi

.if n \{\

.RE

.\}

.SH "DETAILS"

.PP

\fIkeyfile\fR

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

\fIkeyfile\fR

plugin are listed below\&. Refer to

\fBnm-settings\fR(5)

for all available settings and properties and their description\&.

.PP

\fBName aliases\fR. Some of the NetworkManager setting names are somewhat hard to type or remember\&. Therefore

\fIkeyfile\fR

introduces aliases that can be used instead of the names\&.

.RS 4

\fIsetting name                 keyfile alias\fR

.RE

.RS 4

802\-3\-ethernet            =  ethernet

.RE

.RS 4

802\-11\-wireless           =  wifi

.RE

.RS 4

802\-11\-wireless\-security  =  wifi\-security

.RE

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&1.\ \&bridge setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l.

T{

mac\-address

T}:T{

mac\-address

T}:T{

usual hex\-digits\-and\-colons notation

T}:T{

MAC address in traditional hex\-digits\-and\-colons notation, or semicolon separated list of 6 decimal bytes (obsolete)\fB

Example: \fRmac\-address=00:22:68:12:79:A2 mac\-address=0;34;104;18;121;162;

T}

.TE

.sp 1

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&2.\ \&infiniband setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l.

T{

mac\-address

T}:T{

mac\-address

T}:T{

usual hex\-digits\-and\-colons notation

T}:T{

MAC address in traditional hex\-digits\-and\-colons notation, or or semicolon separated list of 20 decimal bytes (obsolete)\fB

Example: \fRmac\-address= 80:00:00:6d:fe:80:00:00:00:00:00:00:00:02:55:00:70:33:cf:01

T}

.TE

.sp 1

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&3.\ \&ipv4 setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l

l l l l

l l l l

l l l l.

T{

dns

T}:T{

dns

T}:T{

list of DNS IP addresses

T}:T{

List of DNS servers\&.\fB

Example: \fRdns=1\&.2\&.3\&.;;8\&.8\&.8\&.;;8\&.8\&.4\&.;;

T}

T{

addresses

T}:T{

address1, address2, \&.\&.\&.

T}:T{

address/plen

T}:T{

List of static IP addresses\&.\fB

Example: \fRaddress1=192\&.168\&.100\&.100/24 address2=10\&.1\&.1\&.5/24

T}

T{

gateway

T}:T{

gateway

T}:T{

string

T}:T{

Gateway IP addresses as a string\&.\fB

Example: \fRgateway=192\&.168\&.100\&.1

T}

T{

routes

T}:T{

route1, route2, \&.\&.\&.

T}:T{

route/plen[,gateway,metric]

T}:T{

List of IP routes\&.\fB

Example: \fRroute1=8\&.8\&.8\&.0/24,10\&.1\&.1\&.1,77 route2=7\&.7\&.0\&.0/16

T}

.TE

.sp 1

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&4.\ \&ipv6 setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l

l l l l

l l l l

l l l l.

T{

dns

T}:T{

dns

T}:T{

list of DNS IP addresses

T}:T{

List of DNS servers\&.\fB

Example: \fRdns=2001:4860:4860::8888;2001:4860:4860::8844;

T}

T{

addresses

T}:T{

address1, address2, \&.\&.\&.

T}:T{

address/plen

T}:T{

List of static IP addresses\&.\fB

Example: \fRaddress1=abbe::cafe/96 address2=2001::1234

T}

T{

gateway

T}:T{

gateway

T}:T{

string

T}:T{

Gateway IP addresses as a string\&.\fB

Example: \fRgateway=abbe::1

T}

T{

routes

T}:T{

route1, route2, \&.\&.\&.

T}:T{

route/plen[,gateway,metric]

T}:T{

List of IP routes\&.\fB

Example: \fRroute1=2001:4860:4860::/64,2620:52:0:2219:222:68ff:fe11:5403

T}

.TE

.sp 1

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&5.\ \&serial setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l.

T{

parity

T}:T{

parity

T}:T{

\*(Aqe\*(Aq, \*(Aqo\*(Aq, or \*(Aqn\*(Aq

T}:T{

The connection parity; even, odd, or none\&. Note that older versions of NetworkManager stored this as an integer: 69 (\*(AqE\*(Aq) for even, 111 (\*(Aqo\*(Aq) for odd, or 110 (\*(Aqn\*(Aq) for none\&.\fB

Example: \fRparity=n

T}

.TE

.sp 1

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&6.\ \&vpn setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l

l l l l.

T{

data

T}:T{

separate variables named after keys of the dictionary

T}:T{

\ \&

T}:T{

The keys of the data dictionary are used as variable names directly under [vpn] section\&.\fB

Example: \fRremote=ovpn\&.corp\&.com cipher=AES\-256\-CBC username=joe

T}

T{

secrets

T}:T{

separate variables named after keys of the dictionary

T}:T{

\ \&

T}:T{

The keys of the secrets dictionary are used as variable names directly under [vpn\-secrets] section\&.\fB

Example: \fRpassword=Popocatepetl

T}

.TE

.sp 1

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&7.\ \&wifi\-p2p setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l.

T{

peer

T}:T{

peer

T}:T{

usual hex\-digits\-and\-colons notation

T}:T{

MAC address in traditional hex\-digits\-and\-colons notation (e\&.g\&. 00:22:68:12:79:A2), or semicolon separated list of 6 bytes (obsolete) (e\&.g\&. 0;34;104;18;121;162)\&.

T}

.TE

.sp 1

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&8.\ \&802\-3\-ethernet setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l

l l l l

l l l l.

T{

mac\-address

T}:T{

mac\-address

T}:T{

usual hex\-digits\-and\-colons notation

T}:T{

MAC address in traditional hex\-digits\-and\-colons notation (e\&.g\&. 00:22:68:12:79:A2), or semicolon separated list of 6 bytes (obsolete) (e\&.g\&. 0;34;104;18;121;162)

T}

T{

cloned\-mac\-address

T}:T{

cloned\-mac\-address

T}:T{

usual hex\-digits\-and\-colons notation

T}:T{

Cloned MAC address in traditional hex\-digits\-and\-colons notation (e\&.g\&. 00:22:68:12:79:B2), or semicolon separated list of 6 bytes (obsolete) (e\&.g\&. 0;34;104;18;121;178)\&.

T}

T{

mac\-address\-blacklist

T}:T{

mac\-address\-blacklist

T}:T{

list of MACs (separated with semicolons)

T}:T{

MAC address blacklist\&.\fB

Example: \fRmac\-address\-blacklist= 00:22:68:12:79:A6;00:22:68:12:79:78

T}

.TE

.sp 1

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&9.\ \&802\-11\-wireless setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l

l l l l

l l l l

l l l l.

T{

ssid

T}:T{

ssid

T}:T{

string (or decimal\-byte list \- obsolete)

T}:T{

SSID of Wi\-Fi network\&.\fB

Example: \fRssid=Quick Net

T}

T{

mac\-address

T}:T{

mac\-address

T}:T{

usual hex\-digits\-and\-colons notation

T}:T{

MAC address in traditional hex\-digits\-and\-colons notation (e\&.g\&. 00:22:68:12:79:A2), or semicolon separated list of 6 bytes (obsolete) (e\&.g\&. 0;34;104;18;121;162)\&.

T}

T{

cloned\-mac\-address

T}:T{

cloned\-mac\-address

T}:T{

usual hex\-digits\-and\-colons notation

T}:T{

Cloned MAC address in traditional hex\-digits\-and\-colons notation (e\&.g\&. 00:22:68:12:79:B2), or semicolon separated list of 6 bytes (obsolete) (e\&.g\&. 0;34;104;18;121;178)\&.

T}

T{

mac\-address\-blacklist

T}:T{

mac\-address\-blacklist

T}:T{

list of MACs (separated with semicolons)

T}:T{

MAC address blacklist\&.\fB

Example: \fRmac\-address\-blacklist= 00:22:68:12:79:A6;00:22:68:12:79:78

T}

.TE

.sp 1

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.B Table\ \&10.\ \&wpan setting (section)

.TS

allbox tab(:);

lB lB lB lB.

T{

Property

T}:T{

Keyfile Variable

T}:T{

Format

T}:T{

Description

T}

.T&

l l l l.

T{

mac\-address

T}:T{

mac\-address

T}:T{

usual hex\-digits\-and\-colons notation

T}:T{

MAC address in hex\-digits\-and\-colons notation (e\&.g\&. 76:d8:9b:87:66:60:84:ee)\&.

T}

.TE

.sp 1

.SS "Secret flags"

.PP

Each secret property in a NetworkManager setting has an associated

\fIflags\fR

property that describes how to handle that secret\&. In the

\fIkeyfile\fR

plugin, the value of

\fI\-flags\fR

variable is a decimal number (0 \- 7) defined as a sum of the following values:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

0 \- (NM owned) \- the system is responsible for providing and storing this secret\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

1 \- (agent\-owned) \- a user\-session secret agent is responsible for providing and storing this secret; when it is required, agents will be asked to provide it\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

2 \- (not\-saved) \- this secret should not be saved but should be requested from the user each time it is required\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

4 \- (not\-required) \- in some situations it cannot 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\&.

.RE

.SH "FILES"

.PP

/etc/NetworkManager/system\-connections/*

.SH "SEE ALSO"

.PP

\fBnm-settings\fR(5),

\fBnm-settings-ifcfg-rh\fR(5),

\fBNetworkManager\fR(8),

\fBNetworkManager.conf\fR(5),

\fBnmcli\fR(1),

\fBnmcli-examples\fR(7)

.SH "NOTES"

.IP " 1." 4

GLib key file format

.RS 4

\%https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html#glib-Key-value-file-parser.description

.RE