The home interface

one interface for users for app developers for Ubuntu Core developers

Read and write access to the files you own in your home directory except the hidden entries at its top and ~/snap. It auto-connects on classic and Core Desktop but not on other Ubuntu Core systems. Its one attribute read set to all widens it to other users' files and needs a store rule. With AppArmor prompting switched on its rules ask before they allow.

On the map: a postern north of the gatehouse

▶ Watch this deck — 5 scenes, ~4 min

01 What home grants

HOME photo-editorhome /home/userPictures/ ✓Documents/ ✓notes.txt ✓ .ssh/ ✗ hidden.config/ ✗ hiddensnap/ ✗ snap data read and write, only files you own AppArmor rules added to each app that has the plug
photo-editor with the home plug reaching the user's home directory: Pictures and Documents are allowed, the hidden .ssh and .config and the snap directory are not, and only files the user owns

Read and write access to the files you own in your home directory, except hidden entries at its top level and ~/snap. The rules are AppArmor rules added to each app that has the plug.

You've installed photo-editor and you want to open a picture from your Pictures folder. That's what the home plug is for. Once it's connected, the app may read and write the files in your real home folder, not just the private one the snap gets as its home. Two things stay out of reach: the hidden entries at the top, like .ssh and .config, and the snap folder, where every snap keeps its own data. And the rules only cover files you own. All of this is a handful of AppArmor rules that the interface adds to the profile of each app with the plug.

02 When it auto-connects general version

THE RULE base-declaration, slots:home:allow-installation:slot-snap-type: [core] deny-auto-connection:- on-classic: falseon-core-desktop: false laptop: connects at installUbuntu Core gateway: by hand - plug-attributes:read: alldeny-connection: read: all read: all → store rule needed
The base-declaration rule for home: slot on the system, auto-connection denied except on classic and Core Desktop, read all denied connection

home auto-connects on classic systems and on Ubuntu Core Desktop; on other Ubuntu Core systems it is connected by hand. A plug with read: all needs a store rule to connect, unless the snap was installed with --dangerous.

Should photo-editor get your home folder the moment it's installed? That depends on the device, and the base declaration decides. The slot belongs to the system. Auto-connection is denied unless the device is a classic system or Ubuntu Core Desktop. So on your laptop home connects at install, and on an Ubuntu Core gateway it waits until someone connects it by hand. A second rule watches the plug's read attribute. A plug that asks for read: all is denied connection, by hand too, unless a store rule in the snap's declaration allows it, or the snap was installed with --dangerous.

03 When it is connected for users in place of the general version

HOME · FOR USERS your laptopconnected automatically at install Ubuntu Core devicedisconnected until someone connects it $ snap connections photo-editor $ snap connect photo-editor:home$ snap disconnect photo-editor:home disconnecting an automatic connection is remembered across refreshes
Where home is connected automatically and the commands to check and change it for photo-editor

Connected automatically on classic desktops, not on Ubuntu Core. Check with snap connections; connect or disconnect by hand. Disconnecting an automatic connection is remembered across refreshes.

On your laptop, home is connected the moment photo-editor is installed, so it can open your pictures straight away. On an Ubuntu Core device it stays disconnected until someone connects it. snap connections shows you which it is. You can connect it with snap connect, or cut the app off from your files with snap disconnect. If you disconnect a connection that was made automatically, snapd remembers your choice, so a refresh won't quietly put it back.

04 The read attribute for app developers for Ubuntu Core developers for snapd developers

THE READ ATTRIBUTE snap.yaml, the defaultplugs:home:# owner only: files you own snap.yaml, widenedplugs:home:read: all# the only accepted value adds to the AppArmor profile:capability dac_read_search,@{HOME}/[^s.]** r, (no owner) needs a store rule to connect the standard rules, either way:audit deny @{HOME}/bin/{,**} wl,no writing into your bin folder
The home plug's read attribute: owner-only by default, read: all adds non-owner reads of other users' homes and needs a store rule; writes to ~/bin are always denied

read is the only attribute and all its only value: it adds capability dac_read_search and read rules without owner. A plug with it needs a store rule to connect. The standard rules also deny writes to ~/bin.

