basic/linux: update kernel headers from v6.14-rc1
[systemd.io.git] / man / org.freedesktop.network1.xml
blob0b7a6b5ed3d11fa2b6e6a4c2058a4990fee89e8d
1 <?xml version="1.0"?>
2 <!--*-nxml-*-->
3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
4   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
5 <!ENTITY % entities SYSTEM "custom-entities.ent" >
6 %entities;
7 ]>
8 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
10 <refentry id="org.freedesktop.network1" conditional='ENABLE_NETWORKD'
11     xmlns:xi="http://www.w3.org/2001/XInclude">
12   <refentryinfo>
13     <title>org.freedesktop.network1</title>
14     <productname>systemd</productname>
15   </refentryinfo>
17   <refmeta>
18     <refentrytitle>org.freedesktop.network1</refentrytitle>
19     <manvolnum>5</manvolnum>
20   </refmeta>
22   <refnamediv>
23     <refname>org.freedesktop.network1</refname>
24     <refpurpose>The D-Bus interface of systemd-networkd</refpurpose>
25   </refnamediv>
27   <refsect1>
28     <title>Introduction</title>
30     <para>
31     <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
32     is a system service that manages and configures network interfaces. This page describes the D-Bus
33     interface.</para>
34   </refsect1>
36   <refsect1>
37     <title>The Manager Object</title>
39     <para>The service exposes the following interfaces on the Manager object on the bus:</para>
41     <programlisting executable="systemd-networkd" node="/org/freedesktop/network1" interface="org.freedesktop.network1.Manager">
42 node /org/freedesktop/network1 {
43   interface org.freedesktop.network1.Manager {
44     methods:
45       ListLinks(out a(iso) links);
46       GetLinkByName(in  s name,
47                     out i ifindex,
48                     out o path);
49       GetLinkByIndex(in  i ifindex,
50                      out s name,
51                      out o path);
52       SetLinkNTP(in  i ifindex,
53                  in  as servers);
54       SetLinkDNS(in  i ifindex,
55                  in  a(iay) addresses);
56       SetLinkDNSEx(in  i ifindex,
57                    in  a(iayqs) addresses);
58       SetLinkDomains(in  i ifindex,
59                      in  a(sb) domains);
60       SetLinkDefaultRoute(in  i ifindex,
61                           in  b enable);
62       SetLinkLLMNR(in  i ifindex,
63                    in  s mode);
64       SetLinkMulticastDNS(in  i ifindex,
65                           in  s mode);
66       SetLinkDNSOverTLS(in  i ifindex,
67                         in  s mode);
68       SetLinkDNSSEC(in  i ifindex,
69                     in  s mode);
70       SetLinkDNSSECNegativeTrustAnchors(in  i ifindex,
71                                         in  as names);
72       RevertLinkNTP(in  i ifindex);
73       RevertLinkDNS(in  i ifindex);
74       RenewLink(in  i ifindex);
75       ForceRenewLink(in  i ifindex);
76       ReconfigureLink(in  i ifindex);
77       Reload();
78       DescribeLink(in  i ifindex,
79                    out s json);
80       Describe(out s json);
81     properties:
82       readonly s OperationalState = '...';
83       readonly s CarrierState = '...';
84       readonly s AddressState = '...';
85       readonly s IPv4AddressState = '...';
86       readonly s IPv6AddressState = '...';
87       readonly s OnlineState = '...';
88       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
89       readonly t NamespaceId = ...;
90       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
91       readonly u NamespaceNSID = ...;
92   };
93   interface org.freedesktop.DBus.Peer { ... };
94   interface org.freedesktop.DBus.Introspectable { ... };
95   interface org.freedesktop.DBus.Properties { ... };
97 </programlisting>
99     <!--method ListLinks is not documented!-->
101     <!--method GetLinkByName is not documented!-->
103     <!--method GetLinkByIndex is not documented!-->
105     <!--method SetLinkNTP is not documented!-->
107     <!--method SetLinkDNS is not documented!-->
109     <!--method SetLinkDNSEx is not documented!-->
111     <!--method SetLinkDomains is not documented!-->
113     <!--method SetLinkDefaultRoute is not documented!-->
115     <!--method SetLinkLLMNR is not documented!-->
117     <!--method SetLinkMulticastDNS is not documented!-->
119     <!--method SetLinkDNSOverTLS is not documented!-->
121     <!--method SetLinkDNSSEC is not documented!-->
123     <!--method SetLinkDNSSECNegativeTrustAnchors is not documented!-->
125     <!--method RevertLinkNTP is not documented!-->
127     <!--method RevertLinkDNS is not documented!-->
129     <!--method RenewLink is not documented!-->
131     <!--method ForceRenewLink is not documented!-->
133     <!--method ReconfigureLink is not documented!-->
135     <!--method Reload is not documented!-->
137     <!--method DescribeLink is not documented!-->
139     <!--method Describe is not documented!-->
141     <!--property OperationalState is not documented!-->
143     <!--property CarrierState is not documented!-->
145     <!--property AddressState is not documented!-->
147     <!--property IPv4AddressState is not documented!-->
149     <!--property IPv6AddressState is not documented!-->
151     <!--property OnlineState is not documented!-->
153     <!--Autogenerated cross-references for systemd.directives, do not edit-->
155     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Manager"/>
157     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Manager"/>
159     <variablelist class="dbus-method" generated="True" extra-ref="ListLinks()"/>
161     <variablelist class="dbus-method" generated="True" extra-ref="GetLinkByName()"/>
163     <variablelist class="dbus-method" generated="True" extra-ref="GetLinkByIndex()"/>
165     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkNTP()"/>
167     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNS()"/>
169     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSEx()"/>
171     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDomains()"/>
173     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDefaultRoute()"/>
175     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkLLMNR()"/>
177     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkMulticastDNS()"/>
179     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSOverTLS()"/>
181     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSSEC()"/>
183     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSSECNegativeTrustAnchors()"/>
185     <variablelist class="dbus-method" generated="True" extra-ref="RevertLinkNTP()"/>
187     <variablelist class="dbus-method" generated="True" extra-ref="RevertLinkDNS()"/>
189     <variablelist class="dbus-method" generated="True" extra-ref="RenewLink()"/>
191     <variablelist class="dbus-method" generated="True" extra-ref="ForceRenewLink()"/>
193     <variablelist class="dbus-method" generated="True" extra-ref="ReconfigureLink()"/>
195     <variablelist class="dbus-method" generated="True" extra-ref="Reload()"/>
197     <variablelist class="dbus-method" generated="True" extra-ref="DescribeLink()"/>
199     <variablelist class="dbus-method" generated="True" extra-ref="Describe()"/>
201     <variablelist class="dbus-property" generated="True" extra-ref="OperationalState"/>
203     <variablelist class="dbus-property" generated="True" extra-ref="CarrierState"/>
205     <variablelist class="dbus-property" generated="True" extra-ref="AddressState"/>
207     <variablelist class="dbus-property" generated="True" extra-ref="IPv4AddressState"/>
209     <variablelist class="dbus-property" generated="True" extra-ref="IPv6AddressState"/>
211     <variablelist class="dbus-property" generated="True" extra-ref="OnlineState"/>
213     <variablelist class="dbus-property" generated="True" extra-ref="NamespaceId"/>
215     <variablelist class="dbus-property" generated="True" extra-ref="NamespaceNSID"/>
217     <!--End of Autogenerated section-->
219     <para>
220       Provides information about the manager.
221     </para>
223     <refsect2>
224       <title>Properties</title>
226       <para><varname>NamespaceId</varname> contains the inode number of the network namespace that the
227       network service runs in. A client may compare this with the inode number of its own network namespace
228       to verify whether the service manages the same network namespace.</para>
230       <para><varname>NamespaceNSID</varname> contains the "nsid" identifier the kernel maintains for the
231       network namespace, if there's one assigned.</para>
232     </refsect2>
233   </refsect1>
235   <refsect1>
236     <title>Link Object</title>
238     <programlisting executable="systemd-networkd" node="/org/freedesktop/network1/link/_1" interface="org.freedesktop.network1.Link">
239 node /org/freedesktop/network1/link/_1 {
240   interface org.freedesktop.network1.Link {
241     methods:
242       SetNTP(in  as servers);
243       SetDNS(in  a(iay) addresses);
244       SetDNSEx(in  a(iayqs) addresses);
245       SetDomains(in  a(sb) domains);
246       SetDefaultRoute(in  b enable);
247       SetLLMNR(in  s mode);
248       SetMulticastDNS(in  s mode);
249       SetDNSOverTLS(in  s mode);
250       SetDNSSEC(in  s mode);
251       SetDNSSECNegativeTrustAnchors(in  as names);
252       RevertNTP();
253       RevertDNS();
254       Renew();
255       ForceRenew();
256       Reconfigure();
257       Describe(out s json);
258     properties:
259       readonly s OperationalState = '...';
260       readonly s CarrierState = '...';
261       readonly s AddressState = '...';
262       readonly s IPv4AddressState = '...';
263       readonly s IPv6AddressState = '...';
264       readonly s OnlineState = '...';
265       readonly s AdministrativeState = '...';
266       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
267       readonly (tt) BitRates = ...;
268   };
269   interface org.freedesktop.DBus.Peer { ... };
270   interface org.freedesktop.DBus.Introspectable { ... };
271   interface org.freedesktop.DBus.Properties { ... };
273 </programlisting>
275     <!--method SetNTP is not documented!-->
277     <!--method SetDNS is not documented!-->
279     <!--method SetDNSEx is not documented!-->
281     <!--method SetDomains is not documented!-->
283     <!--method SetDefaultRoute is not documented!-->
285     <!--method SetLLMNR is not documented!-->
287     <!--method SetMulticastDNS is not documented!-->
289     <!--method SetDNSOverTLS is not documented!-->
291     <!--method SetDNSSEC is not documented!-->
293     <!--method SetDNSSECNegativeTrustAnchors is not documented!-->
295     <!--method RevertNTP is not documented!-->
297     <!--method RevertDNS is not documented!-->
299     <!--method Renew is not documented!-->
301     <!--method ForceRenew is not documented!-->
303     <!--method Reconfigure is not documented!-->
305     <!--method Describe is not documented!-->
307     <!--property OperationalState is not documented!-->
309     <!--property CarrierState is not documented!-->
311     <!--property AddressState is not documented!-->
313     <!--property IPv4AddressState is not documented!-->
315     <!--property IPv6AddressState is not documented!-->
317     <!--property OnlineState is not documented!-->
319     <!--property AdministrativeState is not documented!-->
321     <!--property BitRates is not documented!-->
323     <!--Autogenerated cross-references for systemd.directives, do not edit-->
325     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Link"/>
327     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Link"/>
329     <variablelist class="dbus-method" generated="True" extra-ref="SetNTP()"/>
331     <variablelist class="dbus-method" generated="True" extra-ref="SetDNS()"/>
333     <variablelist class="dbus-method" generated="True" extra-ref="SetDNSEx()"/>
335     <variablelist class="dbus-method" generated="True" extra-ref="SetDomains()"/>
337     <variablelist class="dbus-method" generated="True" extra-ref="SetDefaultRoute()"/>
339     <variablelist class="dbus-method" generated="True" extra-ref="SetLLMNR()"/>
341     <variablelist class="dbus-method" generated="True" extra-ref="SetMulticastDNS()"/>
343     <variablelist class="dbus-method" generated="True" extra-ref="SetDNSOverTLS()"/>
345     <variablelist class="dbus-method" generated="True" extra-ref="SetDNSSEC()"/>
347     <variablelist class="dbus-method" generated="True" extra-ref="SetDNSSECNegativeTrustAnchors()"/>
349     <variablelist class="dbus-method" generated="True" extra-ref="RevertNTP()"/>
351     <variablelist class="dbus-method" generated="True" extra-ref="RevertDNS()"/>
353     <variablelist class="dbus-method" generated="True" extra-ref="Renew()"/>
355     <variablelist class="dbus-method" generated="True" extra-ref="ForceRenew()"/>
357     <variablelist class="dbus-method" generated="True" extra-ref="Reconfigure()"/>
359     <variablelist class="dbus-method" generated="True" extra-ref="Describe()"/>
361     <variablelist class="dbus-property" generated="True" extra-ref="OperationalState"/>
363     <variablelist class="dbus-property" generated="True" extra-ref="CarrierState"/>
365     <variablelist class="dbus-property" generated="True" extra-ref="AddressState"/>
367     <variablelist class="dbus-property" generated="True" extra-ref="IPv4AddressState"/>
369     <variablelist class="dbus-property" generated="True" extra-ref="IPv6AddressState"/>
371     <variablelist class="dbus-property" generated="True" extra-ref="OnlineState"/>
373     <variablelist class="dbus-property" generated="True" extra-ref="AdministrativeState"/>
375     <variablelist class="dbus-property" generated="True" extra-ref="BitRates"/>
377     <!--End of Autogenerated section-->
379     <para>
380       Provides information about interfaces.
381     </para>
382   </refsect1>
384   <refsect1>
385     <title>Network Object</title>
387     <programlisting executable="systemd-networkd" node="/org/freedesktop/network1/network/_1" interface="org.freedesktop.network1.Network">
388 node /org/freedesktop/network1/network/_1 {
389   interface org.freedesktop.network1.Network {
390     properties:
391       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
392       readonly s Description = '...';
393       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
394       readonly s SourcePath = '...';
395       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
396       readonly as MatchMAC = ['...', ...];
397       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
398       readonly as MatchPath = ['...', ...];
399       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
400       readonly as MatchDriver = ['...', ...];
401       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
402       readonly as MatchType = ['...', ...];
403       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
404       readonly as MatchName = ['...', ...];
405   };
406   interface org.freedesktop.DBus.Peer { ... };
407   interface org.freedesktop.DBus.Introspectable { ... };
408   interface org.freedesktop.DBus.Properties { ... };
410 </programlisting>
412     <!--property Description is not documented!-->
414     <!--property SourcePath is not documented!-->
416     <!--property MatchMAC is not documented!-->
418     <!--property MatchPath is not documented!-->
420     <!--property MatchDriver is not documented!-->
422     <!--property MatchType is not documented!-->
424     <!--property MatchName is not documented!-->
426     <!--Autogenerated cross-references for systemd.directives, do not edit-->
428     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Network"/>
430     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Network"/>
432     <variablelist class="dbus-property" generated="True" extra-ref="Description"/>
434     <variablelist class="dbus-property" generated="True" extra-ref="SourcePath"/>
436     <variablelist class="dbus-property" generated="True" extra-ref="MatchMAC"/>
438     <variablelist class="dbus-property" generated="True" extra-ref="MatchPath"/>
440     <variablelist class="dbus-property" generated="True" extra-ref="MatchDriver"/>
442     <variablelist class="dbus-property" generated="True" extra-ref="MatchType"/>
444     <variablelist class="dbus-property" generated="True" extra-ref="MatchName"/>
446     <!--End of Autogenerated section-->
448     <para>
449       Provides information about .network files.
450     </para>
451   </refsect1>
453   <refsect1>
454     <title>DHCP Server Object</title>
456     <programlisting executable="systemd-networkd" node="/org/freedesktop/network1/link/_1" interface="org.freedesktop.network1.DHCPServer">
457 node /org/freedesktop/network1/link/_1 {
458   interface org.freedesktop.network1.DHCPServer {
459     properties:
460       readonly a(uayayayayt) Leases = [...];
461   };
462   interface org.freedesktop.DBus.Peer { ... };
463   interface org.freedesktop.DBus.Introspectable { ... };
464   interface org.freedesktop.DBus.Properties { ... };
465   interface org.freedesktop.network1.Link { ... };
467 </programlisting>
469     <!--property Leases is not documented!-->
471     <!--Autogenerated cross-references for systemd.directives, do not edit-->
473     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Link"/>
475     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.DHCPServer"/>
477     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Link"/>
479     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.DHCPServer"/>
481     <variablelist class="dbus-property" generated="True" extra-ref="Leases"/>
483     <!--End of Autogenerated section-->
485     <para>
486       Provides information about leases.
487     </para>
488   </refsect1>
490   <refsect1>
491     <title>DHCPv4 Client Object</title>
493     <programlisting executable="systemd-networkd" node="/org/freedesktop/network1/link/_1" interface="org.freedesktop.network1.DHCPv4Client">
494 node /org/freedesktop/network1/link/_1 {
495   interface org.freedesktop.network1.DHCPv4Client {
496     properties:
497       readonly s State = '...';
498   };
499   interface org.freedesktop.DBus.Peer { ... };
500   interface org.freedesktop.DBus.Introspectable { ... };
501   interface org.freedesktop.DBus.Properties { ... };
502   interface org.freedesktop.network1.Link { ... };
504 </programlisting>
506     <!--property State is not documented!-->
508     <!--Autogenerated cross-references for systemd.directives, do not edit-->
510     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Link"/>
512     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.DHCPv4Client"/>
514     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Link"/>
516     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.DHCPv4Client"/>
518     <variablelist class="dbus-property" generated="True" extra-ref="State"/>
520     <!--End of Autogenerated section-->
522     <para>
523       Provides information about DHCPv4 client status.
524     </para>
525   </refsect1>
527   <refsect1>
528     <title>DHCPv6 Client Object</title>
530     <programlisting executable="systemd-networkd" node="/org/freedesktop/network1/link/_1" interface="org.freedesktop.network1.DHCPv6Client">
531 node /org/freedesktop/network1/link/_1 {
532   interface org.freedesktop.network1.DHCPv6Client {
533     properties:
534       readonly s State = '...';
535   };
536   interface org.freedesktop.DBus.Peer { ... };
537   interface org.freedesktop.DBus.Introspectable { ... };
538   interface org.freedesktop.DBus.Properties { ... };
539   interface org.freedesktop.network1.Link { ... };
541 </programlisting>
543     <!--property State is not documented!-->
545     <!--Autogenerated cross-references for systemd.directives, do not edit-->
547     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Link"/>
549     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.DHCPv6Client"/>
551     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.Link"/>
553     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.network1.DHCPv6Client"/>
555     <variablelist class="dbus-property" generated="True" extra-ref="State"/>
557     <!--End of Autogenerated section-->
559     <para>
560       Provides information about DHCPv6 client status.
561     </para>
562   </refsect1>
564   <refsect1>
565     <title>Examples</title>
567     <example>
568       <title>Introspect <interfacename>org.freedesktop.network1.Manager</interfacename> on the bus</title>
570       <programlisting>
571 $ gdbus introspect --system \
572   --dest org.freedesktop.network1 \
573   --object-path /org/freedesktop/network1
574 </programlisting>
575     </example>
577     <example>
578       <title>Introspect <interfacename>org.freedesktop.network1.Link</interfacename> on the bus</title>
580       <programlisting>
581 $ gdbus introspect --system \
582   --dest org.freedesktop.network1 \
583   --object-path /org/freedesktop/network1/link/_11
584 </programlisting>
585     </example>
586   </refsect1>
588   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
590   <refsect1>
591     <title>History</title>
592     <refsect2>
593       <title>DHCPv4 Client Object</title>
594       <para><varname>State</varname> was added in version 255.</para>
595     </refsect2>
596     <refsect2>
597       <title>DHCPv6 Client Object</title>
598       <para><varname>State</varname> was added in version 255.</para>
599     </refsect2>
600     <refsect2>
601       <title>Manager Object</title>
602       <para><varname>NamespaceNSID</varname> was added in version 256.</para>
603     </refsect2>
604   </refsect1>
606   <refsect1>
607     <title>See Also</title>
608     <para><simplelist type="inline">
609       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
610       <member><citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
611       <member><citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
612     </simplelist></para>
613   </refsect1>
614 </refentry>