Update Linux handbook pages with comprehensive documentation

title: Linux Desktop OS

---

This page contains information related to Linux Desktop OS usage in GitLab. See

the information below.

Linux is available as an alternative to macOS for GitLab team members, but is not encouraged due to limited support. By choosing Linux, you accept full responsibility for maintaining your environment and understand that IT does not provide support. There is a `#linux` channel in Slack for exchanging tips and tricks, but it is not an official helpdesk resource.

## Approved Distribution

**Ubuntu LTS (latest version) is the only approved Linux distribution.** Dell is the only approved Linux laptop vendor. Ubuntu LTS is required to support the necessary software packages for remote management and EDR solutions.

## Requirements

All Linux endpoints must meet the following security and compliance standards:

| Requirement | Details |

| :--- | :--- |

| **Fleet Enrollment** | Mandatory for all Linux endpoints. [Enrollment instructions](https://internal.gitlab.com/handbook/security/corporate/tooling/fleet/#enrolling-in-fleet) (internal link) |

| **EDR Agent** | CrowdStrike or SentinelOne (region-dependent, installed automatically via Fleet) |

| **Full-Disk Encryption** | LUKS encryption required |

| **Firewall** | Must be enabled (`ufw`) |

| **OS Version** | Ubuntu LTS (Latest) |

| **Security Patches** | Must be applied within 7 days of release |

| **User Account** | Must be a regular user account; use `sudo` for administrative actions |

| **YubiKey** | YubiKey 5 FIPS required for authentication |

For YubiKey setup, see the [ordering guide](/handbook/security/corporate/systems/yubikey/purchasing/) and [user guide](/handbook/security/corporate/systems/yubikey/2fa/).

## EDR Requirements by Region

EDR deployment is required on all team member endpoint systems, including virtual machines. Docker containers are excluded from MDM/EDR enrollment requirements.

| EDR Solution | Regions |

| :--- | :--- |

| **SentinelOne** | Netherlands, Germany, Italy, Austria |

| **CrowdStrike** | All other regions |

**Note:** Virtual hosts on laptops must also have the EDR agent installed.

## Fleet Enrollment

Fleet is our osquery-based device management and visibility platform for Linux endpoints. It is used to:

- Confirm security settings

- Verify encryption and firewall status

- Deploy the EDR solution

- Enable remote wipe capability

- Provide real-time queries of device state

- Software inventory and vulnerability detection

All Linux endpoints must be enrolled in Fleet. Visit the [Fleet handbook page](https://internal.gitlab.com/handbook/security/corporate/tooling/fleet/) for enrollment instructions.

## Firewall

Linux machines use their built-in firewall (`ufw`), managed through Fleet. This differs from macOS and Windows devices which use the CrowdStrike integrated firewall.

## Your Responsibilities

As a Linux user, you are responsible for:

- Maintaining your Linux environment

- Applying security patches and version upgrades

- Ensuring compliance with all endpoint management policies

- Keeping your system enrolled in Fleet and running the required EDR agent

## Support

- **Slack Channel:** `#linux` - for tips and tricks (not official helpdesk)

- **Security Support:** `#security_help` - for Fleet and EDR assistance

- **EDR Help:** `#crowdstrike` or `#sentinelone` (depending on your region)

## Additional Resources

- [Linux Setup Guide](/handbook/security/corporate/systems/linux/setup/)

- [Linux Security Standards](/handbook/security/corporate/systems/linux/security/)

- [Linux Tools & Tips](/handbook/tools-and-tips/linux/)

- [Fleet Documentation](https://fleetdm.com/docs)

title: Linux Desktop OS Setup Guide

---

## Prerequisites

Before starting, ensure you have:

- A company-provided Dell laptop (Dell is the only approved Linux laptop vendor)

- Ubuntu LTS (latest version) - the only approved Linux distribution

## Setup and Deployment Steps

These steps assume you are using a company-provided Dell laptop running **Ubuntu LTS (latest version)** - the only approved Linux distribution. Dell is the only approved Linux laptop vendor. Ubuntu LTS is required to support the necessary software packages for remote management and EDR solutions.

### 1. Install Linux (if needed)

Certain circumstances (world region and availability of hardware) might require the self-installation of Linux on a Dell that was shipped with OEM Windows. If this is the case:

1. Set up a USB drive with Ubuntu LTS

2. Perform the installation

**Optional backup:** For laptops shipped with OEM Windows, you may want to make a full drive backup (e.g., using open source utility [Clonezilla](https://clonezilla.org/)) to an external drive before installing Linux. This makes the RMA process easier if needed.

### 2. Enable Full-Disk Encryption (LUKS Required)

Full-disk encryption is mandatory. To verify encryption is enabled:

```bash

sudo dmsetup ls

```

If there is a reference to `cryptdata` or `dm_crypt-0` in the output, encryption is enabled. If not, you will need to reinstall Ubuntu and enable LUKS drive encryption during the installation process.

### 3. Enable the Firewall

Linux endpoints must have the firewall enabled. Check the status and enable if needed:

```bash

# Check firewall status

sudo ufw status

# If inactive, enable it

sudo ufw enable

# If ufw is not installed

sudo apt install ufw

```

### 4. Set Your Hostname

Before enrolling in Fleet, your hostname must follow the standardized naming convention:

```plaintext

gitlabEmail--dateOfInitialConnect-lastFiveOfSerialNumber

```

For example, if your email is `jsmith@gitlab.com`:

```plaintext

jsmith--20241202-RT7A2

```

**To rename your hostname:**

You can use `hostnamectl` to set your hostname manually:

```bash

# Get your serial number (last 5 characters)

sudo dmidecode -s system-serial-number | tail -c 6

# Set the hostname (replace with your actual values)

sudo hostnamectl set-hostname "yourusername--YYYYMMDD-SERIAL"

# Update /etc/hosts

sudo sed -i "s/127.0.1.1.*/127.0.1.1\t$(hostname)/" /etc/hosts

```

Alternatively, you can use the hostname rename script available on the internal handbook. Contact `#security_help` if you need assistance.

### 5. Install Fleet

All Linux endpoints must have Fleet installed. Fleet will also install the EDR tool (CrowdStrike or SentinelOne depending on your region).

**Download the package:**

The Fleet binary is available for DEB and RPM package managers for both x86-64 and ARM CPUs. Download the latest release from the [fleet-builds repository](https://gitlab.com/gitlab-com/gl-security/corp/tooling/fleet-builds/-/releases).

**Install the package:**

For Debian/Ubuntu (the only approved distribution):

```bash

sudo apt install ./fleet-osquery_*.deb

```

**Verify Fleet is installed:**

```bash

sudo systemctl is-enabled orbit.service

sudo systemctl is-active orbit.service

```

With supported Linux Desktop Environments (like GNOME with [the required GNOME Shell extension](https://extensions.gnome.org/extension/615/appindicator-support/)), you can see if Fleet Desktop is showing on your top bar.

For detailed Fleet enrollment instructions, see the [Fleet handbook page](https://internal.gitlab.com/handbook/security/corporate/tooling/fleet/).

### 6. Verify EDR Installation

The EDR agent should be installed automatically via Fleet. To verify:

**For SentinelOne (Netherlands, Germany, Italy, Austria):**

```bash

systemctl status sentinelone

```

Verify connectivity:

```bash

sudo sentinelctl management status

```

You should see `Connectivity: On` and a valid SentinelOne URL.

**For CrowdStrike (all other regions):**

```bash

# Check if the Falcon sensor is running

sudo systemctl status falcon-sensor

# Verify the agent ID

sudo /opt/CrowdStrike/falconctl -g --aid

```

You should see the service as active and an Agent ID (AID) value returned.

1. **Ensure your laptop is running Linux**. Certain circumstances (world region and availability of hardware) might require the self installation of Linux on a Dell that was shipped with OEM Windows. If this is the case, you will need to set up a USB drive with Ubuntu and perform the installation.

If you need assistance, reach out in `#sentinelone` or `#crowdstrike` Slack channels.

For laptops shipped with OEM Windows you may want to make a full drive backup (e.g. by using open source utility [Clonezilla](https://clonezilla.org/)) to an external drive before installing Linux. That way you could restore your laptop to the original state at any time. It will make the RMA process much easier in case you need it. This is optional and not required.

### 7. Install Standard Applications

1. **Ensure full-disk encryption is enabled (LUKS required)**. From a terminal window run the command `sudo dmsetup ls`. If there is a reference to something like `cryptdata` or `dm_crypt-0` in the output, encryption is enabled. If not, you will need to reinstall Ubuntu and enable LUKS drive encryption during the installation process.

Install the regular approved applications:

1. **Ensure the firewall is enabled**. From a terminal window run the command `sudo ufw status`. If the response is `Status: inactive` run `sudo ufw enable`. If `ufw` is not installed, run `sudo apt install ufw` first.

- **Google Chrome** (and sign into Okta)

- **Zoom**

- **Slack**

- Other applications for your job description (e.g., development tools)

1. **Ensure Fleet is installed**. All Linux endpoints must have Fleet installed. Follow the instructions listed [here](https://internal.gitlab.com/handbook/security/corporate/tooling/fleet/#enrolling-in-fleet) (internal link). This will also install the EDR tool (CrowdStrike or SentinelOne depending on your region).

Complete the steps in your onboarding issue and/or laptop equipment issue.

1. **Regular Applications**. Use the regular approved applications such as Google Chrome (and sign into Okta), Zoom, and Slack. Install the other applications for your job description (e.g. development tools) as needed. Complete the steps in your onboarding issue and/or laptop equipment issue.

## Additional Configuration

## Additional Steps

### Automatic Updates (Recommended)

_Automatic Updates_ - While not required it is highly recommended that automatic updates are configured to ensure the latest security patches are available. As many of the Linux users in GitLab are developers, it is understood that there might be hesitancy that various components used for developments - particularly those impacting a build process - could cause difficulties. That being said, here are two recommended options for enabling automated updates:

While not required, it is highly recommended that automatic updates are configured to ensure the latest security patches are available. Options include:

- The GNOME Update Manager's _Software & Updates_ can be configured for automatic updates.

- Installation and configuration of the `unattended-upgrades` package.

- **GNOME Update Manager:** Configure _Software & Updates_ for automatic updates

- **unattended-upgrades:** Install and configure the `unattended-upgrades` package

More detail is available [here](https://help.ubuntu.com/community/AutomaticSecurityUpdates).

More detail is available at [Ubuntu Automatic Security Updates](https://help.ubuntu.com/community/AutomaticSecurityUpdates).

_Fingerprint Reader_ - If your Dell laptop has a fingerprint reader, modern Ubuntu may support it out of the box, if not consider the following steps (YMMV, it may require another solution):

### Fingerprint Reader

If your Dell laptop has a fingerprint reader, modern Ubuntu may support it out of the box. If not, consider the following steps (results may vary):

```bash

sudo apt install libpam-fprintd

sudo systemctl status fprintd.service

sudo systemctl restart fprintd.service

```

## Troubleshooting

### SentinelOne Installation Issues

If you're using Advanced Intrusion Detection Environment (AIDE), create an exclusion for SentinelOne:

```bash

echo '!/opt/sentinelone/mount' | sudo tee -a /etc/aide.conf

```

### SentinelOne Agent Offline

The most common reason for a SentinelOne agent to appear offline is a local firewall prohibiting outbound connections to `*.sentinelone.net`. HTTPS (port 443) needs to be allowed outbound to that domain.

Check agent status:

```bash

sudo sentinelctl management status

```

Common local firewalls that may block access include pfSense and iptables.

### Fleet Package Not Available

If the appropriate Fleet package doesn't exist for your endpoint, contact `#security_help` for assistance building fleetd from source.

## Support

- **Fleet/EDR Issues:** `#security_help`

- **SentinelOne Help:** `#sentinelone`

- **CrowdStrike Help:** `#crowdstrike`

- **General Linux Tips:** `#linux`