* [pve-devel] [RFC PATCH] api: network: add return schema for interface listing
@ 2024-12-05 8:27 Dominik Csapak
2024-12-05 8:29 ` Dominik Csapak
` (3 more replies)
0 siblings, 4 replies; 8+ messages in thread
From: Dominik Csapak @ 2024-12-05 8:27 UTC (permalink / raw)
To: pve-devel; +Cc: s.hahnreich
Most optiosn come from the api call parameter list
(`json_config_properties`). The description and types for the remaining
ons are either taken from the manpages, source code or similar
documentation where available.
Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
---
sending as RFC because some descriptions are very barebones due to lack
of documentation on the specific properties (link-type, vxlan-*, etc.)
@s.hahnreich, maybe could you take a look at these and expand on some of
them?
PVE/API2/Network.pm | 97 ++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 95 insertions(+), 2 deletions(-)
diff --git a/PVE/API2/Network.pm b/PVE/API2/Network.pm
index b9db9b27..df3db5af 100644
--- a/PVE/API2/Network.pm
+++ b/PVE/API2/Network.pm
@@ -38,7 +38,7 @@ my $bond_mode_enum = [
];
my $network_type_enum = ['bridge', 'bond', 'eth', 'alias', 'vlan',
- 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort'];
+ 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort', 'vnet'];
my $confdesc = {
type => {
@@ -223,7 +223,100 @@ __PACKAGE__->register_method({
type => "array",
items => {
type => "object",
- properties => {},
+ properties => json_config_properties({
+ iface => get_standard_option('pve-iface'),
+ active => {
+ type => 'boolean',
+ optional => 1,
+ description => "Set to 1 if the interface is active.",
+ },
+ exists => {
+ type => 'boolean',
+ optional => 1,
+ description => "Set to 1 if the interface physically exists.",
+ },
+ families => {
+ type => "array",
+ description => "The network families.",
+ items => {
+ type => "string",
+ description => "A ntework familiy.",
+ enum => ["inet", "inet6"],
+ },
+ optional => 1,
+ },
+ method => {
+ type => "string",
+ description => "The network configuration method for IPv4.",
+ enum => ["manual", "static", "auto"],
+ optional => 1,
+ },
+ method6 => {
+ type => "string",
+ description => "The network configuration method for IPv6.",
+ enum => ["manual", "static", "auto"],
+ optional => 1,
+ },
+ priority => {
+ type => 'integer',
+ description => "The order of the interface.",
+ optional => 1,
+ },
+ options => {
+ type => 'array',
+ optional => 1,
+ description => "A list of additional interface options for IPv4.",
+ items => {
+ type => "string",
+ description => "An interface property.",
+ },
+ },
+ options6 => {
+ type => 'array',
+ optional => 1,
+ description => "A list of additional interface options for IPv6.",
+ items => {
+ type => "string",
+ description => "An interface property.",
+ },
+ },
+ 'uplink-id' => {
+ type => 'string',
+ optional => 1,
+ description => "The uplink ID.",
+ },
+ 'link-type' => {
+ type => 'string',
+ optional => 1,
+ description => "The link type.",
+ },
+ 'vlan-protocol' => {
+ type => 'string',
+ optional => 1,
+ enum => [qw(802.1ad 802.1q)],
+ description => "The vlan protocol.",
+ },
+ 'vxlan-id' => {
+ type => 'integer',
+ optional => 1,
+ description => "The VXLAN ID.",
+ },
+ 'vxlan-svcnodeip' => {
+ type => 'string',
+ optional => 1,
+ description => "The VXLAN SVC node IP.",
+ },
+ 'vxlan-physdev' => {
+ type => 'string',
+ optional => 1,
+ description => "The physical device for the VXLAN tunnel communication.",
+ },
+ 'vxlan-local-tunnelip' => {
+ type => 'string',
+ optional => 1,
+ description => "The VXLAN local tunnel IP.",
+ },
+ }),
},
links => [ { rel => 'child', href => "{iface}" } ],
},
--
2.39.5
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: [pve-devel] [RFC PATCH] api: network: add return schema for interface listing
2024-12-05 8:27 [pve-devel] [RFC PATCH] api: network: add return schema for interface listing Dominik Csapak
@ 2024-12-05 8:29 ` Dominik Csapak
2024-12-05 8:43 ` Thomas Lamprecht
` (2 subsequent siblings)
3 siblings, 0 replies; 8+ messages in thread
From: Dominik Csapak @ 2024-12-05 8:29 UTC (permalink / raw)
To: pve-devel
argh, this should be pve-manager and i wanted to include s.hanreich but miswrote twice (sorry !)
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: [pve-devel] [RFC PATCH] api: network: add return schema for interface listing
2024-12-05 8:27 [pve-devel] [RFC PATCH] api: network: add return schema for interface listing Dominik Csapak
2024-12-05 8:29 ` Dominik Csapak
@ 2024-12-05 8:43 ` Thomas Lamprecht
2024-12-05 11:53 ` Stefan Hanreich
2024-12-06 8:52 ` Dominik Csapak
2024-12-05 12:49 ` Gabriel Goller
2024-12-06 11:16 ` Dominik Csapak
3 siblings, 2 replies; 8+ messages in thread
From: Thomas Lamprecht @ 2024-12-05 8:43 UTC (permalink / raw)
To: Proxmox VE development discussion, Dominik Csapak
Am 05.12.24 um 09:27 schrieb Dominik Csapak:
> Most optiosn come from the api call parameter list
> (`json_config_properties`). The description and types for the remaining
> ons are either taken from the manpages, source code or similar
> documentation where available.
>
> Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
> ---
> sending as RFC because some descriptions are very barebones due to lack
> of documentation on the specific properties (link-type, vxlan-*, etc.)
>
> @s.hahnreich, maybe could you take a look at these and expand on some of
> them?
>
> PVE/API2/Network.pm | 97 ++++++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 95 insertions(+), 2 deletions(-)
>
> diff --git a/PVE/API2/Network.pm b/PVE/API2/Network.pm
> index b9db9b27..df3db5af 100644
> --- a/PVE/API2/Network.pm
> +++ b/PVE/API2/Network.pm
> @@ -38,7 +38,7 @@ my $bond_mode_enum = [
> ];
>
> my $network_type_enum = ['bridge', 'bond', 'eth', 'alias', 'vlan',
> - 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort'];
> + 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort', 'vnet'];
>
> my $confdesc = {
> type => {
> @@ -223,7 +223,100 @@ __PACKAGE__->register_method({
> type => "array",
> items => {
> type => "object",
> - properties => {},
> + properties => json_config_properties({
> + iface => get_standard_option('pve-iface'),
> + active => {
> + type => 'boolean',
> + optional => 1,
> + description => "Set to 1 if the interface is active.",
some rather higher level and certainly pre-existing in quite a few places, but might
it be better to do s/1/true/ here? IIRC the API accepts both IIRC, so not really a
problem if the user takes this literally,
Some extra checking would be certainly good, but FWIW, if there's not something totally
amiss here (@Stefan Hanreich) then I could apply this now and we improve descriptions
later™.
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: [pve-devel] [RFC PATCH] api: network: add return schema for interface listing
2024-12-05 8:43 ` Thomas Lamprecht
@ 2024-12-05 11:53 ` Stefan Hanreich
2024-12-06 8:52 ` Dominik Csapak
1 sibling, 0 replies; 8+ messages in thread
From: Stefan Hanreich @ 2024-12-05 11:53 UTC (permalink / raw)
To: Thomas Lamprecht, Proxmox VE development discussion, Dominik Csapak
On 12/5/24 09:43, Thomas Lamprecht wrote:
> Some extra checking would be certainly good, but FWIW, if there's not something totally
> amiss here (@Stefan Hanreich) then I could apply this now and we improve descriptions
> later™.
From a quick glance a few properties are missing. From what I can tell
it's the following:
bridge-access
bridge-learning
bridge-arp-nd-suppress
bridge-unicast-flood
bridge-multicast-flood
Taken from [1]
The descriptions are already better than what ifupdown2 man pages are
providing, but that's not really a high bar to jump over. They're fine
for now I'd say.
[1]
https://git.proxmox.com/?p=pve-common.git;a=blob;f=src/PVE/INotify.pm;h=54b883e95f3288a9dd27abe1733b8e1a96c6bad4;hb=HEAD#l945
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [pve-devel] [RFC PATCH] api: network: add return schema for interface listing
2024-12-05 8:43 ` Thomas Lamprecht
2024-12-05 11:53 ` Stefan Hanreich
@ 2024-12-06 8:52 ` Dominik Csapak
2024-12-06 10:00 ` Thomas Lamprecht
1 sibling, 1 reply; 8+ messages in thread
From: Dominik Csapak @ 2024-12-06 8:52 UTC (permalink / raw)
To: Thomas Lamprecht, Proxmox VE development discussion
On 12/5/24 09:43, Thomas Lamprecht wrote:
> Am 05.12.24 um 09:27 schrieb Dominik Csapak:
>> Most optiosn come from the api call parameter list
>> (`json_config_properties`). The description and types for the remaining
>> ons are either taken from the manpages, source code or similar
>> documentation where available.
>>
>> Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
>> ---
>> sending as RFC because some descriptions are very barebones due to lack
>> of documentation on the specific properties (link-type, vxlan-*, etc.)
>>
>> @s.hahnreich, maybe could you take a look at these and expand on some of
>> them?
>>
>> PVE/API2/Network.pm | 97 ++++++++++++++++++++++++++++++++++++++++++++-
>> 1 file changed, 95 insertions(+), 2 deletions(-)
>>
>> diff --git a/PVE/API2/Network.pm b/PVE/API2/Network.pm
>> index b9db9b27..df3db5af 100644
>> --- a/PVE/API2/Network.pm
>> +++ b/PVE/API2/Network.pm
>> @@ -38,7 +38,7 @@ my $bond_mode_enum = [
>> ];
>>
>> my $network_type_enum = ['bridge', 'bond', 'eth', 'alias', 'vlan',
>> - 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort'];
>> + 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort', 'vnet'];
>>
>> my $confdesc = {
>> type => {
>> @@ -223,7 +223,100 @@ __PACKAGE__->register_method({
>> type => "array",
>> items => {
>> type => "object",
>> - properties => {},
>> + properties => json_config_properties({
>> + iface => get_standard_option('pve-iface'),
>> + active => {
>> + type => 'boolean',
>> + optional => 1,
>> + description => "Set to 1 if the interface is active.",
>
> some rather higher level and certainly pre-existing in quite a few places, but might
> it be better to do s/1/true/ here? IIRC the API accepts both IIRC, so not really a
> problem if the user takes this literally,
>
this is the return schema only though, and we actually return a 1. Should i use
true regardless ? (no hard feelings either way)
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: [pve-devel] [RFC PATCH] api: network: add return schema for interface listing
2024-12-06 8:52 ` Dominik Csapak
@ 2024-12-06 10:00 ` Thomas Lamprecht
0 siblings, 0 replies; 8+ messages in thread
From: Thomas Lamprecht @ 2024-12-06 10:00 UTC (permalink / raw)
To: Dominik Csapak, Proxmox VE development discussion
Am 06.12.24 um 09:52 schrieb Dominik Csapak:
> On 12/5/24 09:43, Thomas Lamprecht wrote:
>> Am 05.12.24 um 09:27 schrieb Dominik Csapak:
>>> Most optiosn come from the api call parameter list
>>> (`json_config_properties`). The description and types for the remaining
>>> ons are either taken from the manpages, source code or similar
>>> documentation where available.
>>>
>>> Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
>>> ---
>>> sending as RFC because some descriptions are very barebones due to lack
>>> of documentation on the specific properties (link-type, vxlan-*, etc.)
>>>
>>> @s.hahnreich, maybe could you take a look at these and expand on some of
>>> them?
>>>
>>> PVE/API2/Network.pm | 97 ++++++++++++++++++++++++++++++++++++++++++++-
>>> 1 file changed, 95 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/PVE/API2/Network.pm b/PVE/API2/Network.pm
>>> index b9db9b27..df3db5af 100644
>>> --- a/PVE/API2/Network.pm
>>> +++ b/PVE/API2/Network.pm
>>> @@ -38,7 +38,7 @@ my $bond_mode_enum = [
>>> ];
>>>
>>> my $network_type_enum = ['bridge', 'bond', 'eth', 'alias', 'vlan',
>>> - 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort'];
>>> + 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort', 'vnet'];
>>>
>>> my $confdesc = {
>>> type => {
>>> @@ -223,7 +223,100 @@ __PACKAGE__->register_method({
>>> type => "array",
>>> items => {
>>> type => "object",
>>> - properties => {},
>>> + properties => json_config_properties({
>>> + iface => get_standard_option('pve-iface'),
>>> + active => {
>>> + type => 'boolean',
>>> + optional => 1,
>>> + description => "Set to 1 if the interface is active.",
>>
>> some rather higher level and certainly pre-existing in quite a few places, but might
>> it be better to do s/1/true/ here? IIRC the API accepts both IIRC, so not really a
>> problem if the user takes this literally,
>>
> this is the return schema only though, and we actually return a 1. Should i use
> true regardless ? (no hard feelings either way)
Nah, it probably is really fine as is then.
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [pve-devel] [RFC PATCH] api: network: add return schema for interface listing
2024-12-05 8:27 [pve-devel] [RFC PATCH] api: network: add return schema for interface listing Dominik Csapak
2024-12-05 8:29 ` Dominik Csapak
2024-12-05 8:43 ` Thomas Lamprecht
@ 2024-12-05 12:49 ` Gabriel Goller
2024-12-06 11:16 ` Dominik Csapak
3 siblings, 0 replies; 8+ messages in thread
From: Gabriel Goller @ 2024-12-05 12:49 UTC (permalink / raw)
To: Dominik Csapak; +Cc: pve-devel
Just in case you haven't noticed, a few typos inline:
On 05.12.2024 09:27, Dominik Csapak wrote:
>Most optiosn come from the api call parameter list
s/optiosn/options/
>(`json_config_properties`). The description and types for the remaining
>ons are either taken from the manpages, source code or similar
>documentation where available.
> [snip]
>diff --git a/PVE/API2/Network.pm b/PVE/API2/Network.pm
>index b9db9b27..df3db5af 100644
>--- a/PVE/API2/Network.pm
>+++ b/PVE/API2/Network.pm
>@@ -38,7 +38,7 @@ my $bond_mode_enum = [
> ];
>
> my $network_type_enum = ['bridge', 'bond', 'eth', 'alias', 'vlan',
>- 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort'];
>+ 'OVSBridge', 'OVSBond', 'OVSPort', 'OVSIntPort', 'vnet'];
>
> my $confdesc = {
> type => {
>@@ -223,7 +223,100 @@ __PACKAGE__->register_method({
> type => "array",
> items => {
> type => "object",
>- properties => {},
>+ properties => json_config_properties({
>+ iface => get_standard_option('pve-iface'),
>+ active => {
>+ type => 'boolean',
>+ optional => 1,
>+ description => "Set to 1 if the interface is active.",
>+ },
>+ exists => {
>+ type => 'boolean',
>+ optional => 1,
>+ description => "Set to 1 if the interface physically exists.",
>+ },
>+ families => {
>+ type => "array",
>+ description => "The network families.",
>+ items => {
>+ type => "string",
>+ description => "A ntework familiy.",
s/ntework/network/
s/familiy/family/
>+ enum => ["inet", "inet6"],
>+ },
>+ optional => 1,
>+ },
>+ method => {
>+ type => "string",
>+ description => "The network configuration method for IPv4.",
>+ enum => ["manual", "static", "auto"],
>+ optional => 1,
>+ },
>+ method6 => {
>+ type => "string",
>+ description => "The network configuration method for IPv6.",
>+ enum => ["manual", "static", "auto"],
>+ optional => 1,
>+ },
>+ priority => {
>+ type => 'integer',
>+ description => "The order of the interface.",
>+ optional => 1,
>+ },
>+ options => {
>+ type => 'array',
>+ optional => 1,
>+ description => "A list of additional interface options for IPv4.",
>+ items => {
>+ type => "string",
>+ description => "An interface property.",
>+ },
>+ },
>+ options6 => {
>+ type => 'array',
>+ optional => 1,
>+ description => "A list of additional interface options for IPv6.",
>+ items => {
>+ type => "string",
>+ description => "An interface property.",
>+ },
>+ },
>+ 'uplink-id' => {
>+ type => 'string',
>+ optional => 1,
>+ description => "The uplink ID.",
>+ },
>+ 'link-type' => {
>+ type => 'string',
>+ optional => 1,
>+ description => "The link type.",
>+ },
>+ 'vlan-protocol' => {
>+ type => 'string',
>+ optional => 1,
>+ enum => [qw(802.1ad 802.1q)],
>+ description => "The vlan protocol.",
s/vlan/VLAN/
>+ },
>+ 'vxlan-id' => {
>+ type => 'integer',
>+ optional => 1,
>+ description => "The VXLAN ID.",
>+ },
>+ 'vxlan-svcnodeip' => {
>+ type => 'string',
>+ optional => 1,
>+ description => "The VXLAN SVC node IP.",
>+ },
>+ 'vxlan-physdev' => {
>+ type => 'string',
>+ optional => 1,
>+ description => "The physical device for the VXLAN tunnel communication.",
I would remove the "communication" as it's kinda redundant IMO.
>+ },
>+ 'vxlan-local-tunnelip' => {
>+ type => 'string',
>+ optional => 1,
>+ description => "The VXLAN local tunnel IP.",
>+ },
>+ }),
> },
> links => [ { rel => 'child', href => "{iface}" } ],
> },
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: [pve-devel] [RFC PATCH] api: network: add return schema for interface listing
2024-12-05 8:27 [pve-devel] [RFC PATCH] api: network: add return schema for interface listing Dominik Csapak
` (2 preceding siblings ...)
2024-12-05 12:49 ` Gabriel Goller
@ 2024-12-06 11:16 ` Dominik Csapak
3 siblings, 0 replies; 8+ messages in thread
From: Dominik Csapak @ 2024-12-06 11:16 UTC (permalink / raw)
To: pve-devel
sent a v2:
https://lore.proxmox.com/pve-devel/20241206092407.960823-1-d.csapak@proxmox.com/
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2024-12-06 11:16 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-12-05 8:27 [pve-devel] [RFC PATCH] api: network: add return schema for interface listing Dominik Csapak
2024-12-05 8:29 ` Dominik Csapak
2024-12-05 8:43 ` Thomas Lamprecht
2024-12-05 11:53 ` Stefan Hanreich
2024-12-06 8:52 ` Dominik Csapak
2024-12-06 10:00 ` Thomas Lamprecht
2024-12-05 12:49 ` Gabriel Goller
2024-12-06 11:16 ` Dominik Csapak
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox