diff --git a/docs/Using Fleet/Puppet-module.md b/docs/Using Fleet/Puppet-module.md new file mode 100644 index 0000000000..6da85051b0 --- /dev/null +++ b/docs/Using Fleet/Puppet-module.md @@ -0,0 +1,157 @@ +# Puppet module + +_Available in Fleet Premium_ + +Use [Fleet's Puppet module](https://forge.puppet.com/modules/fleetdm/fleetdm/readme) to automatically install custom configuration profiles on your macOS hosts based on host attributes you define in Puppet. + +The module also includes functions for releasing a macOS host from [Await Configuration](https://developer.apple.com/documentation/devicemanagement/release_device_from_await_configuration) and sending any custom MDM commands. + +## Setup + +To set up the Puppet module, we will do the following steps: + +1. Install the Puppet module +2. Configure Puppet to talk to Fleet using Hiera +3. Set Fleet as a reporter + +### Step 1: install the Puppet module + +Install [Fleet's Puppet module](https://forge.puppet.com/modules/fleetdm/fleetdm/readme). For more instructions on how to install Puppet modules, check out the Puppet docs [here](https://www.puppet.com/docs/puppet/8/modules_installing.html). + +### Step 2: configure Puppet to talk to Fleet using Heira + +1. Create an API-only user with the GitOps role in Fleet. Instructions for creating an API-only user in Fleet are [here](./fleetctl-CLI.md#create-an-api-only-user). + +2. Get the API token for your new API-only user. Learn how [here](./fleetctl-CLI.md#get-the-api-token-of-an-api-only-user). + +3. Set `fleetdm::host` and `fleetdm::token` values to your Fleet server's URL and the API token respectively. Here's an example of the Hiera YAML: + +```yaml +fleetdm::host: https://fleet.example.com +fleetdm::token: your-api-token +``` + +Puppet docs on configuring Hiera are [here](https://www.puppet.com/docs/puppet/6/hiera_config_yaml_5.html). + +If you have staging and production Puppet environments, you can optionally set different values for each environment. This allows you to have your staging and production environments that talk to separate staging and production Fleet servers. + +### Step 3: set Fleet as a reporter + +In your Puppet configuration, set `http:fleetdm` as the value for `reports`. Here's an example of the Puppet configuration: + +``` +reports = http,fleetdm +``` + +Puppet configuration reference docs are [here](https://www.puppet.com/docs/puppet/7/configuration#reports). + +## Install configuration profiles + +Using the Puppet module you can define the set of configuration profiles for each host (Puppet node) and Fleet will create a team with these profiles and assign the host to that team. + +When a host is assigned to a team in Fleet, all configuration profiles for that team are installed on the host. + +As an example, let's install one configuration profile on all hosts. Here's what your Puppet code will look like: + +```pp +node default { + fleetdm::profile { 'com.apple.payload.identifier': + template => template('example-profile.mobileconfig'), + group => 'MacOS workstations', + } +} +``` + +This will create a team called "MacOS workstations" with the `example-profile.mobileconfig` configuration profile and assign all hosts to this team. + +Use the `group` parameter to define the team name in Fleet. + +As another example, let's assign one configuration profile to all hosts and another configuration profile to only my M1 hosts. Here's what your Puppet code will look like: + +```pp +node default { + fleetdm::profile { 'com.apple.payload.identifier-1': + template => template('example-profile.mobileconfig'), + group => 'MacOS workstations', + } + + if $facts['architecture'] == 'intel' { + fleetdm::profile { 'com.apple.payload.identifier-2': + ensure => absent, + template => template('m1-only.mobileconfig'), + group => 'Intel', + } + } else { + fleetdm::profile { 'com.apple.example-2': + template => template('com.apple.payload.identifier-2'), + group => 'MacOS workstations', + } + } +} +``` + +This will create two teams in Fleet: + +1. "MacOS workstations" with two configuration profiles: `example-profile.mobileconfig` and `m1-only.mobileconfig`. +2. "MacOS workstations - Intel" with one configuration profile: `example-profile.mobileconfig`. + +Set the `ensure` parameter to `absent` to create teams that exclude specific profiles. + +For more examples check out the `examples/` folder in Fleet's GitHub repository [here](https://github.com/fleetdm/fleet/tree/main/ee/tools/puppet/fleetdm/examples). + +> Note that all teams created by Puppet inherit the bootstrap package, macOS Setup Assistant settings, and end user authentication settings from "No team." Learn more about these [here](./MDM-macOS-setup.md). In addition all teams automatically enable disk encryption. Learn more about disk encryption [here](./MDM-disk-encryption.md). + +## Release host + +If you set `await_device_configured` to `true` in your [macOS Setup Assistant settings](./MDM-macOS-setup.md#macos-setup-assistant), you can use the `fleetdm::release_device` function to release the host from the Setup Assistant. + +Here's what your Puppet code, with error handling, will look like: + +```pp +$host_uuid = $facts['system_profiler']['hardware_uuid'] +$response = fleetdm::release_device($host_uuid) +$err = $response['error'] + +if $err != '' { + notify { "error releasing device: ${err}": } +} +``` + +## Custom commands + +You can use the `fleetdm::command_xml` function to send any custom MDM command to a host. + +Here's what your Puppet code, with error handling, will look like: + +```pp +$host_uuid = $facts['system_profiler']['hardware_uuid'] +$command_uuid = generate('/usr/bin/uuidgen').strip + +$xml_data = " + + + + Command + + RequestType + EnableRemoteDesktop + + CommandUUID + ${command_uuid} + +" + +$response = fleetdm::command_xml($host_uuid, $xml_data) +$err = $response['error'] + +if $err != '' { + notify { "Error sending MDM command: ${err}": } +} +``` + +The above example includes the XML payload for the `EnableRemoteDesktop` MDM command. Learn more about creating the payload for other custom commands [here](./MDM-commands.md). + + + + + diff --git a/ee/tools/puppet/fleetdm/README.md b/ee/tools/puppet/fleetdm/README.md index d8f62178d7..d70473f014 100644 --- a/ee/tools/puppet/fleetdm/README.md +++ b/ee/tools/puppet/fleetdm/README.md @@ -1,150 +1 @@ -# fleetdm - -## Table of Contents - -1. [Description](#description) -1. [Setup - The basics of getting started with fleetdm](#setup) - * [Setup requirements](#setup-requirements) - * [Beginning with fleetdm](#beginning-with-fleetdm) -1. [Usage - Configuration options and additional functionality](#usage) - * [Defining profiles for a device](#defining-profiles-for-a-device) - * [Releasing a device from await configuration](#releasing-a-device-from-await-configuration) -3. [Limitations - OS compatibility, etc.](#limitations) -4. [Development - Guide for contributing to the module](#development) - -## Description - -Manage MDM settings for macOS devices using [Fleet](https://fleetdm.com) - -## 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: - -```yaml ---- -fleetdm::host: https://example.com -fleetdm::token: my_token -``` - -Note: for the token, we recommend using an [API-only user][1], 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`: - - -```pp -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: - -```pp -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: - -```pp -$host_uuid = $facts['system_profiler']['hardware_uuid'] -$command_uuid = generate('/usr/bin/uuidgen').strip - -$xml_data = " - - - - Command - - RequestType - EnableRemoteDesktop - - CommandUUID - ${command_uuid} - -" - -$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](https://github.com/fleetdm/fleet/blob/main/ee/tools/puppet/fleetdm/CONTRIBUTING.md). - -[1]: https://fleetdm.com/docs/using-fleet/fleetctl-cli#using-fleetctl-with-an-api-only-user +Learn how to setup and use Fleet's Puppet module here on [fleetdm.com/docs](https://fleetdm.com/docs/using-fleet/puppet-module).