Skip to content

Commit c09f72e

Browse files
denisebmsftdenisebmsft
authored
Merge pull request #2195 from meghapriyams/docs-editor/linux-install-with-puppet-1734344381
Update linux-install-with-puppet.md
2 parents 6204f81 + e625639 commit c09f72e

File tree

1 file changed

+179
-91
lines changed

1 file changed

+179
-91
lines changed

‎defender-endpoint/linux-install-with-puppet.md‎

Lines changed: 179 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ms.collection:
1515
ms.topic: conceptual
1616
ms.subservice: linux
1717
search.appverid: met150
18-
ms.date: 10/11/2024
18+
ms.date: 12/16/2024
1919
---
2020

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

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

3030
> 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)
3131
3232
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:
3333

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

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

4141

4242
## Prerequisites and system requirements
4343

44-
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).
44+
For a description of prerequisites and system requirements, see [Microsoft Defender for Endpoint on Linux](microsoft-defender-endpoint-linux.md).
4545

4646
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.
4747

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

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

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

5656
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.
5757

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

7373
5. Extract the contents of the archive.
7474

75-
```bash
76-
unzip WindowsDefenderATPOnboardingPackage.zip
77-
```
75+
```bash
76+
unzip WindowsDefenderATPOnboardingPackage.zip
77+
```
7878

79-
```console
80-
Archive: WindowsDefenderATPOnboardingPackage.zip
81-
inflating: mdatp_onboard.json
82-
```
79+
```console
80+
Archive: WindowsDefenderATPOnboardingPackage.zip
81+
inflating: mdatp_onboard.json
82+
```
8383

8484
## Create a Puppet manifest
8585

86-
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.
86+
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.
8787

88-
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.
88+
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.
8989

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

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

114-
### Contents of `install_mdatp/manifests/init.pp`
114+
### Create a manifest file
115+
116+
There are two ways to create a manifest file:
117+
118+
- Use an installer script; or
119+
- Configure your repositories manually.
120+
121+
#### Create a manifest to deploy Defender for Endpoint using an installer script
122+
123+
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)
124+
125+
```bash
126+
127+
# Puppet manifest to install Microsoft Defender for Endpoint on Linux.
128+
# @param channel The release channel based on your environment, insider-fast or prod.
129+
130+
class install_mdatp (
131+
$channel = 'prod',
132+
) {
133+
# Ensure that the directory /tmp/mde_install exists
134+
file { '/tmp/mde_install':
135+
ensure => directory,
136+
mode => '0755',
137+
}
138+
139+
# Copy the installation script to the destination
140+
file { '/tmp/mde_install/mde_installer.sh':
141+
ensure => file,
142+
source => 'puppet:///modules/install_mdatp/mde_installer.sh',
143+
mode => '0777',
144+
}
145+
146+
# Copy the onboarding script to the destination
147+
file { '/tmp/mde_install/mdatp_onboard.json':
148+
ensure => file,
149+
source => 'puppet:///modules/install_mdatp/mdatp_onboard.json',
150+
mode => '0777',
151+
}
152+
153+
# Install MDE on the host using an external script
154+
exec { 'install_mde':
155+
command => "/tmp/mde_install/mde_installer.sh --install --channel ${channel} --onboard /tmp/mde_install/mdatp_onboard.json",
156+
path => '/bin:/usr/bin',
157+
user => 'root',
158+
logoutput => true,
159+
require => File['/tmp/mde_install/mde_installer.sh', '/tmp/mde_install/mdatp_onboard.json'], # Ensure the script is copied before running the installer
160+
}
161+
162+
}
163+
164+
```
165+
#### Create a manifest to deploy Defender for Endpoint by configuring repositories manually
115166

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

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

124175
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*.
125176

126-
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*.
177+
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*.
127178

