public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
From: Stefan Hanreich <s.hanreich@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH proxmox 1/4] network-types: add a type for network interface names
Date: Thu, 12 Nov 2026 18:10:57 +0100	[thread overview]
Message-ID: <20261112171102.674232-2-s.hanreich@proxmox.com> (raw)
In-Reply-To: <20261112171102.674232-1-s.hanreich@proxmox.com>

There is no common type for network interface names yet, and the
pve-iface format of the Perl JSON schema even accepts names that the
kernel rejects, e.g. names longer than 15 bytes, while it rejects
names with a '-' (bug #6366 [1]).

NetworkInterfaceName accepts every name that the APIs of PVE, PBS and
PDM accept and the kernel can use, plus a few that pve-iface rejects:
names with a '-', names starting with a digit or '_', single-character
names and names with more than one or a non-numeric dotted suffix,
e.g. eth0.100.200. It uses the format of the network API of PBS and
PDM.

The api_string_type macro requires anyhow, so add it to the api-types
feature.

[1] https://bugzilla.proxmox.com/show_bug.cgi?id=6366

Signed-off-by: Stefan Hanreich <s.hanreich@proxmox.com>
---
 proxmox-network-types/Cargo.toml              |   4 +-
 proxmox-network-types/src/lib.rs              |   2 +
 .../src/network_interface.rs                  | 102 ++++++++++++++++++
 3 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100644 proxmox-network-types/src/network_interface.rs

diff --git a/proxmox-network-types/Cargo.toml b/proxmox-network-types/Cargo.toml
index 1e1eacbf..b5ab5c5e 100644
--- a/proxmox-network-types/Cargo.toml
+++ b/proxmox-network-types/Cargo.toml
@@ -10,6 +10,7 @@ exclude.workspace = true
 rust-version.workspace = true
 
 [dependencies]
+anyhow = { workspace = true, optional = true }
 regex = { workspace = true, optional = true }
 serde = { workspace = true, features = [ "derive", "std" ] }
 serde_with = "3.8.1"
@@ -17,7 +18,8 @@ serde_plain.workspace = true
 thiserror.workspace = true
 
 proxmox-schema = { workspace = true, features = [ "api-macro", "api-types" ], optional = true}
+proxmox-serde = { workspace = true, optional = true }
 
 [features]
 default = []
-api-types = ["dep:proxmox-schema", "dep:regex"]
+api-types = ["dep:anyhow", "dep:proxmox-schema", "dep:proxmox-serde", "dep:regex"]
diff --git a/proxmox-network-types/src/lib.rs b/proxmox-network-types/src/lib.rs
index 6a5ddbf9..ebbabe76 100644
--- a/proxmox-network-types/src/lib.rs
+++ b/proxmox-network-types/src/lib.rs
@@ -9,3 +9,5 @@ pub use ip_address::*;
 
 pub mod mac_address;
 pub use mac_address::*;
+
+pub mod network_interface;
diff --git a/proxmox-network-types/src/network_interface.rs b/proxmox-network-types/src/network_interface.rs
new file mode 100644
index 00000000..24972058
--- /dev/null
+++ b/proxmox-network-types/src/network_interface.rs
@@ -0,0 +1,102 @@
+//! Types for network interface names.
+//!
+//! The API, the kernel and existing configurations accept different names, so each kind of name
+//! has its own type, with explicit conversions between them. The API types are in `api_types` and
+//! require the `api-types` feature.
+//!
+//! # Which type to use
+//!
+//! * `api_types::NetworkInterfaceName`: names in the API and in configuration files, and names
+//!   that are created or passed to `ip`. Not for values that can also be altnames, and not for
+//!   reading names from the kernel, which can be outside of the API format.
+
+/// API types for network interface names.
+///
+/// [`NetworkInterfaceName`](api_types::NetworkInterfaceName) is the name of a network interface
+/// as accepted by the API. It is meant for every network interface that our stack creates,
+/// configures or references:
+///
+/// ```
+/// # use proxmox_network_types::network_interface::api_types::NetworkInterfaceName;
+/// let name: NetworkInterfaceName = "uplink-0".parse().unwrap();
+/// assert_eq!(name.as_str(), "uplink-0");
+///
+/// assert!("veth999999999i31".parse::<NetworkInterfaceName>().is_err());
+/// ```
+#[cfg(feature = "api-types")]
+pub mod api_types {
+    use proxmox_schema::{api, api_string_type, api_types::SAFE_ID_FORMAT};
+
+    /// The size of the kernel buffer for network interface names, including the terminating NUL.
+    const IFNAMSIZ: usize = 16;
+
+    api_string_type! {
+        #[api(format: &SAFE_ID_FORMAT, min_length: 1, max_length: IFNAMSIZ - 1)]
+        /// The name of a network interface.
+        ///
+        /// Uses the format of other names in the API, limited to the 15 bytes the kernel allows
+        /// for interface names. Every such name is valid for the kernel.
+        #[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
+        #[repr(transparent)]
+        pub struct NetworkInterfaceName(String);
+    }
+
+    proxmox_serde::forward_deserialize_to_from_str!(NetworkInterfaceName);
+    proxmox_serde::forward_serialize_to_display!(NetworkInterfaceName);
+
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+
+        #[test]
+        fn parse_network_interface_name() {
+            for name in [
+                "eth0",
+                "vmbr0",
+                "bond0.100",
+                "eth0.100.200",
+                "uplink-0",
+                "0eth",
+                "_eth0",
+                "a",
+                "tap100i0",
+                // 15 bytes is the longest name the kernel accepts
+                "abcdefghijklmno",
+            ] {
+                let parsed: NetworkInterfaceName = name.parse().expect(name);
+                assert_eq!(parsed.as_str(), name);
+                assert_eq!(parsed.to_string(), name);
+            }
+
+            for name in [
+                "",
+                ".",
+                "..",
+                ".eth0",
+                "-eth0",
+                "eth 0",
+                "eth0/1",
+                "eth0:1",
+                "eth\u{e9}",
+                "abcdefghijklmnop",
+                "veth999999999i31",
+            ] {
+                assert!(name.parse::<NetworkInterfaceName>().is_err(), "{name:?}");
+            }
+        }
+
+        #[test]
+        fn deserialize_network_interface_name() {
+            let name: NetworkInterfaceName = serde_plain::from_str("eth0").expect("valid name");
+            assert_eq!(name.as_str(), "eth0");
+            assert_eq!(serde_plain::to_string(&name).expect("serializable"), "eth0");
+
+            for name in ["eth:0", "abcdefghijklmnop"] {
+                assert!(
+                    serde_plain::from_str::<NetworkInterfaceName>(name).is_err(),
+                    "{name:?}"
+                );
+            }
+        }
+    }
+}
-- 
2.47.3





  reply	other threads:[~2026-11-12 17:11 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-12 17:10 [PATCH proxmox 0/4] network-types: add types for network interface names Stefan Hanreich
2026-11-12 17:10 ` Stefan Hanreich [this message]
2026-11-12 17:10 ` [PATCH proxmox 2/4] network-types: add a type for network interface altnames Stefan Hanreich
2026-11-12 17:10 ` [PATCH proxmox 3/4] network-types: add types for names reported by the kernel Stefan Hanreich
2026-11-12 17:11 ` [PATCH proxmox 4/4] network-types: add a type for names of existing configurations Stefan Hanreich
2026-11-12 17:36   ` Stefan Hanreich

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261112171102.674232-2-s.hanreich@proxmox.com \
    --to=s.hanreich@proxmox.com \
    --cc=pve-devel@lists.proxmox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal