reflector

2024-05-17 22:37 UTC
  • Xyne

Metadata

Description: A Python 3 module and script to retrieve and filter the latest Pacman mirror list.
Latest Version: 2023
Source Code: src/
Architecture:
  • any
Dependencies:
  • python3
Build Dependencies:
  • python-setuptools
Optional Dependencies:
  • rsync: rate rsync mirrors
Arch Repositories:
  • [community]
  • [xyne-any]
  • [xyne-i686]
  • [xyne-x86_64]
Arch Forum Thread: 115714
Tags:

About

Reflector retrieves information from archlinux.org’s Mirror Status service via the JSON interface and filters servers based on user options to generate Pacman mirrorlists. Please see reflector --help for details.

Acknowledgement

Thanks to Pierre for creating the previous MirrorStatus interface for Reflector on archlinux.de.

REFLECTOR(1)

Name

reflector - retrieve and filter the latest Pacman mirrorlist

Synopsis

reflector [arguments]

Description

reflector is a Python script and associated Python module that can retrieve up-to-date Arch Linux mirror data from the Mirror Status web interface.

Arguments

See reflector --help.

Examples

Print the latest mirrorlist to STDOUT:

reflector

Sort the five most recently synchronized mirrors by download speed and overwrite the local mirrorlist:

reflector --latest 5 --sort rate --save /etc/pacman.d/mirrorlist

Select the 200 most recently synchronized HTTP or HTTPS mirrors, sort them by download speed, and overwrite the file /etc/pacman.d/mirrorlist:

reflector --latest 200 --protocol http,https --sort rate --save /etc/pacman.d/mirrorlist

Select the HTTPS mirrors synchronized within the last 12 hours and located in either France or Germany, sort them by download speed, and overwrite the file /etc/pacman.d/mirrorlist with the results:

reflector --country France,Germany --age 12 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

Systemd Integration

Reflector includes systemd service and timer units that can be used to automatically update Pacman’s mirrorlist. To use the timer, edit the configuration file at /etc/xdg/reflector/reflector.conf and then enable the timer with

systemctl enable reflector.timer
systemctl start reflector.timer

Check that status with systemctl list-timers. To update the mirrorlist immediately instead of waiting for the scheduled operation, run systemctl start reflector.service.

See Also

pacman(8)

Help Message

$ reflector --help

usage: reflector [-h] [--connection-timeout n] [--download-timeout n]
                 [--list-countries] [--cache-timeout n] [--url URL]
                 [--save <filepath>] [--sort {age,rate,country,score,delay}]
                 [--threads n] [--verbose] [--info] [-a n] [--delay n]
                 [-c <country name or code>] [-f n] [-i <regex>] [-x <regex>]
                 [-l n] [--score n] [-n n] [-p <protocol>]
                 [--completion-percent [0-100]] [--isos] [--ipv4] [--ipv6]

retrieve and filter a list of the latest Arch Linux mirrors

options:
  -h, --help            show this help message and exit
  --connection-timeout n
                        The number of seconds to wait before a connection
                        times out. Default: 5
  --download-timeout n  The number of seconds to wait before a download times
                        out. Default: 5
  --list-countries      Display a table of the distribution of servers by
                        country.
  --cache-timeout n     The cache timeout in seconds for the data retrieved
                        from the Arch Linux Mirror Status API. The default is
                        300.
  --url URL             The URL from which to retrieve the mirror data in JSON
                        format. If different from the default, it must follow
                        the same format. Default:
                        https://archlinux.org/mirrors/status/json/
  --save <filepath>     Save the mirrorlist to the given path.
  --sort {age,rate,country,score,delay}
                        Sort the mirrorlist. "age": last server
                        synchronization; "rate": download rate; "country":
                        country name, either alphabetically or in the order
                        given by the --country option; "score": MirrorStatus
                        score; "delay": MirrorStatus delay.
  --threads n           Use n threads for rating mirrors. This option will
                        speed up the rating step but the results will be
                        inaccurate if the local bandwidth is saturated at any
                        point during the operation. If rating takes too long
                        without this option then you should probably apply
                        more filters to reduce the number of rated servers
                        before using this option.
  --verbose             Print extra information to STDERR. Only works with
                        some options.
  --info                Print mirror information instead of a mirror list.
                        Filter options apply.

