Klaus Kaempf wrote / napísal(a):

* Martin Vidner [Aug 12. 2009 15:53]:

...

If you wonder why another model for the same, I have started this in parallel to Miso looking at CIM, and intentionally it does not include any CIM yet.

Next we will look how it can be made more CIM-like and whether the anticipated resulting complication is too much :)

The request for 'CIM-like' is mainly to prevent us from inventing 'new' property or function names. Defining a REST API is essentially modeling the resource, and thats what the CIM model already provides. Just pick what you need.

Hm, we already have sysconfig names. But I can understand CIM requirement.

...

* /network

No!

The URL is generated internally when registering the resource within the rest-service. Just define the 'interface' name below config/resources/network.yml, the rest will be taken care of.

...

http://mschmidkunz.110mb.com/network.html

This is a UI proposal and should not influence the resource model too much.

This UI is visualisation of network requirement - just to imagine what we're going to configure, nothing else.

...

But the network services, including a DHCP *server*, will be outside

Agreed.

...

Basic Config ------------

* /network/devices/ (RO)

Devices and interfaces are the same for now.

How would I be able to distinguish them ?

Device is physical hardware. It can exists without configuration. Interface is software representation of physical device or virtual device. Virtual devices are software-created. Without configuration, they disappears after "rcnetwork restart"

...

Devices are read only (for physial devices, but see below for virtual). The read-write part are the configs.

* /network/devices/1 (RO) interface=eth0 product=MSI 1341

Hmm, why "1" as the id ? The interface name (eth0) should be distinct and can be used as the id.

Right, it makes sense

...

* /network/configs/ (RO)

Configs are separated from devices

Can you document the purpose of configs in more detail ?

It's configuration of Layer3 of the ISO/OSI model. Devices defines Layer2 of the ISO/OSI model.

...

like ifcfg-* (shown here like key-value pairs but xml in fact)

* /network/configs/1 (RW) startmode=dhcp4 * /network/configs/2 bootproto=static ipaddr=1.2.3.4/24 * /network/configs/3 startmode=dhcp4 wireless_essid=HomeWiFi wireless_key=HomeSweetHome * /network/configs/4 startmode=dhcp4 wireless_essid=WorkWiFi wireless_wpa_psk=HomeSweetHome

In the above form, configs are not associated with devices and it works like in NetworkManager, a call like /network/devices/1/configure?config=/network/configs/42 is needed.

Hmm, if the configs are completely separated from interfaces, passing the complete path (network/configs/42) makes sense. But since they are related to network, passing the config id should be sufficient, no ?

Yes

...

But a config can get another attribute, "device" that makes it the default config for a device, and it works like our ifcfg (where "device" is in the filename)

Don't over-engineer it ! Nothing in the feature request asks for the separation of device and its config.

For the future, this can be usefull. For wireless devices you can switch between several APs just by associate different configurations to one device.

...

For simplicity, the UI can hide the device-config separation and always edit the single config for a device.

Yes, focus on a single config for now.

...

* /network/devices/1/current-config (RO) (current_config? TODO style) ipaddr=1.2.3.4/24

