diff options
| author | Michael Biebl <biebl@debian.org> | 2024-02-22 17:21:11 +0100 |
|---|---|---|
| committer | Michael Biebl <biebl@debian.org> | 2024-02-22 17:21:11 +0100 |
| commit | bba2e4b4de668db525cbfdfc35292e5a0b51671a (patch) | |
| tree | 38d20cddfcc6f71572b9e169deefab5fa96e8d0c /man | |
| parent | 6681f77b757bbc42ce5c8868ee9142b7ebc8c059 (diff) | |
New upstream version 1.46.0 upstream/1.46.0
Diffstat (limited to 'man')
| -rw-r--r-- | man/NetworkManager-dispatcher.8 | 105 | ||||
| -rw-r--r-- | man/NetworkManager-dispatcher.xml | 84 | ||||
| -rw-r--r-- | man/NetworkManager-wait-online.service.8 | 4 | ||||
| -rw-r--r-- | man/NetworkManager.8 | 6 | ||||
| -rw-r--r-- | man/NetworkManager.conf.5 | 10 | ||||
| -rw-r--r-- | man/NetworkManager.conf.xml | 3 | ||||
| -rw-r--r-- | man/nm-cloud-setup.8 | 6 | ||||
| -rw-r--r-- | man/nm-initrd-generator.8 | 6 | ||||
| -rw-r--r-- | man/nm-online.1 | 6 | ||||
| -rw-r--r-- | man/nm-openvswitch.7 | 6 | ||||
| -rw-r--r-- | man/nm-settings-dbus.5 | 81 | ||||
| -rw-r--r-- | man/nm-settings-dbus.xml | 30 | ||||
| -rw-r--r-- | man/nm-settings-ifcfg-rh.5 | 6 | ||||
| -rw-r--r-- | man/nm-settings-ifcfg-rh.xml | 2 | ||||
| -rw-r--r-- | man/nm-settings-keyfile.5 | 6 | ||||
| -rw-r--r-- | man/nm-settings-keyfile.xml | 2 | ||||
| -rw-r--r-- | man/nm-settings-nmcli.5 | 74 | ||||
| -rw-r--r-- | man/nm-settings-nmcli.xml | 19 | ||||
| -rw-r--r-- | man/nmcli-examples.7 | 6 | ||||
| -rw-r--r-- | man/nmcli.1 | 6 | ||||
| -rw-r--r-- | man/nmtui.1 | 6 |
21 files changed, 417 insertions, 57 deletions
diff --git a/man/NetworkManager-dispatcher.8 b/man/NetworkManager-dispatcher.8 index 803f807b..4e263d62 100644 --- a/man/NetworkManager-dispatcher.8 +++ b/man/NetworkManager-dispatcher.8 @@ -2,9 +2,9 @@ .\" Title: NetworkManager-dispatcher .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Network management daemons -.\" Source: NetworkManager-dispatcher 1.45.91 +.\" Source: NetworkManager-dispatcher 1.46.0 .\" Language: English .\" .TH "NETWORKMANAGER\-DISPATCHER" "8" "" "NetworkManager\-dispatcher 1\&" "Network management daemons" @@ -130,6 +130,41 @@ The DNS configuration has changed\&. This action is raised even if NetworkManage /run/NetworkManager/resolv\&.conf .RE .PP +\fIdevice\-add\fR +.RS 4 +This action is called when a connection of type +generic +has the +generic\&.device\-handler +property set\&. The property indicates the name of a dispatcher script to be executed in directory +/{etc,usr/lib}/NetworkManager/dispatcher\&.d/device\&. Note that differently from other actions, only one script is executed\&. +.sp +The script needs to perform any action needed to create the device for the generic connection\&. On successful termination, the script returns zero\&. Otherwise, it returns a non\-zero value to indicate an error\&. The script can return values to NetworkManager by writing to standard output; each line should contain a key name followed by the equal sign \*(Aq=\*(Aq and a key value\&. The keys understood at the moment are: +.PP +\fIIFINDEX\fR +.RS 4 +Indicates the interface index of the interface created by the script\&. This key is required when the script succeeds; if it is not set, the activation will fail\&. The key is ignored in case of script failure\&. +.RE +.PP +\fIERROR\fR +.RS 4 +Specifies an error message indicating the cause of the script failure\&. It is ignored when the script succeeds\&. +.RE +.sp +Since the dispatcher service captures stdout for parsing those keys, anything written to stdout will not appear in the dispatcher service journal log\&. Use stderr if you want to print messages to the journal (for example, for debugging)\&. Only the first 8KiB of stdout are considered and among those, only the first 64 lines; the rest is ignored\&. +.RE +.PP +\fIdevice\-delete\fR +.RS 4 +This action is the counterpart of +device\-add +and is called to delete the device for a generic connection\&. All the aspects described for +device\-add +also apply to this action, with the only exception that key +\fIIFINDEX\fR +is ignored\&. It is not necessary to delete the kernel link in the handler because NetworkManager already does that; therefore the action is useful for any additional cleanup needed\&. +.RE +.PP The environment contains more information about the interface and the connection\&. The following variables are available for the use in the dispatcher scripts: .PP \fINM_DISPATCHER_ACTION\fR @@ -231,6 +266,72 @@ FULL\&. Note: this variable will only be set for connectivity\-change actions\&. .PP In case of VPN, VPN_IP_IFACE is set, and IP4_*, IP6_* variables with VPN prefix are exported too, like VPN_IP4_ADDRESS_0, VPN_IP4_NUM_ADDRESSES\&. .PP +The content of the +user +setting for the connection being activated is also passed via environment variables\&. Each key is stored in a variable with name +CONNECTION_USER_ +concatenated with the encoding of the key name\&. The encoding works as follows: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +lowercase letters become uppercase +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +uppercase letters are prefixed with an underscore +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +numbers do not change +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +a dot is replaced with a double underscore +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +any other character is encoded with an underscore followed by its 3\-digit octal representation +.RE +.sp +For example, key +test\&.foo\-Bar2 +is stored in a variable named +CONNECTION_USER_TEST__FOO_055_BAR2\&. +.PP Dispatcher scripts are run one at a time, but asynchronously from the main NetworkManager process, and will be killed if they run for too long\&. If your script might take arbitrarily long to complete, you should spawn a child process and have the parent return immediately\&. Scripts that are symbolic links pointing inside the /etc/NetworkManager/dispatcher\&.d/no\-wait\&.d/ directory are run immediately, without waiting for the termination of previous scripts, and in parallel\&. Also beware that once a script is queued, it will always be run, even if a later event renders it obsolete\&. (Eg, if an interface goes up, and then back down again quickly, it is possible that one or more "up" scripts will be run after the interface has gone down\&.) diff --git a/man/NetworkManager-dispatcher.xml b/man/NetworkManager-dispatcher.xml index f6e1d22d..f85a495a 100644 --- a/man/NetworkManager-dispatcher.xml +++ b/man/NetworkManager-dispatcher.xml @@ -172,6 +172,63 @@ looking at file <filename>/run/NetworkManager/resolv.conf</filename> </para></listitem> </varlistentry> + <varlistentry> + <term><varname>device-add</varname></term> + <listitem> + <para> + This action is called when a connection of type <literal>generic</literal> + has the <literal>generic.device-handler</literal> property set. The property + indicates the name of a dispatcher script to be executed in directory + <filename>/{etc,usr/lib}/NetworkManager/dispatcher.d/device</filename>. Note + that differently from other actions, only one script is executed. + </para> + <para> + The script needs to perform any action needed to create the device + for the generic connection. On successful termination, the script + returns zero. Otherwise, it returns a non-zero value to indicate an + error. The script can return values to NetworkManager by writing to + standard output; each line should contain a key name followed by the + equal sign '=' and a key value. The keys understood at the moment + are: + <variablelist> + <varlistentry> + <term><varname>IFINDEX</varname></term> + <listitem><para> Indicates the interface index of the interface + created by the script. This key is required when the script + succeeds; if it is not set, the activation will fail. The key is + ignored in case of script failure. </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>ERROR</varname></term> + <listitem><para> Specifies an error message indicating the cause + of the script failure. It is ignored when the script succeeds. + </para></listitem> + </varlistentry> + </variablelist> + Since the dispatcher service captures stdout for parsing those keys, + anything written to stdout will not appear in the dispatcher service + journal log. Use stderr if you want to print messages to the journal + (for example, for debugging). Only the first 8KiB of stdout are + considered and among those, only the first 64 lines; the rest is + ignored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>device-delete</varname></term> + <listitem> + <para> + This action is the counterpart of <literal>device-add</literal> and + is called to delete the device for a generic connection. All the + aspects described for <literal>device-add</literal> also apply to + this action, with the only exception that key + <varname>IFINDEX</varname> is ignored. It is not necessary to delete + the kernel link in the handler because NetworkManager already does + that; therefore the action is useful for any additional cleanup + needed. + </para> + </listitem> + </varlistentry> </variablelist> <para> The environment contains more information about the interface and the connection. @@ -309,6 +366,33 @@ exported too, like VPN_IP4_ADDRESS_0, VPN_IP4_NUM_ADDRESSES. </para> <para> + The content of the <literal>user</literal> setting for the connection + being activated is also passed via environment variables. Each key is + stored in a variable with name <literal>CONNECTION_USER_</literal> + concatenated with the encoding of the key name. The encoding works as + follows: + <itemizedlist> + <listitem> + <para>lowercase letters become uppercase</para> + </listitem> + <listitem> + <para>uppercase letters are prefixed with an underscore</para> + </listitem> + <listitem> + <para>numbers do not change</para> + </listitem> + <listitem> + <para>a dot is replaced with a double underscore</para> + </listitem> + <listitem> + <para>any other character is encoded with an underscore followed by + its 3-digit octal representation</para> + </listitem> + </itemizedlist> + For example, key <literal>test.foo-Bar2</literal> is stored in a variable named + <literal>CONNECTION_USER_TEST__FOO_055_BAR2</literal>. + </para> + <para> Dispatcher scripts are run one at a time, but asynchronously from the main NetworkManager process, and will be killed if they run for too long. If your script might take arbitrarily long to complete, you should spawn a child process and have the diff --git a/man/NetworkManager-wait-online.service.8 b/man/NetworkManager-wait-online.service.8 index 971644cb..17f61261 100644 --- a/man/NetworkManager-wait-online.service.8 +++ b/man/NetworkManager-wait-online.service.8 @@ -2,9 +2,9 @@ .\" Title: NetworkManager-wait-online.service .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Network management daemons -.\" Source: NetworkManager-wait-online.service 1.45.91 +.\" Source: NetworkManager-wait-online.service 1.46.0 .\" Language: English .\" .TH "NETWORKMANAGER\-WAIT\-ONLINE\&" "8" "" "NetworkManager\-wait\-online\&" "Network management daemons" diff --git a/man/NetworkManager.8 b/man/NetworkManager.8 index 829e88c9..4233c56e 100644 --- a/man/NetworkManager.8 +++ b/man/NetworkManager.8 @@ -2,12 +2,12 @@ .\" Title: NetworkManager .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Network management daemons -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NETWORKMANAGER" "8" "" "NetworkManager 1\&.45\&.91" "Network management daemons" +.TH "NETWORKMANAGER" "8" "" "NetworkManager 1\&.46\&.0" "Network management daemons" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/man/NetworkManager.conf.5 b/man/NetworkManager.conf.5 index 357da0c0..1fa1b2de 100644 --- a/man/NetworkManager.conf.5 +++ b/man/NetworkManager.conf.5 @@ -2,12 +2,12 @@ .\" Title: NetworkManager.conf .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Configuration -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NETWORKMANAGER\&.CONF" "5" "" "NetworkManager 1\&.45\&.91" "Configuration" +.TH "NETWORKMANAGER\&.CONF" "5" "" "NetworkManager 1\&.46\&.0" "Configuration" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -985,6 +985,10 @@ If left unspecified, routes are only added to the main table\&. Note that this i If configured explicitly to 0, the MTU is not reconfigured during device activation unless it is required due to IPv6 constraints\&. If left unspecified, a DHCP/IPv6 SLAAC provided value is used or the MTU is left unspecified on activation\&. .RE .PP +\fImacsec\&.offload\fR +.RS 4 +.RE +.PP \fIsriov\&.autoprobe\-drivers\fR .RS 4 If left unspecified, drivers are autoprobed when the SR\-IOV VF gets created\&. diff --git a/man/NetworkManager.conf.xml b/man/NetworkManager.conf.xml index 442c7140..69cfdb07 100644 --- a/man/NetworkManager.conf.xml +++ b/man/NetworkManager.conf.xml @@ -1022,6 +1022,9 @@ ipv6.ip6-privacy=0 <listitem><para>If configured explicitly to 0, the MTU is not reconfigured during device activation unless it is required due to IPv6 constraints. If left unspecified, a DHCP/IPv6 SLAAC provided value is used or the MTU is left unspecified on activation.</para></listitem> </varlistentry> <varlistentry> + <term><varname>macsec.offload</varname></term> + </varlistentry> + <varlistentry> <term><varname>sriov.autoprobe-drivers</varname></term> <listitem><para>If left unspecified, drivers are autoprobed when the SR-IOV VF gets created.</para></listitem> </varlistentry> diff --git a/man/nm-cloud-setup.8 b/man/nm-cloud-setup.8 index decfcc4b..43a72c57 100644 --- a/man/nm-cloud-setup.8 +++ b/man/nm-cloud-setup.8 @@ -2,12 +2,12 @@ .\" Title: nm-cloud-setup .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Automatic Network Configuration in Cloud with NetworkManager -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NM\-CLOUD\-SETUP" "8" "" "NetworkManager 1\&.45\&.91" "Automatic Network Configuratio" +.TH "NM\-CLOUD\-SETUP" "8" "" "NetworkManager 1\&.46\&.0" "Automatic Network Configuratio" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/man/nm-initrd-generator.8 b/man/nm-initrd-generator.8 index aafa7992..b3b6ca3f 100644 --- a/man/nm-initrd-generator.8 +++ b/man/nm-initrd-generator.8 @@ -2,12 +2,12 @@ .\" Title: nm-initrd-generator .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: System Administration -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NM\-INITRD\-GENERATOR" "8" "" "NetworkManager 1\&.45\&.91" "System Administration" +.TH "NM\-INITRD\-GENERATOR" "8" "" "NetworkManager 1\&.46\&.0" "System Administration" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/man/nm-online.1 b/man/nm-online.1 index 54ec05b8..cd739472 100644 --- a/man/nm-online.1 +++ b/man/nm-online.1 @@ -2,12 +2,12 @@ .\" Title: nm-online .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: General Commands Manual -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NM\-ONLINE" "1" "" "NetworkManager 1\&.45\&.91" "General Commands Manual" +.TH "NM\-ONLINE" "1" "" "NetworkManager 1\&.46\&.0" "General Commands Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/man/nm-openvswitch.7 b/man/nm-openvswitch.7 index fda3ef9d..35f5589b 100644 --- a/man/nm-openvswitch.7 +++ b/man/nm-openvswitch.7 @@ -2,12 +2,12 @@ .\" Title: nm-openvswitch .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Open vSwitch support overview -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NM\-OPENVSWITCH" "7" "" "NetworkManager 1\&.45\&.91" "Open vSwitch support overview" +.TH "NM\-OPENVSWITCH" "7" "" "NetworkManager 1\&.46\&.0" "Open vSwitch support overview" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/man/nm-settings-dbus.5 b/man/nm-settings-dbus.5 index 480ccc0e..f586b00d 100644 --- a/man/nm-settings-dbus.5 +++ b/man/nm-settings-dbus.5 @@ -2,12 +2,12 @@ .\" Title: nm-settings-dbus .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Configuration -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NM\-SETTINGS\-DBUS" "5" "" "NetworkManager 1\&.45\&.91" "Configuration" +.TH "NM\-SETTINGS\-DBUS" "5" "" "NetworkManager 1\&.46\&.0" "Configuration" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -136,9 +136,9 @@ T} T{ autoconnect\-ports T}:T{ -NMTernary (int32) +int32 T}:T{ -\ \& +\-1 T}:T{ Whether or not ports of this connection should be automatically brought up when NetworkManager activates this connection\&. This only has a real effect for controller connections\&. The properties "autoconnect", "autoconnect\-priority" and "autoconnect\-retries" are unrelated to this setting\&. The permitted values are: 0: leave port connections untouched, 1: activate all the port connections with this connection, \-1: default\&. If \-1 (default) is set, global connection\&.autoconnect\-ports is read to determine the real value\&. If it is default as well, this fallbacks to 0\&. T} @@ -1836,7 +1836,20 @@ T}:T{ Value Description T} .T& -. +l l l l. +T{ +device\-handler +T}:T{ +string +T}:T{ +\ \& +T}:T{ +Name of the device handler that will be invoked to add and delete the device for this connection\&. The name can only contain ASCII alphanumeric characters and \*(Aq\-\*(Aq, \*(Aq_\*(Aq, \*(Aq\&.\*(Aq\&. It cannot start with \*(Aq\&.\*(Aq\&. + +See the NetworkManager\-dispatcher(8) man page for more details about how to write the device handler\&. + +By setting this property the generic connection becomes "virtual", meaning that it can be activated without an existing device; the device will be created at the time the connection is started by invoking the device\-handler\&. +T} .TE .sp 1 .SS "gsm setting" @@ -3197,6 +3210,7 @@ l l l l l l l l l l l l l l l l +l l l l l l l l. T{ encrypt @@ -3244,6 +3258,21 @@ T}:T{ Specifies how the CAK (Connectivity Association Key) for MKA (MACsec Key Agreement) is obtained\&. T} T{ +offload +T}:T{ +int32 +T}:T{ +\-1 +T}:T{ +Specifies the MACsec offload mode\&. + +0 (off) disables MACsec offload\&. + +1 (phy) and 2 (mac) request offload respectively to the PHY or to the MAC; if the selected mode is not available, the connection will fail\&. + +\-1 (default) uses the global default value specified in NetworkManager configuration; if no global default is defined, the built\-in default is 0 (off)\&. +T} +T{ parent T}:T{ string @@ -4153,6 +4182,9 @@ T} .T& l l l l l l l l +l l l l +l l l l +l l l l l l l l. T{ autoprobe\-drivers @@ -4170,6 +4202,43 @@ If set to 0 (false), VFs will not be claimed and no network interfaces will be c When set to \-1 (default), the global default is used; in case the global default is unspecified it is assumed to be 1 (true)\&. T} T{ +eswitch\-encap\-mode +T}:T{ +int32 +T}:T{ +\-1 +T}:T{ +Select the eswitch encapsulation support\&. + +Currently it\*(Aqs only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF\&. + +If set to \-1 (preserve) (default) the eswitch encap\-mode won\*(Aqt be modified by NetworkManager\&. +T} +T{ +eswitch\-inline\-mode +T}:T{ +int32 +T}:T{ +\-1 +T}:T{ +Select the eswitch inline\-mode of the device\&. Some HWs need the VF driver to put part of the packet headers on the TX descriptor so the e\-switch can do proper matching and steering\&. + +Currently it\*(Aqs only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF\&. + +If set to \-1 (preserve) (default) the eswitch inline\-mode won\*(Aqt be modified by NetworkManager\&. +T} +T{ +eswitch\-mode +T}:T{ +int32 +T}:T{ +\-1 +T}:T{ +Select the eswitch mode of the device\&. Currently it\*(Aqs only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF\&. + +If set to \-1 (preserve) (default) the eswitch mode won\*(Aqt be modified by NetworkManager\&. +T} +T{ total\-vfs T}:T{ uint32 diff --git a/man/nm-settings-dbus.xml b/man/nm-settings-dbus.xml index 11001e71..ec9bd0ec 100644 --- a/man/nm-settings-dbus.xml +++ b/man/nm-settings-dbus.xml @@ -1,6 +1,6 @@ <?xml version="1.0"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> -<refentry id="nm-settings-dbus"><refentryinfo><title>nm-settings-dbus</title><author>NetworkManager developers</author></refentryinfo><refmeta><refentrytitle>nm-settings-dbus</refentrytitle><manvolnum>5</manvolnum><refmiscinfo class="source">NetworkManager</refmiscinfo><refmiscinfo class="manual">Configuration</refmiscinfo><refmiscinfo class="version">1.45.91</refmiscinfo></refmeta><refnamediv><refname>nm-settings-dbus</refname><refpurpose>Description of settings and properties of NetworkManager connection profiles on the D-Bus API</refpurpose></refnamediv><refsect1 id="description"><title>Description</title><para> +<refentry id="nm-settings-dbus"><refentryinfo><title>nm-settings-dbus</title><author>NetworkManager developers</author></refentryinfo><refmeta><refentrytitle>nm-settings-dbus</refentrytitle><manvolnum>5</manvolnum><refmiscinfo class="source">NetworkManager</refmiscinfo><refmiscinfo class="manual">Configuration</refmiscinfo><refmiscinfo class="version">1.46.0</refmiscinfo></refmeta><refnamediv><refname>nm-settings-dbus</refname><refpurpose>Description of settings and properties of NetworkManager connection profiles on the D-Bus API</refpurpose></refnamediv><refsect1 id="description"><title>Description</title><para> NetworkManager is based on a concept of connection profiles, sometimes referred to as connections only. These connection profiles contain a network configuration. When NetworkManager activates a connection profile on a network device the configuration will @@ -42,7 +42,7 @@ Note that autoconnect is not implemented for VPN profiles. See "secondaries" as If multiple profiles are ready to autoconnect on the same device, the one with the better "connection.autoconnect-priority" is chosen. If the priorities are equal, then the most recently connected profile is activated. If the profiles were not connected earlier or their "connection.timestamp" is identical, the choice is undefined. -Depending on "connection.multi-connect", a profile can (auto)connect only once at a time or multiple times.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.autoconnect-ports">autoconnect-ports</entry><entry align="left">NMTernary (int32)</entry><entry align="left"/><entry>Whether or not ports of this connection should be automatically brought up when NetworkManager activates this connection. This only has a real effect for controller connections. The properties "autoconnect", "autoconnect-priority" and "autoconnect-retries" are unrelated to this setting. The permitted values are: 0: leave port connections untouched, 1: activate all the port connections with this connection, -1: default. If -1 (default) is set, global connection.autoconnect-ports is read to determine the real value. If it is default as well, this fallbacks to 0.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.autoconnect-priority">autoconnect-priority</entry><entry align="left">int32</entry><entry align="left">0</entry><entry>The autoconnect priority in range -999 to 999. If the connection is set to autoconnect, connections with higher priority will be preferred. The higher number means higher priority. Defaults to 0. Note that this property only matters if there are more than one candidate profile to select for autoconnect. In case of equal priority, the profile used most recently is chosen.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.autoconnect-retries">autoconnect-retries</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>The number of times a connection should be tried when autoactivating before giving up. Zero means forever, -1 means the global default (4 times if not overridden). Setting this to 1 means to try activation only once before blocking autoconnect. Note that after a timeout, NetworkManager will try to autoconnect again.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.autoconnect-slaves">autoconnect-slaves</entry><entry align="left">NMSettingConnectionAutoconnectSlaves (int32)</entry><entry align="left"/><entry>Whether or not slaves of this connection should be automatically brought up when NetworkManager activates this connection. This only has a real effect for master connections. The properties "autoconnect", "autoconnect-priority" and "autoconnect-retries" are unrelated to this setting. The permitted values are: 0: leave slave connections untouched, 1: activate all the slave connections with this connection, -1: default. If -1 (default) is set, global connection.autoconnect-slaves is read to determine the real value. If it is default as well, this fallbacks to 0.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.controller">controller</entry><entry align="left">string</entry><entry align="left"/><entry>Interface name of the controller device or UUID of the controller connection.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.dns-over-tls">dns-over-tls</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>Whether DNSOverTls (dns-over-tls) is enabled for the connection. DNSOverTls is a technology which uses TLS to encrypt dns traffic. +Depending on "connection.multi-connect", a profile can (auto)connect only once at a time or multiple times.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.autoconnect-ports">autoconnect-ports</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>Whether or not ports of this connection should be automatically brought up when NetworkManager activates this connection. This only has a real effect for controller connections. The properties "autoconnect", "autoconnect-priority" and "autoconnect-retries" are unrelated to this setting. The permitted values are: 0: leave port connections untouched, 1: activate all the port connections with this connection, -1: default. If -1 (default) is set, global connection.autoconnect-ports is read to determine the real value. If it is default as well, this fallbacks to 0.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.autoconnect-priority">autoconnect-priority</entry><entry align="left">int32</entry><entry align="left">0</entry><entry>The autoconnect priority in range -999 to 999. If the connection is set to autoconnect, connections with higher priority will be preferred. The higher number means higher priority. Defaults to 0. Note that this property only matters if there are more than one candidate profile to select for autoconnect. In case of equal priority, the profile used most recently is chosen.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.autoconnect-retries">autoconnect-retries</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>The number of times a connection should be tried when autoactivating before giving up. Zero means forever, -1 means the global default (4 times if not overridden). Setting this to 1 means to try activation only once before blocking autoconnect. Note that after a timeout, NetworkManager will try to autoconnect again.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.autoconnect-slaves">autoconnect-slaves</entry><entry align="left">NMSettingConnectionAutoconnectSlaves (int32)</entry><entry align="left"/><entry>Whether or not slaves of this connection should be automatically brought up when NetworkManager activates this connection. This only has a real effect for master connections. The properties "autoconnect", "autoconnect-priority" and "autoconnect-retries" are unrelated to this setting. The permitted values are: 0: leave slave connections untouched, 1: activate all the slave connections with this connection, -1: default. If -1 (default) is set, global connection.autoconnect-slaves is read to determine the real value. If it is default as well, this fallbacks to 0.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.controller">controller</entry><entry align="left">string</entry><entry align="left"/><entry>Interface name of the controller device or UUID of the controller connection.</entry></row><row><entry align="left" id="nm-settings-dbus.property.connection.dns-over-tls">dns-over-tls</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>Whether DNSOverTls (dns-over-tls) is enabled for the connection. DNSOverTls is a technology which uses TLS to encrypt dns traffic. The permitted values are: "yes" (2) use DNSOverTls and disabled fallback, "opportunistic" (1) use DNSOverTls but allow fallback to unencrypted resolution, "no" (0) don't ever use DNSOverTls. If unspecified "default" depends on the plugin used. Systemd-resolved uses global setting. @@ -156,7 +156,11 @@ $vid [pvid] [untagged] [, $vid [pvid] [untagged]]... where $vid is either a single id between 1 and 4094 or a range, represented as a couple of ids separated by a dash.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>cdma setting</title><para>CDMA-based Mobile Broadband Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.cdma.mtu">mtu</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple frames.</entry></row><row><entry align="left" id="nm-settings-dbus.property.cdma.number">number</entry><entry align="left">string</entry><entry align="left"/><entry>The number to dial to establish the connection to the CDMA-based mobile broadband network, if any. If not specified, the default number (#777) is used when required.</entry></row><row><entry align="left" id="nm-settings-dbus.property.cdma.password">password</entry><entry align="left">string</entry><entry align="left"/><entry>The password used to authenticate with the network, if required. Many providers do not require a password, or accept any password. But if a password is required, it is specified here.</entry></row><row><entry align="left" id="nm-settings-dbus.property.cdma.password-flags">password-flags</entry><entry align="left">NMSettingSecretFlags (uint32)</entry><entry align="left"/><entry>Flags indicating how to handle the "password" property.</entry></row><row><entry align="left" id="nm-settings-dbus.property.cdma.username">username</entry><entry align="left">string</entry><entry align="left"/><entry>The username used to authenticate with the network, if required. Many providers do not require a username, or accept any username. But if a username is required, it is specified here.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>dcb setting</title><para>Data Center Bridging Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.dcb.app-fcoe-flags">app-fcoe-flags</entry><entry align="left">NMSettingDcbFlags (uint32)</entry><entry align="left"/><entry>Specifies the NMSettingDcbFlags for the DCB FCoE application. Flags may be any combination of 0x1 (enable), 0x2 (advertise), and 0x4 (willing).</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-fcoe-mode">app-fcoe-mode</entry><entry align="left">string</entry><entry align="left"/><entry>The FCoE controller mode; either "fabric" or "vn2vn". -Since 1.34, NULL is the default and means "fabric". Before 1.34, NULL was rejected as invalid and the default was "fabric".</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-fcoe-priority">app-fcoe-priority</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>The highest User Priority (0 - 7) which FCoE frames should use, or -1 for default priority. Only used when the "app-fcoe-flags" property includes the 0x1 (enable) flag.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-fip-flags">app-fip-flags</entry><entry align="left">NMSettingDcbFlags (uint32)</entry><entry align="left"/><entry>Specifies the NMSettingDcbFlags for the DCB FIP application. Flags may be any combination of 0x1 (enable), 0x2 (advertise), and 0x4 (willing).</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-fip-priority">app-fip-priority</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>The highest User Priority (0 - 7) which FIP frames should use, or -1 for default priority. Only used when the "app-fip-flags" property includes the 0x1 (enable) flag.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-iscsi-flags">app-iscsi-flags</entry><entry align="left">NMSettingDcbFlags (uint32)</entry><entry align="left"/><entry>Specifies the NMSettingDcbFlags for the DCB iSCSI application. Flags may be any combination of 0x1 (enable), 0x2 (advertise), and 0x4 (willing).</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-iscsi-priority">app-iscsi-priority</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>The highest User Priority (0 - 7) which iSCSI frames should use, or -1 for default priority. Only used when the "app-iscsi-flags" property includes the 0x1 (enable) flag.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-bandwidth">priority-bandwidth</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 uint values, where the array index corresponds to the User Priority (0 - 7) and the value indicates the percentage of bandwidth of the priority's assigned group that the priority may use. The sum of all percentages for priorities which belong to the same group must total 100 percents.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-flow-control">priority-flow-control</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 boolean values, where the array index corresponds to the User Priority (0 - 7) and the value indicates whether or not the corresponding priority should transmit priority pause.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-flow-control-flags">priority-flow-control-flags</entry><entry align="left">NMSettingDcbFlags (uint32)</entry><entry align="left"/><entry>Specifies the NMSettingDcbFlags for DCB Priority Flow Control (PFC). Flags may be any combination of 0x1 (enable), 0x2 (advertise), and 0x4 (willing).</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-group-bandwidth">priority-group-bandwidth</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 uint values, where the array index corresponds to the Priority Group ID (0 - 7) and the value indicates the percentage of link bandwidth allocated to that group. Allowed values are 0 - 100, and the sum of all values must total 100 percents.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-group-flags">priority-group-flags</entry><entry align="left">NMSettingDcbFlags (uint32)</entry><entry align="left"/><entry>Specifies the NMSettingDcbFlags for DCB Priority Groups. Flags may be any combination of 0x1 (enable), 0x2 (advertise), and 0x4 (willing).</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-group-id">priority-group-id</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 uint values, where the array index corresponds to the User Priority (0 - 7) and the value indicates the Priority Group ID. Allowed Priority Group ID values are 0 - 7 or 15 for the unrestricted group.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-strict-bandwidth">priority-strict-bandwidth</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 boolean values, where the array index corresponds to the User Priority (0 - 7) and the value indicates whether or not the priority may use all of the bandwidth allocated to its assigned group.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-traffic-class">priority-traffic-class</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 uint values, where the array index corresponds to the User Priority (0 - 7) and the value indicates the traffic class (0 - 7) to which the priority is mapped.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>dummy setting</title><para>Dummy Link Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody/></tgroup></informaltable></refsect2><refsect2><title>ethtool setting</title><para>Ethtool Ethernet Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody/></tgroup></informaltable></refsect2><refsect2><title>generic setting</title><para>Generic Link Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody/></tgroup></informaltable></refsect2><refsect2><title>gsm setting</title><para>GSM-based Mobile Broadband Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.gsm.apn">apn</entry><entry align="left">string</entry><entry align="left"/><entry>The GPRS Access Point Name specifying the APN used when establishing a data session with the GSM-based network. The APN often determines how the user will be billed for their network usage and whether the user has access to the Internet or just a provider-specific walled-garden, so it is important to use the correct APN for the user's mobile broadband plan. The APN may only be composed of the characters a-z, 0-9, ., and - per GSM 03.60 Section 14.9. +Since 1.34, NULL is the default and means "fabric". Before 1.34, NULL was rejected as invalid and the default was "fabric".</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-fcoe-priority">app-fcoe-priority</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>The highest User Priority (0 - 7) which FCoE frames should use, or -1 for default priority. Only used when the "app-fcoe-flags" property includes the 0x1 (enable) flag.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-fip-flags">app-fip-flags</entry><entry align="left">NMSettingDcbFlags (uint32)</entry><entry align="left"/><entry>Specifies the NMSettingDcbFlags for the DCB FIP application. Flags may be any combination of 0x1 (enable), 0x2 (advertise), and 0x4 (willing).</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-fip-priority">app-fip-priority</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>The highest User Priority (0 - 7) which FIP frames should use, or -1 for default priority. Only used when the "app-fip-flags" property includes the 0x1 (enable) flag.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-iscsi-flags">app-iscsi-flags</entry><entry align="left">NMSettingDcbFlags (uint32)</entry><entry align="left"/><entry>Specifies the NMSettingDcbFlags for the DCB iSCSI application. Flags may be any combination of 0x1 (enable), 0x2 (advertise), and 0x4 (willing).</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.app-iscsi-priority">app-iscsi-priority</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>The highest User Priority (0 - 7) which iSCSI frames should use, or -1 for default priority. Only used when the "app-iscsi-flags" property includes the 0x1 (enable) flag.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-bandwidth">priority-bandwidth</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 uint values, where the array index corresponds to the User Priority (0 - 7) and the value indicates the percentage of bandwidth of the priority's assigned group that the priority may use. The sum of all percentages for priorities which belong to the same group must total 100 percents.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-flow-control">priority-flow-control</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 boolean values, where the array index corresponds to the User Priority (0 - 7) and the value indicates whether or not the corresponding priority should transmit priority pause.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-flow-control-flags">priority-flow-control-flags</entry><entry align="left">NMSettingDcbFlags (uint32)</entry><entry align="left"/><entry>Specifies the NMSettingDcbFlags for DCB Priority Flow Control (PFC). Flags may be any combination of 0x1 (enable), 0x2 (advertise), and 0x4 (willing).</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-group-bandwidth">priority-group-bandwidth</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 uint values, where the array index corresponds to the Priority Group ID (0 - 7) and the value indicates the percentage of link bandwidth allocated to that group. Allowed values are 0 - 100, and the sum of all values must total 100 percents.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-group-flags">priority-group-flags</entry><entry align="left">NMSettingDcbFlags (uint32)</entry><entry align="left"/><entry>Specifies the NMSettingDcbFlags for DCB Priority Groups. Flags may be any combination of 0x1 (enable), 0x2 (advertise), and 0x4 (willing).</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-group-id">priority-group-id</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 uint values, where the array index corresponds to the User Priority (0 - 7) and the value indicates the Priority Group ID. Allowed Priority Group ID values are 0 - 7 or 15 for the unrestricted group.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-strict-bandwidth">priority-strict-bandwidth</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 boolean values, where the array index corresponds to the User Priority (0 - 7) and the value indicates whether or not the priority may use all of the bandwidth allocated to its assigned group.</entry></row><row><entry align="left" id="nm-settings-dbus.property.dcb.priority-traffic-class">priority-traffic-class</entry><entry align="left">array of uint32</entry><entry align="left"/><entry>An array of 8 uint values, where the array index corresponds to the User Priority (0 - 7) and the value indicates the traffic class (0 - 7) to which the priority is mapped.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>dummy setting</title><para>Dummy Link Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody/></tgroup></informaltable></refsect2><refsect2><title>ethtool setting</title><para>Ethtool Ethernet Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody/></tgroup></informaltable></refsect2><refsect2><title>generic setting</title><para>Generic Link Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.generic.device-handler">device-handler</entry><entry align="left">string</entry><entry align="left"/><entry>Name of the device handler that will be invoked to add and delete the device for this connection. The name can only contain ASCII alphanumeric characters and '-', '_', '.'. It cannot start with '.'. + +See the NetworkManager-dispatcher(8) man page for more details about how to write the device handler. + +By setting this property the generic connection becomes "virtual", meaning that it can be activated without an existing device; the device will be created at the time the connection is started by invoking the device-handler.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>gsm setting</title><para>GSM-based Mobile Broadband Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.gsm.apn">apn</entry><entry align="left">string</entry><entry align="left"/><entry>The GPRS Access Point Name specifying the APN used when establishing a data session with the GSM-based network. The APN often determines how the user will be billed for their network usage and whether the user has access to the Internet or just a provider-specific walled-garden, so it is important to use the correct APN for the user's mobile broadband plan. The APN may only be composed of the characters a-z, 0-9, ., and - per GSM 03.60 Section 14.9. If the APN is unset (the default) then it may be detected based on "auto-config" setting. The property can be explicitly set to the empty string to prevent that and use no APN.</entry></row><row><entry align="left" id="nm-settings-dbus.property.gsm.auto-config">auto-config</entry><entry align="left">boolean</entry><entry align="left">FALSE</entry><entry>When TRUE, the settings such as APN, username, or password will default to values that match the network the modem will register to in the Mobile Broadband Provider database.</entry></row><row><entry align="left" id="nm-settings-dbus.property.gsm.device-id">device-id</entry><entry align="left">string</entry><entry align="left"/><entry>The device unique identifier (as given by the WWAN management service) which this connection applies to. If given, the connection will only apply to the specified device.</entry></row><row><entry align="left" id="nm-settings-dbus.property.gsm.home-only">home-only</entry><entry align="left">boolean</entry><entry align="left">FALSE</entry><entry>When TRUE, only connections to the home network will be allowed. Connections to roaming networks will not be made.</entry></row><row><entry align="left" id="nm-settings-dbus.property.gsm.initial-eps-bearer-apn">initial-eps-bearer-apn</entry><entry align="left">string</entry><entry align="left"/><entry>For LTE modems, this sets the APN for the initial EPS bearer that is set up when attaching to the network. Setting this parameter implies initial-eps-bearer-configure to be TRUE.</entry></row><row><entry align="left" id="nm-settings-dbus.property.gsm.initial-eps-bearer-configure">initial-eps-bearer-configure</entry><entry align="left">boolean</entry><entry align="left">FALSE</entry><entry>For LTE modems, this setting determines whether the initial EPS bearer shall be configured when bringing up the connection. It is inferred TRUE if initial-eps-bearer-apn is set.</entry></row><row><entry align="left" id="nm-settings-dbus.property.gsm.mtu">mtu</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple frames.</entry></row><row><entry align="left" id="nm-settings-dbus.property.gsm.network-id">network-id</entry><entry align="left">string</entry><entry align="left"/><entry>The Network ID (GSM LAI format, ie MCC-MNC) to force specific network registration. If the Network ID is specified, NetworkManager will attempt to force the device to register only on the specified network. This can be used to ensure that the device does not roam when direct roaming control of the device is not otherwise possible.</entry></row><row><entry align="left" id="nm-settings-dbus.property.gsm.number">number</entry><entry align="left">string</entry><entry align="left"/><entry>Legacy setting that used to help establishing PPP data sessions for GSM-based modems. @@ -360,7 +364,13 @@ If the table setting is left at zero, it is eligible to be overwritten via globa Policy routing disabled means that NetworkManager will add all routes to the main table (except static routes that explicitly configure a different table). Additionally, NetworkManager will not delete any extraneous routes from tables except the main table. This is to preserve backward compatibility for users who manage routing tables outside of NetworkManager.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ipv6.routes">routes</entry><entry align="left">array of legacy IPv6 route struct (a(ayuayu))</entry><entry align="left"/><entry>Deprecated in favor of the 'route-data' property, but this can be used for backward-compatibility with older daemons. Note that if you send this property the daemon will ignore 'route-data'. Array of IPv6 route structures. Each IPv6 route structure is composed of an IPv6 address, a prefix length (0 - 128), an IPv6 next hop address (which may be zeroed out if there is no next hop), and a metric. If the metric is 0, NM will choose an appropriate default metric for the device.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ipv6.routing-rules">routing-rules</entry><entry align="left">array of 'a{sv}'</entry><entry align="left"/><entry>Array of dictionaries for routing rules. Each routing rule supports the following options: action (y), dport-end (q), dport-start (q), family (i), from (s), from-len (y), fwmark (u), fwmask (u), iifname (s), invert (b), ipproto (s), oifname (s), priority (u), sport-end (q), sport-start (q), supress-prefixlength (i), table (u), to (s), tos (y), to-len (y), range-end (u), range-start (u).</entry></row><row><entry align="left" id="nm-settings-dbus.property.ipv6.token">token</entry><entry align="left">string</entry><entry align="left"/><entry>Configure the token for draft-chown-6man-tokenised-ipv6-identifiers-02 IPv6 tokenized interface identifiers. Useful with eui64 addr-gen-mode. -When set, the token is used as IPv6 interface identifier instead of the hardware address. This only applies to addresses from stateless autoconfiguration, not to IPv6 link local addresses.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>ip-tunnel setting</title><para>IP Tunneling Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.encapsulation-limit">encapsulation-limit</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>How many additional levels of encapsulation are permitted to be prepended to packets. This property applies only to IPv6 tunnels. To disable this option, add 0x1 (ip6-ign-encap-limit) to ip-tunnel flags.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.flags">flags</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>Tunnel flags. Currently, the following values are supported: 0x1 (ip6-ign-encap-limit), 0x2 (ip6-use-orig-tclass), 0x4 (ip6-use-orig-flowlabel), 0x8 (ip6-mip6-dev), 0x10 (ip6-rcv-dscp-copy), 0x20 (ip6-use-orig-fwmark). They are valid only for IPv6 tunnels.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.flow-label">flow-label</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The flow label to assign to tunnel packets. This property applies only to IPv6 tunnels.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.fwmark">fwmark</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The fwmark value to assign to tunnel packets. This property can be set to a non zero value only on VTI and VTI6 tunnels.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.input-key">input-key</entry><entry align="left">string</entry><entry align="left"/><entry>The key used for tunnel input packets; the property is valid only for certain tunnel modes (GRE, IP6GRE). If empty, no key is used.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.local">local</entry><entry align="left">string</entry><entry align="left"/><entry>The local endpoint of the tunnel; the value can be empty, otherwise it must contain an IPv4 or IPv6 address.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.mode">mode</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The tunneling mode. Valid values: 1 (ipip), 2 (gre), 3 (sit), 4 (isatap), 5 (vti), 6 (ip6ip6), 7 (ipip6), 8 (ip6gre), 9 (vti6), 10 (gretap) and 11 (ip6gretap)</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.mtu">mtu</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple fragments.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.output-key">output-key</entry><entry align="left">string</entry><entry align="left"/><entry>The key used for tunnel output packets; the property is valid only for certain tunnel modes (GRE, IP6GRE). If empty, no key is used.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.parent">parent</entry><entry align="left">string</entry><entry align="left"/><entry>If given, specifies the parent interface name or parent connection UUID the new device will be bound to so that tunneled packets will only be routed via that interface.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.path-mtu-discovery">path-mtu-discovery</entry><entry align="left">boolean</entry><entry align="left">TRUE</entry><entry>Whether to enable Path MTU Discovery on this tunnel.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.remote">remote</entry><entry align="left">string</entry><entry align="left"/><entry>The remote endpoint of the tunnel; the value must contain an IPv4 or IPv6 address.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.tos">tos</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The type of service (IPv4) or traffic class (IPv6) field to be set on tunneled packets.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.ttl">ttl</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The TTL to assign to tunneled packets. 0 is a special value meaning that packets inherit the TTL value.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>macsec setting</title><para>MACSec Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.macsec.encrypt">encrypt</entry><entry align="left">boolean</entry><entry align="left">TRUE</entry><entry>Whether the transmitted traffic must be encrypted.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.mka-cak">mka-cak</entry><entry align="left">string</entry><entry align="left"/><entry>The pre-shared CAK (Connectivity Association Key) for MACsec Key Agreement. Must be a string of 32 hexadecimal characters.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.mka-cak-flags">mka-cak-flags</entry><entry align="left">NMSettingSecretFlags (uint32)</entry><entry align="left"/><entry>Flags indicating how to handle the "mka-cak" property.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.mka-ckn">mka-ckn</entry><entry align="left">string</entry><entry align="left"/><entry>The pre-shared CKN (Connectivity-association Key Name) for MACsec Key Agreement. Must be a string of hexadecimal characters with a even length between 2 and 64.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.mode">mode</entry><entry align="left">int32</entry><entry align="left">0</entry><entry>Specifies how the CAK (Connectivity Association Key) for MKA (MACsec Key Agreement) is obtained.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.parent">parent</entry><entry align="left">string</entry><entry align="left"/><entry>If given, specifies the parent interface name or parent connection UUID from which this MACSEC interface should be created. If this property is not specified, the connection must contain an "802-3-ethernet" setting with a "mac-address" property.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.port">port</entry><entry align="left">int32</entry><entry align="left">1</entry><entry>The port component of the SCI (Secure Channel Identifier), between 1 and 65534.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.send-sci">send-sci</entry><entry align="left">boolean</entry><entry align="left">TRUE</entry><entry>Specifies whether the SCI (Secure Channel Identifier) is included in every packet.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.validation">validation</entry><entry align="left">int32</entry><entry align="left">2</entry><entry>Specifies the validation mode for incoming frames.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>macvlan setting</title><para>MAC VLAN Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.macvlan.mode">mode</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The macvlan mode, which specifies the communication mechanism between multiple macvlans on the same lower device.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macvlan.parent">parent</entry><entry align="left">string</entry><entry align="left"/><entry>If given, specifies the parent interface name or parent connection UUID from which this MAC-VLAN interface should be created. If this property is not specified, the connection must contain an "802-3-ethernet" setting with a "mac-address" property.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macvlan.promiscuous">promiscuous</entry><entry align="left">boolean</entry><entry align="left">TRUE</entry><entry>Whether the interface should be put in promiscuous mode.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macvlan.tap">tap</entry><entry align="left">boolean</entry><entry align="left">FALSE</entry><entry>Whether the interface should be a MACVTAP.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>match setting</title><para>Match settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.match.driver">driver</entry><entry align="left">array of string</entry><entry align="left"/><entry>A list of driver names to match. Each element is a shell wildcard pattern. +When set, the token is used as IPv6 interface identifier instead of the hardware address. This only applies to addresses from stateless autoconfiguration, not to IPv6 link local addresses.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>ip-tunnel setting</title><para>IP Tunneling Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.encapsulation-limit">encapsulation-limit</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>How many additional levels of encapsulation are permitted to be prepended to packets. This property applies only to IPv6 tunnels. To disable this option, add 0x1 (ip6-ign-encap-limit) to ip-tunnel flags.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.flags">flags</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>Tunnel flags. Currently, the following values are supported: 0x1 (ip6-ign-encap-limit), 0x2 (ip6-use-orig-tclass), 0x4 (ip6-use-orig-flowlabel), 0x8 (ip6-mip6-dev), 0x10 (ip6-rcv-dscp-copy), 0x20 (ip6-use-orig-fwmark). They are valid only for IPv6 tunnels.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.flow-label">flow-label</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The flow label to assign to tunnel packets. This property applies only to IPv6 tunnels.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.fwmark">fwmark</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The fwmark value to assign to tunnel packets. This property can be set to a non zero value only on VTI and VTI6 tunnels.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.input-key">input-key</entry><entry align="left">string</entry><entry align="left"/><entry>The key used for tunnel input packets; the property is valid only for certain tunnel modes (GRE, IP6GRE). If empty, no key is used.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.local">local</entry><entry align="left">string</entry><entry align="left"/><entry>The local endpoint of the tunnel; the value can be empty, otherwise it must contain an IPv4 or IPv6 address.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.mode">mode</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The tunneling mode. Valid values: 1 (ipip), 2 (gre), 3 (sit), 4 (isatap), 5 (vti), 6 (ip6ip6), 7 (ipip6), 8 (ip6gre), 9 (vti6), 10 (gretap) and 11 (ip6gretap)</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.mtu">mtu</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple fragments.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.output-key">output-key</entry><entry align="left">string</entry><entry align="left"/><entry>The key used for tunnel output packets; the property is valid only for certain tunnel modes (GRE, IP6GRE). If empty, no key is used.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.parent">parent</entry><entry align="left">string</entry><entry align="left"/><entry>If given, specifies the parent interface name or parent connection UUID the new device will be bound to so that tunneled packets will only be routed via that interface.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.path-mtu-discovery">path-mtu-discovery</entry><entry align="left">boolean</entry><entry align="left">TRUE</entry><entry>Whether to enable Path MTU Discovery on this tunnel.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.remote">remote</entry><entry align="left">string</entry><entry align="left"/><entry>The remote endpoint of the tunnel; the value must contain an IPv4 or IPv6 address.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.tos">tos</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The type of service (IPv4) or traffic class (IPv6) field to be set on tunneled packets.</entry></row><row><entry align="left" id="nm-settings-dbus.property.ip-tunnel.ttl">ttl</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The TTL to assign to tunneled packets. 0 is a special value meaning that packets inherit the TTL value.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>macsec setting</title><para>MACSec Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.macsec.encrypt">encrypt</entry><entry align="left">boolean</entry><entry align="left">TRUE</entry><entry>Whether the transmitted traffic must be encrypted.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.mka-cak">mka-cak</entry><entry align="left">string</entry><entry align="left"/><entry>The pre-shared CAK (Connectivity Association Key) for MACsec Key Agreement. Must be a string of 32 hexadecimal characters.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.mka-cak-flags">mka-cak-flags</entry><entry align="left">NMSettingSecretFlags (uint32)</entry><entry align="left"/><entry>Flags indicating how to handle the "mka-cak" property.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.mka-ckn">mka-ckn</entry><entry align="left">string</entry><entry align="left"/><entry>The pre-shared CKN (Connectivity-association Key Name) for MACsec Key Agreement. Must be a string of hexadecimal characters with a even length between 2 and 64.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.mode">mode</entry><entry align="left">int32</entry><entry align="left">0</entry><entry>Specifies how the CAK (Connectivity Association Key) for MKA (MACsec Key Agreement) is obtained.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.offload">offload</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>Specifies the MACsec offload mode. + +0 (off) disables MACsec offload. + +1 (phy) and 2 (mac) request offload respectively to the PHY or to the MAC; if the selected mode is not available, the connection will fail. + +-1 (default) uses the global default value specified in NetworkManager configuration; if no global default is defined, the built-in default is 0 (off).</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.parent">parent</entry><entry align="left">string</entry><entry align="left"/><entry>If given, specifies the parent interface name or parent connection UUID from which this MACSEC interface should be created. If this property is not specified, the connection must contain an "802-3-ethernet" setting with a "mac-address" property.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.port">port</entry><entry align="left">int32</entry><entry align="left">1</entry><entry>The port component of the SCI (Secure Channel Identifier), between 1 and 65534.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.send-sci">send-sci</entry><entry align="left">boolean</entry><entry align="left">TRUE</entry><entry>Specifies whether the SCI (Secure Channel Identifier) is included in every packet.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macsec.validation">validation</entry><entry align="left">int32</entry><entry align="left">2</entry><entry>Specifies the validation mode for incoming frames.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>macvlan setting</title><para>MAC VLAN Settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.macvlan.mode">mode</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The macvlan mode, which specifies the communication mechanism between multiple macvlans on the same lower device.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macvlan.parent">parent</entry><entry align="left">string</entry><entry align="left"/><entry>If given, specifies the parent interface name or parent connection UUID from which this MAC-VLAN interface should be created. If this property is not specified, the connection must contain an "802-3-ethernet" setting with a "mac-address" property.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macvlan.promiscuous">promiscuous</entry><entry align="left">boolean</entry><entry align="left">TRUE</entry><entry>Whether the interface should be put in promiscuous mode.</entry></row><row><entry align="left" id="nm-settings-dbus.property.macvlan.tap">tap</entry><entry align="left">boolean</entry><entry align="left">FALSE</entry><entry>Whether the interface should be a MACVTAP.</entry></row></tbody></tgroup></informaltable></refsect2><refsect2><title>match setting</title><para>Match settings.</para><informaltable><tgroup cols="4"><thead><row><entry>Key Name</entry><entry>Value Type</entry><entry>Default Value</entry><entry>Value Description</entry></row></thead><tbody><row><entry align="left" id="nm-settings-dbus.property.match.driver">driver</entry><entry align="left">array of string</entry><entry align="left"/><entry>A list of driver names to match. Each element is a shell wildcard pattern. See NMSettingMatch:interface-name for how special characters '|', '&', '!' and '\\' are used for optional and mandatory matches and inverting the pattern.</entry></row><row><entry align="left" id="nm-settings-dbus.property.match.interface-name">interface-name</entry><entry align="left">array of string</entry><entry align="left"/><entry>A list of interface names to match. Each element is a shell wildcard pattern. @@ -384,7 +394,17 @@ If set to 1 (true), the kernel will try to bind VFs to a compatible driver and i If set to 0 (false), VFs will not be claimed and no network interfaces will be created for them. -When set to -1 (default), the global default is used; in case the global default is unspecified it is assumed to be 1 (true).</entry></row><row><entry align="left" id="nm-settings-dbus.property.sriov.total-vfs">total-vfs</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The total number of virtual functions to create. +When set to -1 (default), the global default is used; in case the global default is unspecified it is assumed to be 1 (true).</entry></row><row><entry align="left" id="nm-settings-dbus.property.sriov.eswitch-encap-mode">eswitch-encap-mode</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>Select the eswitch encapsulation support. + +Currently it's only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF. + +If set to -1 (preserve) (default) the eswitch encap-mode won't be modified by NetworkManager.</entry></row><row><entry align="left" id="nm-settings-dbus.property.sriov.eswitch-inline-mode">eswitch-inline-mode</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>Select the eswitch inline-mode of the device. Some HWs need the VF driver to put part of the packet headers on the TX descriptor so the e-switch can do proper matching and steering. + +Currently it's only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF. + +If set to -1 (preserve) (default) the eswitch inline-mode won't be modified by NetworkManager.</entry></row><row><entry align="left" id="nm-settings-dbus.property.sriov.eswitch-mode">eswitch-mode</entry><entry align="left">int32</entry><entry align="left">-1</entry><entry>Select the eswitch mode of the device. Currently it's only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF. + +If set to -1 (preserve) (default) the eswitch mode won't be modified by NetworkManager.</entry></row><row><entry align="left" id="nm-settings-dbus.property.sriov.total-vfs">total-vfs</entry><entry align="left">uint32</entry><entry align="left">0</entry><entry>The total number of virtual functions to create. Note that when the sriov setting is present NetworkManager enforces the number of virtual functions on the interface (also when it is zero) during activation and resets it upon deactivation. To prevent any changes to SR-IOV parameters don't add a sriov setting to the connection.</entry></row><row><entry align="left" id="nm-settings-dbus.property.sriov.vfs">vfs</entry><entry align="left">array of vardict</entry><entry align="left"/><entry>Array of virtual function descriptors. diff --git a/man/nm-settings-ifcfg-rh.5 b/man/nm-settings-ifcfg-rh.5 index 40af6afb..9685f866 100644 --- a/man/nm-settings-ifcfg-rh.5 +++ b/man/nm-settings-ifcfg-rh.5 @@ -2,12 +2,12 @@ .\" Title: nm-settings-ifcfg-rh .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Configuration -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NM\-SETTINGS\-IFCFG\-RH" "5" "" "NetworkManager 1\&.45\&.91" "Configuration" +.TH "NM\-SETTINGS\-IFCFG\-RH" "5" "" "NetworkManager 1\&.46\&.0" "Configuration" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/man/nm-settings-ifcfg-rh.xml b/man/nm-settings-ifcfg-rh.xml index 2d583774..a7f99eb8 100644 --- a/man/nm-settings-ifcfg-rh.xml +++ b/man/nm-settings-ifcfg-rh.xml @@ -1,6 +1,6 @@ <?xml version="1.0"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> -<refentry id="nm-settings-ifcfg-rh"><refentryinfo><title>nm-settings-ifcfg-rh</title><author>NetworkManager developers</author></refentryinfo><refmeta><refentrytitle>nm-settings-ifcfg-rh</refentrytitle><manvolnum>5</manvolnum><refmiscinfo class="source">NetworkManager</refmiscinfo><refmiscinfo class="manual">Configuration</refmiscinfo><refmiscinfo class="version">1.45.91</refmiscinfo></refmeta><refnamediv><refname>nm-settings-ifcfg-rh</refname><refpurpose>Description of <emphasis>ifcfg-rh</emphasis> settings plugin</refpurpose></refnamediv><refsect1 id="description"><title>Description</title><para> +<refentry id="nm-settings-ifcfg-rh"><refentryinfo><title>nm-settings-ifcfg-rh</title><author>NetworkManager developers</author></refentryinfo><refmeta><refentrytitle>nm-settings-ifcfg-rh</refentrytitle><manvolnum>5</manvolnum><refmiscinfo class="source">NetworkManager</refmiscinfo><refmiscinfo class="manual">Configuration</refmiscinfo><refmiscinfo class="version">1.46.0</refmiscinfo></refmeta><refnamediv><refname>nm-settings-ifcfg-rh</refname><refpurpose>Description of <emphasis>ifcfg-rh</emphasis> settings plugin</refpurpose></refnamediv><refsect1 id="description"><title>Description</title><para> NetworkManager is based on the concept of connection profiles that contain network configuration (see <citerefentry><refentrytitle>nm-settings-nmcli</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details). The profiles can be stored in various formats. NetworkManager uses plugins for reading and writing diff --git a/man/nm-settings-keyfile.5 b/man/nm-settings-keyfile.5 index 40ec1a65..1b2bf22f 100644 --- a/man/nm-settings-keyfile.5 +++ b/man/nm-settings-keyfile.5 @@ -2,12 +2,12 @@ .\" Title: nm-settings-keyfile .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Configuration -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NM\-SETTINGS\-KEYFILE" "5" "" "NetworkManager 1\&.45\&.91" "Configuration" +.TH "NM\-SETTINGS\-KEYFILE" "5" "" "NetworkManager 1\&.46\&.0" "Configuration" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/man/nm-settings-keyfile.xml b/man/nm-settings-keyfile.xml index 2eb8d48c..ac4d9375 100644 --- a/man/nm-settings-keyfile.xml +++ b/man/nm-settings-keyfile.xml @@ -1,6 +1,6 @@ <?xml version="1.0"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> -<refentry id="nm-settings-keyfile"><refentryinfo><title>nm-settings-keyfile</title><author>NetworkManager developers</author></refentryinfo><refmeta><refentrytitle>nm-settings-keyfile</refentrytitle><manvolnum>5</manvolnum><refmiscinfo class="source">NetworkManager</refmiscinfo><refmiscinfo class="manual">Configuration</refmiscinfo><refmiscinfo class="version">1.45.91</refmiscinfo></refmeta><refnamediv><refname>nm-settings-keyfile</refname><refpurpose>Description of <emphasis>keyfile</emphasis> settings plugin</refpurpose></refnamediv><refsect1 id="description"><title>Description</title><para> +<refentry id="nm-settings-keyfile"><refentryinfo><title>nm-settings-keyfile</title><author>NetworkManager developers</author></refentryinfo><refmeta><refentrytitle>nm-settings-keyfile</refentrytitle><manvolnum>5</manvolnum><refmiscinfo class="source">NetworkManager</refmiscinfo><refmiscinfo class="manual">Configuration</refmiscinfo><refmiscinfo class="version">1.46.0</refmiscinfo></refmeta><refnamediv><refname>nm-settings-keyfile</refname><refpurpose>Description of <emphasis>keyfile</emphasis> settings plugin</refpurpose></refnamediv><refsect1 id="description"><title>Description</title><para> NetworkManager is based on the concept of connection profiles that contain network configuration (see <citerefentry><refentrytitle>nm-settings-nmcli</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details). The profiles can be stored in various formats. NetworkManager uses plugins for reading and writing diff --git a/man/nm-settings-nmcli.5 b/man/nm-settings-nmcli.5 index 8285c2df..d33da534 100644 --- a/man/nm-settings-nmcli.5 +++ b/man/nm-settings-nmcli.5 @@ -2,12 +2,12 @@ .\" Title: nm-settings-nmcli .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Configuration -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NM\-SETTINGS\-NMCLI" "5" "" "NetworkManager 1\&.45\&.91" "Configuration" +.TH "NM\-SETTINGS\-NMCLI" "5" "" "NetworkManager 1\&.46\&.0" "Configuration" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -2098,6 +2098,22 @@ Format: integer .sp Valid values: 0 \- 4294967295 .RE +.SS "generic setting" +.PP +Generic Link Settings\&. +.PP +Properties: +.PP +\fBgeneric\&.device\-handler\fR +.RS 4 +Name of the device handler that will be invoked to add and delete the device for this connection\&. The name can only contain ASCII alphanumeric characters and \*(Aq\-\*(Aq, \*(Aq_\*(Aq, \*(Aq\&.\*(Aq\&. It cannot start with \*(Aq\&.\*(Aq\&. +.sp +See the NetworkManager\-dispatcher(8) man page for more details about how to write the device handler\&. +.sp +By setting this property the generic connection becomes "virtual", meaning that it can be activated without an existing device; the device will be created at the time the connection is started by invoking the device\-handler\&. +.sp +Format: string +.RE .SS "gsm setting" .PP GSM\-based Mobile Broadband Settings\&. @@ -3842,6 +3858,21 @@ Format: choice (NMSettingMacsecMode) Valid values: psk (0), eap (1) .RE .PP +\fBmacsec\&.offload\fR +.RS 4 +Specifies the MACsec offload mode\&. +.sp +"off" (0) disables MACsec offload\&. +.sp +"phy" (1) and "mac" (2) request offload respectively to the PHY or to the MAC; if the selected mode is not available, the connection will fail\&. +.sp +"default" (\-1) uses the global default value specified in NetworkManager configuration; if no global default is defined, the built\-in default is "off" (0)\&. +.sp +Format: choice (NMSettingMacsecOffload) +.sp +Valid values: default (\-1), off (0), phy (1), mac (2) +.RE +.PP \fBmacsec\&.parent\fR .RS 4 Alias: dev @@ -4534,6 +4565,43 @@ Format: ternary Valid values: true/yes/on, false/no/off, default/unknown .RE .PP +\fBsriov\&.eswitch\-encap\-mode\fR +.RS 4 +Select the eswitch encapsulation support\&. +.sp +Currently it\*(Aqs only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF\&. +.sp +If set to "preserve" (\-1) (default) the eswitch encap\-mode won\*(Aqt be modified by NetworkManager\&. +.sp +Format: choice (NMSriovEswitchEncapMode) +.sp +Valid values: preserve (\-1), none (0), basic (1) +.RE +.PP +\fBsriov\&.eswitch\-inline\-mode\fR +.RS 4 +Select the eswitch inline\-mode of the device\&. Some HWs need the VF driver to put part of the packet headers on the TX descriptor so the e\-switch can do proper matching and steering\&. +.sp +Currently it\*(Aqs only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF\&. +.sp +If set to "preserve" (\-1) (default) the eswitch inline\-mode won\*(Aqt be modified by NetworkManager\&. +.sp +Format: choice (NMSriovEswitchInlineMode) +.sp +Valid values: preserve (\-1), none (0), link (1), network (2), transport (3) +.RE +.PP +\fBsriov\&.eswitch\-mode\fR +.RS 4 +Select the eswitch mode of the device\&. Currently it\*(Aqs only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF\&. +.sp +If set to "preserve" (\-1) (default) the eswitch mode won\*(Aqt be modified by NetworkManager\&. +.sp +Format: choice (NMSriovEswitchMode) +.sp +Valid values: preserve (\-1), legacy (0), switchdev (1) +.RE +.PP \fBsriov\&.total\-vfs\fR .RS 4 The total number of virtual functions to create\&. diff --git a/man/nm-settings-nmcli.xml b/man/nm-settings-nmcli.xml index 1a18a20c..89130b99 100644 --- a/man/nm-settings-nmcli.xml +++ b/man/nm-settings-nmcli.xml @@ -1,6 +1,6 @@ <?xml version="1.0"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> -<refentry id="nm-settings-nmcli"><refentryinfo><title>nm-settings-nmcli</title><author>NetworkManager developers</author></refentryinfo><refmeta><refentrytitle>nm-settings-nmcli</refentrytitle><manvolnum>5</manvolnum><refmiscinfo class="source">NetworkManager</refmiscinfo><refmiscinfo class="manual">Configuration</refmiscinfo><refmiscinfo class="version">1.45.91</refmiscinfo></refmeta><refnamediv><refname>nm-settings-nmcli</refname><refpurpose>Description of settings and properties of NetworkManager connection profiles for nmcli</refpurpose></refnamediv><refsect1 id="description"><title>Description</title><para> +<refentry id="nm-settings-nmcli"><refentryinfo><title>nm-settings-nmcli</title><author>NetworkManager developers</author></refentryinfo><refmeta><refentrytitle>nm-settings-nmcli</refentrytitle><manvolnum>5</manvolnum><refmiscinfo class="source">NetworkManager</refmiscinfo><refmiscinfo class="manual">Configuration</refmiscinfo><refmiscinfo class="version">1.46.0</refmiscinfo></refmeta><refnamediv><refname>nm-settings-nmcli</refname><refpurpose>Description of settings and properties of NetworkManager connection profiles for nmcli</refpurpose></refnamediv><refsect1 id="description"><title>Description</title><para> NetworkManager is based on a concept of connection profiles, sometimes referred to as connections only. These connection profiles contain a network configuration. When NetworkManager activates a connection profile on a network device the configuration will @@ -503,7 +503,10 @@ Format: integer</para><para> Valid values: 0 - 4294967295</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.ethtool.ring-tx">ethtool.ring-tx</option></term><listitem><para> Format: integer</para><para> - Valid values: 0 - 4294967295</para></listitem></varlistentry></variablelist></para></refsect2><refsect2><title>gsm setting</title><para>GSM-based Mobile Broadband Settings.</para><para> + Valid values: 0 - 4294967295</para></listitem></varlistentry></variablelist></para></refsect2><refsect2><title>generic setting</title><para>Generic Link Settings.</para><para> + Properties: + <variablelist><varlistentry><term><option id="nm-settings-nmcli.property.generic.device-handler">generic.device-handler</option></term><listitem><para>Name of the device handler that will be invoked to add and delete the device for this connection. The name can only contain ASCII alphanumeric characters and '-', '_', '.'. It cannot start with '.'.</para><para>See the NetworkManager-dispatcher(8) man page for more details about how to write the device handler.</para><para>By setting this property the generic connection becomes "virtual", meaning that it can be activated without an existing device; the device will be created at the time the connection is started by invoking the device-handler.</para><para> + Format: string</para></listitem></varlistentry></variablelist></para></refsect2><refsect2><title>gsm setting</title><para>GSM-based Mobile Broadband Settings.</para><para> Properties: <variablelist><varlistentry><term><option id="nm-settings-nmcli.property.gsm.apn">gsm.apn</option></term><listitem><para> Alias: apn</para><para>The GPRS Access Point Name specifying the APN used when establishing a data session with the GSM-based network. The APN often determines how the user will be billed for their network usage and whether the user has access to the Internet or just a provider-specific walled-garden, so it is important to use the correct APN for the user's mobile broadband plan. The APN may only be composed of the characters a-z, 0-9, ., and - per GSM 03.60 Section 14.9.</para><para>If the APN is unset (the default) then it may be detected based on "auto-config" setting. The property can be explicitly set to the empty string to prevent that and use no APN.</para><para> @@ -925,7 +928,9 @@ Example: <literal>priority 5 from 1:2:3::5/128 table 45</literal> Format: string</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.macsec.mode">macsec.mode</option></term><listitem><para> Alias: mode</para><para>Specifies how the CAK (Connectivity Association Key) for MKA (MACsec Key Agreement) is obtained.</para><para> Format: choice (NMSettingMacsecMode)</para><para> - Valid values: psk (0), eap (1)</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.macsec.parent">macsec.parent</option></term><listitem><para> + Valid values: psk (0), eap (1)</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.macsec.offload">macsec.offload</option></term><listitem><para>Specifies the MACsec offload mode.</para><para>"off" (0) disables MACsec offload.</para><para>"phy" (1) and "mac" (2) request offload respectively to the PHY or to the MAC; if the selected mode is not available, the connection will fail.</para><para>"default" (-1) uses the global default value specified in NetworkManager configuration; if no global default is defined, the built-in default is "off" (0).</para><para> + Format: choice (NMSettingMacsecOffload)</para><para> + Valid values: default (-1), off (0), phy (1), mac (2)</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.macsec.parent">macsec.parent</option></term><listitem><para> Alias: dev</para><para>If given, specifies the parent interface name or parent connection UUID from which this MACSEC interface should be created. If this property is not specified, the connection must contain an "802-3-ethernet" setting with a "mac-address" property.</para><para> Format: string</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.macsec.port">macsec.port</option></term><listitem><para> Alias: port</para><para>The port component of the SCI (Secure Channel Identifier), between 1 and 65534.</para><para> @@ -1085,7 +1090,13 @@ Example: <literal>priority 5 from 1:2:3::5/128 table 45</literal> Properties: <variablelist><varlistentry><term><option id="nm-settings-nmcli.property.sriov.autoprobe-drivers">sriov.autoprobe-drivers</option></term><listitem><para>Whether to autoprobe virtual functions by a compatible driver.</para><para>If set to "true" (1), the kernel will try to bind VFs to a compatible driver and if this succeeds a new network interface will be instantiated for each VF.</para><para>If set to "false" (0), VFs will not be claimed and no network interfaces will be created for them.</para><para>When set to "default" (-1), the global default is used; in case the global default is unspecified it is assumed to be "true" (1).</para><para> Format: ternary</para><para> - Valid values: true/yes/on, false/no/off, default/unknown</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.sriov.total-vfs">sriov.total-vfs</option></term><listitem><para>The total number of virtual functions to create.</para><para>Note that when the sriov setting is present NetworkManager enforces the number of virtual functions on the interface (also when it is zero) during activation and resets it upon deactivation. To prevent any changes to SR-IOV parameters don't add a sriov setting to the connection.</para><para> + Valid values: true/yes/on, false/no/off, default/unknown</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.sriov.eswitch-encap-mode">sriov.eswitch-encap-mode</option></term><listitem><para>Select the eswitch encapsulation support.</para><para>Currently it's only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF.</para><para>If set to "preserve" (-1) (default) the eswitch encap-mode won't be modified by NetworkManager.</para><para> + Format: choice (NMSriovEswitchEncapMode)</para><para> + Valid values: preserve (-1), none (0), basic (1)</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.sriov.eswitch-inline-mode">sriov.eswitch-inline-mode</option></term><listitem><para>Select the eswitch inline-mode of the device. Some HWs need the VF driver to put part of the packet headers on the TX descriptor so the e-switch can do proper matching and steering.</para><para>Currently it's only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF.</para><para>If set to "preserve" (-1) (default) the eswitch inline-mode won't be modified by NetworkManager.</para><para> + Format: choice (NMSriovEswitchInlineMode)</para><para> + Valid values: preserve (-1), none (0), link (1), network (2), transport (3)</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.sriov.eswitch-mode">sriov.eswitch-mode</option></term><listitem><para>Select the eswitch mode of the device. Currently it's only supported for PCI PF devices, and only if the eswitch device is managed from the same PCI address than the PF.</para><para>If set to "preserve" (-1) (default) the eswitch mode won't be modified by NetworkManager.</para><para> + Format: choice (NMSriovEswitchMode)</para><para> + Valid values: preserve (-1), legacy (0), switchdev (1)</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.sriov.total-vfs">sriov.total-vfs</option></term><listitem><para>The total number of virtual functions to create.</para><para>Note that when the sriov setting is present NetworkManager enforces the number of virtual functions on the interface (also when it is zero) during activation and resets it upon deactivation. To prevent any changes to SR-IOV parameters don't add a sriov setting to the connection.</para><para> Format: integer</para><para> Valid values: 0 - 4294967295</para></listitem></varlistentry><varlistentry><term><option id="nm-settings-nmcli.property.sriov.vfs">sriov.vfs</option></term><listitem><para>Array of virtual function descriptors.</para><para>Each VF descriptor is a dictionary mapping attribute names to GVariant values. The 'index' entry is mandatory for each VF.</para><para>When represented as string a VF is in the form:</para><para>"INDEX [ATTR=VALUE[ ATTR=VALUE]...]".</para><para>for example:</para><para>"2 mac=00:11:22:33:44:55 spoof-check=true".</para><para>Multiple VFs can be specified using a comma as separator. Currently, the following attributes are supported: mac, spoof-check, trust, min-tx-rate, max-tx-rate, vlans.</para><para>The "vlans" attribute is represented as a semicolon-separated list of VLAN descriptors, where each descriptor has the form</para><para>"ID[.PRIORITY[.PROTO]]".</para><para>PROTO can be either 'q' for 802.1Q (the default) or 'ad' for 802.1ad.</para><para> Format: list of sriov.vfs objects</para></listitem></varlistentry></variablelist></para></refsect2><refsect2><title>tc setting</title><para>Linux Traffic Control Settings.</para><para> diff --git a/man/nmcli-examples.7 b/man/nmcli-examples.7 index 783c0166..68b24fa3 100644 --- a/man/nmcli-examples.7 +++ b/man/nmcli-examples.7 @@ -2,12 +2,12 @@ .\" Title: nmcli-examples .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: Examples -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NMCLI\-EXAMPLES" "7" "" "NetworkManager 1\&.45\&.91" "Examples" +.TH "NMCLI\-EXAMPLES" "7" "" "NetworkManager 1\&.46\&.0" "Examples" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/man/nmcli.1 b/man/nmcli.1 index 12793187..5bd86fb3 100644 --- a/man/nmcli.1 +++ b/man/nmcli.1 @@ -2,12 +2,12 @@ .\" Title: nmcli .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: General Commands Manual -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NMCLI" "1" "" "NetworkManager 1\&.45\&.91" "General Commands Manual" +.TH "NMCLI" "1" "" "NetworkManager 1\&.46\&.0" "General Commands Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/man/nmtui.1 b/man/nmtui.1 index f7c479dc..4d58cadc 100644 --- a/man/nmtui.1 +++ b/man/nmtui.1 @@ -2,12 +2,12 @@ .\" Title: nmtui .\" Author: .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/09/2024 +.\" Date: 02/22/2024 .\" Manual: General Commands Manual -.\" Source: NetworkManager 1.45.91 +.\" Source: NetworkManager 1.46.0 .\" Language: English .\" -.TH "NMTUI" "1" "" "NetworkManager 1\&.45\&.91" "General Commands Manual" +.TH "NMTUI" "1" "" "NetworkManager 1\&.46\&.0" "General Commands Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- |