fast-apt-mirror.sh

Feedback and high-quality pull requests are highly welcome!

1. What is it?
2. Usage as GitHub Action
3. Usage on the commandline
   1. Installation
   2. current command
   3. find command
   4. set command
4. Alternatives
5. License

What is it?

fast-apt-mirror.sh is a self-contained Bash script that helps you to easily and quickly determine and configure a fast APT repository mirror on Debian, Ubuntu, Pop!_OS, Kali systems.

It was born out of the ongoing stability issues with the azure.archive.ubuntu.com Ubuntu mirror pre-configured in GitHub Actions runners.

Usage as GitHub Action

name: Build
on: [ push, pull_request ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Configure Fast APT Mirror
      uses: vegardit/fast-apt-mirror.sh@v1
      with: # the following parameters are listed with their action default values and are optional
        healthchecks:  20 # Number of mirrors from the mirrors list to check for availability and up-to-dateness
        speedtests:    10 # Maximum number of healthy mirrors to test for speed
        parallel:       2 # Number of parallel speed tests
        sample-size: 1024 # Number of kilobytes to download during the speed from each mirror
        sample-time:    3 # Maximum number of seconds within the sample download from a mirror must finish
        country:       "" # The country code for selecting Ubuntu mirrors. If not set, defaults to http://mirrors.ubuntu.com/mirrors.txt
        exclude-current: false # If set to "true", don't include the current APT mirror in the speed tests

The action output will look like this:

Current mirror: http://azure.archive.ubuntu.com/ubuntu/ (/etc/apt/sources.list)
Randomly selecting 20 mirrors...done
Checking health status of 20 mirrors....................done
 -> 17 mirrors are reachable and up-to-date
Speed testing 10 of the available 17 mirrors (sample download size: 1024KB)..........done
 -> http://azure.archive.ubuntu.com/ubuntu/ (85MB/s) determined as fastest mirror within 4 seconds
 -> http://pubmirrors.dal.corespace.com/ubuntu/ (3.7MB/s)
 -> http://mirrors.xmission.com/ubuntu/ (3.0MB/s)
 -> http://www.gtlib.gatech.edu/pub/ubuntu/ (2.0MB/s)
 -> http://mirrors.rit.edu/ubuntu/ (1.8MB/s)
 -> http://ubuntu.cs.utah.edu/ubuntu/ (1.8MB/s)
 -> https://mirror.us.leaseweb.net/ubuntu/ (1.6MB/s)
 -> https://mirrors.iu13.net/ubuntu/ (1.5MB/s)
 -> http://mirrors.syringanetworks.net/ubuntu-archive/ (1.4MB/s)
 -> https://mirrors.bloomu.edu/ubuntu/ (1.1MB/s)
Current mirror: http://azure.archive.ubuntu.com/ubuntu/ (/etc/apt/sources.list)
Nothing to do, already using: http://azure.archive.ubuntu.com/ubuntu/

Usage on the command line

Installation

For example:

# install pre-reqs for HTTPS mirror coverage: curl and CA certificates for apt
$ sudo apt-get install -y curl ca-certificates

# install fast-apt-mirror.sh under /usr/local/bin/ to make it automatically available via $PATH
$ sudo curl https://raw.githubusercontent.com/vegardit/fast-apt-mirror.sh/v1/fast-apt-mirror.sh -o /usr/local/bin/fast-apt-mirror.sh
$ sudo chmod 755 /usr/local/bin/fast-apt-mirror.sh

# show the help
$ fast-apt-mirror.sh --help
fast-apt-mirror.sh COMMAND

Available commands:
 current - Prints the currently configured APT mirror.
 find    - Finds and prints the URL of a fast APT mirror and optionally applies it using the 'fast-apt-mirror.sh set' command.
 set     - Configures the given APT mirror in /etc/apt/sources.list and runs 'sudo apt-get update'.

The current sub command

Determines the currently effective APT mirror.

$ fast-apt-mirror.sh current
Current mirror: http://artfiles.org/ubuntu

Capture the current mirror URL in a variable:

$ current_mirror=$(fast-apt-mirror.sh current)
$ echo $current_mirror
http://artfiles.org/ubuntu

The find sub command

Determines and prints the URL of a fast APT mirror and optionally activates it.

The find command prefers curl, but it can fall back to python3 when curl is not installed and Python can complete HTTPS requests with certificate validation.

Usage:

fast-apt-mirror.sh find [OPTION]...

Options:
     --apply             - Replaces the current APT mirror in /etc/apt/(sources.list|sources.list.d/system.sources) with a fast mirror and runs 'sudo apt-get update'
     --country CODE      - The country code to use for selecting mirrors. NOTE: Only applies to Ubuntu based distros. Defaults to http://mirrors.ubuntu.com/mirrors.txt
     --exclude-current   - If specified, don't include the current APT mirror in the speed tests.
     --healthchecks N    - Number of mirrors from the mirrors list to check for availability and up-to-dateness - default is 20
     --ignore-sync-state - Don't check up-to-dateness of mirrors as part of healthchecks
     --speedtests N      - Maximum number of healthy mirrors to test for speed - default is 5
 -p, --parallel N        - Number of parallel speed tests. May result in incorrect results because of competing connections but finds a suitable mirror faster.
     --sample-size KB    - Number of kilobytes to download during the speed from each mirror - default is 200KB
     --sample-time SECS  - Maximum number of seconds within the sample download from a mirror must finish - default is 3
 -v, --verbose           - More output. Specify multiple times to increase verbosity.

Finding a fast mirror:

$ fast-apt-mirror.sh find

Current mirror: http://artfiles.org/ubuntu/
Randomly selecting 20 mirrors...done
Checking sync status of 20 mirrors....................done
 -> 20 mirrors are reachable and up-to-date
Speed testing 5 of the available 20 mirrors (sample download size: 200KB).....done
 -> https://mirror.netzwerge.de/ubuntu/ (1470 KB/s) determined as fastest mirror within 4 seconds

Capturing the determined mirror URL in a variable

$ fast_mirror=$(fast-apt-mirror.sh find)
$ echo $fast_mirror
https://mirror.netzwerge.de/ubuntu/

Finding and activating a fast mirror:

$ fast-apt-mirror.sh find --apply

Current mirror: http://azure.archive.ubuntu.com/ubuntu/
Randomly selecting 20 mirrors...done
Checking sync status of 20 mirrors....................done
 -> 20 mirrors are reachable and up-to-date
Speed testing 5 of the available 20 mirrors (sample download size: 200KB).....done
 -> https://ubuntu.mirror.shastacoe.net/ubuntu/ (2409 KB/s) determined as fastest mirror within 6 seconds
Current mirror: http://azure.archive.ubuntu.com/ubuntu/
Creating backup /etc/apt/sources.list.bak.20230207_211544
Changing mirror from [http://azure.archive.ubuntu.com/ubuntu/] to [https://ubuntu.mirror.shastacoe.net/ubuntu/]...
Hit:1 https://packages.microsoft.com/ubuntu/20.04/prod focal InRelease
Get:2 https://ubuntu.mirror.shastacoe.net/ubuntu focal InRelease [265 kB]
....
Fetched 27.1 MB in 5s (5915 kB/s)
Reading package lists... Done

The set sub command

Finds and prints the URL of a fast APT mirror and optionally applies it using the fast-apt-mirror.sh set command.

Usage:

fast-apt-mirror.sh set MIRROR_URL

Parameters:
  MIRROR_URL - the APT mirror URL to configure.

Example:

$ fast-apt-mirror.sh set https://mirrors.xtom.com/ubuntu/

Current mirror: http://azure.archive.ubuntu.com/ubuntu/
Creating backup /etc/apt/sources.list.bak.20230207_211544
Changing mirror from [http://azure.archive.ubuntu.com/ubuntu/] to [https://mirrors.xtom.com/ubuntu/]...
Hit:1 https://packages.microsoft.com/ubuntu/20.04/prod focal InRelease
Get:2 https://ubuntu.mirror.shastacoe.net/ubuntu focal InRelease [265 kB]....
...
Fetched 26.9 MB in 5s (4211 kB/s)
Reading package lists... Done

Alternatives

Here is a list of possible alternative which didn't work for us for one reason or another:

• apt-spy2 https://github.com/lagged/apt-spy2 (Ruby based, actively maintained)
• apt-select https://github.com/jblakeman/apt-select (Python based, last commit 11/2019)
• apt-smart https://github.com/martin68/apt-smart (Python based, last commit 05/2020)
• apt-spy https://github.com/scanepa/apt-spy (C based, last commit 01/2012, repo is archived)
• getfastmirror https://github.com/hychen/getfastmirror (Python based, last commit 07/2010)
• python-apt-mirror-updater https://github.com/xolox/python-apt-mirror-updater (Python based, last commit 09/2021)
• netselect-apt https://github.com/apenwarr/netselect/blob/master/netselect-apt (Bash based, 10/2010, Limitations)

License

All files are released under the Apache License 2.0.

Individual files contain the following tag instead of the full license text:

SPDX-License-Identifier: Apache-2.0

This enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/.