mirror of https://github.com/podman-desktop/podman-desktop synced 2026-04-21 17:47:22 +00:00

docs(managed-by): elaborate more on managed-by config settings (#15199 )

chore(docs): elaborate more on managed-by config settings

### What does this PR do?

Updates the documentation with more information with regards to more
eloration on how `default-settings.json` works, as well as `locked.json`
information.

### Screenshot / video of UI

<!-- If this PR is changing UI, please include
screenshots or screencasts showing the difference -->

N/A

### What issues does this PR fix or reference?

<!-- Include any related issues from Podman Desktop
repository (or from another issue tracker). -->

Closes https://github.com/podman-desktop/podman-desktop/issues/15198

### How to test this PR?

<!-- Please explain steps to verify the functionality,
do not forget to provide unit/component tests -->

N/A, it's docs!

Signed-off-by: Charlie Drage <charlie@charliedrage.com>

2025-12-03 16:07:49 -05:00

2.9 KiB

Raw Blame History

sidebar_position

title

description

Troubleshooting managed configuration

When implementing managed configuration in an enterprise environment, you may encounter some common issues often caused by file location, permissions, or syntax errors.

Locked configuration not working

If your locked configuration is not being applied, try the following solutions:

Verify file locations are correct for your operating system.
Check file permissions (files must be owned by root/administrator).
Ensure JSON syntax is valid (use a JSON validator).
Restart Podman Desktop after creating configuration files.

Settings not being enforced

If settings appear to be locked but values are not being enforced correctly:

Check that the key name in locked.json exactly matches the key in default-settings.json.
Verify the configuration key uses dot notation (e.g., proxy.http, not proxy: { http: ... }).
Check console output for error messages.

Verifying configuration is loaded

To verify that your managed configuration is being loaded correctly:

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

Look for messages in the console like:

[Managed-by]: Loaded managed ...
[Managed-by]: Applied default settings for: setting.key1, setting.key2

If you don't see these messages, the configuration files may not be in the correct location or may have syntax errors.

:::note

The "Applied default settings" message only appears when settings are copied from default-settings.json to the user's settings.json. This occurs once per setting when it doesn't already exist in the user's configuration.

:::

Verifying if a value is locked by the managed-by configuration

To verify in the GUI if a value is locked by your managed-by configuration:

Open Podman Desktop.
Go to Settings > Preferences.
Find your managed-by value:

Confirm that it has the Managed label applied.

File permission issues

On Linux and macOS, managed configuration files must have appropriate permissions:

Files must be owned by root/administrator
Files should be readable by all users but writable only by root/administrator
Use chmod 644 for the configuration files on Linux/macOS

2.9 KiB Raw Blame History