ORG.FREEDESKTOP.NETWORK1(5)

📦
version 262.1 · 14 versions
, in arch rolling

💖 org.freedesktop.network1 💖

hey bestie, this is ORG.FREEDESKTOP.NETWORK1(5), and we're talking about the D-Bus interface of systemd-networkd — yes, the whole thing, every method, every property, no skips. grab a strawberry 🍓 and let's go.

🌈 NAME

org.freedesktop.network1 — the D-Bus interface of systemd-networkd

✨ INTRODUCTION

so systemd-networkd.service(8) is that service that manages and configures network interfaces, right? iconic behaviour honestly. and this page? this page is where we spill all the tea about its D-Bus interface. 💅

👑 THE MANAGER OBJECT

the service puts these interfaces out there on the Manager object, sitting on the bus like the main character it is:

node /org/freedesktop/network1 {
  interface org.freedesktop.network1.Manager {
    methods:
      ListLinks(out a(iso) links);
      GetLinkByName(in  s name,
                    out i ifindex,
                    out o path);
      GetLinkByIndex(in  i ifindex,
                     out s name,
                     out o path);
      SetLinkNTP(in  i ifindex,
                 in  as servers);
      SetLinkDNS(in  i ifindex,
                 in  a(iay) addresses);
      SetLinkDNSEx(in  i ifindex,
                   in  a(iayqs) addresses);
      SetLinkDomains(in  i ifindex,
                     in  a(sb) domains);
      SetLinkDefaultRoute(in  i ifindex,
                          in  b enable);
      SetLinkLLMNR(in  i ifindex,
                   in  s mode);
      SetLinkMulticastDNS(in  i ifindex,
                          in  s mode);
      SetLinkDNSOverTLS(in  i ifindex,
                        in  s mode);
      SetLinkDNSSEC(in  i ifindex,
                    in  s mode);
      SetLinkDNSSECNegativeTrustAnchors(in  i ifindex,
                                        in  as names);
      RevertLinkNTP(in  i ifindex);
      RevertLinkDNS(in  i ifindex);
      RenewLink(in  i ifindex);
      ForceRenewLink(in  i ifindex);
      ReconfigureLink(in  i ifindex);
      Reload();
      DescribeLink(in  i ifindex,
                   out s json);
      Describe(out s json);
    properties:
      readonly s OperationalState = '...';
      readonly s CarrierState = '...';
      readonly s AddressState = '...';
      readonly s IPv4AddressState = '...';
      readonly s IPv6AddressState = '...';
      readonly s OnlineState = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly t NamespaceId = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly u NamespaceNSID = ...;
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

it provides info about the manager. that's the vibe. 🫶

💅 Properties

  • NamespaceId — this one holds the inode number of the network namespace that the network service is running in. a client can compare it against the inode number of its own network namespace, and that tells you whether the service is managing the same network namespace as you. basically a vibe check for namespaces. ✨
  • NamespaceNSID — this holds the "nsid" identifier that the kernel keeps for the network namespace, if there's one assigned. if there isn't, well… 🙈
node /org/freedesktop/network1/link/_1 {
  interface org.freedesktop.network1.Link {
    methods:
      SetNTP(in  as servers);
      SetDNS(in  a(iay) addresses);
      SetDNSEx(in  a(iayqs) addresses);
      SetDomains(in  a(sb) domains);
      SetDefaultRoute(in  b enable);
      SetLLMNR(in  s mode);
      SetMulticastDNS(in  s mode);
      SetDNSOverTLS(in  s mode);
      SetDNSSEC(in  s mode);
      SetDNSSECNegativeTrustAnchors(in  as names);
      RevertNTP();
      RevertDNS();
      Renew();
      ForceRenew();
      Reconfigure();
      Describe(out s json);
    properties:
      readonly s OperationalState = '...';
      readonly s CarrierState = '...';
      readonly s AddressState = '...';
      readonly s IPv4AddressState = '...';
      readonly s IPv6AddressState = '...';
      readonly s OnlineState = '...';
      readonly s AdministrativeState = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly (tt) BitRates = ...;
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

it provides info about interfaces. love that for it. 💜

🎀 NETWORK OBJECT

node /org/freedesktop/network1/network/_1 {
  interface org.freedesktop.network1.Network {
    properties:
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s Description = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s SourcePath = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly as MatchMAC = ['...', ...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly as MatchPath = ['...', ...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly as MatchDriver = ['...', ...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly as MatchType = ['...', ...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly as MatchName = ['...', ...];
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

it provides info about .network files. periodt. 🌸

🔥 DHCP SERVER OBJECT

node /org/freedesktop/network1/link/_1 {
  interface org.freedesktop.network1.DHCPServer {
    properties:
      readonly a(uayayayayt) Leases = [...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly u PoolSize = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly u PoolOffset = ...;
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
  interface org.freedesktop.network1.Link { ... };
};

it provides info about the DHCP server, and here's the breakdown bestie:

  • Leases — holds the currently active leases. currently, as in right now. 🔥
  • PoolSize — the total number of addresses in the dynamic address pool.
  • PoolOffset — the offset from the subnet base address to where the pool starts.

these two correspond to the PoolSize= and PoolOffset= settings in systemd.network(5).

⚠️ okay important: UINT32_MAX is used as a sentinel value for PoolSize and PoolOffset to indicate that the information is unavailable — like, no DHCP server is configured, or the link is in relay mode — rather than an actual valid pool size or offset. so don't get played by that number. 💀

🌈 DHCPV4 CLIENT OBJECT

node /org/freedesktop/network1/link/_1 {
  interface org.freedesktop.network1.DHCPv4Client {
    properties:
      readonly s State = '...';
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
  interface org.freedesktop.network1.Link { ... };
};

it provides info about DHCPv4 client status. keeping you posted, fr fr. 🫶

⭐ DHCPV6 CLIENT OBJECT

node /org/freedesktop/network1/link/_1 {
  interface org.freedesktop.network1.DHCPv6Client {
    properties:
      readonly s State = '...';
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
  interface org.freedesktop.network1.Link { ... };
};

it provides info about DHCPv6 client status. yes, v6 gets its own moment. as it should. 👑

🧚 EXAMPLES

Example 1. Introspect org.freedesktop.network1.Manager on the bus

$ gdbus introspect --system \
  --dest org.freedesktop.network1 \
  --object-path /org/freedesktop/network1
$ gdbus introspect --system \
  --dest org.freedesktop.network1 \
  --object-path /org/freedesktop/network1/link/_11

go off. run them, they eat every time. ✨

🎀 VERSIONING

these D-Bus interfaces follow the usual interface versioning guidelines[1]. iykyk.

📜 HISTORY

DHCP Server Object

PoolSize and PoolOffset were added in version 261.

DHCPv4 Client Object

State was added in version 255.

DHCPv6 Client Object

State was added in version 255.

Manager Object

NamespaceNSID was added in version 256.

💜 SEE ALSO

📝 NOTES

  1. the usual interface versioning guidelines https://0pointer.de/blog/projects/versioning-dbus.html

and that's the whole page, no cap. this beauty is from systemd 262.1 and it lives under the manual name ORG.FREEDESKTOP.NETWORK1(5). slay, read it again, and go configure something. 💅✨🦋

📦 where this page comes from
  • arch rolling: systemd 262.1-1 · LGPL-2.1-or-later AND CC0-1.0 AND GPL-2.0-or-later AND MIT-0
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms