mirror of
https://github.com/fleetdm/fleet
synced 2026-04-21 21:47:20 +00:00
110 lines
6.4 KiB
Markdown
110 lines
6.4 KiB
Markdown
# Variables in scripts and configuration profiles
|
||
|
||
<div purpose="embedded-content">
|
||
<iframe src="https://www.youtube.com/embed/VRK-3rN7-aY" frameborder="0" allowfullscreen></iframe>
|
||
</div>
|
||
|
||
In Fleet you can add variables, in [scripts](https://fleetdm.com/guides/scripts) and [configuration profiles](https://fleetdm.com/guides/custom-os-settings). Variables are hidden when the script or configuration profile is viewed in the Fleet UI or API.
|
||
|
||
Configuration profiles can also use any of Fleet's [built-in variables](https://fleetdm.com/docs/configuration/yaml-files#variables).
|
||
|
||
## Add variables
|
||
|
||
A variable can be used in a script or configuration profile by specifying a variable in the format `$FLEET_SECRET_MYNAME` or `${FLEET_SECRET_MYNAME}`. When the script or profile is sent to the host, Fleet will replace the variable with the variable's value. The prefix `FLEET_SECRET_` is required to indicate that this is a variable, and Fleet reserves this prefix for variables.
|
||
|
||
For macOS and Linux scripts, if a variable doesn't have the `$FLEET_SECRET_` prefix, it will be treated as a [local environment variable](https://support.apple.com/en-my/guide/terminal/apd382cc5fa-4f58-4449-b20a-41c53c006f8f/mac).
|
||
|
||
### UI
|
||
|
||
To add or delete a variable in the UI, go to `Controls` > `Variables` and click `+ Add custom variable`:
|
||
|
||
|
||
|
||
Variables are global, meaning they can be used in scripts and profiles across all fleets.
|
||
|
||
### GitOps
|
||
|
||
1. Add the variable to your [GitHub](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository) or [GitLab](https://docs.gitlab.com/ci/variables/#define-a-cicd-variable-in-the-ui) repository's secrets to use the variable in GitOps.
|
||
|
||
2. Define the variable in the `env` section of in your `workflows.yml` file, as shown below:
|
||
|
||
```yaml
|
||
env:
|
||
### Variables used by the GitOps workflow ###
|
||
FLEET_URL: ${{ secrets.FLEET_URL }}
|
||
FLEET_API_TOKEN: ${{ secrets.FLEET_API_TOKEN }}
|
||
WORKSTATIONS_ENROLL_SECRET: ${{ secrets.WORKSTATIONS_ENROLL_SECRET }}
|
||
```
|
||
|
||
### Scripts and configuration profiles
|
||
|
||
During a GitOps run, Fleet scans scripts and profiles for variables, pulls their values from GitHub or GitLab, and uploads them to Fleet.
|
||
|
||
Profiles with variables aren’t validated during a GitOps dry run because the variables may be missing or incorrect in Fleet. This means they’re more likely to fail during a real run. Best practice: test the script or profile by adding it to Fleet via the UI first.
|
||
|
||
Some variables trigger a profile resend when their value changes. See which variables support this in the [YAML reference docs](https://fleetdm.com/docs/configuration/yaml-files#variables).
|
||
|
||
If a variable is a secret (for example, an API token), prefix it with FLEET_SECRET_. This masks the value when viewed or downloaded from the Fleet UI or API.
|
||
|
||
Variables aren't removed on GitOps runs. To remove a variable, delete it on the `Controls` > `Variables` page.
|
||
|
||
> Profiles with variables are not entirely validated during a GitOps dry run because the required variables may not exist or may be incorrect in the database. As a result, these profiles have a higher chance of failing during a non-dry run. Test them by uploading to a small fleet first.
|
||
|
||
## Using the secret on a configuration profile
|
||
|
||
Here's an example profile with `$FLEET_SECRET_CERT_PASSWORD` and `$FLEET_SECRET_CERT_BASE64` variables:
|
||
```xml
|
||
<?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>PayloadDisplayName</key>
|
||
<!-- Note: Do not use $FLEET_SECRET_ variables in PayloadDisplayName -->
|
||
<string>Certificate PKCS12</string>
|
||
<key>PayloadIdentifier</key>
|
||
<string>com.example.certificate</string>
|
||
<key>PayloadType</key>
|
||
<string>Configuration</string>
|
||
<key>PayloadUUID</key>
|
||
<string>918ee83d-ebd5-4192-bcd4-8b4feb750e4b</string>
|
||
<key>PayloadVersion</key>
|
||
<integer>1</integer>
|
||
<key>PayloadContent</key>
|
||
<array>
|
||
<dict>
|
||
<key>Password</key>
|
||
<string>$FLEET_SECRET_CERT_PASSWORD</string>
|
||
<key>PayloadContent</key>
|
||
<data>${FLEET_SECRET_CERT_BASE64}</data>
|
||
<key>PayloadDisplayName</key>
|
||
<string>Certificate PKCS12</string>
|
||
<key>PayloadIdentifier</key>
|
||
<string>com.example.certificate</string>
|
||
<key>PayloadType</key>
|
||
<string>com.apple.security.pkcs12</string>
|
||
<key>PayloadUUID</key>
|
||
<string>25cdd076-f1e7-4932-aa30-1d4240534fb0</string>
|
||
<key>PayloadVersion</key>
|
||
<integer>1</integer>
|
||
</dict>
|
||
</array>
|
||
</dict>
|
||
</plist>
|
||
```
|
||
|
||
> Fleet variables are automatically escaped in Apple (`.mobileconfig`) and Windows (`.xml`) configuration profiles. For example, `&` will become `&`. Special characters outside of Fleet variables must be manually escaped because they have special meanings in XML.
|
||
|
||
## Known limitations and issues
|
||
|
||
- **Apple MDM profiles**: Fleet secret variables (`$FLEET_SECRET_*`) cannot be used in the `PayloadDisplayName` field of Apple configuration profiles. This field becomes the visible name of the profile and using secrets here could expose sensitive information. Place secrets in other fields like `PayloadDescription`, `Password`, or `PayloadContent` instead.
|
||
- After changing a variable used by a Windows profile, that profile is currently not re-sent to the device when the GitHub action (or GitLab pipeline) runs: [story #27351](https://github.com/fleetdm/fleet/issues/27351)
|
||
- Fleet does not hide the secret in script results. Don't print/echo your secrets to the console output.
|
||
- There is no way to explicitly delete a secret variable. Instead, you can overwrite it with any value.
|
||
- Do not use deprecated API endpoint(s) to upload profiles containing secret variables. Use endpoints documented in [Fleet's REST API](https://fleetdm.com/docs/rest-api/rest-api).
|
||
|
||
<meta name="articleTitle" value="Variables in scripts and configuration profiles">
|
||
<meta name="authorFullName" value="Victor Lyuboslavsky">
|
||
<meta name="authorGitHubUsername" value="getvictor">
|
||
<meta name="category" value="guides">
|
||
<meta name="publishedOn" value="2025-01-02">
|
||
<meta name="description" value="A guide on using variables in scripts and configuration profiles.">
|