The personal-files interface


#1

personal-files provides access to the specified files in the user’s home. This interface gives privileged access to the user’s data.

Auto-connect: no
Attributes:

  • read (plug): list of files and/or directories for read-only access (eg, ‘read: [ $HOME/.file-read, $HOME/.dir-read ]
  • write (plug): list of files and/or directories for read/write access (eg, ‘write: [ $HOME/.file-write, $HOME/.dir-write ]

Transitional: no

Requires snapd version 2.37+.

This interface is typically used to provide read-only access to top-level hidden data directories within a user’s home directory in order to support importing data from existing applications where the snap is the clear owner of the target directory.

For distribution via the Snap store, consumers of this interface require an approved snap declaration. For acceptance, you will need to make a descriptive interface reference, as used by snap connections|interfaces|connect|disconnect commands.

For example, if a foo application is being packaged as a snap and its publisher wants the snap to import an existing configuration from ~/.config/foo, the snapcraft.yaml could include the following:

name: foo
...
plugs:
  config-foo:
    interface: personal-files
    read:
    - $HOME/.config/foo

apps:
  foo:
    plugs:
    - config-foo
    ...

With the above built snap, you would then be able to use the following to enable access to personal files:

$ snap connect foo:config-foo

ⓘ This is a snap interface. See Interface management and Supported interfaces for further details on how interfaces are used.


Interface auto-connect request for the guvcview snap (personal-files)
Gallery-dl: Previously granted *-files plugs now trigger manual review
Snap documentation
Request for classic confinement: snap ds2
Please allow use of personal-files for gitl [Was: Classic confinement for gitl]
Manual Review Requested: wpe-cli
Classic confinement request: fce
Autoconnect of personal-files for exoscale-cli
Request for personal-files confinement for fuzzit CLI
Permission requests
Request use of docker interface [Was: Classic confinement request: Dunner]
Clj-kondo personal-files request [Was: Clj-kondo linter classic snap]
Fluxctl personal-files [Was: Fluxctl snap wants to be classic]
#2

This is not what I need. There’s no way I know the files the user writes beforehand. I need classic.


#3

I would like to ask if it’s acceptable to use this interface on the applications’s cache directory (e.g. ~/.cache/_app_id_)? In the case that the application doesn’t honour XDG_CACHE_HOME.


#4

It’s not totally clear from this whether store approval is necessary for simply using this interface, or whether store approval is only needed for auto-connection of this interface. Can this interface be used without auto-connection with any directory? I am pretty sure the answer is no, it still needs store approval to release the snap at all


#5

A snap declaration is required for use of the interface at all. Auto-connection would be a separate component of that snap declaration.


#6

I reviewed the docs, but can’t find how to see which files personal-files is a providing access to in a downloaded snap, or how to modify that list for an installed app. For example, I’m using the chromium snap on Ubuntu, and it seems to be not be able to read or write to ~/.local/share/icons which is required to make icons work when creating a “shortcut” .desktop file for a site.

I just upgraded the Chromium snap and all my custom apps using .desktop files broke. I believe this is because I can’t use symlinks in the Exec= line of those files, so hardcoded paths to specific snap versions are in there. When the snap version changes, all those references break.


#7

The personal-files interface is declared by the snap and is unmodifiable by the user. The user may simply snap connect or snap disconnect the interface to allow/disallow the declared access. At some point, we may add the ability for admins to adjust the security policy beyond snap connect/disconnect, but that is not available today.

Furthermore, it is a current limitation of the feature that you cannot see what accesses are granted when connecting the personal-files interface, which is why as part of our approval process we require that the interface reference provide a clue to what is being granted. You can fetch the snap yaml like so prior to downloading (requires the http and jq snaps to be installed; there is probably a curl invocation that would achieve the same):

$ SNAPNAME=chromium ; http https://api.snapcraft.io/v2/snaps/info/$SNAPNAME Snap-Device-Series:16 fields==snap-yaml | jq -r '."channel-map"[0]."snap-yaml"'

name: chromium
...
plugs:
  ...
  chromium-config:
    interface: personal-files
    read:
    - $HOME/.config/chromium
...

#8

Can the declaration of read or write pathnames include wildcards?

For example, universal-ctags reads from config files at:

$HOME/.ctags.d/*.ctags

I’m not able to get my snap of universal-ctags to read a config file at:

$HOME/.ctags.d/python.ctags

I’ve added the following to my snapcraft.yaml:

plugs:
  config-universal-ctags:
    interface: personal-files
    read:
    - $HOME/.ctags.d/*.ctags

apps:
  universal-ctags:
    command: ctags
    plugs:
      - home
      - config-universal-ctags

…and, after installing this snap from a local file with ‘–dangerous’, I executed the command

sudo snap connect universal-ctags:config-universal-ctags

yielding:

$ snap connections universal-ctags
Interface       Plug                                    Slot             Notes
home            universal-ctags:home                    :home            -
personal-files  universal-ctags:config-universal-ctags  :personal-files  manual

But running the snap’s executable doesn’t honor the settings placed in ~/.ctags.d/python.ctags (whereas the apt-installed version does)

Alternatively, I tried sharing the parent directory:

    read:
    - $HOME/.ctags.d/

but installing the generated snap file warns that this won’t work (path can’t end with ‘/’)

Removing the trailing slash:

    read:
    - $HOME/.ctags.d

My installed snap still isn’t able to read ~/.ctags.d/python.ctags.

Actually, I just tried a sanity check, just giving read access to one file:

    read:
    - $HOME/.ctags.d/python.ctags

and that doesn’t work for me either. I must be doing it wrong.

I have tried doing a “snap disconnect …” and “snap connect …” for the personal-files interface after installing each upgraded snap file, in case that is needed, but it didn’t help.

Sorry, I should probably move this post off this ‘doc’ page and into a forum post bleating for help with this simple single-file case, I’ll come back here and update this post with my actual question, if any remain.


#10

Could it be that when I use a “descriptive interface reference”, (which this page says is needed for approval of the snap declaration for distribution via the store.) that causes it to not work for snaps installed from a local file? I’ll try declaring it without a descriptive reference. (Could this page usefully add an example showing how to do that?)


#11

The “descriptive interface reference” is just for store approval, you can name the plug whatever you like while developing the snap locally, but note you will have to manually connect it. Then during the request for usage of the interface, a “descriptive interface reference” will be negotiated proposed and you will have to use that to upload your snap to the store.