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 stores values for the following types of configuration in three separate JSON files:

  1. User configuration - Editable user-enforced values for Podman Desktop customization.
  2. Managed defaults configuration - Read-only administrator-enforced default values that cannot be edited by the user.
  3. Locked configuration - Read-only administrator-enforced list of keys that must use managed values.

When a configuration changes, Podman Desktop returns a value after checking the user configuration files in the following priority order:

  1. Locked keys - Return a value from the managed defaults configuration file, which is of highest priority
  2. Unlocked keys - Return a value from the user configuration file
  3. Default value - Returns the default value built into Podman Desktop

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/containers/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/containers/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​