> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safesquid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Ubuntu

> Non-interactive upgrade of SafeSquid SWG from Ubuntu 20.04 LTS to 24.04 LTS: prerequisites, OS upgrade, DNS, Netplan, and verification.

# Upgrade Ubuntu 20.04 to 24.04 for SafeSquid compatibility

## OS upgrade scope and procedure

Use this step-by-step, non-interactive procedure to upgrade the SafeSquid Secure Web Gateway system from Ubuntu 20.04 LTS to Ubuntu 24.04 LTS, then to SafeSquid version 2025.1001.1232.3.

The steps ensure **compatibility**, **security**, and **service continuity** for SafeSquid deployments running in production environments.

***

## Why This Upgrade Is Required

### **1. SafeSquid Compatibility Requirements for** The latest release:

**SafeSquid Secure Web Gateway 2025.1001.1232.3**

introduces the following **minimum system requirements**:

* **Linux Kernel:** 6.8 or higher
* **glibc:** 2.39 or higher

Ubuntu **20.04 LTS** includes:

* Kernel up to **5.15**
* glibc **2.31**

These versions are **too old** for SafeSquid verion 2025.1001.1232.3, which requires newer kernel APIs and library functions available only in **Ubuntu 24.04 LTS**.
Attempting to install the new version on 20.04 will cause dependency and runtime failures.

***

### **2. Ubuntu 20.04 End of Life (EoL)**

Ubuntu **20.04 LTS** reaches **End of Standard Support in April 2025**.
After this date:

* No further security patches or OS updates will be provided
* Package repositories may become unavailable
* Vulnerabilities and compatibility issues will accumulate

Upgrading to **Ubuntu 24.04 LTS (Noble Numbat)** ensures long-term security and system support until **2034** under extended maintenance.

***

## Important Pre-Requisite

1. Login as root

You **must be logged in as the root user** (or have full administrative privileges using `sudo`) to execute all commands in this procedure.

Upgrading the operating system and SafeSquid involves modifying system-level files, packages, and services that require **root-level access**.

To switch to the root user, run:

```bash theme={null}
sudo -i
```

Verify root access by checking the prompt changes to:

```bash theme={null}
root@hostname:~#
```

If you see this, you can proceed safely with the upgrade process

***

1. **Free Storage in `/root`:**

   The `/root` partition must have **more than 15 GB of free space** to accommodate upgrade files, temporary packages, and extracted data.

   Check available space:

```bash theme={null}
df -h
```

**Expected output for sufficient free space:**

```
Filesystem                                     Size  Used Avail Use% Mounted on
/dev/mapper/vgsab--ubantu-root                  20G  4.0G  16G  20% /
tmpfs                                          392M  900K  391M   1% /run
tmpfs                                          2.0G     0  2.0G   0% /dev/shm
tmpfs                                          5.0M     0  5.0M   0% /run/lock
/dev/mapper/vgsab--ubantu-home                  24G   48K   23G   1% /home
/dev/mapper/vgsab--ubantu-var+cache+safesquid  7.0G   24K  6.7G   1% /var/cache/safesquid
/dev/mapper/vgsab--ubantu-opt+safesquid        3.7G   48M  3.5G   2% /opt/safesquid
/dev/mapper/vgsab--ubantu-var+lib+safesquid    7.5G  4.3G  2.8G  61% /var/lib/safesquid
/dev/mapper/vgsab--ubantu-var+www+safesquid     14G   24K   14G   1% /var/www/safesquid
/dev/sda1                                      1.9G  193M  1.6G  11% /boot
/dev/mapper/vgsab--ubantu-usr+local+safesquid  3.7G   9.2M  3.5G   1% /usr/local/safesquid
/dev/mapper/vgsab--ubantu-var+log+safesquid     96G  885M   90G   1% /var/log/safesquid
/dev/mapper/vgsab--ubantu-var+db+safesquid      73G  1.1M   69G   1% /var/db/safesquid
/dev/ram1                                       60M  3.0M   54M   6% /tmp/safesquid
tmpfs                                          392M  8.0K  392M   1% /run/user/0
```

> Note: If free space is below 15 GB, clean up unnecessary files or resize the /root partition before proceeding.

***

1. Check Current OS Version

**Purpose:**
This step confirms the current OS version before proceeding, ensuring the system is actually running **Ubuntu 20.04**. The upgrade procedure must be followed sequentially, so the version check prevents applying incorrect upgrade steps.

**Command:**

```bash theme={null}
lsb_release -a
```

**Expected Output:**

```
description:    Ubuntu 20.04 LTS
```

If the version shows **18.04**, perform an upgrade to **20.04** first before continuing.

***

## Step 1: Upgrade Ubuntu from 20.04 → 24.04 (Two-Step Process)

Ubuntu LTS upgrades must be done **sequentially** (20.04 → 22.04 → 24.04).
This ensures all intermediate packages, kernel modules, and libraries are properly migrated.

***

### **Phase 1 – Upgrade from 20.04 to 22.04**

**Why:**

* Ubuntu cannot skip LTS versions directly
* This step ensures that kernel, libc, and dependent packages are incrementally upgraded to versions compatible with 22.04

**Commands:**

```bash theme={null}
apt autoclean -y && apt autoremove -y
apt-get clean
apt update && apt upgrade -y
do-release-upgrade -f DistUpgradeViewNonInteractive
```

* `apt autoclean` removes obsolete package files
* `apt autoremove` clears unused dependencies to prevent clutter
* `apt-get clean`: Removes cached packages to free space and avoid conflicts
* `apt update && apt upgrade -y`: Ensures the system is fully patched before upgrading
* `do-release-upgrade -f DistUpgradeViewNonInteractive`: Initiates the upgrade to Ubuntu 22.04 in non-interactive mode,
  This upgrades Ubuntu to the next LTS version **without stopping to ask questions**, ensuring a fully automated process suitable for remote servers or critical systems.

