@@ -408,29 +408,74 @@ from ipv4.connman.net (for IPv4 connectivity) and ipv6.connman.net
(for IPv6 connectivity). The used URL looks like this
http://ipv{4|6}.connman.net/online/status.html
-When an online check request fails, another one is triggered after a
-longer interval. The intervals follows one of two mathemetical
-sequences, depending on the "OnlineCheckIntervalStyle" setting:
-"fibonacci" or "geometric", with a default of "geometric". The
-geometric setting is the square series of numbers in the range
-specified by "OnlineCheckInitialInterval" and "OnlineCheckMaxInterval".
-The default values for "OnlineCheckInitialInterval" and
-"OnlineCheckMaxInterval" are the range [1, 12], which correspond to the
-following "geometric" intervals, in seconds: 1, 4, 9, 16, 25, 36, 49, 64,
-81, 100, 121 and 144 over that range. By contrast, the correspending
-"fibonacci" sequence over that range is 1, 1, 2, 3, 5, 8, 13, 21, 34, 55,
-89, and 144. The "fibonacci" series and style is more aggressive in check
-rate up to 12 steps (its equivalence point with "geometric" at 144 seconds)
-than "geometric" but backs off far more aggressively past that point
-reaching an hour at interval 19 which "geometric" does not reach until
-interval 60.
-
-See connman.conf(5) for the EnableOnlineCheck option, if you need to
-disable the feature.
-It is also possible to specify other URLs via OnlineCheckIPv4URL and
-OnlineCheckIPv6URL options.
-The range of intervals between two online check requests can be fine-tuned
-via OnlineCheckInitialInterval and OnlineCheckMaxInterval options.
+The online check operates in one of three modes:
+
+ * "none"
+ * "one-shot"
+ * "continuous"
+
+where "one-shot" is the default and is governed by the
+"OnlineCheckMode" setting.
+
+In "none" mode, there are no "online" HTTP-based Internet
+reachability checks. Any connected service and the manager state
+will terminate at the Ready state and will not progress to
+Online.
+
+In "one-shot", the default mode, there is a single, one-shot "online"
+HTTP-based Internet reachability check for the default service (that
+is, the service with the high-priority (metric 0) gateway default
+route). When the check succeeds, the associated service and the
+manager state will terminate at the "online" state. When the check
+fails, subsequent checks will be rescheduled according to
+"OnlineCheckIntervalStyle", "OnlineCheckInitialInterval", and
+"OnlineCheckMaxInterval" and will continue indefinitely until one
+succeeds or until the service is disconnected.
+
+In "continuous" mode, there are ongoing "online" HTTP-based Internet
+reachability checks for the default service (that is, the service with
+the high-priority (metric 0) gateway default route). As with
+"one-shot" mode, when the first check succeeds, the associated service
+and the manager state will terminate at the Online state. Thereafter,
+subsequent checks will be scheduled according to
+"OnlineCheckIntervalStyle" and "OnlineCheckMaxInterval". When the
+check fails, subsequent checks will be rescheduled according to
+"OnlineCheckIntervalStyle", "OnlineCheckInitialInterval", and
+"OnlineCheckMaxInterval". When and if "OnlineCheckFailuresThreshold"
+is met, the service and manager state will be demoted to Ready and the
+service will have its "Error" property set to "online-check-failed"
+while subsequent checks will continue. In the interim, if available,
+another service may be promoted to the default service and online
+checks will be initiated for it. When and if, for the demoted service,
+"OnlineCheckSuccessesThreshold" is met, the service "Error" property
+will be cleared and the service state promoted to Online, potentially
+causing it to become the default service again.
+
+See connman.conf(5) for the "OnlineCheckMode" option, if you need to
+disable the feature. It is also possible to specify other URLs via
+"OnlineCheckIPv4URL" and "OnlineCheckIPv6URL" options. The range of
+intervals between two online check requests can be fine-tuned via
+"OnlineCheckInitialInterval" and "OnlineCheckMaxInterval" options as
+well as with the "OnlineCheckIntervalStyle" option.
+
+As intimated above, for the "one-shot" and "continuous" modes, when an
+online check request fails (or, in the case of "continuous" mode,
+succeeds as well), another one is triggered after a longer
+interval. The intervals follows one of two mathemetical sequences,
+depending on the "OnlineCheckIntervalStyle" setting: "fibonacci" or
+"geometric", with a default of "geometric". The geometric setting is
+the square series of numbers in the range specified by
+"OnlineCheckInitialInterval" and "OnlineCheckMaxInterval". The
+default values for "OnlineCheckInitialInterval" and
+"OnlineCheckMaxInterval" are the range [1, 12], which correspond to
+the following "geometric" intervals, in seconds: 1, 4, 9, 16, 25, 36,
+49, 64, 81, 100, 121 and 144 over that range. By contrast, the
+correspending "fibonacci" sequence over that range is 1, 1, 2, 3, 5,
+8, 13, 21, 34, 55, 89, and 144. The "fibonacci" series and style is
+more aggressive in check rate up to 12 steps (its equivalence point
+with "geometric" at 144 seconds) than "geometric" but backs off far
+more aggressively past that point reaching an hour at interval 19
+which "geometric" does not reach until interval 60.
During the online check procedure, ConnMan will temporarily install
a host route to both the ipv4.connman.net and ipv6.connman.net so that
@@ -223,9 +223,8 @@ default one, in replacement.
Default value is false.
.TP
.BI OnlineCheckFailuresThreshold= failures
-When both \fBEnableOnlineCheck\fR and
-\fBEnableOnlineToReadyTransition\fR are asserted, this is the number
-of failed back-to-back "ready" to "online" HTTP-based Internet
+When \fBOnlineCheckMode\fR is "continuous", this is the number of
+failed back-to-back "ready" to "online" HTTP-based Internet
reachability checks that will be allowed before marking a service as
"failed" from a reachability perspective, sorting it at a lower
priority than other services not so marked.
@@ -234,16 +233,14 @@ Lower values may result in higher-frequency network service cycling
while higher values may result in a longer period of time before
failing from a non-Internet reachable service to one that might be.
-See \fBOnlineCheckIntervalStyle\fR, \fBOnlineCheckInitialInterval\fR,
-and \fBOnlineCheckMaxInterval\fR for other values that influence
-network service failure/recovery transition time.
-
+See \fBOnlineCheckIntervalStyle\fR, \fBOnlineCheckInitialInterval\fR, and
+\fBOnlineCheckMaxInterval\fR for other values that influence network
+service failure/recovery transition time.
The default value is 6.
.TP
.BI OnlineCheckSuccessesThreshold= successes
-When both \fBEnableOnlineCheck\fR and
-\fBEnableOnlineToReadyTransition\fR are asserted, this is the number
-of successful back-to-back "ready" to "online" HTTP-based Internet
+When \fBOnlineCheckMode\fR is "continuous", this is the number of
+successful back-to-back "ready" to "online" HTTP-based Internet
reachability checks that must be met before clearing a service as
"failed" from a reachability perspective and allowing it to transition
to the "online" state again, allowing it to sort back to a higher
@@ -254,9 +251,9 @@ while higher values may result in a longer period of time before
transitioning back to more a preferred, Internet reachable network
service.
-See \fBOnlineCheckIntervalStyle\fR, \fBOnlineCheckInitialInterval\fR,
-and \fBOnlineCheckMaxInterval\fR for other values that influence
-network service failure/recovery transition time.
+See \fBOnlineCheckIntervalStyle\fR, \fBOnlineCheckInitialInterval\fR, and
+\fBOnlineCheckMaxInterval\fR for other values that influence network
+service failure/recovery transition time.
The default value is 6.
.TP
@@ -116,11 +116,51 @@
# section 4.1).
# Enable6to4 = false
-# Enable use of http get as on online status check.
-# When a service is in a READY state, and is selected as default,
-# ConnMan will issue an HTTP GET request to verify that end-to-end
-# connectivity is successful. Only then the service will be
-# transitioned to ONLINE state.
+# This indicates the "online" HTTP-based Internet reachability check
+# mode. Possible values are "none", "one-shot", "continuous".
+#
+# In "none" mode, there are no "online" HTTP-based Internet
+# reachability checks. Any connected service and the manager state
+# will terminate at the "ready" state and will not progress to
+# "online".
+#
+# In "one-shot" mode, there is a single, one-shot "online" HTTP-based
+# Internet reachability check for the default service. When the check
+# succeeds, the associated service and the manager state will
+# terminate at the "online" state. When the check fails, subsequent
+# checks will be rescheduled according to "OnlineCheckIntervalStyle",
+# "OnlineCheckInitialInterval", and "OnlineCheckMaxInterval" and will
+# continue indefinitely until one succeeds or until the service is
+# disconnected.
+#
+# In "continuous" mode, there are ongoing "online" HTTP-based Internet
+# reachability check for the default service. As with "one-shot" mode,
+# when the first check succeeds, the associated service and the
+# manager state will terminate at the "online" state. Thereafter,
+# subsequent checks will be scheduled according to
+# "OnlineCheckIntervalStyle" and "OnlineCheckMaxInterval". When the
+# check fails, subsequent checks will be rescheduled according to
+# "OnlineCheckIntervalStyle", "OnlineCheckInitialInterval", and
+# "OnlineCheckMaxInterval". When and if "OnlineCheckFailuresThreshold"
+# is met, the service and manager state will be demoted to "ready" and
+# the service will have its "Error" property set to
+# "online-check-failed" while subsequent checks will continue. In the
+# interim, if available, another service may be promoted to the
+# default service and online checks will be initiated for it. When and
+# if, for the demoted service, "OnlineCheckSuccessesThreshold" is met,
+# the service "Error" property will be cleared and the service state
+# promoted to "online", potentially causing it to become the default
+# service again.
+# Default value is "one-shot".
+# OnlineCheckMode = one-shot
+
+# NOTE: This setting is deprecated; use "OnlineCheckMode" instead with
+# a value of "one-shot" or "none".
+# Enable the use of "online" HTTP-baesd Internet reachability check as
+# an online status check. When a service is in a READY state, and is
+# selected as default, ConnMan will issue an HTTP GET request to
+# verify that end-to-end connectivity is successful. Only then the
+# service will be transitioned to ONLINE state.
# If this setting is false, the default service will remain in READY state.
# Default value is true.
# EnableOnlineCheck = false
@@ -147,24 +187,28 @@
# OnlineCheckInitialInterval = 1
# OnlineCheckMaxInterval = 12
-# WARNING: Experimental feature!!!
-# In addition to EnableOnlineCheck setting, enable or disable use of HTTP GET
-# to detect the loss of end-to-end connectivity.
-# If this setting is false, when the default service transitions to ONLINE
-# state, the HTTP GET request is no more called until next cycle, initiated
-# by a transition of the default service to DISCONNECT state.
-# If this setting is true, the HTTP GET request keeps beeing called to guarantee
-# that end-to-end connectivity is still successful. If not, the default service
-# will transition to READY state, enabling another service to become the
-# default one, in replacement.
+# NOTE: This setting is deprecated; use "OnlineCheckMode" instead with
+# a value of "continuous" or "none".
+# In addition to the "EnableOnlineCheck" setting, enable or disable
+# continuous use of "online" HTTP-based Internet reachability checks
+# to detect the loss of end-to-end connectivity.
+# If this setting is false, when the default service transitions to
+# ONLINE state, the "online" HTTP-based Internet reachability check is
+# terminated until a transition of the default service to DISCONNECT
+# state.
+# If this setting is true, the "online" HTTP-based Internet
+# reachability checks continue to be rescheduled to guarantee that
+# end-to-end connectivity is still successful. If not, the default
+# service will transition to READY state, enabling another service to
+# become the default one, in replacement.
# EnableOnlineToReadyTransition = false
# When both "EnableOnlineCheck" and "EnableOnlineToReadyTransition"
-# are asserted, this is the number of failed back-to-back "ready" to
-# "online" HTTP-based Internet reachability checks that will be
-# allowed before marking a service as "failed" from a reachability
-# perspective, sorting it at a lower priority than other services not
-# so marked.
+# are asserted or "OnlineCheckMode" is "continuous", this is the
+# number of failed back-to-back "ready" to "online" HTTP-based
+# Internet reachability checks that will be allowed before marking a
+# service as "failed" from a reachability perspective, sorting it at a
+# lower priority than other services not so marked.
#
# Lower values may result in higher-frequency network service cycling
# while higher values may result in a longer period of time before
@@ -178,12 +222,12 @@
# OnlineCheckFailuresThreshold=6
# When both "EnableOnlineCheck" and "EnableOnlineToReadyTransition"
-# are asserted, this is the number of successful back-to-back "ready"
-# to "online" HTTP-based Internet reachability checks that must be met
-# before clearing a service as "failed" from a reachability
-# perspective and allowing it to transition to the "online" state
-# again, allowing it to sort back to a higher priority relative to
-# other network services.
+# are asserted or "OnlineCheckMode" is "continuous", this is the
+# number of successful back-to-back "ready" to "online" HTTP-based
+# Internet reachability checks that must be met before clearing a
+# service as "failed" from a reachability perspective and allowing it
+# to transition to the "online" state again, allowing it to sort back
+# to a higher priority relative to other network services.
#
# Lower values may result in higher-frequency network service cycling
# while higher values may result in a longer period of time before
@@ -211,9 +255,13 @@
# interval of 6, the time, in seconds, is 8 seconds.
#
# "fibonacci" is more aggressive in check rate up to 12 steps (its
-# equivalence point with "geometric" at 144 seconds) but is far less
-# aggressive past that point, reacing an hour at interval 19 compared
-# to "geometric" which does not reach an hour until interval 60.
+# equivalence point with "geometric" at 144 seconds) than "geometric"
+# and yields quicker recovery for transient failures. For example, for
+# an "OnlineCheckSuccessesThreshold" of six (6), "fibonacci" gets the
+# failing service back to "online" in 20 seconds versus 91 seconds for
+# "geometric". By comparison, past 12 steps, "fibonacci" backs off far
+# more aggressively, which is less wasteful, particularly for a
+# metered interface like Cellular, when the failures are more enduring.
#
# Default value is "geometric".
# OnlineCheckIntervalStyle=geometric