network: add an online state for links and manager

Add a new state of type LinkOnlineState which indicates whether a link
is online or not. The state is also used by networkd's manager to expose
the overall online state of the system.

The possible states are:

  offline  the link (or system) is offline
  partial  at least one required link is online (see below)
  online   all required links are online

For links, a link is defined to be "online" if:
  - it is managed; and
  - its operational state is within the range defined by
    RequiredForOnline=; and
  - it has an IPv4 address if RequiredFamilyForOnline=ipv4 or =both; and
  - it has an IPv6 address if RequiredFamilyForOnline=ipv6 or =both.

A link is defined to be "offline" if:
  - it is managed; and
  - it is not online, i.e. its operational state is not within the range
    defined by RequiredForOnline=, and/or it is missing an IP address in
    a required address family.

Otherwise, the link online state is undefined (represented internally as
_LINK_ONLINE_STATUS_INVALID or -EINVAL). Put another way, networkd will
only offer a meaningful online state for managed links where
RequiredForOnline=yes.

For the manager, the online state is a function of the online state of
all links which are requried for online, i.e. RequiredForOnline=yes. If
all required links are online, then the manager online state is defined
to be "online". If at least one of the required links is online, then
the manager online state is defined to be "partial". If none of
the required links are online, then the manager online state is defined
to be "offline". If there are no managed links, or RequiredForOnline=no
for all managed links, then the manager online state is undefined as
above.

The purpose of the "partial" state is analogous to the --any switch in
systemd-networkd-wait-online.service(8). For example, a required link
which lacks a carrier on boot will not force the overall (manager)
online state to "offline" if there is an alternative link available.

3 files changed, 27 insertions, 0 deletions

diff --git a/src/libsystemd/sd-network/network-util.c b/src/libsystemd/sd-network/network-util.c
index 4570098388..b01f883666 100644
--- a/src/libsystemd/sd-network/network-util.c
+++ b/src/libsystemd/sd-network/network-util.c
@@ -73,6 +73,14 @@ static const char* const link_address_state_table[_LINK_ADDRESS_STATE_MAX] = {
 
 DEFINE_STRING_TABLE_LOOKUP(link_address_state, LinkAddressState);
 
+static const char *const link_online_state_table[_LINK_ONLINE_STATE_MAX] = {
+        [LINK_ONLINE_STATE_OFFLINE] = "offline",
+        [LINK_ONLINE_STATE_PARTIAL] = "partial",
+        [LINK_ONLINE_STATE_ONLINE]  = "online",
+};
+
+DEFINE_STRING_TABLE_LOOKUP(link_online_state, LinkOnlineState);
+
 int parse_operational_state_range(const char *str, LinkOperationalStateRange *out) {
         LinkOperationalStateRange range = { _LINK_OPERSTATE_INVALID, _LINK_OPERSTATE_INVALID };
         _cleanup_free_ const char *min = NULL;
diff --git a/src/libsystemd/sd-network/network-util.h b/src/libsystemd/sd-network/network-util.h
index d33f42cfb0..3a2e4a7f6c 100644
--- a/src/libsystemd/sd-network/network-util.h
+++ b/src/libsystemd/sd-network/network-util.h
@@ -54,6 +54,14 @@ typedef enum LinkAddressState {
         _LINK_ADDRESS_STATE_INVALID = -EINVAL,
 } LinkAddressState;
 
+typedef enum LinkOnlineState {
+        LINK_ONLINE_STATE_OFFLINE,
+        LINK_ONLINE_STATE_PARTIAL,
+        LINK_ONLINE_STATE_ONLINE,
+        _LINK_ONLINE_STATE_MAX,
+        _LINK_ONLINE_STATE_INVALID = -EINVAL,
+} LinkOnlineState;
+
 const char* link_operstate_to_string(LinkOperationalState s) _const_;
 LinkOperationalState link_operstate_from_string(const char *s) _pure_;
 
@@ -66,6 +74,9 @@ AddressFamily link_required_address_family_from_string(const char *s) _pure_;
 const char* link_address_state_to_string(LinkAddressState s) _const_;
 LinkAddressState link_address_state_from_string(const char *s) _pure_;
 
+const char* link_online_state_to_string(LinkOnlineState s) _const_;
+LinkOnlineState link_online_state_from_string(const char *s) _pure_;
+
 typedef struct LinkOperationalStateRange {
         LinkOperationalState min;
         LinkOperationalState max;
diff --git a/src/libsystemd/sd-network/sd-network.c b/src/libsystemd/sd-network/sd-network.c
index b190e8f881..552ec381b6 100644
--- a/src/libsystemd/sd-network/sd-network.c
+++ b/src/libsystemd/sd-network/sd-network.c
@@ -56,6 +56,10 @@ _public_ int sd_network_get_ipv6_address_state(char **state) {
         return network_get_string("IPV6_ADDRESS_STATE", state);
 }
 
+_public_ int sd_network_get_online_state(char **state) {
+        return network_get_string("ONLINE_STATE", state);
+}
+
 static int network_get_strv(const char *key, char ***ret) {
         _cleanup_strv_free_ char **a = NULL;
         _cleanup_free_ char *s = NULL;
@@ -204,6 +208,10 @@ _public_ int sd_network_link_get_ipv6_address_state(int ifindex, char **state) {
         return network_link_get_string(ifindex, "IPV6_ADDRESS_STATE", state);
 }
 
+_public_ int sd_network_link_get_online_state(int ifindex, char **state) {
+        return network_link_get_string(ifindex, "ONLINE_STATE", state);
+}
+
 _public_ int sd_network_link_get_dhcp6_client_iaid_string(int ifindex, char **iaid) {
         return network_link_get_string(ifindex, "DHCP6_CLIENT_IAID", iaid);
 }