Now say photo-editor needs files that aren't yours, like pictures in another user's home. The standard rules can't reach them, because every one of them says owner. The plug has one attribute for this, read, and the only value it accepts is all. With read: all, the interface adds a capability to read past file permissions, and read rules without the owner match, still skipping hidden entries and the snap folder. That crosses between users, so the base declaration denies the connection unless a store rule allows it. Either way, writes to your bin folder are denied, because it's on the path on many systems.

05 When home asks first

HOME · WITH PROMPTING $ snap set system experimental.apparmor-prompting=true photo-editorcat.jpg in PicturesAllow photo-editorto read cat.jpg?the open call waits an answer that lasts becomes a rule home must still be connected: prompting only narrows what it allows off unless someone switches it on · refused on Ubuntu Core, except Core Desktop
With AppArmor prompting on, photo-editor's read of cat.jpg through the connected home plug waits for a question; a lasting answer becomes a rule; the feature is off by default and not on Ubuntu Core other than Core Desktop

With the experimental apparmor-prompting feature on, the home rules ask the user before allowing, and lasting answers become rules. The plug must still be connected. Not available on Ubuntu Core other than Core Desktop.

There's one more way home can behave. With the experimental.apparmor-prompting feature switched on, home's rules don't allow straight away. They ask. When photo-editor opens your cat picture, the open call waits while a prompt asks you, and an answer that lasts is kept as a rule, so you aren't asked again. Home still has to be connected first: prompting only narrows what the connection allows. It's off unless someone switches it on, and Ubuntu Core refuses it, apart from Core Desktop. The prompting deck has the whole story.

Read more

What you give a snap

Your files in your home folder, read and write; not hidden top-level folders such as .ssh, and not ~/snap.

for app developers for Ubuntu Core developers for snapd developers

What the plug allows

PathAccess
~/ itselfread (list the top level)
every entry below ~/ except those whose top-level name starts with . or is snapread, write, lock, link, and run programs (ix) unless another connected interface turns ix off
~/snap/read the directory only, so that apps can walk up from their own data
/run/user/<uid>/gvfs/read, and write files inside a mount, for desktop remote mounts
~/binwrites and links denied and logged

Every allow rule says owner: files and directories under ~ that belong to another user are not readable. ~ is the user's real home directory, not the snap's $HOME (~/snap/<snap>/<revision>).

Connecting

WhereAt installBy hand
classic systemconnectedsnap disconnect / snap connect
Ubuntu Core Desktopconnectedas on classic
other Ubuntu Core systemsnot connectedsnap connect <snap>:home
any system, a plug asking to read other users' filesnot connectedrefused without a store rule; allowed for a --dangerous install
  • snap connections <snap> lists the plug and its slot, :home.
  • Disconnecting a connection that was made automatically records it as undesired, so a refresh does not connect it again. snap disconnect --forget drops the record instead.

for app developers for Ubuntu Core developers for snapd developers

The rule in the base declaration

KeyValueEffect
allow-installationslot-snap-type: [core]the slot exists only on the system
deny-connectionplug-attributes: read: allread: all cannot be connected without a snap declaration rule
deny-auto-connectionon-classic: false with on-core-desktop: false, or plug-attributes: read: allno auto-connection on Ubuntu Core other than Core Desktop, and none for read: all

A plug with read set to anything but all is rejected when the snap is installed: home plug requires "read" be 'all'.

for app developers for Ubuntu Core developers for snapd developers

What read: all adds

capability dac_read_search and read rules without owner for ~/, every non-hidden top-level entry except snap, and everything below them. Hidden top-level entries and ~/snap stay out of reach. Write access is unchanged: only files the user owns.

With AppArmor prompting

With experimental.apparmor-prompting on, each allow rule of the home interface becomes a prompt rule: the access waits for an answer from the user or a stored rule. The ~/bin deny rules are unchanged. The feature can be switched on only on classic systems and on Ubuntu Core Desktop. See AppArmor prompting.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

POLICY · who may install and connect what

DESKTOP · snaps in a user session