Skip to content

Commit

Permalink
Merge pull request #2199 from MicrosoftDocs/main
Browse files Browse the repository at this point in the history 
Publish main to live, 12/16/24, 3:30 PM PT
  • Loading branch information
@Ruchika-mittal01
Ruchika-mittal01 authored Dec 16, 2024
2 parents f19e164 + c09f72e commit df42682
Showing 1 changed file with 179 additions and 91 deletions.
270 changes: 179 additions & 91 deletions defender-endpoint/linux-install-with-puppet.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ ms.collection:
ms.topic: conceptual
ms.subservice: linux
search.appverid: met150
ms.date: 10/11/2024
ms.date: 12/16/2024
---

# Deploy Microsoft Defender for Endpoint on Linux with Puppet
Expand All @@ -25,23 +25,23 @@ ms.date: 10/11/2024
**Applies to**:

- Microsoft Defender for Endpoint Server
- [Microsoft Defender for Servers](/azure/defender-for-cloud/integration-defender-for-endpoint)
- [Microsoft Defender for Servers](/azure/defender-for-cloud/integration-defender-for-endpoint)

> Want to experience Defender for Endpoint? [Sign up for a free trial.](https://signup.microsoft.com/create-account/signup?products=7f379fee-c4f9-4278-b0a1-e4c8c2fcdf7e&ru=https://aka.ms/MDEp2OpenTrial?ocid=docs-wdatp-investigateip-abovefoldlink)
This article describes how to deploy Defender for Endpoint on Linux using Puppet. A successful deployment requires the completion of all of the following tasks:

- [Download the onboarding package](#download-the-onboarding-package)
- [Create Puppet manifest](#create-a-puppet-manifest)
- [Deployment](#deployment)
- [Check onboarding status](#check-onboarding-status)
- [Deployment (include the manifest inside the site.pp file)](#include-the-manifest-inside-the-sitepp-file)
- [Monitor your Puppet deployment](#monitor-puppet-deployment)

[!INCLUDE [Microsoft Defender for Endpoint third-party tool support](../includes/support.md)]


## Prerequisites and system requirements

For a description of prerequisites and system requirements for the current software version, see [the main Defender for Endpoint on Linux page](microsoft-defender-endpoint-linux.md).
For a description of prerequisites and system requirements, see [Microsoft Defender for Endpoint on Linux](microsoft-defender-endpoint-linux.md).

In addition, for Puppet deployment, you need to be familiar with Puppet administration tasks, have Puppet configured, and know how to deploy packages. Puppet has many ways to complete the same task. These instructions assume availability of supported Puppet modules, such as *apt* to help deploy the package. Your organization might use a different workflow. Refer to the [Puppet documentation](https://puppet.com/docs) for details.

Expand All @@ -51,7 +51,7 @@ Download the onboarding package from Microsoft Defender portal.

[!INCLUDE [Defender for Endpoint repackaging warning](../includes/repackaging-warning.md)]

1. In Microsoft Defender portal, go to **Settings** > **Endpoints** > **Device management** > **Onboarding**.
1. In the [Microsoft Defender portal](https://security.microsoft.com), go to **Settings** > **Endpoints** > **Device management** > **Onboarding**.

2. In the first drop-down menu, select **Linux Server** as the operating system. In the second drop-down menu, select **Your preferred Linux configuration management tool** as the deployment method.

Expand All @@ -72,20 +72,20 @@ Download the onboarding package from Microsoft Defender portal.

5. Extract the contents of the archive.

```bash
unzip WindowsDefenderATPOnboardingPackage.zip
```
```bash
unzip WindowsDefenderATPOnboardingPackage.zip
```

```console
Archive: WindowsDefenderATPOnboardingPackage.zip
inflating: mdatp_onboard.json
```
```console
Archive: WindowsDefenderATPOnboardingPackage.zip
inflating: mdatp_onboard.json
```

## Create a Puppet manifest

You need to create a Puppet manifest for deploying Defender for Endpoint on Linux to devices managed by a Puppet server. This example makes use of the `apt` and `yumrepo` modules available from puppetlabs, and assumes that the modules have been installed on your Puppet server.
You need to create a Puppet manifest for deploying Defender for Endpoint on Linux to devices managed by a Puppet server. This example makes use of the `apt` and `yumrepo` modules available from `puppetlabs`, and assumes that the modules are installed on your Puppet server.

1. Create the folders `install_mdatp/files` and `install_mdatp/manifests` under the modules folder of your Puppet installation. This folder is typically located in `/etc/puppetlabs/code/environments/production/modules` on your Puppet server.
1. Under the **modules** folder if your Puppet installation, create the folders `install_mdatp/files` and `install_mdatp/manifests`. The **modules** folder is typically located at `/etc/puppetlabs/code/environments/production/modules` on your Puppet server.

2. Copy the `mdatp_onboard.json` file created earlier to the `install_mdatp/files` folder.

Expand All @@ -111,7 +111,58 @@ You need to create a Puppet manifest for deploying Defender for Endpoint on Linu
└── init.pp
```

### Contents of `install_mdatp/manifests/init.pp`
### Create a manifest file

There are two ways to create a manifest file:

- Use an installer script; or
- Configure your repositories manually.

#### Create a manifest to deploy Defender for Endpoint using an installer script

Add the following content to the `install_mdatp/manifests/init.pp` file. You can also download the file directly from [GitHub](https://teams.microsoft.com/l/message/19:2c1dc910-b8b7-415a-a9fd-2cd04843b43c_cb7ab2ef-8a66-4fcf-8c66-1723507f52df@unq.gbl.spaces/1734343607885?context=%7B%22contextType%22%3A%22chat%22%7D)

```bash
# Puppet manifest to install Microsoft Defender for Endpoint on Linux.
# @param channel The release channel based on your environment, insider-fast or prod.
class install_mdatp (
$channel = 'prod',
) {
# Ensure that the directory /tmp/mde_install exists
file { '/tmp/mde_install':
ensure => directory,
mode => '0755',
}
# Copy the installation script to the destination
file { '/tmp/mde_install/mde_installer.sh':
ensure => file,
source => 'puppet:///modules/install_mdatp/mde_installer.sh',
mode => '0777',
}
# Copy the onboarding script to the destination
file { '/tmp/mde_install/mdatp_onboard.json':
ensure => file,
source => 'puppet:///modules/install_mdatp/mdatp_onboard.json',
mode => '0777',
}
# Install MDE on the host using an external script
exec { 'install_mde':
command => "/tmp/mde_install/mde_installer.sh --install --channel ${channel} --onboard /tmp/mde_install/mdatp_onboard.json",
path => '/bin:/usr/bin',
user => 'root',
logoutput => true,
require => File['/tmp/mde_install/mde_installer.sh', '/tmp/mde_install/mdatp_onboard.json'], # Ensure the script is copied before running the installer
}
}
```
#### Create a manifest to deploy Defender for Endpoint by configuring repositories manually

Defender for Endpoint on Linux can be deployed from one of the following channels:

Expand All @@ -123,7 +174,7 @@ Each channel corresponds to a Linux software repository.

The choice of the channel determines the type and frequency of updates that are offered to your device. Devices in *insiders-fast* are the first ones to receive updates and new features, followed later by *insiders-slow*, and lastly by *prod*.

In order to preview new features and provide early feedback, it's recommended that you configure some devices in your enterprise to use either *insiders-fast* or *insiders-slow*.
In order to preview new features and provide early feedback, we recommend that you configure some devices in your enterprise to use either *insiders-fast* or *insiders-slow*.

> [!WARNING]
> Switching the channel after the initial installation requires the product to be reinstalled. To switch the product channel: uninstall the existing package, re-configure your device to use the new channel, and follow the steps in this document to install the package from the new location.
Expand All @@ -135,76 +186,109 @@ In the below commands, replace *[distro]* and *[version]* with the information y
> [!NOTE]
> In case of RedHat, Oracle Linux, Amazon Linux 2, and CentOS 8, replace *[distro]* with 'rhel'.
```puppet
Add the following content to the `install_mdatp/manifests/init.pp` file:
```bash
# Puppet manifest to install Microsoft Defender for Endpoint on Linux.
# @param channel The release channel based on your environment, insider-fast or prod.
# @param distro The Linux distribution in lowercase. In case of RedHat, Oracle Linux, Amazon Linux 2, and CentOS 8, the distro variable should be 'rhel'.
# @param version The Linux distribution release number, e.g. 7.4.
class install_mdatp (
$channel = 'insiders-fast',
$distro = undef,
$version = undef
) {
case $facts['os']['family'] {
'Debian' : {
$release = $channel ? {
'prod' => $facts['os']['distro']['codename'],
default => $channel
}
apt::source { 'microsoftpackages' :
location => "https://packages.microsoft.com/${distro}/${version}/prod",
release => $release,
repos => 'main',
key => {
'id' => 'BC528686B50D79E339D3721CEB3E94ADBE1229CF',
'server' => 'keyserver.ubuntu.com',
},
}
}
'RedHat' : {
yumrepo { 'microsoftpackages' :
baseurl => "https://packages.microsoft.com/${distro}/${version}/${channel}",
descr => "packages-microsoft-com-prod-${channel}",
enabled => 1,
gpgcheck => 1,
gpgkey => 'https://packages.microsoft.com/keys/microsoft.asc',
}
class install_mdatp::configure_debian_repo (
String $channel,
String $distro,
String $version ) {
# Configure the APT repository for Debian-based systems
$release = $channel ? {
'prod' => $facts['os']['distro']['codename'],
default => $channel
}
default : { fail("${facts['os']['family']} is currently not supported.") }
apt::source { 'microsoftpackages':
location => "https://packages.microsoft.com/${distro}/${version}/prod",
release => $release,
repos => 'main',
key => {
'id' => 'BC528686B50D79E339D3721CEB3E94ADBE1229CF',
'server' => 'keyserver.ubuntu.com',
},
}
}
class install_mdatp::configure_redhat_repo (
String $channel,
String $distro,
String $version) {
# Configure the Yum repository for RedHat-based systems
yumrepo { 'microsoftpackages':
baseurl => "https://packages.microsoft.com/rhel/${version}/prod",
descr => 'packages-microsoft-com-prod',
enabled => 1,
gpgcheck => 1,
gpgkey => 'https://packages.microsoft.com/keys/microsoft.asc',
}
}
class install_mdatp::install {
# Common configurations for both Debian and RedHat
file { ['/etc/opt', '/etc/opt/microsoft', '/etc/opt/microsoft/mdatp']:
ensure => directory,
owner => 'root',
group => 'root',
mode => '0755',
}
file { '/etc/opt/microsoft/mdatp/mdatp_onboard.json':
source => 'puppet:///modules/install_mdatp/mdatp_onboard.json',
owner => 'root',
group => 'root',
mode => '0600',
require => File['/etc/opt/microsoft/mdatp'],
}
# Install mdatp package
package { 'mdatp':
ensure => installed,
require => [
File['/etc/opt/microsoft/mdatp/mdatp_onboard.json'],
],
}
}
class install_mdatp (
$channel = 'prod'
) {
# Include the appropriate class based on the OS family
$distro = downcase($facts['os']['name'])
$version = $facts['os']['release']['major']
case $facts['os']['family'] {
/(Debian|RedHat)/: {
file { ['/etc/opt', '/etc/opt/microsoft', '/etc/opt/microsoft/mdatp']:
ensure => directory,
owner => root,
group => root,
mode => '0755',
}
file { '/etc/opt/microsoft/mdatp/mdatp_onboard.json':
source => 'puppet:///modules/install_mdatp/mdatp_onboard.json',
owner => root,
group => root,
mode => '0600',
require => File['/etc/opt/microsoft/mdatp'],
}
package { 'mdatp':
ensure => 'installed',
require => File['/etc/opt/microsoft/mdatp/mdatp_onboard.json'],
}
'Debian': {
class { 'install_mdatp::configure_debian_repo':
channel => 'prod',
distro => $distro,
version => $version
} -> class { 'install_mdatp::install': }
}
'RedHat': {
class { 'install_mdatp::configure_redhat_repo':
channel => 'prod',
distro => $distro,
version => $version,
} -> class { 'install_mdatp::install': }
}
default : { fail("${facts['os']['family']} is currently not supported.") }
default: { fail("${facts['os']['family']} is currently not supported.")}
}
}
```
## Deployment
## Include the manifest inside the site.pp file
Include the above manifest in your `site.pp` file:
Include the manifest described earlier in this article in your `site.pp` file:
```bash
cat /etc/puppetlabs/code/environments/production/manifests/site.pp
Expand All @@ -216,52 +300,56 @@ node "default" {
}
```
Enrolled agent devices periodically poll the Puppet Server and install new configuration profiles and policies as soon as they are detected.
Enrolled agent devices periodically poll the Puppet Server and install new configuration profiles and policies as soon as they're detected.

## Monitor Puppet deployment

On the agent device, you can also check the onboarding status by running:
On the agent device, you can also check the deployment status by running the following command:

```bash
mdatp health
```

```console
...
healthy : true
health_issues : []
licensed : true
org_id : "[your organization identifier]"
...
```

- **licensed**: This confirms that the device is tied to your organization.
- `healthy`: Confirm that Defender for Endpoint is successfully deployed and operational.
- `health_issues`: States the issues which caused the healthy status to become false.
- `licensed`: Confirms that the device is tied to your organization.
- `orgId`: Your Defender for Endpoint organization identifier.

- **orgId**: This is your Defender for Endpoint organization identifier.
## Troubleshoot installation issues

## Check onboarding status
If you encounter issues during installation, try these self-troubleshooting steps:

You can check that devices have been correctly onboarded by creating a script. For example, the following script checks enrolled devices for onboarding status:
1. Refer to [Log installation issues](linux-resources.md#log-installation-issues) for more information on how to find the automatically generated log that is created by the installer when an error occurs.

```bash
mdatp health --field healthy
```
2. Refer to [Installation issues](/defender-endpoint/linux-support-install) for more information on commonly occurring installation issues

3. If health of the device is false, refer to [MDE agent health issues](/defender-endpoint/health-status)

The above command prints `1` if the product is onboarded and functioning as expected.
4. For product performance issues, refer to [Troubleshoot performance issues](/defender-endpoint/linux-support-perf), [performance tuning](/defender-endpoint/linux-support-perf?branch=main)

> [!IMPORTANT]
> When the product starts for the first time, it downloads the latest antimalware definitions. Depending on your Internet connection, this can take up to a few minutes. During this time the above command returns a value of `0`.
5. For proxy and connectivity issues, refer to [Troubleshoot cloud connectivity issues](/defender-endpoint/linux-support-connectivity)

If the product is not healthy, the exit code (which can be checked through `echo $?`) indicates the problem:
To get support from Microsoft, raise a support ticket and provide log files by using the [client analyzer](/defender-endpoint/run-analyzer-macos-linux)

- `1` if the device isn't onboarded yet.
- `3` if the connection to the daemon cannot be established.
## How to configure policies for Microsoft Defender on Linux

## Log installation issues
You can configure antivirus and EDR settings on your endpoints using following methods:

For more information on how to find the automatically generated log that is created by the installer when an error occurs, see [Log installation issues](linux-resources.md#log-installation-issues).
- See [Set preferences for Microsoft Defender for Endpoint on Linux](/defender-endpoint/linux-preferences) to learn more about the available settings
- See [security settings management](/mem/intune/protect/mde-security-integration) to configure settings in the Microsoft Defender portal.

## Operating system upgrades

When upgrading your operating system to a new major version, you must first uninstall Defender for Endpoint on Linux, install the upgrade, and finally reconfigure Defender for Endpoint on Linux on your device.
When upgrading your operating system to a new major version, you must first uninstall Defender for Endpoint on Linux, install the upgrade, and then reconfigure Defender for Endpoint on Linux on your device.

## Uninstallation

Expand Down

0 comments on commit df42682

Please sign in to comment.