# NAME

select-debian-mirror - dynamically select the best nearby Debian mirror

# SYNOPSIS

**select-debian-mirror** \[**--verbose**\] \[**--n-top-sites**=_N_\] \[**--use-default-on-error**\] {**rsync**|**http**}

**select-debian-mirror** \[**--test-mirror-status-down**\] \[**--test-master-list-down**\] \[**--use-default-on-error**\] {**rsync**|**http**}

# DESCRIPTION

**select-debian-mirror** selects the best Debian package mirror for use
as an upstream sync source. It works by scraping the mirror health
scores from the Debian mirror-master status page and cross-referencing
them with the Mirrors.masterlist to identify mirrors in eligible
countries that support the requested protocol.

Mirrors whose score meets or exceeds the score cutoff (currently 90% of
the maximum score) are collected as candidates. From those candidates,
the top _N_ are selected at random (default 1) and printed to standard
output, one hostname per line.

By default, if any problem occurs -- the mirror-master site is
unreachable or times out (default 10 seconds), a fetched page parses to
zero entries, or no mirror passes the score cutoff -- the script prints
a diagnostic to standard error and exits with a non-zero status. Pass
**--use-default-on-error** to instead print a randomly-chosen entry from
a built-in fallback list of known-good mirrors and exit 0.

# ARGUMENTS

- **rsync**|**http**

    The sync protocol to use.  This determines which mirrors are eligible:
    only mirrors that advertise `Archive-rsync` or `Archive-http` in the
    Debian Mirrors.masterlist are considered.  Required.

# OPTIONS

- **--verbose**

    Print debug information to standard error.  This includes fetch
    progress, the number of mirrors parsed, which mirrors were skipped and
    why, the full ranked candidate list with scores and country codes, and
    which mirror(s) were randomly selected.

- **--n-top-sites**=_N_

    Return the top _N_ sites by score, chosen in random order.  Default
    is 1.  If fewer than _N_ candidates are available, all candidates are
    returned.

- **--use-default-on-error**

    On any error (fetch failure, empty parse, or no mirror passing the
    score cutoff), print a randomly-chosen entry from the built-in
    fallback list of mirrors and exit 0 instead of exiting non-zero. A
    warning is still written to standard error.

- **--test-mirror-status-down**

    Simulate the mirror status page being unreachable. The script will
    treat this as a fetch failure: exit non-zero by default, or use the
    fallback list if **--use-default-on-error** is also given.

- **--test-master-list-down**

    Simulate the Mirrors.masterlist being unreachable. The script will
    treat this as a fetch failure: exit non-zero by default, or use the
    fallback list if **--use-default-on-error** is also given.

# EXIT STATUS

- **0**

    A mirror was successfully selected from live data, or
    **--use-default-on-error** was given and a fallback mirror was printed.

- **1**

    Live mirror data could not be obtained (fetch failure, the data parsed
    to zero entries, or no mirror passed the score cutoff) and
    **--use-default-on-error** was not given.

- **2**

    Invalid command-line arguments (set by **argparse**).

# EXAMPLES

Select a single mirror for rsync:

    $ select-debian-mirror rsync
    debian.csail.mit.edu

Select 3 top mirrors for HTTP with verbose output:

    $ select-debian-mirror --verbose --n-top-sites=3 http
    mirror.us.leaseweb.net
    mirrors.xtom.com
    debian.csail.mit.edu

Simulate a fetch failure in strict mode (exits 1):

    $ select-debian-mirror --test-mirror-status-down rsync
    Error: could not fetch mirror data: ...

Same simulated failure, but fall back to a built-in mirror instead:

    $ select-debian-mirror --use-default-on-error --test-mirror-status-down rsync
    Warning: could not fetch mirror data: ...; using fallback
    debian.csail.mit.edu

# CONFIGURATION

The following parameters are defined as constants in the script and can
be edited directly:

- **SCORE\_CUTOFF**

    A value between 0.0 and 1.0 representing the minimum acceptable score
    as a fraction of the maximum score (100.0).  Default is 0.90.

- **ELIGIBLE\_COUNTRIES**

    A list of two-letter country codes.  Only mirrors in these countries are
    considered.  Default is `['CA', 'US']`.

- **FALLBACK\_MIRRORS**

    A static list of mirror hostnames used when the mirror-master site
    cannot be reached.

- **FETCH\_TIMEOUT**

    Timeout in seconds for HTTP requests to the mirror-master site.
    Default is 10.

# DATA SOURCES

- [https://mirror-master.debian.org/status/mirror-status.html](https://mirror-master.debian.org/status/mirror-status.html)

    The Debian mirror status page, which provides health scores for each
    mirror.

- [https://mirror-master.debian.org/status/Mirrors.masterlist](https://mirror-master.debian.org/status/Mirrors.masterlist)

    The Debian Mirrors.masterlist, which provides country, protocol, and
    other metadata for each mirror.

# AUTHOR

Claude Code directed by Adam H. Lewenberg <adamhl@stanford.edu>