**After completion:**

```bash theme={null}
reboot
```

Reboot is required to boot into the new kernel and load updated system libraries.

***

### **Phase 2 – Upgrade from 22.04 to 24.04**

**Why:**
This phase upgrades the system to the final target OS, **Ubuntu 24.04 LTS**, which provides:

* Kernel **6.8**
* glibc **2.39**
* Modern dependencies required by SafeSquid 2025.1001.1232.3

**Commands:**

```bash theme={null}
apt autoclean -y && apt autoremove -y
apt-get clean
apt update && apt upgrade -y
do-release-upgrade -f DistUpgradeViewNonInteractive
```

* `apt autoclean` removes obsolete package files
* `apt autoremove` clears unused dependencies to prevent clutter
* **`apt-get clean`:** Removes all cached package files from `/var/cache/apt/archives` to free up space and prevent conflicts
* **`apt update && apt upgrade -y`:** Updates the package index and upgrades all installed packages to the latest available versions automatically
* **`do-release-upgrade -f DistUpgradeViewNonInteractive`:** Initiates the Ubuntu OS upgrade to the next release in a fully automated, non-interactive mode

***

After the upgrade completes:

```bash theme={null}
apt autoclean -y && apt autoremove -y
reboot
```

* `apt autoclean` removes obsolete package files
* `apt autoremove` clears unused dependencies to prevent clutter
* Reboot ensures the system loads the new kernel and environment

***

## Step 2: Update BIND Configuration

**Why:**

SafeSquid, during its operation, creates or modifies `/etc/bind/named.conf.appliance.options`, which automatically add options `dnssec-validation` and TTL limits.

These options cause conflicts when starting bind9 service.

The reason SafeSquid does this is to **ensure Active Directory (AD) integration works smoothly**, as these options control DNS validation and caching behavior, which are critical for resolving AD domain controllers and Kerberos services.

**Commands:**

```bash theme={null}
vim /etc/bind/named.conf.options
```

Comment the following lines:

```bash theme={null}
// dnssec-validation auto;

// max-cache-ttl 300;
// max-ncache-ttl 300;
```

**Save and restart BIND:**

```bash theme={null}
systemctl restart bind9
```

This restarts the DNS service with updated configuration.

***

## Step 3: Rename `msktutil` Binary

**Why:**`msktutil` is a tool used for managing machine accounts in Active Directory.

SafeSquid or system processes may attempt to use the existing `msktutil` binary, which was built for Ubuntu 20.04.

On Ubuntu 24.04, this older binary can have **dependency issues** with newer Kerberos libraries.

**Command:**

```bash theme={null}
mv /usr/local/bin/msktutil /usr/local/bin/msktutil_
```

***

## Step 4: Update Netplan Configuration

**Why:**
During OS upgrades, network settings may change or revert.
Updating Netplan ensures the system uses the **local DNS resolver (127.0.0.1)**, allowing proper DNS resolution through your AD-integrated BIND server.

**Commands:**

```bash theme={null}
vim /etc/netplan/00-installer-config.yaml
```

Add or modify the nameserver section:

```yaml theme={null}
nameservers:
  addresses: [127.0.0.1]
```

**Apply the configuration:**

```bash theme={null}
netplan apply
```

This ensures DNS resolution functions correctly with BIND post-upgrade.

***

## Step 5: Upgrade SafeSquid Application

**Why:**
Once the OS environment is compatible (kernel 6.8, glibc 2.39), install the new SafeSquid version.
The latest release provides updated filtering features, enhanced TLS handling, and improved performance.

**Commands:**

```bash theme={null}
wget -P /usr/local/src https://downloads.safesquid.com/appliance/unstable/safesquid-2025.1001.1232.3-swg-standard.tar.gz
tar -xzf /usr/local/src/safesquid-2025.1001.1232.3-swg-standard.tar.gz -C /usr/local/src
/usr/local/src/_mkappliance/installation/setup.sh
```

**Check status:**

```bash theme={null}
systemctl status safesquid.service
```

**Enable at boot:**

```bash theme={null}
systemctl enable safesquid
```

This ensures SafeSquid starts automatically after system reboots.

***

## Step 6: Post-Upgrade Cleanup and Verification

**Why:**
Cleaning residual packages prevents storage bloat and ensures a consistent, stable environment.
Verification confirms that both OS and SafeSquid versions are upgraded successfully.

**Commands:**

```bash theme={null}
apt autoclean -y && apt autoremove -y
reboot
```

After reboot, verify OS versions:

```bash theme={null}
lsb_release -a
```

**Expected:**

```
description:    Ubuntu 24.04 LTS
```

***

Verify Installed SafeSquid Version.

```bash theme={null}
ls -rlt /opt/safesquid/bin/safesquid
```

**Expected:**

```bash theme={null}
lrwxrwxrwx 1 ssquid root 39 Oct 13 22:22 /opt/safesquid/bin/safesquid -> safesquid-2025.1001.1232.3-swg-standard
```


## Related topics

- [Upgrade SafeSquid](/use_cases/upgrade/version_upgrade.md)
- [Monit Service Governance](/safesquid_swg/interface/supporting_services_monit.md)
- [Application Binaries and Modules](/safesquid_swg/files_and_folders/application_binaries_and_modules.md)
- [Security Logs](/use_cases/audit_and_forensics/security_logs.md)
- [Runtime Data and Signatures](/safesquid_swg/files_and_folders/runtime_data_and_signatures.md)