Why 'current-config' ? Retrieving the resource instance (i.e. /network/devices/eth0 should get you all instance properties; similar to calling 'ifconfig eth0'.

...

This distinguishes the config, which can specify the IP or say DHCP from the current-config, which always specifies the IP (or does not exist). Think /etc versus "ip" output.

* /network/routes/ * /network/routes/default (RW) <route> <via>1.2.3.4 ("ip r" keyword) <route>

What about multiple default routes ?

...

* /network/resolver (RW) <nameservers> <nameserver>1.2.3.4 <nameserver>1.2.3.42 <searches> <search>example.com <search>example.net

...

(use-dhcp ?)

Hmm, I'd assume /network/resolver to represent /etc/resolv.conf, right ? However, /etc/resolv.conf is autogenerated, so /network/resolver should be 'RO'.

/etc/resolv.conf doesn't record anything about how it was generated, i.e. via dhcp or manual setup. Thus 'use-dhcp' is a (RW) config property, not a resolver property.

No, it represents /etc/sysconfig/network/config.NETCONFIG_DNS_STATIC_SEARCHLIST

...

* /network/resolver/current-config (RO) Like with the devices, this shows the config even if /network/resolver says DHCP

* /network/hostname (RW) hostname=trikolka domain=suse.cz fqdn=trikolka.suse.cz

Why 'fqdn' ? Are there cases where fqdn isn't a concatenation of hostname and domain ?

...

(dhcp??)

No, not for /network/hostname. "set hostname via dhcp" is a property of the network device config since it determines which interface sets the hostname via dhcp.

...

Virtual Devices ---------------

(This is for the future, included here just to show that the API accomodates them)

For virtual devices (special interfaces not based on hardware devices - bridge, bonding, vlan) is sysconfig configuration splitted into device and configuration parts. /network/configs stays the same and /network/devices becomes writable (details to be worked out but the REST paths are unchanged from the basic config)

bridge ------ ifcfg-br0 STARTMODE='auto' BOOTPROTO='dhcp' BRIDGE='yes' BRIDGE_PORTS='eth0 eth1' BRIDGE_PORTPRIORITIES='50 20'

* /network/devices/1 interface=br0 bridge='yes' bridge_ports='eth0 eth1' bridge_portpriorities='50 20'

Hehe, here the object oriented model of CIM shows its value. A physical and a virtual network device should be based on a common parent class. Thus documenting the properties of the virtual device should only show the subclass ('VirtualDevice').

But in this case, there's nothing in common ...

For bridge_ports, don't name interfaces but RESTful pathes (i.e. bridge_ports = [ /network/devices/eth0, /network/devices/eth1 ])

See "A closer look at REST" (http://kkaempf.blogspot.com/2009/04/yast-opensuse-installation-and.html) and "REST APIs must be hypertext-driven" (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) for the reasoning.

...

* /network/configs/1 bootproto='dhcp'

VLAN ---- ifcfg-vlan3 STARTMODE=onboot ETHERDEVICE=eth0 IPADDR=192.168.3.27/24

* /network/devices/1 interface=vlan3 etherdevice=eth0 # /network/devices/10 * /network/configs/1 ipaddr=192.168.3.27/24

The same applies as above.

...

bonding ------- ifcfg-bond0 STARTMODE='onboot' BOOTPROTO='static' IPADDR='192.168.0.1/24'

BONDING_MASTER='yes' BONDING_SLAVE_0='eth0' BONDING_SLAVE_1='eth1' BONDING_MODULE_OPTS='mode=1' # backup mode

* /network/devices/1 interface=bond0 bonding_master='yes' bonding_slave_0='eth0' # /network/devices/10 bonding_slave_1='eth1' # /network/devices/11 bonding_module_opts='mode=1' # backup mode * /network/configs/1 ipaddr='192.168.0.1/24'

One question remains: Is all this covered by the current YaST 'yapi' ?

No, there's no network-yapi yet

Thanks !

Klaus --- SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg)

Bye, Michal -- Best Regards, Michal Zugec Software developer --------------------------------------------------------------------- SuSE CR, s.r.o. e-mail: mzugec@suse.cz Lihovarska 1060/12 tel: +420 284 028 960 190 00 Praha 9 fax: +420 296 542 374 Czech Republic http://www.suse.cz/ -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org

Klaus Kaempf wrote / napísal(a):

* Michal Zugec [Aug 13. 2009 16:07]:

[shortened to focus on relevant parts]

...

...

...

Basic Config ------------

* /network/devices/ (RO)

Devices and interfaces are the same for now. How would I be able to distinguish them ?

Device is physical hardware. It can exists without configuration. Interface is software representation of physical device or virtual device. Virtual devices are software-created. Without configuration, they disappears after "rcnetwork restart"

Ok, understood. But it doesn't answer my question. Let me restate it: If interfaces and devices all show up below /network/devices/, how do I know which is which ? I'd rather not have to retrieve every instance and check a property.

Hm, you don't need to know that. Let's say there are only network interfaces. Two types of interfaces : based on physical devices and virtual ones. Main difference between them is that first one you can "just see", second one you need to create (or configure them). Reason why Martin mentioned that is that for first one RO is enough, but for virtual devices you need RW access to create them.

...

...

...

* /network/configs/ (RO)

Configs are separated from devices

Can you document the purpose of configs in more detail ? It's configuration of Layer3 of the ISO/OSI model. Devices defines Layer2 of the ISO/OSI model.

Ah, ok.

[...]

...

...

...

But a config can get another attribute, "device" that makes it the default config for a device, and it works like our ifcfg (where "device" is in the filename)

Don't over-engineer it ! Nothing in the feature request asks for the separation of device and its config.

For the future, this can be usefull. For wireless devices you can switch between several APs just by associate different configurations to one device.

No question about the usefulness. Just focus on the simple parts (one config per interface) now and extend later.

Hm, but here's conflict of requirements. As I understand from Jiri, we should define rest-api not only for this simple purpose but also for future. We need to discuss this ...

[...]

...

...

Hmm, I'd assume /network/resolver to represent /etc/resolv.conf, right ? However, /etc/resolv.conf is autogenerated, so /network/resolver should be 'RO'.

/etc/resolv.conf doesn't record anything about how it was generated, i.e. via dhcp or manual setup. Thus 'use-dhcp' is a (RW) config property, not a resolver property.

No, it represents /etc/sysconfig/network/config.NETCONFIG_DNS_STATIC_SEARCHLIST

Ok, understood. Then please name it accordingly, 'resolver' is confusing.

CIM property is CIM_DNSGeneralSettingData.DNSSuffixesToAppend, so DNSGeneralSettingData/DNSSuffixesToAppend ? I will write this in the next mail.

...

...

...

bridge ------ ifcfg-br0 STARTMODE='auto' BOOTPROTO='dhcp' BRIDGE='yes' BRIDGE_PORTS='eth0 eth1' BRIDGE_PORTPRIORITIES='50 20'

* /network/devices/1 interface=br0 bridge='yes' bridge_ports='eth0 eth1' bridge_portpriorities='50 20'

Hehe, here the object oriented model of CIM shows its value. A physical and a virtual network device should be based on a common parent class. Thus documenting the properties of the virtual device should only show the subclass ('VirtualDevice'). But in this case, there's nothing in common ...

Startmode ? bootproto ? Some property for 'virtual' device ?

No! This properties are for Layer3 - not /devices/ but /configs/

...

...

One question remains: Is all this covered by the current YaST 'yapi' ? No, there's no network-yapi yet

So how are you going to implement the network rest-service then ?

For first iteration we can use CLI backend and then write yapi

Klaus --- SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg)

