Skip to content

Commit

Permalink
Update the man page entry for the countme option
Browse files Browse the repository at this point in the history
Make it a bit more explanatory, format the age buckets as a table and
reflect the changes from the libdnf PR #1662.
  • Loading branch information
dmnks authored and jan-kolarik committed Jun 11, 2024
1 parent f211e1a commit a8c77bb
Showing 1 changed file with 44 additions and 17 deletions.
61 changes: 44 additions & 17 deletions doc/conf_ref.rst
Original file line number Diff line number Diff line change
Expand Up @@ -858,23 +858,50 @@ configuration.
``countme``
:ref:`boolean <boolean-label>`

Determines whether a special flag should be added to a single, randomly
chosen metalink/mirrorlist query each week.
This allows the repository owner to estimate the number of systems
consuming it, by counting such queries over a week's time, which is much
more accurate than just counting unique IP addresses (which is subject to
both overcounting and undercounting due to short DHCP leases and NAT,
respectively).

The flag is a simple "countme=N" parameter appended to the metalink and
mirrorlist URL, where N is an integer representing the "longevity" bucket
this system belongs to.
The following 4 buckets are defined, based on how many full weeks have
passed since the beginning of the week when this system was installed: 1 =
first week, 2 = first month (2-4 weeks), 3 = six months (5-24 weeks) and 4
= more than six months (> 24 weeks).
This information is meant to help distinguish short-lived installs from
long-term ones, and to gather other statistics about system lifecycle.
When enabled, one (and only one) HTTP GET request for the metalink file
will be selected at random every week to carry a special URL flag.

This flag allows the repository provider to estimate the number of systems
consuming the repository, by counting such requests over a week's time.
This method is more accurate than just counting unique IP addresses (which
is subject to both overcounting and undercounting due to short DHCP leases
and NAT, respectively).

This is *not* an out-of-band HTTP request made for this purpose alone.
Only requests initiated by DNF during normal operation, such as to check
for metadata updates, can get this flag.

The flag is a simple "countme=N" parameter appended to the metalink URL
where N is an integer representing the age "bucket" this system belongs to.
Four buckets are defined, based on how many full weeks have passed since
the installation of a system:

====== ===============================
bucket system age
====== ===============================
1 first week
2 first month (2 - 4 weeks)
3 first 6 months (5 - 24 weeks)
4 more than 6 months (> 24 weeks)
====== ===============================

This number is meant to help distinguish short-lived (throwaway) machines
from long-term installs and get a better picture of how systems are used
over time.

To determine a system's installation time ("epoch"), the ``machine-id(5)``
file's modification time is used as the single source of truth. This file
is semantically tied to the system's lifetime as it's typically populated
at installation time or during the first boot by an installer tool or init
system (such as ``systemd(1)``), respectively, and remains unchanged.

If the file is empty or missing (such as in containers), the time of the
very first request made using the expanded metalink URL (i.e. with any
repository variables such as ``$releasever`` substituted) that carried the
flag is declared as the epoch.

If no metalink URL is defined for this repository but a mirrorlist URL is,
the latter is used for this purpose instead.

Default is False.

Expand Down

0 comments on commit a8c77bb

Please sign in to comment.