"Interfaces: network"

interface family for users for app developers for Ubuntu Core developers for snapd developers for administrators

Twenty-four interfaces for using, serving, observing and configuring the network. Most have a system slot and only network, network-bind and network-status auto-connect. The daemon interfaces such as network-manager have a system slot on classic only; on Ubuntu Core a snap provides the slot and connecting to it needs a store rule.

On the map: interfaces district, family row

▶ Watch this deck — 8 scenes, ~6 min

01 Two shapes in one family

TWO SHAPES 1 · implicit system slotsystemacme-agenton classic and Ubuntu Core; the app snap carries the plug auto-connect, three onlynetwork · network-bind · network-status the other 13: snap connect or a store rule 2 · the service patternsystem (classic)app snapNetworkManager, BlueZ, oFono: part of the classic OS network-manager snapapp snapUbuntu Core: no implicit slot, a snap provides itconnecting to it needs a store rule 24 interfaces: 16 with a system slot (openvswitch on classic only) · 7 service daemons · netlink-driver
Two shapes in the network family: an implicit system slot where only network, network-bind and network-status auto-connect, and the service pattern where the slot is implicit on classic and provided by a snap on Ubuntu Core

Shape one: an implicit system slot; only network, network-bind and network-status auto-connect, the rest need snap connect or a store rule. Shape two: a daemon interface such as network-manager, with an implicit slot on classic only and a snap's slot on Ubuntu Core, where connecting needs a store rule.

The acme-agent on your gateway gets the network without anyone being asked. Why that one, and not the rest? This family has twenty four interfaces, nearly all in one of two shapes. In the first, snapd puts the slot on the system itself and the app carries the plug. Only network, network-bind and network-status auto-connect. The rest wait for snap connect or a store rule. In the second, the other end is a daemon, such as NetworkManager, BlueZ or oFono. On classic it's part of the operating system. On Ubuntu Core a snap has to provide it, and connecting to that snap needs a store rule.

02 The ladder for app developers for Ubuntu Core developers for snapd developers

THE LADDER networkauto-connectsbind · socket AF_NETLINK - NETLINK_ROUTEsocket AF_CONN network-bindauto-connects+ accept · accept4 · listenNETLINK_ROUTE kept acme-agent, snap.yamlapps:agent:sockets:"network-bind" interfaceplug is required whensockets are used network-observemanual connect+ capset · NETLINK_INET_DIAG+ NETLINK_GENERIC · NETLINK_KOBJECT_UEVENT network-controlmanual connect+ mount · umount · umount2 · unshare · bpf+ setns - CLONE_NEWNET · more netlink neither observe nor control adds listen: a listening daemon plugs network-bind too
Four rungs: network, network-bind, network-observe and network-control, with the seccomp system calls each adds; sockets in snap.yaml require network-bind; only network-bind adds listen

network and network-bind auto-connect; network-observe and network-control are manual. Only network-bind adds accept and listen, and a strictly confined app with sockets: must plug it. Pick the lowest rung that works.

Which of the four basic network interfaces should the acme-agent plug? The lowest that works. The seccomp filter shows what each adds. Network allows bind, and the routing netlink protocol that Go's net library needs. network-bind adds accept and listen. If an app declares sockets in snap.yaml, a strict snap without a network-bind plug fails validation. Those two auto-connect. network-observe adds capset and the diagnostic netlink protocols that ss and ping use. network-control adds mount, unshare and setns for network namespaces, and bpf for XDP. Those two need snap connect. Neither adds listen, so a listening daemon plugs network-bind too.

03 What you will be asked to connect for users for administrators

WHAT YOU CONNECT connect on their ownnetwork · network-bindat install, on every system wait for you to connectnetwork-control · firewall-controlnetwork-setup-controlhostname-control · timeserver-controlthey can reconfigure the machine $ snap connections acme-agent$ snap connect acme-agent:firewall-control# the slot is :firewall-control, the system's on Ubuntu Corea NetworkManager, BlueZ or oFonoclient needs the provider snapinstalled first; a store rulemay be needed to connect
network and network-bind connect on their own; network-control, firewall-control, network-setup-control, hostname-control and timeserver-control wait for snap connect; the commands; the provider-snap step on Ubuntu Core

network and network-bind connect on their own. The grants that reconfigure the machine wait: check with snap connections and connect with snap connect acme-agent:firewall-control. On Ubuntu Core a NetworkManager, BlueZ or oFono client needs the provider snap installed first.

Most snaps that use the network need nothing from you. Network and network-bind connect by themselves at install, on every system. Interfaces that change how the machine itself is networked don't. network-control, firewall-control, network-setup-control, hostname-control and timeserver-control stay disconnected until someone connects them. So if the acme-agent wants to manage the gateway's firewall, it waits for you. Check with snap connections, then snap connect the snap's plug. On Ubuntu Core, a client of NetworkManager, BlueZ or oFono also needs the provider snap installed first, and the connection may need a store rule as well.

04 Two homes for one slot for app developers for Ubuntu Core developers for snapd developers

TWO HOMES FOR ONE SLOT classic:network-manageracme-agentpeer=(label=unconfined)the daemon is part of the OS and runs unconfined Ubuntu Corenetwork-manager snapacme-agentpeer=(label="snap.network-manager.*")no implicit slot; the snap provides it base-declaration, slots:network-manager:deny-auto-connection: truedeny-connection:on-classic: false on Ubuntu Core: connection refusedunless a store declaration allows iton classic: the rule does not matchsnap connect to the implicit slot works network_manager.go branches on release.OnClassic, not on the slot's snap type:a network-manager snap on classic still has its clients pointed at unconfined
network-manager on classic connects to the implicit slot with peer label unconfined; on Ubuntu Core to the network-manager snap with its label, and deny-connection on-classic false means a store rule is needed there

On classic the plug's rules say peer=(label=unconfined); on Ubuntu Core they name the network-manager snap's label, and deny-connection: on-classic: false means a store rule is needed there. The branch is on release.OnClassic, not on the slot's snap type.

The acme-agent wants to ask NetworkManager about the gateway's uplink. Where is NetworkManager? On a classic system it's part of the operating system and runs unconfined, so the slot is implicit, and the plug's AppArmor rules name the peer as unconfined. On Ubuntu Core there's no implicit slot. A network-manager snap provides it, and the rules name that snap's label instead. The base declaration denies connection when not on classic, so on the gateway snap connect is refused unless a store declaration allows it. Notice what the code branches on: whether the system is classic, not which snap provides the slot.

05 A gadget slot with a family number for app developers for Ubuntu Core developers for snapd developers

A GADGET SLOT WITH A FAMILY NUMBER gateway gadget, snap.yamlslots:nl:interface: netlink-driverfamily: 23family-name: acme-radio acme-agent, snap.yamlplugs:nl:interface: netlink-driverfamily-name: acme-radio seccomp, generated per connection from the slotsocket AF_NETLINK - 23bind AppArmor: network netlink, every family,and capability net_admin;seccomp narrows it to the family number deny-auto-connection: true · AutoConnect(): plug family-name == slot family-namematching names are necessary, but the base declaration denies it: connect by hand or with a store rule
A netlink-driver slot in gadget.yaml with family 23 and family-name acme-radio, a plug with the same family-name, the generated seccomp line socket AF_NETLINK dash 23, and the rule: names must match but auto-connection is still denied

The slot (gadget or system) carries family, an integer, and family-name; the plug carries family-name. The connection generates socket AF_NETLINK - <family> in seccomp. Matching names are necessary for auto-connection, but the base declaration denies it.

Now the gateway's gadget brings a driver that speaks its own netlink family. How does the acme-agent reach that family, and only that one? netlink-driver is the one member with attributes, and the only one with no implicit slot. The gadget declares the slot with two: family, the protocol number as an integer, and family-name. The plug names the family too. On connection, seccomp allows a netlink socket with exactly that number, plus bind. AppArmor allows all of netlink, so seccomp does the narrowing. The names must match for auto-connection, but the base declaration denies it anyway. Connect by hand, or with a store rule.

06 network-control's hidden mount for app developers for snapd developers

THE HIDDEN MOUNT Ubuntu Core 16: snaps saw the host's /var/lib/dhcpwith bases it comes from the base; an app ported to Core 18 stopped working mount entry, added on connection/var/lib/snapd/hostfs/var/lib/dhcp-> /var/lib/dhcpbind,rw,x-snapd.ignore-missing ignore-missing: a host without /var/lib/dhcpdoes not break the connection snap-update-ns profile, rules added/var/ r,/var/lib/ r,/var/lib/snapd/ r, ... hostfs/ r,/var/lib/snapd/hostfs/var/lib/dhcp/ r,/var/lib/dhcp/ r,mount options=(rw bind).../hostfs/var/lib/dhcp/ -> /var/lib/dhcp/,umount /var/lib/dhcp/,
Why network-control mounts the host's /var/lib/dhcp: on Ubuntu Core 16 snaps saw it, with bases they see the base's copy; the mount entry added on connection with ignore-missing; the snap-update-ns AppArmor rules that accompany it

The only mount-backend member: /var/lib/snapd/hostfs/var/lib/dhcp is bind-mounted at /var/lib/dhcp with x-snapd.ignore-missing, restoring what Ubuntu Core 16 snaps saw. Every mount entry needs matching snap-update-ns AppArmor rules.

network-control does one thing that isn't a sandbox rule, and there's a story behind it. On Ubuntu Core 16, snaps saw the host's /var/lib/dhcp. With bases, that directory comes from the base instead, and an app ported to Core 18 stopped working. So when network-control is connected, snapd adds a mount: the host's /var/lib/dhcp, reached through hostfs, bind mounted over the snap's. Ignore missing means a host without that directory doesn't break the connection. snap-update-ns needs matching rules for every mount: read on each directory on the way down, the mount itself, and the unmount.

07 Where to go from here

