Add interface alternative name document

Signed-off-by: Gris Ge <fge@redhat.com>

Author: cathay4t

devel/yaml_api.md

@@ -20,6 +20,7 @@
             * [Accept All MAC addresses](#accept-all-mac-addresses)
             * [Copy MAC From](#copy-mac-from)
             * [Dispatch script](#dispatch-script)
+            * [Interface Alternative Name](#interface-alternative-name)
         * [IP](#ip)
             * [IP Enable](#ip-enable)
             * [DHCP](#dhcp)
@@ -450,6 +451,40 @@ Setting the `post-activation` or `post-deactivation` to empty string will
 remove the dispatch scripts. Removing the interface using
 `state: absent` also remove the dispatch scripts.
 
+#### Interface Alternative Name
+
+Since 2.2.51, nmstate support configuration interface alternative names.
+
+Example YAML for adding alternative names:
+
+```rust
+---
+interfaces:
+  - name: enp7s0
+    alt-names:
+      - name: port1
+      - name: veryveryveryverylonglonglongname
+```
+
+Example YAML for removing alternative names:
+
+```
+---
+interfaces:
+  - name: enp7s0
+    alt-names:
+      - name: port1
+        state: absent
+      - name: veryveryveryverylonglonglongname
+        state: absent
+```
+
+Considering the alternative name might also added by external tools(e.g.
+systemd-udev), nmstate is doing incremental changes to interface alternative
+names, meaning:
+ * Applying YAML only append alt-names to existing.
+ * Only remove names marked with `state: absent`.
+
 ### IP
 
 This is the example of interface with static IP addresses:

features/alt-name.md

@@ -0,0 +1,39 @@
+## Interface Alternative Names
+
+New feature in nmstate 2.2.51.
+
+Interface alternative name is a kernel property of network interface which is
+treat equally as interface kernel name in netlink protocol.
+
+Unlike kernel interface name limitation on 15 characters, alternative name
+length limitation is 255(might change in the future by kernel team).
+
+Like kernel interface name, alternative name should unique among all interface
+names and all alternative names. Nmstate will raise error otherwise.
+
+Nmstate does not override existing alternative names, you can only append
+and remove explicitly.
+
+Example YAML for adding alternative names:
+
+```rust
+---
+interfaces:
+  - name: enp7s0
+    alt-names:
+      - name: port1
+      - name: veryveryveryverylonglonglongname
+```
+
+Example YAML for removing alternative names:
+
+```
+---
+interfaces:
+  - name: enp7s0
+    alt-names:
+      - name: port1
+        state: absent
+      - name: veryveryveryverylonglonglongname
+        state: absent
+```

index.md

@@ -36,6 +36,7 @@ NetworkManager acts as the main (and currently the only) provider supported.
 - [IPsec](./features/ipsec.md)
 - [DNS](./features/dns.md)
 - [Infiniband](./features/infiniband.md)
+- [Interface Alternative Name](./features/alt-name.md)
 
 ## Example output