filters:
  The following filters are inclusive, i.e. the returned list will only
  contain mirrors for which all of the given conditions are met.

  -a n, --age n         Only return mirrors that have synchronized in the last
                        n hours. n may be an integer or a decimal number.
  --delay n             Only return mirrors with a reported sync delay of n
                        hours or less, where n is a float. For example. to
                        limit the results to mirrors with a reported delay of
                        15 minutes or less, pass 0.25.
  -c <country name or code>, --country <country name or code>
                        Restrict mirrors to selected countries. Countries may
                        be given by name or country code, or a mix of both.
                        The case is ignored. Multiple countries may be
                        selected using commas (e.g. --country France,Germany)
                        or by passing this option multiple times (e.g. -c fr
                        -c de). Use "--list-countries" to display a table of
                        available countries along with their country codes.
                        When sorting by country, this option may also be used
                        to sort by a preferred order instead of
                        alphabetically. For example, to select mirrors from
                        Sweden, Norway, Denmark and Finland, in that order,
                        use the options "--country se,no,dk,fi --sort
                        country". To set a preferred country sort order
                        without filtering any countries. this option also
                        recognizes the glob pattern "*", which will match any
                        country. For example, to ensure that any mirrors from
                        Sweden are at the top of the list and any mirrors from
                        Denmark are at the bottom, with any other countries in
                        between, use "--country 'se,*,dk' --sort country". It
                        is however important to note that when "*" is given
                        along with other filter criteria, there is no
                        guarantee that certain countries will be included in
                        the results. For example, with the options "--country
                        'se,*,dk' --sort country --latest 10", the latest 10
                        mirrors may all be from the United States. When the
                        glob pattern is present, it only ensures that if
                        certain countries are included in the results, they
                        will be sorted in the requested order.
  -f n, --fastest n     Return the n fastest mirrors that meet the other
                        criteria. Do not use this option without other
                        filtering options.
  -i <regex>, --include <regex>
                        Include servers that match <regex>, where <regex> is a
                        Python regular express.
  -x <regex>, --exclude <regex>
                        Exclude servers that match <regex>, where <regex> is a
                        Python regular express.
  -l n, --latest n      Limit the list to the n most recently synchronized
                        servers.
  --score n             Limit the list to the n servers with the highest
                        score.
  -n n, --number n      Return at most n mirrors.
  -p <protocol>, --protocol <protocol>
                        Match one of the given protocols, e.g. "https" or
                        "ftp". Multiple protocols may be selected using commas
                        (e.g. "https,http") or by passing this option multiple
                        times.
  --completion-percent [0-100]
                        Set the minimum completion percent for the returned
                        mirrors. Check the mirrorstatus webpage for the
                        meaning of this parameter. Default value: 100.0.
  --isos                Only return mirrors that host ISOs.
  --ipv4                Only return mirrors that support IPv4.
  --ipv6                Only return mirrors that support IPv6.

CHANGELOG

2020-12-20

  • Added support for setting country sort order with the “–country” option.
  • Added headers to table list displayed with “–list-countries”.

2020-12-07

  • Restored download timeout option.

2020-12-03

  • Removed thread support from mirror speed test to avoid skewing results on saturated connections.
  • Changed the speed test target file to the community database for more reliable results.
  • Addressed some pylint warnings.

2020-08-20

  • Added support for comma-separated values in list arguments (country, protocol).
  • Added support for argument files with the “@” prefix.
  • Added systemd integration (inspired by David Runge’s request (Arch Linux FS#63910) and Silvio Knizek’s “reflector-timer” AUR package.

2019-03-02

  • Refactored code to make it more modular. The MirrorStatus class remains with all of its functions for backwards compatibility but this will either be removed for further refactored in the future.
  • Added --isos, --ipv4 and --ipv6 options.

2017-06-13

  • Added --score option.
  • Remove old-style message formatting.
  • Use logging module instead of custom methods.

2017-01-07

  • case-insensitive country name matching

2014-08-15

  • added --info option for displaying info about each mirror
  • added support for filtering by country code

2013-12-15

  • added code to time rsync downloads (suggested by Teo Guo Ci, implemented with a slightly different approach)
  • get_mirrorlist method now accepts an unquoted command list.
  • updated string formatting commands (e.g. 'foo %s %s' % (x, y) to 'foo {} {}'.format(x, y))
  • changed format of generated mirrorlist header
  • fixed help message for --verbose (STDOUT -> STDERR)

2013-01-04

  • added --include and --exclude filter options
  • removed --grep option (replaced by --include)

2012-06-28

  • added JSON data caching to avoid redundant connections to archlinux.org
  • added --connection-timeout and --cache-timeout options

2012-03-24

  • added “delay” and “score” to sort options

2011-03-25

  • rewritten in Python 3 following the deprecation of the perl-xyne-arch package
Contact
echo xyne.archlinux.org | sed 's/\./@/'
Validation
XHTML 1.0 Strict CSS level 3 Atom 1.0