path: root/man/nm-settings-keyfile.5

'\" t
.\"     Title: nm-settings-keyfile
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 05 May 2015
.\"    Manual: Configuration
.\"    Source: NetworkManager 1.0.2
.\"  Language: English
.\"
.TH "NM\-SETTINGS\-KEYFIL" "5" "" "NetworkManager 1\&.0\&.2" "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\&. It writes files out in a \&.ini\-style format in
/etc/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 writeable by any user or group 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 bellow\&. 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 (see
\fImonitor\-connection\-file\fR
in
\fBnm-settings\fR(5)
and
\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 bellow\&. 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{
ususal 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{
ususal 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\&.4;8\&.8\&.8\&.8;8\&.8\&.4\&.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.\ \&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{
ususal 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{
ususal 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\ \&8.\ \&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{
ususal 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{
ususal 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
.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 "AUTHOR"
.PP
NetworkManager developers
.SH "FILES"
.PP
/etc/NetworkManager/system\-connections/*
.SH "SEE ALSO"
.PP
https://developer\&.gnome\&.org/NetworkManager/unstable/ref\-settings\&.html
.PP
nm\-settings(5), nm\-settings\-ifcfg\-rh(5), NetworkManager(8), NetworkManager\&.conf(5), nmcli(1), nmcli\-examples(5)
.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