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
next prev parent 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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.