128179
> [!WARNING]
129180
> 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.
@@ -135,76 +186,109 @@ In the below commands, replace *[distro]* and *[version]* with the information y
135186
> [!NOTE]
136187
> In case of RedHat, Oracle Linux, Amazon Linux 2, and CentOS 8, replace *[distro]* with 'rhel'.
137188
138-
```puppet
189+
Add the following content to the `install_mdatp/manifests/init.pp` file:
190+
191+
```bash
139192
# Puppet manifest to install Microsoft Defender for Endpoint on Linux.
140193
# @param channel The release channel based on your environment, insider-fast or prod.
141-
# @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'.
142-
# @param version The Linux distribution release number, e.g. 7.4.
143194
144-
class install_mdatp (
145-
$channel = 'insiders-fast',
146-
$distro = undef,
147-
$version = undef
148-
) {
149-
case $facts['os']['family'] {
150-
'Debian' : {
151-
$release = $channel ? {
152-
'prod' => $facts['os']['distro']['codename'],
153-
default => $channel
154-
}
155-
apt::source { 'microsoftpackages' :
156-
location => "https://packages.microsoft.com/${distro}/${version}/prod",
157-
release => $release,
158-
repos => 'main',
159-
key => {
160-
'id' => 'BC528686B50D79E339D3721CEB3E94ADBE1229CF',
161-
'server' => 'keyserver.ubuntu.com',
162-
},
163-
}
164-
}
165-
'RedHat' : {
166-
yumrepo { 'microsoftpackages' :
167-
baseurl => "https://packages.microsoft.com/${distro}/${version}/${channel}",
168-
descr => "packages-microsoft-com-prod-${channel}",
169-
enabled => 1,
170-
gpgcheck => 1,
171-
gpgkey => 'https://packages.microsoft.com/keys/microsoft.asc',
172-
}
195+
class install_mdatp::configure_debian_repo (
196+
String $channel,
197+
String $distro,
198+
String $version ) {
199+
# Configure the APT repository for Debian-based systems
200+
201+
$release = $channel ? {
202+
'prod' => $facts['os']['distro']['codename'],
203+
default => $channel
173204
}
174-
default : { fail("${facts['os']['family']} is currently not supported.") }
205+
206+
apt::source { 'microsoftpackages':
207+
location => "https://packages.microsoft.com/${distro}/${version}/prod",
208+
release => $release,
209+
repos => 'main',
210+
key => {
211+
'id' => 'BC528686B50D79E339D3721CEB3E94ADBE1229CF',
212+
'server' => 'keyserver.ubuntu.com',
213+
},
214+
}
215+
}
216+
217+
class install_mdatp::configure_redhat_repo (
218+
String $channel,
219+
String $distro,
220+
String $version) {
221+
# Configure the Yum repository for RedHat-based systems
222+
223+
yumrepo { 'microsoftpackages':
224+
baseurl => "https://packages.microsoft.com/rhel/${version}/prod",
225+
descr => 'packages-microsoft-com-prod',
226+
enabled => 1,
227+
gpgcheck => 1,
228+
gpgkey => 'https://packages.microsoft.com/keys/microsoft.asc',
229+
}
230+
}
231+
232+
class install_mdatp::install {
233+
# Common configurations for both Debian and RedHat
234+
235+
file { ['/etc/opt', '/etc/opt/microsoft', '/etc/opt/microsoft/mdatp']:
236+
ensure => directory,
237+
owner => 'root',
238+
group => 'root',
239+
mode => '0755',
240+
}
241+
242+
file { '/etc/opt/microsoft/mdatp/mdatp_onboard.json':
243+
source => 'puppet:///modules/install_mdatp/mdatp_onboard.json',
244+
owner => 'root',
245+
group => 'root',
246+
mode => '0600',
247+
require => File['/etc/opt/microsoft/mdatp'],
175248
}
176249
250+
# Install mdatp package
251+
package { 'mdatp':
252+
ensure => installed,
253+
require => [
254+
File['/etc/opt/microsoft/mdatp/mdatp_onboard.json'],
255+
],
256+
}
257+
}
258+
259+
260+
class install_mdatp (
261+
$channel = 'prod'
262+
) {
263+
# Include the appropriate class based on the OS family
264+
265+
$distro = downcase($facts['os']['name'])
266+
$version = $facts['os']['release']['major']
267+
177268
case $facts['os']['family'] {
178-
/(Debian|RedHat)/: {
179-
file { ['/etc/opt', '/etc/opt/microsoft', '/etc/opt/microsoft/mdatp']:
180-
ensure => directory,
181-
owner => root,
182-
group => root,
183-
mode => '0755',
184-
}
185-
186-
file { '/etc/opt/microsoft/mdatp/mdatp_onboard.json':
187-
source => 'puppet:///modules/install_mdatp/mdatp_onboard.json',
188-
owner => root,
189-
group => root,
190-
mode => '0600',
191-
require => File['/etc/opt/microsoft/mdatp'],
192-
}
193-
194-
package { 'mdatp':
195-
ensure => 'installed',
196-
require => File['/etc/opt/microsoft/mdatp/mdatp_onboard.json'],
197-
}
269+
'Debian': {
270+
class { 'install_mdatp::configure_debian_repo':
271+
channel => 'prod',
272+
distro => $distro,
273+
version => $version
274+
} -> class { 'install_mdatp::install': }
275+
}
276+
'RedHat': {
277+
class { 'install_mdatp::configure_redhat_repo':
278+
channel => 'prod',
279+
distro => $distro,
280+
version => $version,
281+
} -> class { 'install_mdatp::install': }
198282
}
199-
default : { fail("${facts['os']['family']} is currently not supported.") }
283+
default: { fail("${facts['os']['family']} is currently not supported.")}
200284
}
201285
}
202286
203287
```
204288
205-
## Deployment
289+
## Include the manifest inside the site.pp file
206290
207-
Include the above manifest in your `site.pp` file:
291+
Include the manifest described earlier in this article in your `site.pp` file:
208292
209293
```bash
210294
cat /etc/puppetlabs/code/environments/production/manifests/site.pp
@@ -216,52 +300,56 @@ node "default" {
216300
}
217301
```
218302
219-
Enrolled agent devices periodically poll the Puppet Server and install new configuration profiles and policies as soon as they are detected.
303+
Enrolled agent devices periodically poll the Puppet Server and install new configuration profiles and policies as soon as they're detected.
220304

221305
## Monitor Puppet deployment
222306

223-
On the agent device, you can also check the onboarding status by running:
307+
On the agent device, you can also check the deployment status by running the following command:
224308

225309
```bash
226310
mdatp health
227311
```
228312

229313
```console
230314
...
315+
healthy : true
316+
health_issues : []
231317
licensed : true
232318
org_id : "[your organization identifier]"
233319
...
234320
```
235321

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

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

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

242-
You can check that devices have been correctly onboarded by creating a script. For example, the following script checks enrolled devices for onboarding status:
331+
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.
243332

244-
```bash
245-
mdatp health --field healthy
246-
```
333+
2. Refer to [Installation issues](/defender-endpoint/linux-support-install) for more information on commonly occurring installation issues
334+
335+
3. If health of the device is false, refer to [MDE agent health issues](/defender-endpoint/health-status)
247336

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

250-
> [!IMPORTANT]
251-
> 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`.
339+
5. For proxy and connectivity issues, refer to [Troubleshoot cloud connectivity issues](/defender-endpoint/linux-support-connectivity)
252340

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

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

258-
## Log installation issues
345+
You can configure antivirus and EDR settings on your endpoints using following methods:
259346

260-
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).
347+
- See [Set preferences for Microsoft Defender for Endpoint on Linux](/defender-endpoint/linux-preferences) to learn more about the available settings
348+
- See [security settings management](/mem/intune/protect/mde-security-integration) to configure settings in the Microsoft Defender portal.
261349

262350
## Operating system upgrades
263351

264-
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.
352+
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.
265353

266354
## Uninstallation
267355

0 commit comments

Comments
 (0)