@fredlackey/devutils 0.0.1 → 0.0.3

package/src/installs/apt-transport-https.md

@@ -0,0 +1,678 @@
+# Installing apt-transport-https
+
+## Dependencies
+
+### macOS (Homebrew)
+- **Required:** None
+- **Optional:** None
+- **Auto-installed:** None
+- **Note:** This package is not applicable to macOS. macOS uses Homebrew for package management, which natively supports HTTPS repositories without any additional configuration.
+
+### Ubuntu (APT/Snap)
+- **Required:** None (HTTPS support is built into APT since version 1.5, which is included in Ubuntu 18.04 and later)
+- **Optional:** None
+- **Auto-installed:** None
+- **Note:** The `apt-transport-https` package exists as a dummy transitional package for backward compatibility. It is not required on modern Ubuntu systems.
+
+### Raspberry Pi OS (APT/Snap)
+- **Required:** None (HTTPS support is built into APT since version 1.5, which is included in Raspberry Pi OS Buster and later)
+- **Optional:** None
+- **Auto-installed:** None
+- **Note:** The `apt-transport-https` package exists as a dummy transitional package for backward compatibility. It is not required on modern Raspberry Pi OS systems.
+
+### Amazon Linux (DNF/YUM)
+- **Required:** None
+- **Optional:** None
+- **Auto-installed:** None
+- **Note:** This package is not applicable to Amazon Linux. DNF and YUM natively support HTTPS repositories without any additional packages.
+
+### Windows (Chocolatey/winget)
+- **Required:** None
+- **Optional:** None
+- **Auto-installed:** None
+- **Note:** This package is not applicable to Windows. Both Chocolatey and winget natively support HTTPS repositories without any additional configuration.
+
+### Git Bash (Manual/Portable)
+- **Required:** None
+- **Optional:** None
+- **Auto-installed:** None
+- **Note:** This package is not applicable to Git Bash. Git Bash does not use APT for package management.
+
+## Overview
+
+`apt-transport-https` is a package that historically enabled the APT package manager on Debian-based Linux distributions (Ubuntu, Debian, Raspberry Pi OS) to download packages over HTTPS (HTTP Secure) connections. This provided encrypted, secure communication when fetching packages from repositories.
+
+**Important Status Update:** As of APT version 1.5, HTTPS support is built directly into the `apt` package itself. The `apt-transport-https` package now exists only as a "dummy transitional package" for backward compatibility with older scripts and tutorials that still reference it. On modern systems, installing this package does nothing because the functionality it previously provided is already present.
+
+### When You Need This Package
+
+You **do not need** to install `apt-transport-https` on:
+- Ubuntu 18.04 (Bionic) or later
+- Debian 10 (Buster) or later
+- Raspberry Pi OS Buster or later
+- Any system with APT version 1.5 or higher
+
+You **may need** to install `apt-transport-https` on:
+- Ubuntu 16.04 (Xenial) or earlier
+- Debian 9 (Stretch) or earlier
+- Legacy Raspberry Pi OS (Jessie or earlier)
+
+### Why This Package Exists
+
+Before APT 1.5, the APT package manager only supported HTTP (unencrypted) and FTP protocols for downloading packages. To use HTTPS repositories, administrators had to install the `apt-transport-https` package, which added the HTTPS transport method.
+
+This was particularly important when:
+- Adding third-party repositories that required secure connections
+- Working in environments with security compliance requirements
+- Preventing man-in-the-middle attacks during package installation
+
+## Prerequisites
+
+Before proceeding, determine if you actually need this package:
+
+```bash
+apt --version
+```
+
+If the version is 1.5 or higher, you do not need to install `apt-transport-https`. The functionality is already built into APT.
+
+## Platform-Specific Installation
+
+### macOS (Homebrew)
+
+#### Prerequisites
+
+None required.
+
+#### Installation Steps
+
+**This package is not applicable to macOS.**
+
+macOS uses Homebrew as its package manager, not APT. Homebrew natively supports HTTPS for all package downloads and repository communications. No additional configuration or packages are needed.
+
+If you need to configure HTTPS certificate handling for Homebrew (such as for corporate proxies), Homebrew provides the `ca-certificates` formula:
+
+```bash
+brew install --quiet ca-certificates
+```
+
+However, this is only necessary in special circumstances involving custom certificate authorities.
+
+#### Verification
+
+Homebrew HTTPS support can be verified by installing any package:
+
+```bash
+brew install --quiet wget
+```
+
+If the installation succeeds, HTTPS transport is working correctly.
+
+#### Troubleshooting
+
+**Problem**: SSL certificate errors when running Homebrew commands
+
+**Solution**: Update your CA certificates and ensure your system time is correct:
+
+```bash
+brew install --quiet ca-certificates
+sudo sntp -sS time.apple.com
+```
+
+---
+
+### Ubuntu/Debian (APT)
+
+#### Prerequisites
+
+- Ubuntu 16.04 or later (18.04+ recommended)
+- Debian 9 or later (10+ recommended)
+- sudo privileges
+
+#### Installation Steps
+
+**For Ubuntu 18.04 / Debian 10 and later (APT 1.5+):**
+
+No installation is required. HTTPS support is built into APT. Run the following command to verify:
+
+```bash
+apt --version
+```
+
+If the version is 1.5 or higher, skip to the Verification section.
+
+**For Ubuntu 16.04 / Debian 9 and earlier (legacy systems):**
+
+Run the following command to install the package:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y apt-transport-https
+```
+
+The `DEBIAN_FRONTEND=noninteractive` environment variable ensures the installation proceeds without prompting for user input, making it suitable for automated scripts and CI/CD pipelines.
+
+**Note on legacy systems:** Ubuntu 16.04 reached end of standard support in April 2021 and end of Extended Security Maintenance in April 2024. Debian 9 reached end of long-term support in June 2022. Upgrading to a supported operating system version is strongly recommended.
+
+#### Verification
+
+Verify that APT can access HTTPS repositories:
+
+```bash
+# Check APT version (1.5+ has built-in HTTPS support)
+apt --version
+
+# Test HTTPS repository access
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+If the update command succeeds without errors related to HTTPS transport, the system is correctly configured.
+
+To explicitly verify HTTPS transport is available:
+
+```bash
+ls /usr/lib/apt/methods/ | grep https
+```
+
+On modern systems, you will see `https` listed, indicating the transport method is available.
+
+#### Troubleshooting
+
+**Problem**: Error message "The method driver /usr/lib/apt/methods/https could not be found"
+
+**Solution**: This error occurs on legacy systems without HTTPS support. Install the package:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y apt-transport-https
+```
+
+If APT itself cannot fetch the package (because your only repositories are HTTPS), temporarily add an HTTP mirror:
+
+```bash
+echo "deb http://archive.ubuntu.com/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/temp-http.list
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y apt-transport-https
+sudo rm /etc/apt/sources.list.d/temp-http.list
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+**Problem**: SSL certificate verification errors
+
+**Solution**: Install or update the CA certificates package:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates
+sudo update-ca-certificates
+```
+
+**Problem**: "apt-transport-https is already the newest version" but HTTPS still fails
+
+**Solution**: On modern systems, the transitional package is empty. The actual HTTPS support comes from the `apt` package. Reinstall or update APT:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --reinstall apt
+```
+
+---
+
+### Raspberry Pi OS (APT)
+
+#### Prerequisites
+
+- Raspberry Pi OS Buster (2019) or later recommended
+- sudo privileges
+- Raspberry Pi 2 or later (any architecture)
+
+#### Installation Steps
+
+**For Raspberry Pi OS Buster (2019) and later:**
+
+No installation is required. HTTPS support is built into APT. Run the following command to verify:
+
+```bash
+apt --version
+```
+
+If the version is 1.5 or higher, skip to the Verification section.
+
+**For Raspberry Pi OS Stretch (2017) and earlier (legacy systems):**
+
+Run the following command to install the package:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y apt-transport-https
+```
+
+**Important:** Raspberry Pi OS Jessie and Stretch are no longer supported. These legacy versions may have issues accessing current repositories. Upgrading to Raspberry Pi OS Bookworm or later is strongly recommended.
+
+**ARM Architecture Note:** The `apt-transport-https` package is available for both armhf (32-bit) and arm64 (64-bit) architectures. The installation command is identical regardless of which Raspberry Pi model or architecture you are using.
+
+#### Verification
+
+Verify that APT can access HTTPS repositories:
+
+```bash
+# Check APT version
+apt --version
+
+# Test HTTPS repository access
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+If the update completes successfully, HTTPS transport is working.
+
+#### Troubleshooting
+
+**Problem**: "E: The method driver /usr/lib/apt/methods/https could not be found"
+
+**Solution**: This indicates a very old Raspberry Pi OS installation. Install the package using an HTTP mirror:
+
+```bash
+echo "deb http://archive.raspberrypi.org/debian $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/temp-http.list
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y apt-transport-https ca-certificates
+sudo rm /etc/apt/sources.list.d/temp-http.list
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+**Problem**: 404 errors when accessing repositories on old Raspberry Pi OS
+
+**Solution**: Old Raspberry Pi OS versions (Jessie, Stretch) have been archived. Update your sources.list to use the archive:
+
+```bash
+sudo sed -i 's|raspbian.raspberrypi.org|legacy.raspbian.org|g' /etc/apt/sources.list
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+However, upgrading to a current Raspberry Pi OS version is the recommended solution.
+
+**Problem**: Package installation fails with SSL handshake errors
+
+**Solution**: The system time may be incorrect (common on Raspberry Pi after long periods without power). Synchronize the time:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y ntpdate
+sudo ntpdate pool.ntp.org
+```
+
+Or, if ntpdate is not available:
+
+```bash
+sudo date -s "$(wget -qSO- --max-redirect=0 google.com 2>&1 | grep Date: | cut -d' ' -f5-8)Z"
+```
+
+---
+
+### Amazon Linux (DNF/YUM)
+
+#### Prerequisites
+
+- Amazon Linux 2 or Amazon Linux 2023
+- sudo privileges
+
+#### Installation Steps
+
+**This package is not applicable to Amazon Linux.**
+
+Amazon Linux uses DNF (Amazon Linux 2023) or YUM (Amazon Linux 2) as its package manager, not APT. Both DNF and YUM natively support HTTPS repositories without any additional packages or configuration.
+
+HTTPS repository support is built into these package managers and enabled by default. Amazon Linux repositories are accessed over HTTPS automatically.
+
+#### Verification
+
+Verify that DNF/YUM can access HTTPS repositories:
+
+**For Amazon Linux 2023 (DNF):**
+
+```bash
+sudo dnf repolist -v 2>&1 | grep -i https
+```
+
+**For Amazon Linux 2 (YUM):**
+
+```bash
+sudo yum repolist -v 2>&1 | grep -i https
+```
+
+Both commands should show repository URLs using the `https://` protocol.
+
+#### Troubleshooting
+
+**Problem**: SSL certificate errors when accessing repositories
+
+**Solution**: Update the CA certificates:
+
+```bash
+# Amazon Linux 2023
+sudo dnf install -y ca-certificates
+sudo update-ca-trust
+
+# Amazon Linux 2
+sudo yum install -y ca-certificates
+sudo update-ca-trust
+```
+
+**Problem**: Repository access fails with "SSL connect error"
+
+**Solution**: This may indicate an issue with the system's SSL configuration. Verify the SSL libraries are installed:
+
+```bash
+# Amazon Linux 2023
+sudo dnf install -y openssl
+
+# Amazon Linux 2
+sudo yum install -y openssl
+```
+
+---
+
+### Windows (Chocolatey/winget)
+
+#### Prerequisites
+
+- Windows 10 or Windows 11
+- Administrator privileges
+
+#### Installation Steps
+
+**This package is not applicable to Windows.**
+
+Windows uses Chocolatey or winget for command-line package management, not APT. Both package managers natively support HTTPS for all operations:
+
+- **Chocolatey**: Accesses the Chocolatey Community Repository and all configured sources over HTTPS by default
+- **winget**: Accesses the Windows Package Manager repository over HTTPS by default
+
+No additional configuration or packages are required for HTTPS support.
+
+#### Verification
+
+Verify that Chocolatey can access HTTPS repositories:
+
+```powershell
+choco source list
+```
+
+All sources should show HTTPS URLs.
+
+Verify that winget can access HTTPS repositories:
+
+```powershell
+winget source list
+```
+
+The msstore and winget sources use HTTPS by default.
+
+#### Troubleshooting
+
+**Problem**: SSL/TLS errors when using Chocolatey
+
+**Solution**: Ensure TLS 1.2 is enabled. Run in PowerShell:
+
+```powershell
+[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
+```
+
+To make this permanent, add it to your PowerShell profile or set it system-wide via Group Policy.
+
+**Problem**: Certificate errors when accessing repositories
+
+**Solution**: Update the Windows root certificates:
+
+```powershell
+certutil -generateSSTFromWU roots.sst
+certutil -addstore -f Root roots.sst
+del roots.sst
+```
+
+---
+
+### WSL (Ubuntu)
+
+#### Prerequisites
+
+- Windows 10 version 2004 or later, or Windows 11
+- WSL 2 with Ubuntu distribution installed
+- sudo privileges within WSL
+
+#### Installation Steps
+
+WSL Ubuntu uses APT as its package manager, so the same rules apply as for native Ubuntu.
+
+**For Ubuntu 18.04 / 20.04 / 22.04 / 24.04 in WSL:**
+
+No installation is required. HTTPS support is built into APT version 1.5 and later, which is included in all supported Ubuntu WSL distributions.
+
+Verify your APT version:
+
+```bash
+apt --version
+```
+
+If the version is 1.5 or higher (which it will be on any modern Ubuntu WSL distribution), HTTPS support is already available.
+
+**For legacy Ubuntu versions in WSL (16.04 or earlier):**
+
+Run the following command to install the package:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y apt-transport-https
+```
+
+**Note:** Ubuntu 16.04 is no longer supported. Install a current Ubuntu version in WSL:
+
+```powershell
+wsl --install -d Ubuntu
+```
+
+#### Verification
+
+Verify that APT can access HTTPS repositories:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+If the update completes successfully, HTTPS transport is working correctly.
+
+#### Troubleshooting
+
+**Problem**: SSL errors when running apt-get update in WSL
+
+**Solution**: The Windows host's time may not be synchronized with WSL. Sync the time:
+
+```bash
+sudo hwclock -s
+```
+
+Or manually set the time:
+
+```bash
+sudo ntpdate pool.ntp.org
+```
+
+If ntpdate is not installed:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y ntpdate
+sudo ntpdate pool.ntp.org
+```
+
+**Problem**: Network issues preventing HTTPS access
+
+**Solution**: WSL networking can sometimes have issues. Restart WSL:
+
+```powershell
+# From Windows PowerShell
+wsl --shutdown
+wsl
+```
+
+---
+
+### Git Bash (Manual/Portable)
+
+#### Prerequisites
+
+- Windows 10 or Windows 11
+- Git Bash installed (comes with Git for Windows)
+
+#### Installation Steps
+
+**This package is not applicable to Git Bash.**
+
+Git Bash is a terminal emulator for Windows that provides a Unix-like command-line environment. It does not include or use APT for package management. Git Bash itself does not manage system packages; it provides access to Git and Unix utilities.
+
+If you need APT and Debian-based package management functionality in a Windows environment, use WSL (Windows Subsystem for Linux) instead. See the WSL section above.
+
+#### Verification
+
+Not applicable.
+
+#### Troubleshooting
+
+**Problem**: You need APT functionality in Git Bash
+
+**Solution**: APT is not available in Git Bash. Use one of these alternatives:
+
+1. **WSL (Recommended)**: Install Windows Subsystem for Linux with Ubuntu:
+
+```powershell
+# From Windows PowerShell (Administrator)
+wsl --install -d Ubuntu
+```
+
+2. **Chocolatey**: Use Chocolatey for Windows package management from Git Bash:
+
+```bash
+# From Git Bash (run Git Bash as Administrator)
+choco install <package-name> -y
+```
+
+3. **winget**: Use winget for Windows package management:
+
+```bash
+# From Git Bash
+winget install --id <package.id> --silent --accept-package-agreements --accept-source-agreements
+```
+
+---
+
+## Post-Installation Configuration
+
+### Verifying HTTPS Repository Access
+
+After ensuring HTTPS support is available (either built-in or via the transitional package), you can add HTTPS repositories. Here is an example of adding a typical third-party repository:
+
+```bash
+# Add a GPG key (example using Docker's key)
+sudo install -m 0755 -d /etc/apt/keyrings
+sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
+sudo chmod a+r /etc/apt/keyrings/docker.asc
+
+# Add the repository
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+# Update package lists
+sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+```
+
+### Ensuring CA Certificates Are Current
+
+For HTTPS to work properly, your system needs up-to-date CA (Certificate Authority) certificates. Update them with:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates
+sudo update-ca-certificates
+```
+
+---
+
+## Common Issues
+
+### Issue: "apt-transport-https is already installed" Warning
+
+**Symptoms**: When following older tutorials, you see a message that `apt-transport-https` is already the newest version, but the package appears to do nothing.
+
+**Explanation**: On modern systems (APT 1.5+), this is expected behavior. The package is a dummy transitional package that exists only for backward compatibility. The actual HTTPS functionality is built into the `apt` package.
+
+**Solution**: No action needed. HTTPS support is already working. You can safely ignore this message or remove the line that installs `apt-transport-https` from your scripts.
+
+### Issue: Scripts Fail When apt-transport-https Is Unavailable
+
+**Symptoms**: Older automation scripts fail because they cannot install `apt-transport-https` from an HTTPS repository (circular dependency).
+
+**Solution**: Modern scripts should check the APT version before attempting to install:
+
+```bash
+APT_VERSION=$(apt --version | grep -oP '\d+\.\d+' | head -1)
+if [ "$(echo "$APT_VERSION < 1.5" | bc)" -eq 1 ]; then
+    # Legacy system - need apt-transport-https
+    sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+    sudo DEBIAN_FRONTEND=noninteractive apt-get install -y apt-transport-https
+fi
+```
+
+Or simply attempt the installation and ignore failures on modern systems:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y apt-transport-https 2>/dev/null || true
+```
+
+### Issue: HTTPS Repositories Still Fail After Installation
+
+**Symptoms**: After installing `apt-transport-https`, HTTPS repositories still fail with connection or certificate errors.
+
+**Solutions**:
+
+1. **Update CA certificates**:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y ca-certificates
+sudo update-ca-certificates
+```
+
+2. **Check system time** (incorrect time causes certificate validation failures):
+
+```bash
+date
+sudo ntpdate pool.ntp.org
+```
+
+3. **Verify network connectivity**:
+
+```bash
+curl -I https://archive.ubuntu.com
+```
+
+4. **Check for proxy issues** (corporate environments):
+
+```bash
+export https_proxy=http://your-proxy:port
+sudo -E apt-get update
+```
+
+### Issue: Cannot Remove apt-transport-https
+
+**Symptoms**: Attempting to remove the package warns about breaking dependencies.
+
+**Explanation**: Some older packages may still list `apt-transport-https` as a dependency even though it is not technically required on modern systems.
+
+**Solution**: The package uses minimal disk space (it is essentially empty on modern systems). There is no harm in leaving it installed. If you must remove it:
+
+```bash
+sudo DEBIAN_FRONTEND=noninteractive apt-get remove -y apt-transport-https --allow-remove-essential
+```
+
+However, this is not recommended as it may break dependency resolution for some packages.
+
+---
+
+## References
+
+- [Ubuntu Manpage: apt-transport-https](https://manpages.ubuntu.com/manpages/bionic/man1/apt-transport-https.1.html)
+- [Debian Package: apt-transport-https](https://packages.debian.org/sid/apt-transport-https)
+- [Ubuntu Package Search: apt-transport-https](https://packages.ubuntu.com/search?keywords=apt-transport-https)
+- [Cloudflare Blog: A Tale of Two APT Transports](https://blog.cloudflare.com/apt-transports/)
+- [Raspberry Pi Forums: apt-transport-https Discussion](https://forums.raspberrypi.com/viewtopic.php?t=311075)
+- [GeeksforGeeks: How to Install apt-transport-https on Ubuntu](https://www.geeksforgeeks.org/installation-guide/how-to-install-apt-transport-https-package-on-ubuntu/)
+- [Homebrew Formulae: ca-certificates](https://formulae.brew.sh/formula/ca-certificates)
+- [Chocolatey Documentation: Setup/Install](https://docs.chocolatey.org/en-us/choco/setup/)