The personal-files interface

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

Auto-connect: no
Super-privileged: yes
Transitional: no

  • 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 ]

Specifying a directory in read and write allows access to the directory and all files under it.

Requires snapd version 2.37+.

Snaps by default have access to everything under $SNAP_USER_DATA (eg, ~/snap/<snap name>/<revision>) and $HOME is set to $SNAP_USER_DATA for non-daemon commands. As a result, snaps may freely read and write to dot files in their $HOME (ie, ~/snap/<snap name>/<revision>/...).

The personal-files interface is typically used to provide read-only access to top-level hidden data directories within a user’s real 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 into $SNAP_USER_DATA/.config/foo (ie, $HOME/.config/foo within the snap’s runtime environment or ~/snap/foo/<revision>/.config/foo) on the host), the snapcraft.yaml could include the following:

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

    - dot-config-foo

Note, when declaring an instance of the personal-files plug as above, it should be named with a descriptive name that indicates to a user what access it grants. In this case, the name dot-config-foo is used to reflect the access to ~/.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:dot-config-foo

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

Request for home, removable-media and personal-files interfaces (was: Classic confinement for wksctl)
Gallery-dl: Previously granted *-files plugs now trigger manual review
Interface auto-connect request for the guvcview snap (personal-files)
Apparmor rule request - .hidden file
Request permission for classic confinement for lookauth-lite
Request - Interface Personal-files: read-write
Request for classic confinement for volsung
Classic confinement request: eternalmodmanager
Request for Classic confinement: djlbench
Classic confinement request: batcat
Request for classic confinement: git-local-ignore
Request for Classic confinement: djlbench
Request for alias and interfaces + autoconnection for Ritchie CLI
Request for home for youtubedr
Auto connect / alias request for mob-sh
Please allow use of personal-files for gitl [Was: Classic confinement for gitl]
Request use of docker interface [Was: Classic confinement request: Dunner]
Packaging Etcher as a snap
Request for classic confinement for onedrive
Personal-files for kconnect
Apparmor-related denials for Spotify snap
Request for personal-files access for boxwallet
Request for classic confinement for Quicknav
Classic confinement request for cric
The snapd roadmap
Classic confinement for OpenChrom
Request for classic confinement for hugo snap
Question: Is personal-files interface allowed for $HOME/.netrc?
Request for classic Confinement for Linkerd
Request for classic confinement: kubectx
Classic confinement for autotrash
Devoperator classic confinement request
Classic confinement request for Maestral
Process for reviewing classic confinement snaps
Strict confinement requirements
Classic request for bower
Classic confinement request for dvc
Classic confinement request: fce
Manual Review Requested: wpe-cli
Fluxctl personal-files [Was: Fluxctl snap wants to be classic]
Clj-kondo personal-files request [Was: Clj-kondo linter classic snap]
Request for classic confinement: snap ds2
Request for personal-files confinement for fuzzit CLI
Permission requests
Autoconnect of personal-files for exoscale-cli
Personal-files request for ngrok
'universal-ctags' requests personal-files interface
Request for personal-files confinement for kafkactl snap
Classic confinement for dbeaver-ce
Manual review request for Curiosity app
Manual review request for Curiosity app
Manual review request for Curiosity app
Requesting approval to use classic confinement for Uplift snap
Auto-Connect Request: Audio/Video for Slack
Classic confinement for desync
Classic confinement request: avdl
Snap documentation
Request review for auto connections for interfaces -Personal files, System files & Hardware observe for MqttDesk snap

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

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.

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

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

1 Like

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.

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$SNAPNAME Snap-Device-Series:16 fields==snap-yaml | jq -r '."channel-map"[0]."snap-yaml"'

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

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?)

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.

1 Like

Here are some ideas that I think would improve this documentation page. Obviously ignore or correct these if my understanding is wrong:

  1. Be explicit that granting access to a directory does not grant access to the files in that directory. In order to do that, the snap author needs to grant access to each of the required files within the directory.

  2. If the application is written such that it first lists contents of a directory, and then opens the files it finds, then the snap author needs to grant read access to the directory itself, and then read or write access to the accessed files within that directory.

  3. If the application accesses arbitrary filenames within a directory (for example, my own application reads from “~/.ctags.d/*.ctags”, then the personal-files interface isn’t able to allow that. You have to explicitly list the filenames at snap build time, and wildcards are not supported.

  4. The page shows an example of a descriptive interface reference. Is there also a simpler way it could be expressed, without using a reference? Could an example of that be shown too? (I understand this could not be submitted for auto-connection.)

Granting access to a directory does grant access to the directory and all the files under it.

This is supported. Use:

    interface: personal-files
    - $HOME/.ctags.d
    - dot-ctags

snapd itself supports:

    - $HOME/.ctags.d

but this is not allowed by our store review processes because it is not clear to the user of the snap what snap connect your-snap:personal-files is doing. Better is to use what I suggested above so the user does snap connect your-snap:dot-ctags.

I updated the documentation to include: “Specifying a directory in read and write allows access to the directory and all files under it.

I updated the documentation to include: “Specifying a directory in read and write allows access to the directory and all files under it.

1 Like

@jdstrand Thank you.

I think maybe some of my confusion stemmed from me not realizing $HOME is effectively set to $SNAP_USER_DATA for confined snaps. Because of this, nothing was working for me when I put the config file in /home/USER/.ctags.d.

If this is true, then I think this is also an important thing to mention here.

Based on this, does it mean that I will need something other than $HOME if I want to really access the files in a user’s home directory? Thanks for all the discussion you have done on this issue. The documentation is very confusing!

1 Like

there needs to a way to see which personal files required for snap without digging through yaml file, like cli or snapstore gui.