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
01 What home grants
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
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
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
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
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
| Path | Access |
|---|---|
~/ itself | read (list the top level) |
every entry below ~/ except those whose top-level name starts with . or is snap | read, 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 |
~/bin | writes 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
| Where | At install | By hand |
|---|---|---|
| classic system | connected | snap disconnect / snap connect |
| Ubuntu Core Desktop | connected | as on classic |
| other Ubuntu Core systems | not connected | snap connect <snap>:home |
| any system, a plug asking to read other users' files | not connected | refused 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 --forgetdrops the record instead.
for app developers for Ubuntu Core developers for snapd developers
The rule in the base declaration
| Key | Value | Effect |
|---|---|---|
allow-installation | slot-snap-type: [core] | the slot exists only on the system |
deny-connection | plug-attributes: read: all | read: all cannot be connected without a snap declaration rule |
deny-auto-connection | on-classic: false with on-core-desktop: false, or plug-attributes: read: all | no 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
- The home interface: the published reference entry.
- Connect interfaces: listing, connecting and disconnecting plugs.
- Interface auto-connection: how auto-connection is decided and how a store rule is requested.
Roads from here
INTERFACES AND CONFINEMENT
- Confinement — how the home rules become part of the sandbox
- Interfaces — back to interfaces
- Interfaces for users — how to connect or disconnect it
- The network interface — another single interface
- The content interface — another single interface
- How interfaces are implemented — how the rule is evaluated
POLICY · who may install and connect what
- The base declaration — where the home rule lives
DESKTOP · snaps in a user session
- AppArmor prompting — asking you before home access is granted