From 2d104a52dbdfe4436711d1aee8634cd15e1c147a Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 27 May 2016 21:06:14 +0200 Subject: man: update the nmcli manual for new connection add syntax It allows us to clean up the nmcli "c add" section considerably. We list the old-fashioned aliases in a separate section that applies to both "nmcli c add" and "nmcli c modify". The section is now nicely cross-linked with nm-settings in HTML rendering. --- man/nm-settings.xsl | 2 +- man/nmcli.xml | 1603 ++++++++++++++------------------------------------- 2 files changed, 433 insertions(+), 1172 deletions(-) diff --git a/man/nm-settings.xsl b/man/nm-settings.xsl index 5876dc576c..03a1076635 100644 --- a/man/nm-settings.xsl +++ b/man/nm-settings.xsl @@ -147,7 +147,7 @@ - + nm-settings.property.. (see for flag values) diff --git a/man/nmcli.xml b/man/nmcli.xml index c500bb0911..a1f0062cd7 100644 --- a/man/nmcli.xml +++ b/man/nmcli.xml @@ -544,9 +544,9 @@ show up down + modify add edit - modify delete monitor reload @@ -811,1156 +811,122 @@ - add - ifname - con-name name - - - - yes - no - - - - - - yes - no + modify + + + + + + + ID + + + option value + [+|-]setting.property value - master master - slave-type type - type type - ARGUMENTS - ip4 addr - gw4 addr - ip6 addr - gw6 addr - - - - [+|-]setting.property - value - - - Add a connection for NetworkManager. Arguments differ according to connection types, see below. - - - - - - - interface to bind the connection to. The connection will only be - applicable to this interface name. A special value of * - can be used for interface-independent connections. The - argument is mandatory for all connection types - except bond, team, bridge and vlan. Note: use quotes around - * to suppress shell expansion. - - - - - - - connection name (when not provided a default name is generated: - <type>[-<ifname>][-<num>]). - - - - - - - whether the connection profile can be automatically activated (default: - yes). - - - - - - - whether the connection should be persistent, i.e. NetworkManager should - store it on disk (default: yes). - - - - - - - master interface name, or connection UUID or ID of master connection - profile. The value can be prefixed with ifname/, - uuid/ or id/ to disambiguate it. - - - - - - - type of master connection. Only required when it can not be inferred - (i.e. the master connection does - not exist yet). - - - - - - - connection type; see below for allowed values. Note that types - , and - create connection - profiles. Their use is discouraged in favor of using a specific type with - option. - - - - - - - addr - addr - mtu - - - - - - - MAC address of the device this connection is locked to. - - - - - - - cloned MAC. - - - - - - - MTU. - - - - - - - - - - SSID - addr - addr - - - - infrastructure - ap - adhoc - - - mtu - - - - - - - SSID. - - - - - - - MAC address of the device this connection is locked to. - - - - - - - cloned MAC. - - - - - - - Wi-Fi network mode. If blank, infrastructure - is assumed. - - - - - - - MTU. - - - - - - - - - - addr - nsp - - - - - - - MAC address of the device this connection is locked to. - - - - - - - Network Service Provider name. - - - - - - - - - - user - passwd - name - mtu - addr - - - - - - - PPPoE username. - - - - - - - Password for the PPPoE username. - - - - - - - PPPoE service name (if required by concentrator). - - - - - - - MTU. - - - - - - - MAC address of the device this connection is locked to. - - - - - - - - - - APN - user - passwd - - - - - - - APN - GSM Access Point Name. - - - - - - - user name. - - - - - - - password. - - - - - - - - - - user - passwd - - - - - - - user name. - - - - - - - password. - - - - - - - - - - addr - mtu - - - - datagram - connected - - - device - key - - - - - - - MAC address of the device this connection is locked to - (InfiniBand MAC is 20 bytes). - - - - - - - MTU. - - - - - - - InfiniBand transport mode. - - - - - - - the interface name of the parent device (if any). - - - - - - - the InfiniBand P_Key (16-bit unsigned integer). - - - - - - - - - - addr - - - - panu - dun-gsm - dun-cdma - - - - - - - - - Bluetooth device address (MAC). - - - - - - - Bluetooth connection type. - - - - - - - - - - device - id - flags - mapping - mapping - mtu - - - - - - - parent device this VLAN is on. - - - - - - - VLAN ID in range 0-4095. - - - - - - - flags. - - - - - - - VLAN ingress priority mapping. - - - - - - - VLAN egress priority mapping. - - - - - - - MTU. - - - - - - - - - - - - - active-backup - balance-xor - broadcast - 802.3ad - balance-tlb - balance-alb - num - - - ifname - num - num - num - num - num - - - - - - - - bonding mode (default: balance-rr). - - - - - - - primary interface name (for active-backup mode). - - - - - - - miimon (default: 100). - - - - - - - downdelay (default: 0). - - - - - - - updelay (default: 0). - - - - - - - ARP interval (default: 0). - - - - - - - ARP IP target. - - - - - + Add, modify or remove properties in the connection profile. - - - - master - - - - - - - master bond interface name, or connection UUID or - ID of bond master connection profile. The value can be - prefixed with ifname/, - uuid/ or id/ to - disambiguate it. - - - - - + To set the property just specify the property name followed by the + value. An empty value ("") removes the property value. - - - - - - - file - JSON - - - - - - - - - - JSON configuration for team. - - - - - + In addition to the properties, you can also use short names for some of + the properties. Consult the + section for details. - - - - - - - - - - - - - - master team interface name, or connection UUID or - ID of team master connection profile. The value can be - prefixed with ifname/, - uuid/ or id/to - disambiguate it. - - - - - - - JSON configuration for team. - - - - - - - - - - - - - yes - no - - - num - 2-30 - 1-10 - 6-42 - 0-1000000 - - - - yes - no - - - addr - - - - - - - controls whether Spanning Tree Protocol (STP) is enabled for this bridge - (default: yes). - - - - - - - sets STP priority (default: 128). - - - - - - - STP forwarding delay, in seconds (default: 15). - - - - - - - STP hello time, in seconds (default: 2). - - - - - - - STP maximum message age, in seconds (default: 20). - - - - - - - the Ethernet MAC address aging time, in seconds (default: 300). - - - - - - - controls whether IGMP snooping is enabled (default: yes). - - - - - - - MAC address of the bridge (note: this requires a recent kernel feature, - originally introduced in 3.15 upstream kernel). - - - - - - - - - - master - num - 1-65535 - - - - yes - no - - - - - - - - - master bridge interface name, or connection UUID - or ID of bridge master connection profile. The value - can be prefixed with ifname/, - uuid/ or id/ - to disambiguate it. - - - - - - - STP priority of this slave (default: 32). - - - - - - - STP port cost for destinations via this slave (default: 100). - - - - - - - 'hairpin mode' for the slave, which allows frames to be sent back out - through the slave the frame was received on (default: yes). - - - - - - - - - - type - username - - - - - - - VPN type. - - - - - - - VPN username. - - - - - + If you want to append an item to the existing value, use + + prefix for the property name. If you want to remove just + one item from container-type property, use - prefix for + the property name and specify a value or an zero-based index of the item to + remove (or option name for properties with named options) as + value. The + and - + modifies only have a real effect for multi-value (container) + properties like ipv4.dns, ipv4.addresses, + bond.options, etc. - - - - SSID - 1-13 - MAC - - - - - - - SSID. - - - - - - - channel to use for the network. - - - - - - - anycast DHCP MAC address used when requesting an IP address via DHCP. - - - - - + See nm-settings5 + for complete reference of setting and property names, their descriptions + and default values. The setting and + property can be abbreviated provided they are unique. - - - - username - - - - pppoa - pppoe - ipoatm - - - passwd - - - - vcmux - llc - - - - - - - - - ADSL user name. - - - - - - - ADSL protocol. - - - - - - - ADSL password. - - - - - - - ADSL encapsulation. - - - - - + The connection is identified by its name, UUID or D-Bus path. If + ID is ambiguous, a keyword , + or can be used. + + - - - - - - - tun - tap - - - UID - GID - - - - yes - no - - - - - - yes - no - - - - - - yes - no - - - - - - - - - Mode for the device. - - - - - - - UID of the owner. - - - - - - - GID of the group. - - - - - - - include packet information (~IFF_NO_PI flag). - - - - - - - send and receive large (i.e. GSO) packets and packets with partial - checksums (IFF_VNET_HDR flag). - - - - - - - multi-queue support for tun/tap device (IFF_MULTI_QUEUE flag). - - - - - - - - - - - - ipip - gre - sit - isatap - vti - ip6ip6 - ipip6 - ip6gre - vti6 - tun - - - addr - addr - device - - - - - - - tunnel mode. - - - - - - - IPv4 or IPv6 address of the remote tunnel endpoint. - - - - - - - IPv4 or IPv6 address of the local tunnel endpoint. - - - - - - - device to use for tunnel endpoint communication. - - - - - + + + add + + + yesno + option value + [+|-]setting.property value + + + - - - - device - - - - vepa - bridge - private - passthru - source - - - - - - yes - no - - - - - - - - - parent device this MACVLAN is on. - - - - - - - MACVLAN mode, which specifies the communication mechanism between - multiple MACVLANs on the same lower device. - - - - - - - controls the device type. If set to 'yes' a MACVTAP will be created - (default: no). - - - - - + + Create a new connection using specified properties. + + You need to describe the newly created connections with the property and value pairs. + See nm-settings5 + for the complete reference. You can also use the aliases described in + section. The syntax is + the same as of the nmcli connection modify command. + + To construct a meaningful connection you at the very least need to set the + property (or use the alias) + to one of known NetworkManager connection types: + + + ethernet + wifi + wimax + pppoe + gsm + cdma + infiniband + bluetooth + vlan + bond + bond-slave + team + team-slave + bridge + bridge-slave + vpn + olpc-mesh + adsl + tun + ip-tunnel + macvlan + vxlan + - - - - id - addr - parent device (ifname or connection UUID) - addr - 0-65535 - 0-65535 - 0-65535 - - - - - - - VXLAN Network Identifer to use. - - - - - - - unicast destination IP address or multicast IP address to join. - - - - - - - device to use for tunnel endpoint communication. - - - - - - - source IP address. - - - - - - - minimum UDP source port to communicate to the remote VXLAN tunnel endpoint. - - - - - - - maximum UDP source port to communicate to the remote VXLAN tunnel endpoint. - - - - - - - UDP destination port to communicate to the remote VXLAN tunnel endpoint. - - - - - + The most typical uses are described in the section. - - - - - IPv4 addresses. - - + Aside from the properties and values two special options are accepted: + - - + - IPv6 addresses. + Controls whether the connection should be persistent, i.e. NetworkManager should + store it on disk (default: yes). - If a argument is encountered, the rest of command - line is interpreted as property list in the same format as connection - modify command accepts. This makes it possible to adjust the - connection properties before it's added. + If a single argument is encountered it is ignored. + This is for compatibility with older versions on nmcli. @@ -2028,48 +994,6 @@ - - - modify - - - - - - - ID - - [+|-]setting.property - value - - - - - Modify one or more properties in the connection profile. - - The connection is identified by its name, UUID or D-Bus path. If - ID is ambiguous, a keyword , - or can be used. See - nm-settings5 - for setting and property names, their descriptions and default - values. This command supports abbreviations for setting - and property provided they are unique. Empty - value ("") removes the property value (sets - the property to the default value). The provided value overwrites the existing - property value. - - If you want to append an item to the existing value, use - + prefix for the property name. If you want to remove just - one item from container-type property, use - prefix for - the property name and specify a value or an zero-based index of the item to - remove (or option name for properties with named options) as - value. Of course, + and - - only have a real effect for multi-value (container) - properties like ipv4.dns, ipv4.addresses, - bond.options, etc. - - - clone @@ -2673,6 +1597,343 @@ + Property Aliases + + Apart from the property-value pairs, connection + add and connection modify also accept short forms + of some properties. They exist for convenience and compatiblity with older + versions of nmcli that could not accept the raw + properties. + + The overview of the aliases is below. An actual connection type is used to + disambiguate these options from the options of the same name that are valid for + multiple connection types (such as ). + + Options for all connections + + AliasPropertyNote + + + + type + connection.type + This option also accepts values of , + and . They create + connection profiles. Their use is discouraged in +favor of using a specific type with option. + + + con-name + connection.id + When not provided a default name is generated: <type>[-<ifname>][-<num>]). + + autoconnectconnection.autoconnect + + ifname + connection.interface-name + A value of * will be interpreted as +no value, making the connection profile interface-independent. +Note: use quotes around * to suppress shell expansion. +For bond, team and bridge connections a default name will be generated if not set. + + + master + connection.master + Value specified here will be canonicalized. +It can be prefixed with ifname/, uuid/ +or id/ to disambiguate it. +If the master connection can be found this will set connection.slave-type +property as well. + + slave-typeconnection.slave-type + +
+ + PPPoE options + + AliasProperty + + + usernamepppoe.username + passwordpppoe.password + servicepppoe.service + +
+ + Wired Ethernet options + + AliasProperty + + + mtuwired.mtu + macwired.mac-address + cloned-macwired.cloned-mac-address + +
+ + Infiniband options + + AliasProperty + + + mtuinfiniband.mtu + macinfiniband.mac-address + transport-modeinfiniband.transport-mode + parentinfiniband.parent + p-keyinfiniband.p-key + +
+ + Wi-Fi options + + AliasProperty + + + ssidwireless.ssid + modewireless.mode + mtuwireless.mtu + macwireless.mac-address + cloned-macwireless.cloned-mac-address + +
+ + WiMax options + + AliasProperty + + + nspwimax.network-name + macwimax.mac-address + +
+ + GSM options + + AliasProperty + + + apngsm.apn + usergsm.username + passwordgsm.password + +
+ + CDMA options + + AliasProperty + + + usercdma.username + passwordcdma.password + +
+ + Bluetooth options + + AliasPropertyNote + + + addrbluetooth.bdaddr + + bt-type + bluetooth.type + Apart from the usual dun and +panu options, the values of dun-gsm +and dun-cdma can be used for compatibility with older +versions. They are equivalent to using dun and setting +appropriate gsm.* or cdma.* properties. + + +
+ + VLAN options + + AliasProperty + + + devvlan.parent + idvlan.id + flagsvlan.flags + ingressvlan.ingress-priority-map + egressvlan.egress-priority-map + +
+ + Bonding options + + AliasPropertyNote + + + + mode + bond.options + Setting each of these adds the option to bond.options property. +It's equivalent of using the +bond.options 'option=value' syntax. + + primary + miimon + downdelay + updelay + arp-interval + arp-ip-target + lacp-rate + +
+ + Team options + + AliasProperty + + + configteam.config + +
+ + Team port options + + AliasProperty + + + configteam-port.config + +
+ + Bridge options + + AliasProperty + + + stpbridge.stp + prioritybridge.priority + forward-delaybridge.forward-delay + hello-timebridge.hello-time + max-agebridge.max-age + ageing-timebridge.ageing-time + multicast-snoopingbridge.multicast-snooping + macbridge.mac-address + prioritybridge.port-priority + path-costbridge.port-path-cost + hairpinbridge.port-hairpin-mode + +
+ + VPN options + + AliasProperty + + + vpn-typevpn.service-type + uservpn.user-name + +
+ + OLPC Mesh options + + AliasProperty + + + ssidolpc-mesh.ssid + channelolpc-mesh.channel + dhcp-anycastolpc-mesh.dhcp-anycast-address + +
+ + ADSL options + + AliasProperty + + + usernameadsl.username + protocoladsl.protocol + passwordadsl.password + encapsulationadsl.encapsulation + +
+ + MACVLAN options + + AliasProperty + + + devmacvlan.parent + modemacvlan.mode + tapmacvlan.tap + +
+ + VxLAN options + + AliasProperty + + + idvxlan.id + remotevxlan.remote + devvxlan.parent + localvxlan.local + source-port-minvxlan.source-port-min + source-port-maxvxlan.source-port-max + destination-portvxlan.destination-port + +
+ + Tun options + + AliasProperty + + + modetun.mode + ownertun.owner + grouptun.group + pitun.pi + vnet-hdrtun.vnet-hdr + multi-queuetun.multi-queue + +
+ + IP tunneling options + + AliasProperty + + + modeip-tunnel.mode + localip-tunnel.local + remoteip-tunnel.remote + devip-tunnel.parent + +
+ + IPv4 options + + AliasPropertyNote + + + + ip4 + ipv4.addresses + This option can be specified multiple times. +It's equivalent of using +ipv4.addresses syntax. + + gw4ipv4.gateway + +
+ + IPv6 options + + AliasPropertyNote + + + + ip6 + ipv6.addresses + This option can be specified multiple times. +It's equivalent of using +ipv6.addresses syntax. + + gw6ipv6.gateway + +
+ + + Environment Variables nmcli's behavior is affected by the following @@ -2801,7 +2062,7 @@ - Examples + Examples This section presents various examples of nmcli usage. If you want even more, please refer to @@ -2985,7 +2246,7 @@ - nmcli c a ifname eth0 type ethernet -- ipv4.method disabled ipv6.method link-local + nmcli c a ifname eth0 type ethernet ipv4.method disabled ipv6.method link-local non-interactively adds a connection that will use eth0 Ethernet interface and only have an IPv6 link-local address configured. -- cgit v1.2.1