diff options
Diffstat (limited to 'man/nm-settings-keyfile.5')
| -rw-r--r-- | man/nm-settings-keyfile.5 | 698 |
1 files changed, 698 insertions, 0 deletions
diff --git a/man/nm-settings-keyfile.5 b/man/nm-settings-keyfile.5 new file mode 100644 index 00000000..53e9165f --- /dev/null +++ b/man/nm-settings-keyfile.5 @@ -0,0 +1,698 @@ +'\" t +.\" Title: nm-settings-keyfile +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 19 December 2014 +.\" Manual: Configuration +.\" Source: NetworkManager 1.0.0 +.\" Language: English +.\" +.TH "NM\-SETTINGS\-KEYFIL" "5" "" "NetworkManager 1\&.0\&.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\&. 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 |