-- Best Regards, Michal Zugec Software developer --------------------------------------------------------------------- SuSE CR, s.r.o. e-mail: mzugec@suse.cz Lihovarska 1060/12 tel: +420 284 028 960 190 00 Praha 9 fax: +420 296 542 374 Czech Republic http://www.suse.cz/ -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org

* Jiri Srain [Aug 14. 2009 10:06]:

Dne pátek 14 Srpen 2009 09:55:26 Michal Zugec napsal(a):

...

Klaus Kaempf wrote / napísal(a):

...

* Michal Zugec [Aug 13. 2009 16:07]:

...

...

...

...

...

But a config can get another attribute, "device" that makes it the default config for a device, and it works like our ifcfg (where "device" is in the filename)

Don't over-engineer it ! Nothing in the feature request asks for the separation of device and its config.

For the future, this can be usefull. For wireless devices you can switch between several APs just by associate different configurations to one device.

No question about the usefulness. Just focus on the simple parts (one config per interface) now and extend later.

Hm, but here's conflict of requirements. As I understand from Jiri, we should define rest-api not only for this simple purpose but also for future. We need to discuss this ...

Perhaps I should re-word myself: My intention is to design the API so that we do not have to rewrite it when we need e.g. support for multiple interfaces (and therefore break other web clients or, even worse, existing vendor's modules, which depend on that API).

We have to version the (rest-)api in any case.

What I find important is extensibility of the interface without breaking existing apps (e.g. adding more tags into a XML document is fine, so is defining more paths).

Such kind of extension is backwards-compatible. But clients requesting th extension still need a way to express this: versioning. See e.g. http://barelyenough.org/blog/2008/05/versioning-rest-web-services/ for a discussion on versioning of rest services. Klaus --- SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg) -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org