<a id="how-configure-mount"></a>

# How to configure a mount

<!-- @tests in tests/docs-how-to/configure-mount/task.yaml -->
<!-- @artefact mount interface -->
<!-- @artefact interface plug -->

This guide shows how to tune ownership and permissions
on a `mount` interface plug,
overriding the defaults that **Workshop** derives from the target path.

By default, **Workshop** applies the following rules
when a mount plug omits ownership and permission attributes.
The attributes take effect when **Workshop** creates the target path
and any missing parent directories;
a path that already exists keeps its ownership and permissions.

- `uid` and `gid` default to `1000`
  when `workshop-target` is at or below
  `/home/workshop`,
  `/project`,
  or `/run/user/1000`.
  Otherwise, both default to `0` (root).
- `mode` defaults to `0o755` when the `uid`,
  set explicitly or resolved by the previous rule, is `0` (root),
  and to `0o775` otherwise.
- `read-only` defaults to `false`.

Override the defaults when a mount lives outside the user-owned paths,
when a mount stores secrets that should not be world-readable,
or when the SDK should not be able to write to the mount.

## Prerequisites

You need an `sdkcraft.yaml` that declares at least one mount plug;
[SDK plugs and slots](https://ubuntu.com/workshop/docs//reference/sdks.md#ref-sdk-plugs-slots) covers the declarations.
The attributes below extend the plug entries
under the top-level `plugs:` key.

## Set explicit ownership outside the user-owned paths

For a mount whose target lives outside `/home/workshop`,
`/project`, or `/run/user/1000`,
the ownership defaults to root.
If the `workshop` user needs to read or write the mount,
set `uid` and `gid` to `1000`:

```yaml
plugs:
  state:
    interface: mount
    workshop-target: /var/lib/example
    uid: 1000
    gid: 1000
```

An explicit `uid` doesn’t change the default for `gid`,
which still follows the target path,
so set both attributes.
The default `mode`, in contrast, follows the resolved owner
and becomes `0o775` here.

## Tighten permissions for a private mount

For a mount that stores credentials, tokens, or other secrets,
tighten `mode` to `0o700`
so that only the owning user can access it:

```yaml
plugs:
  secrets:
    interface: mount
    workshop-target: /home/workshop/.private-secrets
    mode: 0o700
```

The owner keeps the path-based default
(here, the workshop user, since the target is under `/home/workshop`).

## Mark a mount read-only

For a mount that should expose data without allowing the consumer to modify it,
set `read-only` to `true`:

```yaml
plugs:
  toolchain:
    interface: mount
    workshop-target: /home/workshop/.local/share/example-toolchain
    read-only: true
```

This is appropriate for shared resources
that the SDK consumes but never writes to.

## Verify inside a workshop

After adding the SDK to a workshop definition and launching the workshop,
inspect the mounts to confirm the applied ownership and permissions.
The numeric uid and gid show how **Workshop** resolved the attributes:

```console
$ workshop exec dev -- ls -ldn /home/workshop/.private-secrets

  drwx------ 2 1000 1000 4096 May 14 10:32 /home/workshop/.private-secrets
```

For a read-only mount,
attempting to write returns an `EROFS` error:

```console
$ workshop exec dev -- touch /home/workshop/.local/share/example-toolchain/probe

  touch: cannot touch '/home/workshop/.local/share/example-toolchain/probe': Read-only file system
```

## See also

Explanation:

- [Mount interface](https://ubuntu.com/workshop/docs//explanation/interfaces/mount-interface.md#exp-mount-interface)
- [Plugs and slots](https://ubuntu.com/workshop/docs//explanation/interfaces/plugs-and-slots.md#exp-plugs-slots)

How-to guides:

- [How to fix plug conflicts with binding](https://ubuntu.com/workshop/docs//how-to/fix-workshops/resolve-plug-conflicts.md#how-resolve-plug-conflicts)

Reference:

- [Mount interface](https://ubuntu.com/workshop/docs//reference/sdks.md#ref-mount-interface)
- [SDK plugs and slots](https://ubuntu.com/workshop/docs//reference/sdks.md#ref-sdk-plugs-slots)

Tutorial:

- [Craft SDKs with SDKcraft](https://ubuntu.com/workshop/docs//tutorial/part-4-craft-sdks.md#tut-craft-sdks)