NMSettingBridge: libnm Reference Manual

## NMSettingBridge NMSettingBridge — Describes connection properties for bridges |

## Functions

NMSetting * | nm_setting_bridge_new ()
const char * | nm_setting_bridge_get_mac_address ()
gboolean | nm_setting_bridge_get_stp ()
guint16 | nm_setting_bridge_get_priority ()
guint16 | nm_setting_bridge_get_forward_delay ()
guint16 | nm_setting_bridge_get_hello_time ()
guint16 | nm_setting_bridge_get_max_age ()
guint32 | nm_setting_bridge_get_ageing_time ()
guint16 | nm_setting_bridge_get_group_forward_mask ()
gboolean | nm_setting_bridge_get_multicast_snooping ()
gboolean | nm_setting_bridge_get_vlan_filtering ()
guint16 | nm_setting_bridge_get_vlan_default_pvid ()
void | nm_setting_bridge_add_vlan ()
guint | nm_setting_bridge_get_num_vlans ()
NMBridgeVlan * | nm_setting_bridge_get_vlan ()
void | nm_setting_bridge_remove_vlan ()
gboolean | nm_setting_bridge_remove_vlan_by_vid ()
void | nm_setting_bridge_clear_vlans ()
NMBridgeVlan * | nm_bridge_vlan_new ()
NMBridgeVlan * | nm_bridge_vlan_ref ()
void | nm_bridge_vlan_unref ()
NMBridgeVlan * | nm_bridge_vlan_new_clone ()
int | nm_bridge_vlan_cmp ()
void | nm_bridge_vlan_seal ()
gboolean | nm_bridge_vlan_is_sealed ()
void | nm_bridge_vlan_set_untagged ()
void | nm_bridge_vlan_set_pvid ()
gboolean | nm_bridge_vlan_get_vid_range ()
gboolean | nm_bridge_vlan_is_untagged ()
gboolean | nm_bridge_vlan_is_pvid ()
char * | nm_bridge_vlan_to_str ()
NMBridgeVlan * | nm_bridge_vlan_from_str ()

## Properties

guint | ageing-time | Read / Write / Construct
guint | forward-delay | Read / Write / Construct
guint | group-forward-mask | Read / Write / Construct
guint | hello-time | Read / Write / Construct
gchar * | mac-address | Read / Write
guint | max-age | Read / Write / Construct
gboolean | multicast-snooping | Read / Write / Construct
guint | priority | Read / Write / Construct
gboolean | stp | Read / Write / Construct
guint | vlan-default-pvid | Read / Write / Construct
gboolean | vlan-filtering | Read / Write / Construct
GPtrArray * | vlans | Read / Write

## Types and Values

#define | NM_SETTING_BRIDGE_SETTING_NAME
#define | NM_SETTING_BRIDGE_MAC_ADDRESS
#define | NM_SETTING_BRIDGE_STP
#define | NM_SETTING_BRIDGE_PRIORITY
#define | NM_SETTING_BRIDGE_FORWARD_DELAY
#define | NM_SETTING_BRIDGE_HELLO_TIME
#define | NM_SETTING_BRIDGE_MAX_AGE
#define | NM_SETTING_BRIDGE_AGEING_TIME
#define | NM_SETTING_BRIDGE_GROUP_FORWARD_MASK
#define | NM_SETTING_BRIDGE_MULTICAST_SNOOPING
#define | NM_SETTING_BRIDGE_VLAN_FILTERING
#define | NM_SETTING_BRIDGE_VLAN_DEFAULT_PVID
#define | NM_SETTING_BRIDGE_VLANS
#define | NM_BRIDGE_VLAN_VID_MIN
#define | NM_BRIDGE_VLAN_VID_MAX
| NMSettingBridge

## Object Hierarchy

        GBoxed
        ╰── NMBridgeVlan
        GObject
        ╰── NMSetting
            ╰── NMSettingBridge

## Description

