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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox