Skip to main content

Configuring Linux Gateways in Production Networks

This guide covers some of the basic network configuration parameters that may cause a Linux system not to work in a production environment due to the isolated infrastructure. Mind that Linux distributions may use different services for the following topics. Therefore, you may not be able to run some of the commands listed below. This section has been written using a Raspberry Pi with native Debian 12 (bookworm) OS version as example.

info

Before your support call with the SDA Team, ensure you have SSH access to the Linux device from your computer for screen sharing during the session.

The following is a list of common areas that may prevent connection.

DNS Serversโ€‹

A Domain Name System (DNS) server resolves domain names to IP addresses to facilitate communication over the internet. Proper DNS configuration is critical for a Linux system operating in a networked environment. Troubleshooting DNS issues involves checking the reachability of the DNS server using commands like ping or nslookup. Ensure that the server is responsive and correctly resolving domain names to IP addresses. Misconfigurations may lead to failure in domain resolution, affecting network communications and internet access.

Testingโ€‹

Check the DNS server IPs configured on the host with:

cat /etc/resolv.conf

Each DNS server can be tested individually with either nslookup or dig. For example, if the server is 8.8.8.8:

nslookup api.eu1.sdaconsole.io 8.8.8.8
dig @8.8.8.8 api.eu1.sdaconsole.io +short

If these commands are not present, they can either be installed with the dnsutils or with the bind9-dnsutils packages in Debian or a native command like ping or getent may be used to test the current DNS configuration:

ping api.eu1.sdaconsole.io
getent hosts api.eu1.sdaconsole.io

Configuringโ€‹

The DNS servers may be managed by different services, depending on the Linux installation. For a Raspberry Pi, it is typically managed by the NetworkManager service. The service that is managing the DNS resolution will likely leave a comment in /etc/resolv.conf telling that it generated the file, such as:

cat /etc/resolv.conf
> # Generated by NetworkManager
> nameserver 192.168.15.1
> nameserver fe80::dec6:37ff:fe36:5ee8%wlan0

cat /etc/resolv.conf
> # Generated by dhcpcd from eth0.dhcp
> # /etc/resolv.conf.head can replace this line
> nameserver 192.168.15.1

To set the global DNS servers, create the file:

sudo nano /etc/NetworkManager/conf.d/dns.conf

And add:

[global-dns-domain-*]
servers=8.8.8.8,4.4.4.4

Restart the NetworkManager service and check the new values in /etc/resolv.conf

sudo systemctl restart NetworkManager
# Verify /etc/resolv.conf was updated
cat /etc/resolv.conf

NTP Serversโ€‹

An Network Time Protocol (NTP) server is used in Linux systems to synchronize the system clock with a time source, such as an atomic clock or a central server. Accurate timekeeping is crucial for logging, security protocols and coordinating actions across a network. The wrong setup of an NTP server will cause HTTPS calls to fail due to SSL certificate invalidation.

Testingโ€‹

Review the NTP synchronization status and if the current date and time are correct.

# Check NTP sync status
timedatectl status

# Check configured NTP servers
timedatectl timesync-status
timedatectl show-timesync --all

# Check logs from the timesync service
journalctl -u systemd-timesyncd -n 20
# Check if service is active
systemctl is-active systemd-timesyncd

Testing the connection to a specific server:

# Using ntpdate, if installed
ntpdate -q 0.debian.pool.ntp.org

# Using Netcat
timeout 2 nc -u -z -v 0.debian.pool.ntp.org 123

Configuringโ€‹

The NTP server may be configured with a domain name, such as 0.debian.pool.ntp.org or ntp.myorg.com or directly with an IP address.

# Configure systemd-timesyncd
sudo nano /etc/systemd/timesyncd.conf

Add the custom NTP server in the [Time] block and make sure the line is not commented. Remove any server in FallbackNTP that cannot be reached.

[Time]
NTP=ntp.myorg.com ntp.myorg.local
FallbackNTP=

Restart and make sure to enable the timesync service.

# Restart and enable
sudo systemctl restart systemd-timesyncd
sudo systemctl enable systemd-timesyncd

# Force synchronization
sudo timedatectl set-ntp true

# Verify sync
timedatectl timesync-status

Proxy Serversโ€‹

A proxy server acts as an intermediary between a client and destination servers, forwarding requests and responses. In enterprise environments, proxy servers are commonly used for security control, content filtering, bandwidth management and logging of outbound traffic. Linux systems in such networks must be configured to route their HTTP/HTTPS requests through the corporate proxy to access external resources, including package repositories and web services.

Testingโ€‹

Check if proxy is currently configured by checking the environment variables and system-wide proxy settings:

# Check shell environment proxy variables
env | grep -i proxy

# Check system-wide proxy configuration
cat /etc/environment | grep -i proxy

# Check if proxy is set for current user
echo $http_proxy
echo $https_proxy
echo $no_proxy

To check wether a proxy server is needed, attempt to connect directly to an external server:

# Try direct connection to a public server
timeout 5 curl -I https://repository.eu1.sdaconsole.io/glue/v2/linux/arm64/release.json 2>&1

# If it fails with connection errors, proxy might be required
# Common error: "Failed to connect" or "Connection timed out"

If it fails with connection errors, proxy may be required. Common errors are, for example, Failed to connect or Connection timed out.

To test a request with a specific proxy server:

# Test with curl
curl -I --proxy http://proxy.company.local:8080 https://repository.eu1.sdaconsole.io/glue/v2/linux/arm64/release.json
# Proxy with user authentication
curl -I --proxy http://user@pwd@proxy.company.local:8080 https://repository.eu1.sdaconsole.io/glue/v2/linux/arm64/release.json
# Test without proxy (direct connection)
curl -I --noproxy "*" https://repository.eu1.sdaconsole.io/glue/v2/linux/arm64/release.json

Configuringโ€‹

info

A proxy address has one of the formats:

<protocol>://<proxy-address>:<port-number>
<protocol>://<username>:<password>@<proxy-address>:<port-number>

Configure proxy for all users and applications:

# Edit system-wide environment
sudo nano /etc/environment

Add or modify the following lines:

http_proxy="http://proxy.company.local:8080"
https_proxy="http://proxy.company.local:8080"
no_proxy="localhost,127.0.0.1,*.company.local,10.0.0.0/8,192.168.0.0/16"

# Uppercase variants (some applications check these)
HTTP_PROXY="http://proxy.company.local:8080"
HTTPS_PROXY="http://proxy.company.local:8080"
NO_PROXY="localhost,127.0.0.1,*.company.local,10.0.0.0/8,192.168.0.0/16"

Apply the changes:

# Reload environment (or log out and back in)
source /etc/environment
# Verify variables are set
env | grep -i proxy

To check wether traffic is actually going through the proxy:

# Verbose curl request showing proxy connection
curl -v -I https://repository.eu1.sdaconsole.io/glue/v2/linux/arm64/release.json 2>&1 | grep -i proxy

# Should show something like:
# * Uses proxy env variable http_proxy == 'http://proxy.company.local:3128'
# * Trying proxy.company.local:3128...
warning

Some proxies perform SSL inspection. You may need to install corporate CA certificates:

# Copy corporate CA certificate
sudo cp company-ca.crt /usr/local/share/ca-certificates/
# Update CA trust store
sudo update-ca-certificates
# Verify
curl -I https://repository.eu1.sdaconsole.io/glue/v2/linux/arm64/release.json

Debian Repositoriesโ€‹

Debian repositories are servers that host software packages and updates for Debian-based systems. In isolated enterprise environments, access to public Debian mirrors (like deb.debian.org or archive.ubuntu.com) may be blocked for security reasons. Companies often maintain their own internal mirrors to control which packages are available and to reduce external bandwidth usage.

Testingโ€‹

Check the currently configured repositories:

# View configured repositories
cat /etc/apt/sources.list

# Check additional repository files
ls -la /etc/apt/sources.list.d/
cat /etc/apt/sources.list.d/*.list 2>/dev/null

Here is a comprehensive bash script to completely test the connectivity to the configured repositories:

# Test if repository servers are reachable
grep -h "^deb http" /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null | \
    awk '{print $2, $3}' | sort -u | while read repo suite; do
    echo "Testing: $repo (suite: $suite)"
    # Test the Release file that APT actually fetches
    # This is what APT checks first when doing 'apt update'
    release_url="${repo}/dists/${suite}"
    # Test with curl (follows redirects, checks certificates)
    if curl -fsSL --connect-timeout 5 --max-time 10 -I "$release_url/InRelease" >/dev/null 2>&1; then
        echo "  > Repository is reachable"
    else
        if curl -fsSL --connect-timeout 5 --max-time 10 -I "$release_url/Release" >/dev/null 2>&1; then
            echo "  > Repository is reachable"
        else
            # If failed, show the specific error
            error=$(curl -fsSL --connect-timeout 5 --max-time 10 -I "$repo" 2>&1 | head -1)
            echo "  X Unreachable: $error"
        fi
    fi
    echo
done

Another method it to attempt to update package lists to identify repository issues:

# Try to update package lists
sudo apt update

# Check for errors in apt logs
tail -20 /var/log/apt/term.log

Common error messages indicating blocked repositories:

  • Failed to fetch http://deb.debian.org/...
  • Could not resolve 'deb.debian.org'
  • Connection timed out
  • Unable to connect to...

Test a specific repository server manually:

# Test HTTP connectivity to a repository
curl -sSL -I --connect-timeout 5 http://deb.debian.org/debian/

# Or using wget
wget --spider --timeout=5 http://deb.debian.org/debian/

# Test DNS resolution
getent hosts deb.debian.org

Configuringโ€‹

Edit the main sources file:

sudo nano /etc/apt/sources.list

Replace the content with your internal mirror. For Debian 12 (bookworm):

# Internal Debian Repository Mirror
deb http://mirror.company.local/debian bookworm main contrib non-free non-free-firmware
deb http://mirror.company.local/debian bookworm-updates main contrib non-free non-free-firmware
deb http://mirror.company.local/debian-security bookworm-security main contrib non-free non-free-firmware

# Optionally, backports for newer packages
deb http://mirror.company.local/debian bookworm-backports main contrib non-free non-free-firmware

If your internal mirror uses HTTPS:

deb https://mirror.company.local/debian bookworm main contrib non-free non-free-firmware

Note: For HTTPS repositories, ensure the apt-transport-https and ca-certificates packages are installed.

Configure Repository Priority (Optional)

If you need to use both internal and external repositories with preference given to internal:

sudo nano /etc/apt/preferences.d/internal-mirror

Add:

Package: *
Pin: origin mirror.company.local
Pin-Priority: 900

Package: *
Pin: origin deb.debian.org
Pin-Priority: 500

This gives internal mirrors higher priority.

Configuring Proxy for Repositories (Optional)

If your network requires a proxy to reach repositories:

# Configure APT proxy
echo 'Acquire::http::Proxy "http://proxy.company.local:3128";' | \
    sudo tee /etc/apt/apt.conf.d/proxy.conf

# For HTTPS repositories
echo 'Acquire::https::Proxy "http://proxy.company.local:3128";' | \
    sudo tee -a /etc/apt/apt.conf.d/proxy.conf

# Test
sudo apt update

Update and Verify

After configuring the repositories:

# Update package lists
sudo apt update

# Check for errors
echo $?  # Should return 0 if successful

# Verify packages can be found
apt-cache policy apt

# Test installing a small package
sudo apt install --dry-run nano

Common Issues

Issue: apt update hangs indefinitely

# Check if repository server is actually responding
timeout 10 curl -v http://mirror.company.local/debian/

# Check for proxy interference
unset http_proxy https_proxy
sudo apt update

Issue: Packages not found after configuring mirror

# Verify the mirror has the correct Debian version
curl http://mirror.company.local/debian/dists/ | grep bookworm

# Check if the mirror is properly synced
curl -sI http://mirror.company.local/debian/dists/bookworm/Release | grep Date

Issue: Mixed repository sources causing conflicts

# Check all active sources
grep -rh "^deb" /etc/apt/sources.list /etc/apt/sources.list.d/ | sort -u

# Disable conflicting sources
sudo mv /etc/apt/sources.list.d/problematic.list /etc/apt/sources.list.d/problematic.list.disabled

sudo apt update