Forge Home

fleetdm

MDM management and profile assignment using FleetDM

462 downloads

141 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.2.3 (latest)
  • 0.2.2
  • 0.2.1
  • 0.2.0
  • 0.1.2
released Jul 26th 2023
This version is compatible with:
  • Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x
  • Puppet >= 6.21.0 < 8.0.0

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'fleetdm-fleetdm', '0.2.3'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add fleetdm-fleetdm
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install fleetdm-fleetdm --version 0.2.3

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

fleetdm/fleetdm — version 0.2.3 Jul 26th 2023

fleetdm

Table of Contents

  1. Description
  2. Setup - The basics of getting started with fleetdm
  3. Usage - Configuration options and additional functionality
  4. Limitations - OS compatibility, etc.
  5. Development - Guide for contributing to the module

Description

Manage MDM settings for macOS devices using Fleet

Setup

Setup Requirements

This module requires to add fleetdm as a reporter in your report settings, this helps Fleet understand when your Puppet run is finished and assign the device to a team with the necessary profiles.

For example, in your server configuration:

reports = http,fleetdm

To communicate with the Fleet server, you also need to provide your server URL and a token as Hiera values:

---
fleetdm::host: https://example.com
fleetdm::token: my_token 

Note: for the token, we recommend using an API-only user, with a GitOps role.

Beginning with fleetdm

Usage

Defining profiles for a device

The examples/ folder in this repo contain some examples. Generally, you can define profiles using the custom resource type fleetdm::profile:

node default {
  fleetdm::profile { 'com.apple.universalaccess':
    template => template('fleetdm/profile-template.mobileconfig.erb'),
    group    => 'workstations',
  }
}

The group parameter is used to create/match profiles with teams in Fleet. In the example above, all devices will be assigned to a team named workstations.

You can use this feature along with the ensure param to create teams that don't contain specific profiles, for example given the following manifest:

node default {
  fleetdm::profile { 'com.apple.universalaccess':
    template => template('fleetdm/profile-template.mobileconfig.erb'),
    group    => 'workstations',
  }

  if $facts['architecture'] == 'x86_64' {
      fleetdm::profile { 'my.arm.only.profile':
        ensure => absent,
        template => template('fleetdm/my-arm-only-profile.mobileconfig.erb'),
        group    => 'amd64',
      }
  } else {
      fleetdm::profile { 'my.arm.only.profile':
        template => template('fleetdm/my-arm-only-profile.mobileconfig.erb'),
        group    => 'workstations',
      }
  }
}

Assuming you have devices with both architectures checking in, you'll end up with the following two teams in Fleet:

  • workstations: with two profiles, com.apple.universalaccess and my.arm.only.profile
  • workstations - amd64: with only one profile, com.apple.universalaccess

Sending a custom MDM Command

You can use the fleetdm::command_xml function to send any custom MDM command to the device:

$host_uuid = $facts['system_profiler']['hardware_uuid']
$command_uuid = generate('/usr/bin/uuidgen').strip

$xml_data = "<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE plist PUBLIC '-//Apple//DTD PLIST 1.0//EN' 'http://www.apple.com/DTDs/PropertyList-1.0.dtd'>
<plist version='1.0'>
<dict>
    <key>Command</key>
    <dict>
        <key>RequestType</key>
        <string>EnableRemoteDesktop</string>
    </dict>
    <key>CommandUUID</key>
    <string>${command_uuid}</string>
</dict>
</plist>"

$response = fleetdm::command_xml($host_uuid, $xml_data)
$err = $response['error']

if $err != '' {
  notify { "Error sending MDM command: ${err}": }
}

Releasing a device from await configuration

If your DEP profile had await_device_configured set to true, you can use the fleetdm::release_device function to release the device:

$host_uuid = $facts['system_profiler']['hardware_uuid']
$response = fleetdm::release_device($host_uuid)
$err = $response['error']

if $err != '' {
  notify { "error releasing device: ${err}": }
}

Limitations

At the moment, this module only works for macOS devices.

Development

Information about how to contribute can be found in the CONTRIBUTING.md file.