Test Netplan Changes Through Its D-Bus Configuration API

You will finish with a repeatable way to ask the installed netplan-dbus service for a private copy of the current Netplan configuration, inspect it, stage one change, test it with a timeout, and either cancel or apply it. The examples use busctl and the netplan.io package version 1.1.2-8ubuntu1~24.04.3 installed on the reference system.

Allow about twenty minutes, plus time to understand the network change you intend to make. You need a Linux system with netplan.io, a running system D-Bus, and root access for the method calls. This workflow can disrupt networking. Keep console or out-of-band access available before testing a change on a remote host.

1. Confirm the service and interface

Check the installed version and ask D-Bus to introspect the well-known service. These commands only inspect local state:

$ dpkg-query -W -f='\${Package} \${Version}\n' netplan.io
netplan.io 1.1.2-8ubuntu1~24.04.3
$ sudo busctl introspect io.netplan.Netplan /io/netplan/Netplan
NAME                     TYPE      SIGNATURE RESULT/VALUE FLAGS
io.netplan.Netplan       interface -         -            -
.Apply                   method    -         b            -
.Config                  method    -         o            -
.Generate                method    -         b            -
.Info                    method    -         a(sv)       -

The daemon provides the io.netplan.Netplan interface on the system bus. Its executable is normally started by D-Bus on demand, so running netplan-dbus directly is not the normal way to use it. The installed service runs it as root.

Checkpoint: if introspection fails, stop here. Check that the system bus is running and that the service name is spelled exactly as shown. A plain, unprivileged method call may be rejected on this machine; use sudo for the examples that change or read configuration state.

2. Check supported features

Call Info() before relying on an optional Netplan feature. The method returns a dictionary containing a Features array. The exact list is version and build specific:

$ sudo busctl call io.netplan.Netplan /io/netplan/Netplan \
    io.netplan.Netplan Info
a(sv) 1 "Features" as 17 "dhcp-use-domains" "auth-phase2" ...

Do not treat a feature name as proof that your renderer or hardware supports every use of it. It reports what this Netplan build advertises. For a script, parse the D-Bus result rather than matching the whole human-readable line.

3. Create a configuration snapshot

Call Config() to create a new configuration object. Netplan copies the current YAML state from /etc/netplan, /run/netplan and /lib/netplan into a temporary configuration directory and returns its object path:

$ sudo busctl call io.netplan.Netplan /io/netplan/Netplan \
    io.netplan.Netplan Config
o "/io/netplan/Netplan/config/ABC123"
$ CONFIG_PATH=/io/netplan/Netplan/config/ABC123

The six-character identifier is generated by the daemon and will differ on every call. Copy the path from your own output. Do not type ABC123 literally. This snapshot is separate from the live configuration until you apply it.

Checkpoint: verify the object exists before using it:

$ sudo busctl introspect io.netplan.Netplan "$CONFIG_PATH" \
    io.netplan.Netplan.Config
NAME                     TYPE      SIGNATURE RESULT/VALUE FLAGS
io.netplan.Netplan.Config interface -         -            -
.Get                     method    -         s            -
.Set                     method    ss        b            -
.Try                     method    u         b            -
.Cancel                  method    -         b            -
.Apply                   method    -         b            -

4. Read the merged snapshot

Get() returns the snapshot as merged YAML. The return type is one string, so ask busctl for the method result and save it only if you have chosen a safe destination:

$ sudo busctl call io.netplan.Netplan "$CONFIG_PATH" \
    io.netplan.Netplan.Config Get
s "network:\n  version: 2\n  ethernets:\n    ..."
$ sudo busctl call io.netplan.Netplan "$CONFIG_PATH" \
    io.netplan.Netplan.Config Get > /tmp/netplan-get.txt
$ sed -n '1,80p' /tmp/netplan-get.txt

The displayed representation is D-Bus string output, not necessarily a ready-to-save YAML file. For automation, use a D-Bus library that returns the string value directly. Treat configuration as sensitive operational data and remove temporary copies when you have finished checking them.

5. Stage one delta with Set()

Set() accepts two strings: a Netplan configuration delta and an origin hint. This example asks Netplan to enable DHCP on an existing interface and requests a generated file named from the hint:

$ sudo busctl call io.netplan.Netplan "$CONFIG_PATH" \
    io.netplan.Netplan.Config Set ss \
    'network.ethernets.eth0.dhcp4=true' '70-dbus-test'
b true

Replace eth0 with the interface you inspected in your own snapshot. The origin hint 70-dbus-test is an example, not a universal filename policy; the resulting YAML name is derived by Netplan. A successful return means the delta was accepted into this temporary configuration object, not that the live network has changed.

Warning: after Set(), other configuration objects are invalidated while this object is dirty. Do not keep several objects open and assume they can all be applied. If this delta is wrong, use Cancel() now:

$ sudo busctl call io.netplan.Netplan "$CONFIG_PATH" \
    io.netplan.Netplan.Config Cancel
b true

Cancel discards the object or rejects its running test. It is the undo for the staged example above. It does not undo a change that has already been applied.

6. Test the staged configuration

Use Try() with a timeout in seconds. Netplan temporarily replaces the main configuration and runs its normal netplan try behaviour:

$ sudo busctl call io.netplan.Netplan "$CONFIG_PATH" \
    io.netplan.Netplan.Config Try u 120
b true

Choose a timeout long enough to reach the host and confirm the result, but not so long that a failed remote change leaves you waiting. A true return reports that the request was accepted. Test reachability, routes and the service you actually need. If the result is wrong, reject it before the timeout with Cancel(). If you lose the session, the timeout is the recovery boundary, but do not rely on it as a substitute for console access.

7. Apply only after the test passes

Once you have checked the staged result, commit it to the main Netplan configuration with Apply():

$ sudo busctl call io.netplan.Netplan "$CONFIG_PATH" \
    io.netplan.Netplan.Config Apply
b true

This is the state-changing step. It replaces the main configuration with the snapshot and runs netplan apply. A false result or a D-Bus error means the operation did not succeed; inspect the error before retrying. Do not re-run Apply() against an older object after another configuration has been accepted, because the daemon invalidates older snapshots.

If you only need to regenerate backend files without changing the snapshot, the top-level Generate() method calls netplan generate. It still operates on system networking configuration and should be treated as a privileged administrative action:

$ sudo busctl call io.netplan.Netplan /io/netplan/Netplan \
    io.netplan.Netplan Generate
b true