The NMSettingBridge object is a NMSetting subclass that describes properties necessary for bridging connections.

## Functions

### nm_setting_bridge_new ()

    NMSetting *
    nm_setting_bridge_new (void);

Creates a new NMSettingBridge object with default values.

#### Returns

the new empty NMSettingBridge object.

[transfer full]

### nm_setting_bridge_get_mac_address ()

    const char *
    nm_setting_bridge_get_mac_address (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “mac-address” property of the setting

### nm_setting_bridge_get_stp ()

    gboolean
    nm_setting_bridge_get_stp (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “stp” property of the setting

### nm_setting_bridge_get_priority ()

    guint16
    nm_setting_bridge_get_priority (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “priority” property of the setting

### nm_setting_bridge_get_forward_delay ()

    guint16
    nm_setting_bridge_get_forward_delay (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “forward-delay” property of the setting

### nm_setting_bridge_get_hello_time ()

    guint16
    nm_setting_bridge_get_hello_time (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “hello-time” property of the setting

### nm_setting_bridge_get_max_age ()

    guint16
    nm_setting_bridge_get_max_age (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “max-age” property of the setting

### nm_setting_bridge_get_ageing_time ()

    guint32
    nm_setting_bridge_get_ageing_time (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “ageing-time” property of the setting

### nm_setting_bridge_get_group_forward_mask ()

    guint16
    nm_setting_bridge_get_group_forward_mask
                                   (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “group-forward-mask” property of the setting

Since: 1.10

### nm_setting_bridge_get_multicast_snooping ()

    gboolean
    nm_setting_bridge_get_multicast_snooping
                                   (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “multicast-snooping” property of the setting

Since: 1.2

### nm_setting_bridge_get_vlan_filtering ()

    gboolean
    nm_setting_bridge_get_vlan_filtering (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “vlan-filtering” property of the setting

Since: 1.18

### nm_setting_bridge_get_vlan_default_pvid ()

    guint16
    nm_setting_bridge_get_vlan_default_pvid
                                   (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the “vlan-default-pvid” property of the setting

Since: 1.18

### nm_setting_bridge_add_vlan ()

    void
    nm_setting_bridge_add_vlan (NMSettingBridge *setting,
                                NMBridgeVlan *vlan);

Appends a new vlan and associated information to the setting. The given vlan gets sealed and a reference to it is added.

#### Parameters

setting | the NMSettingBridge |
vlan | the vlan to add |

Since: 1.18

### nm_setting_bridge_get_num_vlans ()

    guint
    nm_setting_bridge_get_num_vlans (NMSettingBridge *setting);

#### Parameters

setting | the NMSettingBridge |

#### Returns

the number of VLANs

Since: 1.18

### nm_setting_bridge_get_vlan ()

    NMBridgeVlan *
    nm_setting_bridge_get_vlan (NMSettingBridge *setting,
                                guint idx);

#### Parameters

setting | the NMSettingBridge |
idx | index number of the VLAN to return |

#### Returns

the VLAN at index `idx` .

[transfer none]

Since: 1.18

### nm_setting_bridge_remove_vlan ()

    void
    nm_setting_bridge_remove_vlan (NMSettingBridge *setting,
                                   guint idx);

Removes the vlan at index `idx` .

#### Parameters

setting | the NMSettingBridge |
idx | index number of the VLAN. |

Since: 1.18

### nm_setting_bridge_remove_vlan_by_vid ()

    gboolean
    nm_setting_bridge_remove_vlan_by_vid (NMSettingBridge *setting,
                                          guint16 vid_start,
                                          guint16 vid_end);

Remove the VLAN with range `vid_start` to `vid_end` . If `vid_end` is zero, it is assumed to be equal to `vid_start` and so the single-id VLAN with id `vid_start` is removed.

#### Parameters

setting | the NMSettingBridge |
vid_start | the vlan start index |
vid_end | the vlan end index |

#### Returns

`TRUE` if the vlan was found and removed; `FALSE` otherwise

Since: 1.18

### nm_setting_bridge_clear_vlans ()

    void
    nm_setting_bridge_clear_vlans (NMSettingBridge *setting);

Removes all configured VLANs.

#### Parameters

setting | the NMSettingBridge |

Since: 1.18

### nm_bridge_vlan_new ()

    NMBridgeVlan *
    nm_bridge_vlan_new (guint16 vid_start,
                        guint16 vid_end);

Creates a new NMBridgeVlan object for the given VLAN id range. Setting `vid_end` to 0 is equivalent to setting it to `vid_start` and creates a single-id VLAN.

#### Parameters

vid_start | the start VLAN id, must be between 1 and 4094. |
vid_end | the end VLAN id, must be 0 or between `vid_start` and 4094. |

#### Returns

the new NMBridgeVlan object.

[transfer full]

Since: 1.18

### nm_bridge_vlan_ref ()

    NMBridgeVlan *
    nm_bridge_vlan_ref (NMBridgeVlan *vlan);

Increases the reference count of the object.

#### Parameters

vlan | the NMBridgeVlan |

#### Returns

the input argument `vlan` object.

Since: 1.18

### nm_bridge_vlan_unref ()

    void
    nm_bridge_vlan_unref (NMBridgeVlan *vlan);

Decreases the reference count of the object. If the reference count reaches zero the object will be destroyed.

#### Parameters

vlan | the NMBridgeVlan |

Since: 1.18

### nm_bridge_vlan_new_clone ()

    NMBridgeVlan *
    nm_bridge_vlan_new_clone (const NMBridgeVlan *vlan);

#### Parameters

vlan | the NMBridgeVlan instance to copy |

#### Returns

a clone of `vlan` . This instance is always unsealed.

[transfer full]

Since: 1.18

### nm_bridge_vlan_cmp ()

    int
    nm_bridge_vlan_cmp (const NMBridgeVlan *a,
                        const NMBridgeVlan *b);

Compare two bridge VLAN objects.

#### Parameters

a | a NMBridgeVlan |
b | another NMBridgeVlan |

#### Returns

zero of the two instances are equivalent or a non-zero integer otherwise. This defines a total ordering over the VLANs. Whether a VLAN is sealed or not does not affect the comparison.

Since: 1.18

### nm_bridge_vlan_seal ()

    void
    nm_bridge_vlan_seal (NMBridgeVlan *vlan);

Seal the NMBridgeVlan instance. Afterwards, it is a bug to call all functions that modify the instance (except ref/unref). A sealed instance cannot be unsealed again, but you can create an unsealed copy with `nm_bridge_vlan_new_clone()`.

#### Parameters

vlan | the NMBridgeVlan instance |

Since: 1.18

### nm_bridge_vlan_is_sealed ()

    gboolean
    nm_bridge_vlan_is_sealed (const NMBridgeVlan *vlan);

#### Parameters

vlan | the NMBridgeVlan instance |

#### Returns

whether `self` is sealed or not.

Since: 1.18

### nm_bridge_vlan_set_untagged ()

    void
    nm_bridge_vlan_set_untagged (NMBridgeVlan *vlan,
                                 gboolean value);

Change the value of the untagged property of the VLAN.

#### Parameters

vlan | the NMBridgeVlan |
value | the new value |

Since: 1.18

### nm_bridge_vlan_set_pvid ()

    void
    nm_bridge_vlan_set_pvid (NMBridgeVlan *vlan,
                             gboolean value);

Change the value of the PVID property of the VLAN. It is invalid to set the value to `TRUE` for non-single-id VLANs.

#### Parameters

vlan | the NMBridgeVlan |
value | the new value |

Since: 1.18

### nm_bridge_vlan_get_vid_range ()

    gboolean
    nm_bridge_vlan_get_vid_range (const NMBridgeVlan *vlan,
                                  guint16 *vid_start,
                                  guint16 *vid_end);

Gets the VLAN id range.

#### Parameters

vlan | the NMBridgeVlan |
vid_start | location to store the VLAN id range start. | [out]
vid_end | location to store the VLAN id range end. | [out]

#### Returns

`TRUE` is the VLAN specifies a range, `FALSE` if it is a single-id VLAN.

Since: 1.18

### nm_bridge_vlan_is_untagged ()

    gboolean
    nm_bridge_vlan_is_untagged (const NMBridgeVlan *vlan);

Returns whether the VLAN is untagged.

#### Parameters

vlan | the NMBridgeVlan |

#### Returns

`TRUE` if the VLAN is untagged, `FALSE` otherwise

Since: 1.18

### nm_bridge_vlan_is_pvid ()

    gboolean
    nm_bridge_vlan_is_pvid (const NMBridgeVlan *vlan);

Returns whether the VLAN is the PVID for the port.

#### Parameters

vlan | the NMBridgeVlan |

#### Returns

`TRUE` if the VLAN is the PVID

Since: 1.18

### nm_bridge_vlan_to_str ()

    char *
    nm_bridge_vlan_to_str (const NMBridgeVlan *vlan,
                           GError **error);

Convert a `NMBridgeVlan` to a string.

#### Parameters

vlan | the `NMBridgeVlan` |
error | location of the error |

#### Returns

formatted string or `NULL`

Since: 1.18

### nm_bridge_vlan_from_str ()

    NMBridgeVlan *
    nm_bridge_vlan_from_str (const char *str,
                             GError **error);

Parses the string representation of the queueing discipline to a `NMBridgeVlan` instance.

#### Parameters

str | the string representation of a bridge VLAN |
error | location of the error |

#### Returns

the `NMBridgeVlan` or `NULL`

Since: 1.18

## Types and Values

### NM_SETTING_BRIDGE_SETTING_NAME

    #define NM_SETTING_BRIDGE_SETTING_NAME "bridge"

### NM_SETTING_BRIDGE_MAC_ADDRESS

    #define NM_SETTING_BRIDGE_MAC_ADDRESS    "mac-address"

### NM_SETTING_BRIDGE_STP

    #define NM_SETTING_BRIDGE_STP            "stp"

### NM_SETTING_BRIDGE_PRIORITY

    #define NM_SETTING_BRIDGE_PRIORITY       "priority"

### NM_SETTING_BRIDGE_FORWARD_DELAY

    #define NM_SETTING_BRIDGE_FORWARD_DELAY  "forward-delay"

### NM_SETTING_BRIDGE_HELLO_TIME

    #define NM_SETTING_BRIDGE_HELLO_TIME     "hello-time"

### NM_SETTING_BRIDGE_MAX_AGE

    #define NM_SETTING_BRIDGE_MAX_AGE        "max-age"

### NM_SETTING_BRIDGE_AGEING_TIME

    #define NM_SETTING_BRIDGE_AGEING_TIME    "ageing-time"

### NM_SETTING_BRIDGE_GROUP_FORWARD_MASK

    #define NM_SETTING_BRIDGE_GROUP_FORWARD_MASK "group-forward-mask"

### NM_SETTING_BRIDGE_MULTICAST_SNOOPING

    #define NM_SETTING_BRIDGE_MULTICAST_SNOOPING "multicast-snooping"

### NM_SETTING_BRIDGE_VLAN_FILTERING

    #define NM_SETTING_BRIDGE_VLAN_FILTERING     "vlan-filtering"

### NM_SETTING_BRIDGE_VLAN_DEFAULT_PVID

    #define NM_SETTING_BRIDGE_VLAN_DEFAULT_PVID  "vlan-default-pvid"

### NM_SETTING_BRIDGE_VLANS

    #define NM_SETTING_BRIDGE_VLANS              "vlans"

### NM_BRIDGE_VLAN_VID_MIN

    #define NM_BRIDGE_VLAN_VID_MIN            1

### NM_BRIDGE_VLAN_VID_MAX

    #define NM_BRIDGE_VLAN_VID_MAX            4094

### NMSettingBridge

    typedef struct _NMSettingBridge NMSettingBridge;

Bridging Settings

## Property Details

### The `“ageing-time”` property

      “ageing-time”              guint

The Ethernet MAC address aging time, in seconds.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Allowed values: <= 1000000

Default value: 300

### The `“forward-delay”` property

      “forward-delay”            guint

The Spanning Tree Protocol (STP) forwarding delay, in seconds.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Allowed values: <= 30

Default value: 15

### The `“group-forward-mask”` property

      “group-forward-mask”       guint

A mask of group addresses to forward. Usually, group addresses in the range from 01:80:C2:00:00:00 to 01:80:C2:00:00:0F are not forwarded according to standards. This property is a mask of 16 bits, each corresponding to a group address in that range that must be forwarded. The mask can't have bits 0, 1 or 2 set because they are used for STP, MAC pause frames and LACP.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Allowed values: <= 65535

Default value: 0

Since: 1.10

### The `“hello-time”` property

      “hello-time”               guint

The Spanning Tree Protocol (STP) hello time, in seconds.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Allowed values: <= 10

Default value: 2

### The `“mac-address”` property

      “mac-address”              gchar *

If specified, the MAC address of bridge. When creating a new bridge, this MAC address will be set.

If this field is left unspecified, the "ethernet.cloned-mac-address" is referred instead to generate the initial MAC address. Note that setting "ethernet.cloned-mac-address" anyway overwrites the MAC address of the bridge later while activating the bridge. Hence, this property is deprecated.

`NMSettingBridge:mac-address` has been deprecated since version 1.12 and should not be used in newly-written code.

Use the ethernet.cloned-mac-address property instead.

Owner: NMSettingBridge

Flags: Read / Write

Default value: NULL

### The `“max-age”` property

      “max-age”                  guint

The Spanning Tree Protocol (STP) maximum message age, in seconds.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Allowed values: <= 40

Default value: 20

### The `“multicast-snooping”` property

      “multicast-snooping”       gboolean

Controls whether IGMP snooping is enabled for this bridge. Note that if snooping was automatically disabled due to hash collisions, the system may refuse to enable the feature until the collisions are resolved.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Default value: TRUE

Since: 1.2

### The `“priority”` property

      “priority”                 guint

Sets the Spanning Tree Protocol (STP) priority for this bridge. Lower values are "better"; the lowest priority bridge will be elected the root bridge.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Allowed values: <= 65535

Default value: 32768

### The `“stp”` property

      “stp”                      gboolean

Controls whether Spanning Tree Protocol (STP) is enabled for this bridge.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Default value: TRUE

### The `“vlan-default-pvid”` property

      “vlan-default-pvid”        guint

The default PVID for the ports of the bridge, that is the VLAN id assigned to incoming untagged frames.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Allowed values: <= 4094

Default value: 1

Since: 1.18

### The `“vlan-filtering”` property

      “vlan-filtering”           gboolean

Control whether VLAN filtering is enabled on the bridge.

Owner: NMSettingBridge

Flags: Read / Write / Construct

Default value: FALSE

Since: 1.18

### The `“vlans”` property

      “vlans”                    GPtrArray *

Array of bridge VLAN objects. In addition to the VLANs specified here, the bridge will also have the default-pvid VLAN configured by the bridge.vlan-default-pvid property.

In nmcli the VLAN list can be specified with the following syntax:

$vid pvid [, $vid pvid]...

where $vid is either a single id between 1 and 4094 or a range, represented as a couple of ids separated by a dash.

[type GPtrArray(NMBridgeVlan)]

Owner: NMSettingBridge

Flags: Read / Write

Since: 1.18