ROADS Interfaces: network24 interfaces, two shapes The network interfacethe plain one, on its own Interfacesplugs, slots, connections How interfaces are implementedrules evaluated, profiles written Confinementwhere the profiles apply The per-snap mount namespacewhere the dhcp mount lands System control and observethe family next door
The network family in the middle with roads to the network interface, the interfaces overview, how interfaces are implemented, confinement, the per-snap mount namespace, and the system control and observe family

Roads: the network interface on its own, the interfaces overview, how interfaces are implemented, confinement, the per-snap mount namespace, and the system control and observe family next door.

Where next? The network interface deck takes the plain network interface on its own: what it grants and why it connects everywhere. Interfaces is the overview of plugs, slots and connections. How interfaces are implemented shows how the base declaration and store rules are evaluated, and how the backends write the profiles this family feeds. Confinement shows where those profiles apply. The per-snap mount namespace explains the mount that network-control adds. And the system control and observe family next door holds the interfaces that reconfigure the rest of the machine.

08 All 24 interfaces at a glance

ALL 24 INTERFACES AT A GLANCE network network-bind network-status avahi-control avahi-observe bluetooth-control bluez firewall-control hostname-control modem-manager netlink-audit netlink-connector netlink-driver network-control network-manager network-manager-observe network-observe network-setup-control network-setup-observe ofono openvswitch openvswitch-support ppp timeserver-control auto-connectsconditionalby handstore rule to connect* store rule to install · italic: Ubuntu Touch era
Every interface in the network family, sorted and coloured by how it gets connected: auto-connect, conditional, by hand, or store rule needed

Every interface in the family by connection class: 3 auto-connect, 0 conditionally, 21 by hand, 0 need a store rule to connect; 0 are super-privileged.

All 24 interfaces of the network family at a glance, sorted by how they get connected. 3 auto-connect on every system: network, network-bind, network-status. 21 connect by hand with snap connect, which is most of the family. Every one of them is in the catalogue below this deck, with what it grants and its rule.

Read more

The catalogue below this deck lists every interface of the family with its grants, attributes and rules. This page collects what cuts across them.

Commands

CommandEffect
snap connections <snap>the snap's plugs and what each is connected to
snap connect <snap>:<plug>connect a plug to the system slot of the same name
snap connect <snap>:<plug> <provider>:<slot>connect to a slot that another snap provides, such as network-manager on Ubuntu Core
snap disconnect <snap>:<plug>disconnect it; snapd remembers this across refreshes

Where the slot comes from

ShapeInterfacesSlot on classicSlot on Ubuntu CoreAuto-connects
system slotnetwork, network-bind, network-statussystemsystemyes
system slotbluetooth-control, firewall-control, hostname-control, netlink-audit, netlink-connector, network-control, network-observe, network-setup-control, network-setup-observe, openvswitch-support, ppp, timeserver-controlsystemsystemno
system slot, classic onlyopenvswitchsystemnoneno
daemonavahi-control, avahi-observe, bluez, modem-manager, network-manager, network-manager-observe, ofonosystem, or a snapa snap onlyno
gadget slotnetlink-driverthe gadget or the system snap declares itthe sameno

for app developers for Ubuntu Core developers for snapd developers for administrators

Daemon interfaces on Ubuntu Core

For the daemon interfaces the base declaration says deny-connection: on-classic: false. On Ubuntu Core a connection to the providing snap is refused unless a snap-declaration allows it. Their plug's AppArmor rules name the peer unconfined on classic and the providing snap's label on Ubuntu Core; the choice is made on release.OnClassic.

for app developers for Ubuntu Core developers for snapd developers

The ladder in seccomp

InterfaceAdds to the seccomp filter
networkbind, socket AF_NETLINK - NETLINK_ROUTE, socket AF_CONN
network-bindaccept, accept4, bind, listen, socket AF_NETLINK - NETLINK_ROUTE
network-observecapset, bind, socket AF_NETLINK - NETLINK_INET_DIAG, NETLINK_ROUTE, NETLINK_GENERIC, NETLINK_KOBJECT_UEVENT
network-controlcapset, bind, mount, umount, umount2, unshare, setns - CLONE_NEWNET, bpf, netlink ROUTE, FIB_LOOKUP, INET_DIAG, XFRM, DNRTMSG, ISCSI, RDMA, GENERIC, KOBJECT_UEVENT

A strictly confined app that declares sockets: must also plug network-bind; otherwise the snap fails validation with "network-bind" interface plug is required when sockets are used.

for app developers for Ubuntu Core developers for snapd developers

# the gadget's meta/snap.yaml slots: nl: interface: netlink-driver family: 23 # a YAML integer family-name: acme-radio

# the app's snap.yaml plugs: nl: interface: netlink-driver family-name: acme-radio

family-name is at least two characters, starts with a letter and does not end with a hyphen. The connection adds socket AF_NETLINK - 23 and bind to seccomp, and network netlink and capability net_admin to AppArmor.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

INTERFACE FAMILIES · every interface, grouped by what it touches

SANDBOX INTERNALS · the mount namespace