public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
* [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: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: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
                   ` (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
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal