Skip to main content

​
Fix Installation Issues

Troubleshooting Installation Issues can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review. If you see Bad archive mirror, Failed to retrieve pre-configuration, or other installation failures, use the sections below. They help you diagnose and fix the failure. Symptoms are grouped by stage: before install, during install, and network-related.

​
Before Installation

Common issues in this stage include system compatibility and creating a bootable USB or attaching the appropriate .iso file. Another is correctly setting up the BIOS/UEFI settings. Solutions involve checking system requirements, verifying the integrity of the installation media, and ensuring correct boot order.

​
During Installation

Issues during installation can range from partitioning errors, and network configuration problems, to software selection difficulties. Resolutions can include checking disk space, reviewing network settings, and ensuring proper selection of software packages. For the network-related issues below, use the installer console to identify the root cause and act on it.

​
Network Checks for Issue Identification

Network issues can significantly impact the installation and functionality of SafeSquid. If you see “Bad archive mirror” or “Failed to retrieve the pre-configuration file” during installation, use the checks below. They fix DNS and gateway settings. Administrators can perform various checks to identify and resolve network-related problems:
  1. Network Configuration: Review and modify network settings using the ip commands. ip addr show # Display all interface IP addresses ip route show # Display routing table What to check:
    • IP address is assigned to the correct interface (e.g., eth0: inet 192.168.1.100/24)
    • Default gateway is present in routing table (e.g., default via 192.168.1.1 dev eth0) Common issues:
    • No IP address shown -> interface not configured or DHCP failed
    • No default route -> gateway not set during network configuration step
  2. DNS Resolution and Ping check: busybox is a minimal Linux environment. Use ping to verify both DNS resolution and connectivity. ping -c 3 google.com Expected success output: PING google.com (142.250.x.x): 56 data bytes 64 bytes from 142.250.x.x: icmp_seq=0 ttl=xx time=x.x ms Failure symptoms:
    • ping: bad address 'google.com' -> DNS resolution failed (check /etc/resolv.conf for nameserver entries)
    • Network is unreachable -> No default gateway configured
    • Request timeout or 100% packet loss -> Firewall blocking ICMP, or no internet connectivity
  3. Firewall Rules: check your network firewall rules for possible port blocking.
By performing these network checks and using the available networking commands, administrators can pinpoint network-related problems and take corrective actions. Once you have solved the network problem, return to the installer tty using ctrl + alt + F1. Then select continue. Select continue again. Select the “Download debconf preconfiguration file” step. Follow the steps of standard installation and continue your installation process.

​
Conclusion

For additional assistance, consult the SafeSquid forums and community resources.

​
ISO Installation Failure

​
Symptoms

“Failed to retrieve the pre-configuration file” appears during installation. The installer cannot download the automated configuration script from SafeSquid servers. This typically indicates DNS or gateway misconfiguration. “Bad archive mirror” Appears when the installer cannot reach Debian package repositories. This indicates:
  • Firewall blocking outbound HTTP/HTTPS on the assigned proxy IP
  • No default gateway configured
  • DNS resolution failure for deb.debian.org or downloads.safesquid.net

​
Root Causes

  • DNS misconfiguration: Wrong DNS server IP, or DNS server is unreachable
  • Gateway misconfiguration: No default route, or gateway IP is incorrect
  • NIC configuration: Wrong interface selected, or interface is down
  • Firewall rules: Network firewall blocking installation traffic from the SafeSquid server’s IP
If you face any error while installing SafeSquid Appliance Builder (SAB-ISO), you will get debugging logs information by pressing ALT+F4. To return to the previous screen press ALT+F1. Bad Archive Mirror Template Failed to retrieve the pre-configuration file error template

​
Capture useful evidence

Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a [thread or request id] and a module name such as network:. Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.

​
Next steps