2
0

DESIGN 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
  1. Design of the the network interface daemon (netifd)
  2. ----------------------------------------------------
  3. The primary elements of netifd's state are devices and interfaces.
  4. Devices
  5. -------
  6. A device represents either a physical Linux interface (e.g. eth0), or a
  7. virtual link, bound to a static route, a socket or some other external trigger
  8. (e.g. for VPN links or tunnels).
  9. Anything that needs to be aware of device state registers a device_user, which
  10. is bound to the device and contains a callback for receiving events on device
  11. changes. As soon as the last device_user is removed, the device itself is freed
  12. immediately.
  13. Devices can also internally reference other devices, this is used to manage
  14. specific kinds of devices, such as bridges or vlans, which do not require
  15. special treatment from interfaces or other high level data structures, with
  16. the exception of adding more member interfaces via hotplug, which is useful
  17. for bridges or bonding interfaces.
  18. The device up/down state is managed through refcounting. A device can be
  19. brought up using claim_device(), and its reference released again with
  20. release_device(). As soon as the refcount goes to zero, the device is
  21. immediately brought down.
  22. If the device cannot be brought up, claim_device() will return a non-zero
  23. status and the caller will not have increased the refcount.
  24. A registered device may not be available immediately, an interface or another
  25. device could also be attached to it, waiting for it to appear in the system,
  26. to support triggering interfaces via hotplug.
  27. All device state transitions are announced via events to all the device_user
  28. callbacks. The following event types are supported:
  29. DEV_EVENT_ADD:
  30. The device is now present in the system. When a device_user is being added
  31. to a device and the device was already present, this event is generated
  32. immediately.
  33. DEV_EVENT_REMOVE:
  34. The device is no longer available. Either it is currently being removed,
  35. or it has already disappeared. All users should drop their references
  36. immediately and clean up their state for this device.
  37. DEV_EVENT_SETUP:
  38. The device is about to be brought up. This allows device users to apply
  39. some low level configuration parameters if necessary, however this event
  40. may not be emitted in all cases. Externally managed devices added via
  41. hotplug may be already up, and in that case this notification is skipped.
  42. DEV_EVENT_UP:
  43. The device has been successfully brought up.
  44. DEV_EVENT_TEARDOWN:
  45. The device is about to be brought down
  46. DEV_EVENT_DOWN:
  47. The device has been brought down
  48. The following optional events are supported on some devices:
  49. DEV_EVENT_LINK_UP: a link has been established on this device
  50. DEV_EVENT_LINK_DOWN: the link has been lost
  51. Interfaces
  52. ----------
  53. An interface represents a high level configuration applied to one or more
  54. devices. An active interface must always be bound to one main device and
  55. to a layer 3 device. By default, the layer 3 device points at the reference
  56. to the main device, based on how simple protocols like static, dhcp, etc.
  57. are set up. More complex protcol handlers such as ppp/pptp or VPN software
  58. can remap the layer 3 interface to something else, and external modules
  59. such as the firewall can take care of both interfaces if necessary.
  60. An interface always has the following state information:
  61. active:
  62. The interface can be brought up (its main device is available)
  63. autostart:
  64. If the interface switches from inactive to active, netifd will attempt
  65. to bring it up immediately. Manually setting an interface to up (regardless
  66. of whether that was successful or not) will set this flag.
  67. state:
  68. IFS_SETUP:
  69. The interface is currently being configured by the protocol handler
  70. IFS_UP:
  71. The interface is fully configured
  72. IFS_TEARDOWN:
  73. The interface is being deconfigured
  74. IFS_DOWN:
  75. The interface is down
  76. An interface references only one protocol handler state, modular protocol
  77. handlers such as PPP are expected to be written in a way that allows them
  78. to be set up as slave to another protocol handler if necessary (useful for
  79. PPPoE or PPTP).
  80. Protocol handlers
  81. -----------------
  82. A protocol handler can be attached to anything that provides a callback
  83. for state changes. For the simple case it is usually attached to an interface
  84. directly.
  85. The state of a protocol handler is tracked in a struct interface_proto_state,
  86. and it depends on the state of the entity that's controlling it.
  87. It responds to PROTO_CMD_SETUP and PROTO_SETUP_TEARDOWN commands, which
  88. should not block at any point in time. Completion is signalled back to the
  89. master by sending IFPEV_UP and IFPEV_DOWN events.
  90. If the setup can be done fast without blocking for a noticeable amount of
  91. time, the callback can do it and send back those events immediately.
  92. If the setup can take longer, it should use uloop to schedule its actions
  93. asynchronously and (if necessary) fork.
  94. The protocol handler must be able to abort a setup request that's being
  95. processed when it encounters a teardown command.
  96. When a PROTO_SETUP_TEARDOWN call is issued and the 'force' parameter is
  97. set, the protocol handler needs to clean up immediately as good as possible,
  98. without waiting for its pending actions to complete. If it has spawned
  99. any child processes, it needs to kill them and clean up their mess.
  100. Simple protocol handlers can set the PROTO_FLAG_IMMEDIATE flag if they
  101. can perform all required actions immediately without waiting and thus
  102. do not need to schedule IFPEV_UP and IFPEV_DOWN transitions. This will
  103. cause those events to be generated by core code instead.
  104. ## TODO: Configuration management, ubus callbacks