Skip to main content

Configuring a managed user environment

In enterprise environments, administrators can enforce specific configuration values that users are unable to override. This capability allows them to manage configurations, such as proxy servers, telemetry policies, and security policies, ensuring users operate within a controlled environment. Administrators can review and edit the configurations in the user settings file before applying the changes globally to all enterprise users.

How it works​

Podman Desktop supports three types of configuration:

  1. User configuration: Values that users can change in settings.json or through the UI.
  2. Managed defaults: Administrator-provided values in default-settings.json that supply initial settings.
  3. Locked configuration: Keys in locked.json that must use managed values instead of user values.

On macOS, Podman Desktop also reads managed preference plists from /Library/Managed Preferences at startup. The device plist supplies managed defaults and locks. The per-user plist supplies user values. The JSON files remain supported alongside these plists.

For MDM setup, examples, and precedence rules, see Manage macOS settings with MDM.

Default settings​

At startup, Podman Desktop copies managed defaults into the user configuration for keys without a user value. On macOS, device plist values override default-settings.json values for the same key before this copy.

  • Existing user values remain unchanged.
  • Users can change these initial values unless the key is locked.
  • The settings writer omits values that match the registered schema default from settings.json.

This allows administrators to pre-configure settings for new users while respecting existing user preferences.

Locked settings​

Keys in locked.json use managed values on every configuration read. On macOS, the device plist can also supply a locked array. Podman Desktop combines both lock lists.

  • The value comes from the managed defaults, including device plist overrides on macOS.
  • The setting displays a lock icon or a Managed label in the UI.
  • User values do not override the managed value.

Each locked key requires a value in the managed defaults. A lock without a managed value does not enforce a value.

Use locked settings when you need to enforce compliance, such as proxy servers or telemetry policies.

Configuration priority​

Podman Desktop resolves configuration values in this order:

  1. Locked key with a managed value: Return the managed value.
  2. User value: Return the user configuration value, including defaults copied at startup.
  3. Built-in default: Use the default from the setting definition.

On macOS, per-user plist values override settings.json at startup. They cannot override locked managed values.

File locations​

User configuration

  • Location: ~/.local/share/containers/podman-desktop/configuration/settings.json
  • Permissions: User read/write
  • Purpose: Normal user settings configured through the UI

Managed defaults

  • Location: /usr/share/podman-desktop/default-settings.json
  • Permissions: Root only
  • Purpose: Administrator-enforced configuration values

Locked configuration

  • Location: /usr/share/podman-desktop/locked.json
  • Permissions: Root only
  • Purpose: List of configuration keys that are locked by an administrator

Example: Enforcing corporate proxy and telemetry settings​

This example demonstrates how an administrator can lock the proxy and telemetry configuration to enforce corporate policy.

Procedure​

  1. Create a managed defaults file with corporate settings.
  2. Create a locked configuration file to enforce the corporate settings.
  3. Deploy both files to the appropriate system location.
  4. Restart Podman Desktop, the managed values will override user-configured values and enforce compliance.

User Configuration​

The user has configured a local proxy in their settings:

~/.local/share/containers/podman-desktop/configuration/settings.json
{
"proxy.http": "https://127.0.0.1:8081",
"telemetry.enabled": true
}

Managed Defaults Configuration​

The administrator creates a managed defaults file with corporate settings:

/usr/share/podman-desktop/default-settings.json
{
"proxy.http": "http://corp-proxy.example.com:8080",
"telemetry.enabled": false
}

Locked Configuration​

The administrator creates a locked configuration file to enforce these settings:

/usr/share/podman-desktop/locked.json
{
"locked": ["proxy.http", "telemetry.enabled"]
}

Result​

With this configuration in place, Podman Desktop returns:

{
"proxy.http": "http://corp-proxy.example.com:8080",
"telemetry.enabled": false
}

Key observations:

  • proxy.http - Returns managed value, user's local proxy is ignored
  • telemetry.enabled - Returns managed value, user cannot enable telemetry (set to false)
tip

As an administrator, you can implement several use cases to customize user settings based on your enterprise needs and apply those changes globally across your enterprise. For a comprehensive list of common use cases and examples, see Managed configuration use cases.

Deploying a managed configuration​

Procedure​

Step 1: Create configuration files

Save the following files at /usr/share/podman-desktop/:

Managed defaults file:

/usr/share/podman-desktop/default-settings.json
{
"proxy.http": "http://proxy.corp.example.com:8080",
"telemetry.enabled": false
}

Locked configuration file:

/usr/share/podman-desktop/locked.json
{
"locked": ["proxy.http", "telemetry.enabled"]
}

Step 2: Deploy using a deployment tool

Choose a deployment tool: Ansible, Puppet, Chef, Salt, RPM/DEB packages, or shell scripts.

Step 3: Verify the deployment

  1. Restart Podman Desktop.

  2. Go to Help > Troubleshooting, and select the Logs tab to check for messages such as:

    [Managed-by]: Loaded managed ...
  3. Verify that locked settings cannot be changed through the UI.

Locked configuration impact on users​

When a setting is locked:

  • In the UI: The setting appears grayed out or displays a lock icon
  • Editing settings.json: Changes to locked keys in the user's file are ignored
  • Console output: Log messages indicate when locked values are being used
note

Users are notified when settings are managed by administrators, ensuring transparency about which settings they can and cannot control.

Additional resources​

Next steps​