"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
01 Two shapes in one family
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
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
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
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
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.
07 Where to go from here
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
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
| Command | Effect |
|---|---|
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
| Shape | Interfaces | Slot on classic | Slot on Ubuntu Core | Auto-connects |
|---|---|---|---|---|
| system slot | network, network-bind, network-status | system | system | yes |
| system slot | bluetooth-control, firewall-control, hostname-control, netlink-audit, netlink-connector, network-control, network-observe, network-setup-control, network-setup-observe, openvswitch-support, ppp, timeserver-control | system | system | no |
| system slot, classic only | openvswitch | system | none | no |
| daemon | avahi-control, avahi-observe, bluez, modem-manager, network-manager, network-manager-observe, ofono | system, or a snap | a snap only | no |
| gadget slot | netlink-driver | the gadget or the system snap declares it | the same | no |
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
| Interface | Adds to the seccomp filter |
|---|---|
| network | bind, socket AF_NETLINK - NETLINK_ROUTE, socket AF_CONN |
| network-bind | accept, accept4, bind, listen, socket AF_NETLINK - NETLINK_ROUTE |
| network-observe | capset, bind, socket AF_NETLINK - NETLINK_INET_DIAG, NETLINK_ROUTE, NETLINK_GENERIC, NETLINK_KOBJECT_UEVENT |
| network-control | capset, 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
netlink-driver in a gadget
# 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
- network interface: the plain interface from the developer's side.
- network-manager interface: the daemon interface and its slot on Ubuntu Core.
- network-control interface: what the control rung allows.
- netlink-driver interface: the gadget slot attributes.
- Connect interfaces:
snap connections,snap connectandsnap disconnect. - Interface auto-connection: why only some interfaces connect on their own.
Roads from here
INTERFACES AND CONFINEMENT
- The network interface — the plain network interface in detail
- Interfaces — back to interfaces
- How interfaces are implemented — how the rules are evaluated and the profiles written
- Confinement — the AppArmor and seccomp profiles these interfaces feed
INTERFACE FAMILIES · every interface, grouped by what it touches
- "Interfaces: system control and observe" — the neighbouring family of control and observe interfaces
SANDBOX INTERNALS · the mount namespace
- The per-snap mount namespace — the per-snap mount namespace that network-control adds a mount to