> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom file

> Import a custom configuration profile to apply settings not covered by Primo's built-in controls, with support for native profile formats on macOS, iOS/iPadOS, Windows, and Android.

## Platform compatibility

| macOS | Windows | Linux | iOS / iPadOS | Android |
| ----- | ------- | ----- | ------------ | ------- |
| ✅     | ✅       |       | ✅            | ✅       |

## How to set it up

<Steps>
  <Step title="Upload your configuration file">
    Upload your configuration file. The file is delivered to devices via MDM in the same way as any other control.

    <Warning>
      Primo does not validate the contents of custom files. Ensure your configuration is correct before deploying — an invalid or conflicting profile may cause unexpected device behavior.
    </Warning>
  </Step>

  <Step title="Give the control a descriptive name">
    Give the control a descriptive name so it is easy to identify later.
  </Step>

  <Step title="Save and apply">
    Save and apply the control to the relevant device group.
  </Step>
</Steps>

## Modify or remove the control

To change the configuration, re-upload the config file with updated settings. Disabling the control stops enforcement but does not remove existing configurations from devices.

## How it works

Each platform accepts its native configuration format:

| Platform     | Format                     | Description                                     |
| ------------ | -------------------------- | ----------------------------------------------- |
| macOS        | `.mobileconfig` or `.json` | Apple Configuration Profile (XML-based) or JSON |
| iOS / iPadOS | `.mobileconfig`            | Apple Configuration Profile (XML-based)         |
| Windows      | `.xml`                     | Windows MDM custom policy (SyncML format)       |
| Android      | `.json`                    | Android Enterprise managed configuration        |

<Tabs>
  <Tab title="macOS">
    macOS configuration profiles (`.mobileconfig`) are XML files, signed or unsigned, delivered as MDM payloads. macOS also supports `.json` for certain configuration payloads.

    To create profiles, the recommended tools are:

    * **[iMazing Profile Editor](https://imazing.com/profile-editor)** — free, purpose-built for creating and editing `.mobileconfig` files
    * **Apple Configurator** — available on the Mac App Store

    Common use cases include custom certificate payloads, VPN profiles, and per-app VPN configurations.
  </Tab>

  <Tab title="iOS / iPadOS">
    iOS and iPadOS use the same `.mobileconfig` format as macOS.
  </Tab>

  <Tab title="Windows">
    Windows custom files use the SyncML format, which maps to Windows MDM CSPs (Configuration Service Providers). This allows you to configure any policy exposed by the Windows MDM stack that is not covered by Primo's built-in controls.
  </Tab>

  <Tab title="Android">
    Android custom files use JSON to deliver managed configurations to Android Enterprise devices. This is typically used to configure enterprise applications that support managed app configuration.
  </Tab>
</Tabs>

## Troubleshooting

**The file upload fails**

* Confirm the file matches the expected format for the selected OS.
* Check that the file is not corrupted or empty.
* macOS profiles must use valid XML — validate the file with `plutil -lint profile.mobileconfig`.