272 lines
8.5 KiB
Markdown
272 lines
8.5 KiB
Markdown
# FastestMirror 🚀
|
|
|
|
*Because waiting for slow package mirrors is like watching paint dry in a fucking hurricane.*
|
|
|
|
FastestMirror is a blazingly fast, auto-magical tool that finds and configures the fastest package repository mirrors for your Linux distribution. No more suffering through downloads that move slower than continental drift!
|
|
|
|
## Features
|
|
|
|
- **Auto-Detection**: Automatically detects your Linux distribution (because we're not psychic, but we're pretty close)
|
|
- **Concurrent Testing**: Tests multiple mirrors simultaneously using Go's goroutines (multithreading that actually works)
|
|
- **Beautiful Output**: Colorful terminal interface that doesn't make your eyes bleed
|
|
- **Smart Scoring**: Combines speed and latency metrics to find the objectively best mirror
|
|
- **Safe Operations**: Always backs up your config before making changes (we're not monsters)
|
|
- **Wide Support**: Works with major Linux distributions and their families
|
|
|
|
## Supported Distributions
|
|
|
|
| Distribution Family | Distributions | Config File |
|
|
|-------------------|---------------|-------------|
|
|
| **Debian** | Ubuntu, Debian, Mint, Pop!_OS, Elementary, Kali | `/etc/apt/sources.list` |
|
|
| **Arch** | Arch Linux, Manjaro, EndeavourOS, Artix | `/etc/pacman.d/mirrorlist` |
|
|
| **Fedora** | Fedora, CentOS, RHEL, Rocky Linux, AlmaLinux | `/etc/yum.repos.d/` |
|
|
| **openSUSE** | openSUSE, SLES | `/etc/zypp/repos.d/` |
|
|
| **Others** | Gentoo, Alpine, Slackware, Void | Various configs |
|
|
|
|
## Installation
|
|
|
|
### From Binary (Recommended)
|
|
|
|
```bash
|
|
# Download the latest release
|
|
curl -L https://git.gostacks.org/iwasforcedtobehere/fastestmirror/releases/download/latest/fastestmirror-linux-amd64 -o fastestmirror
|
|
|
|
# Make it executable
|
|
chmod +x fastestmirror
|
|
|
|
# Move to your PATH
|
|
sudo mv fastestmirror /usr/local/bin/
|
|
|
|
# Verify it works
|
|
fastestmirror --help
|
|
```
|
|
|
|
### From Source (For the Brave)
|
|
|
|
```bash
|
|
# Clone this beautiful repository
|
|
git clone https://git.gostacks.org/iwasforcedtobehere/fastestmirror.git
|
|
|
|
# Enter the dragon's lair
|
|
cd fastestmirror
|
|
|
|
# Build the damn thing
|
|
go build -o fastestmirror
|
|
|
|
# Install it system-wide
|
|
sudo cp fastestmirror /usr/local/bin/
|
|
```
|
|
|
|
### Package Managers (Coming Soon™)
|
|
|
|
```bash
|
|
# Debian/Ubuntu (when we get our shit together)
|
|
sudo apt install fastestmirror
|
|
|
|
# Arch Linux (AUR package pending)
|
|
yay -S fastestmirror
|
|
|
|
# Fedora (RPM coming soon)
|
|
sudo dnf install fastestmirror
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Find the Fastest Mirrors
|
|
|
|
```bash
|
|
# Basic usage - finds and displays fastest mirrors
|
|
fastestmirror find
|
|
|
|
# Show more results
|
|
fastestmirror find --top 10
|
|
|
|
# Increase timeout for slower connections
|
|
fastestmirror find --timeout 30
|
|
|
|
# Verbose output (because you like details)
|
|
fastestmirror find --verbose
|
|
```
|
|
|
|
### Apply the Fastest Mirror
|
|
|
|
```bash
|
|
# Apply the fastest mirror (requires root)
|
|
sudo fastestmirror apply
|
|
|
|
# See what would happen without making changes
|
|
fastestmirror apply --dry-run
|
|
|
|
# Force application without confirmation (danger zone!)
|
|
sudo fastestmirror apply --force
|
|
|
|
# Use custom backup location
|
|
sudo fastestmirror apply --backup /home/user/my-backup.conf
|
|
```
|
|
|
|
### Other Commands
|
|
|
|
```bash
|
|
# Show version and build info
|
|
fastestmirror version
|
|
|
|
# Show help
|
|
fastestmirror --help
|
|
|
|
# Get help for specific commands
|
|
fastestmirror find --help
|
|
```
|
|
|
|
## Example Output
|
|
|
|
```
|
|
Detecting your Linux distribution...
|
|
Found: Ubuntu 22.04.3 LTS (debian family)
|
|
Loading mirrors for debian family...
|
|
Testing 8 mirrors (timeout: 10s)...
|
|
Testing mirrors ████████████████████████████████████████████████████ 8/8
|
|
|
|
Testing complete! Here are your results:
|
|
|
|
Rank Mirror URL Latency Speed Score
|
|
─────────────────────────────────────────────────────────────────────────────────
|
|
#1 http://mirror.kakao.com/ubuntu/ 45ms 15.2 MB/s 174.2
|
|
#2 http://mirror.math.princeton.edu/pub/ubuntu/ 89ms 12.8 MB/s 139.1
|
|
#3 http://mirrors.kernel.org/ubuntu/ 156ms 8.9 MB/s 95.4
|
|
#4 http://archive.ubuntu.com/ubuntu/ 234ms 6.2 MB/s 66.3
|
|
#5 http://us.archive.ubuntu.com/ubuntu/ 312ms 4.1 MB/s 44.2
|
|
|
|
Winner: http://mirror.kakao.com/ubuntu/
|
|
This bad boy clocks in at 15.2 MB/s with 45ms latency
|
|
|
|
To apply the fastest mirror, run: fastestmirror apply
|
|
```
|
|
|
|
## Configuration
|
|
|
|
FastestMirror works out of the box with sensible defaults, but you can customize its behavior:
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
# Set default timeout (in seconds)
|
|
export FASTESTMIRROR_TIMEOUT=30
|
|
|
|
# Set default number of results to show
|
|
export FASTESTMIRROR_TOP_COUNT=5
|
|
|
|
# Enable verbose output by default
|
|
export FASTESTMIRROR_VERBOSE=true
|
|
```
|
|
|
|
### Config File (Future Feature)
|
|
|
|
```yaml
|
|
# ~/.config/fastestmirror/config.yaml
|
|
timeout: 30
|
|
top_count: 5
|
|
verbose: false
|
|
backup_dir: /etc/fastestmirror/backups
|
|
custom_mirrors:
|
|
debian:
|
|
- "https://my-custom-mirror.example.com/debian/"
|
|
```
|
|
|
|
## How It Works (The Magic Behind the Scenes)
|
|
|
|
1. **Distribution Detection**: Parses `/etc/os-release`, `/etc/lsb-release`, and distribution-specific files to identify your system
|
|
2. **Mirror Discovery**: Uses curated lists of official mirrors for each distribution family
|
|
3. **Concurrent Testing**: Spawns goroutines to test multiple mirrors simultaneously
|
|
4. **Performance Metrics**: Measures both latency (ping-like) and download speed using representative files
|
|
5. **Smart Scoring**: Combines metrics with weighted scoring algorithm to rank mirrors objectively
|
|
6. **Safe Application**: Creates backups before modifying system configuration files
|
|
|
|
## Performance Notes
|
|
|
|
- **Speed Testing**: Downloads small representative files (Release files, database files, etc.)
|
|
- **Timeout Handling**: Respects timeout settings to avoid hanging on dead mirrors
|
|
- **Concurrent Limits**: Limits concurrent connections to avoid overwhelming your network
|
|
- **Retry Logic**: Automatically retries failed tests with exponential backoff
|
|
|
|
## Development
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Install dependencies
|
|
go mod download
|
|
|
|
# Run tests
|
|
go test ./...
|
|
|
|
# Build for current platform
|
|
go build -o fastestmirror
|
|
|
|
# Build for all platforms
|
|
make build-all
|
|
|
|
# Create release packages
|
|
make package
|
|
```
|
|
|
|
### Contributing
|
|
|
|
We welcome contributions! Please:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
### Architecture
|
|
|
|
```
|
|
fastestmirror/
|
|
├── cmd/ # CLI commands and subcommands
|
|
├── internal/ # Internal packages
|
|
│ ├── distro/ # Distribution detection logic
|
|
│ ├── mirror/ # Mirror testing and management
|
|
│ └── config/ # Configuration management
|
|
├── pkg/ # Public packages (if any)
|
|
└── scripts/ # Build and deployment scripts
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**"Could not detect distribution"**
|
|
- Make sure you're running on a supported Linux distribution
|
|
- Check that `/etc/os-release` exists and is readable
|
|
- Try running with `--verbose` for more details
|
|
|
|
**"No working mirrors found"**
|
|
- Check your internet connection
|
|
- Try increasing the timeout with `--timeout 60`
|
|
- Some distributions might have all mirrors temporarily down (rare but it happens)
|
|
|
|
**"Permission denied" when applying**
|
|
- Make sure you're running with `sudo` when using the `apply` command
|
|
- Check that the configuration file is writable
|
|
|
|
**Tests are slow or timing out**
|
|
- Increase timeout with `--timeout 30` or higher
|
|
- Check if your network has restrictions on concurrent connections
|
|
- Some corporate firewalls block multiple simultaneous connections
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## Acknowledgments
|
|
|
|
- Thanks to all the mirror maintainers who keep our packages flowing
|
|
- Inspired by tools like `netselect-apt`, `reflector`, and `fastestmirror` plugin
|
|
- Built with Go because life's too short for slow languages
|
|
- Coffee and mild frustration with slow mirrors
|
|
|
|
## Disclaimer
|
|
|
|
This tool modifies system configuration files. While we take precautions (backups, dry-run mode, etc.), use at your own risk. We're not responsible if you accidentally break your package manager and have to reinstall your entire system. That said, the risk is minimal and the speed gains are fucking worth it.
|