Is the manpage wrong for "ip address delete"?

Is the manpage wrong for "ip address delete"?

[Adam Nielsen]

Hi all,

I'm trying to remove an IP address from an interface, without having to
specify it, but the behaviour doesn't seem to match the manpage.

In the manpage for ip-address it states:

    ip address delete - delete protocol address
       Arguments: coincide with the arguments of ip addr add.  The
       device name is a required  argument. The rest are optional.  If no
       arguments are given, the first address is deleted.

I can't work out how to trigger the "if no arguments are given" part:

  $ ip address delete dev eth0
  RTNETLINK answers: Operation not supported

  $ ip address delete "" dev eth0
  Error: any valid prefix is expected rather than "".

  $ ip address dev eth0 delete
  Command "dev" is unknown, try "ip address help".

In the end I worked out that "ip address flush dev eth0" did what I
wanted, but I'm just wondering whether the manpage needs to be updated
to reflect the current behaviour?

Cheers,
Adam.

(Not subscribed, please CC)

Re: Is the manpage wrong for "ip address delete"?

[Donald Hunter]

Adam Nielsen <a.nielsen@shikadi.net> writes:

> Hi all,
>
> I'm trying to remove an IP address from an interface, without having to
> specify it, but the behaviour doesn't seem to match the manpage.
>
> In the manpage for ip-address it states:
>
>     ip address delete - delete protocol address
>        Arguments: coincide with the arguments of ip addr add.  The
>        device name is a required  argument. The rest are optional.  If no
>        arguments are given, the first address is deleted.
>
> I can't work out how to trigger the "if no arguments are given" part:
>
>   $ ip address delete dev eth0
>   RTNETLINK answers: Operation not supported
>
>   $ ip address delete "" dev eth0
>   Error: any valid prefix is expected rather than "".
>
>   $ ip address dev eth0 delete
>   Command "dev" is unknown, try "ip address help".
>
> In the end I worked out that "ip address flush dev eth0" did what I
> wanted, but I'm just wondering whether the manpage needs to be updated
> to reflect the current behaviour?

Yes, that paragraph of the manpage appears to be wrong. It does not
match the manpage synopsis, nor the usage from "ip address help" which
both say:

  ip address del IFADDR dev IFNAME [ mngtmpaddr ]

The description does match the kernel behaviour for a given address
family, which you can see by using ynl:

$ ip a show dev veth0
2: veth0@veth1: <BROADCAST,MULTICAST,M-DOWN> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether 6a:66:c7:67:bc:81 brd ff:ff:ff:ff:ff:ff
    inet 6.6.6.6/24 scope global fred
       valid_lft forever preferred_lft forever
    inet 2.2.2.2/24 scope global veth0
       valid_lft forever preferred_lft forever
    inet 4.4.4.4/24 scope global veth0
       valid_lft forever preferred_lft forever

$ sudo ./tools/net/ynl/cli.py \
  --spec Documentation/netlink/specs/rt_addr.yaml \
  --do deladdr --json '{"ifa-family": 2, "ifa-index": 2}'
None

$ ip a show dev veth0
2: veth0@veth1: <BROADCAST,MULTICAST,M-DOWN> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether 6a:66:c7:67:bc:81 brd ff:ff:ff:ff:ff:ff
    inet 2.2.2.2/24 scope global veth0
       valid_lft forever preferred_lft forever
    inet 4.4.4.4/24 scope global veth0
       valid_lft forever preferred_lft forever

I guess it makes sense for "ip address del" to be stricter since 'first
address' is quite arbitrary behaviour.

> Cheers,
> Adam.
>
> (Not subscribed, please CC)

Re: Is the manpage wrong for "ip address delete"?

[Stephen Hemminger]

On Fri, 12 Jul 2024 11:33:45 +0100
Donald Hunter <donald.hunter@gmail.com> wrote:

> Adam Nielsen <a.nielsen@shikadi.net> writes:
> 
> > Hi all,
> >
> > I'm trying to remove an IP address from an interface, without having to
> > specify it, but the behaviour doesn't seem to match the manpage.
> >
> > In the manpage for ip-address it states:
> >
> >     ip address delete - delete protocol address
> >        Arguments: coincide with the arguments of ip addr add.  The
> >        device name is a required  argument. The rest are optional.  If no
> >        arguments are given, the first address is deleted.
> >
> > I can't work out how to trigger the "if no arguments are given" part:
> >
> >   $ ip address delete dev eth0
> >   RTNETLINK answers: Operation not supported
> >
> >   $ ip address delete "" dev eth0
> >   Error: any valid prefix is expected rather than "".
> >
> >   $ ip address dev eth0 delete
> >   Command "dev" is unknown, try "ip address help".
> >
> > In the end I worked out that "ip address flush dev eth0" did what I
> > wanted, but I'm just wondering whether the manpage needs to be updated
> > to reflect the current behaviour?  
> 
> Yes, that paragraph of the manpage appears to be wrong. It does not
> match the manpage synopsis, nor the usage from "ip address help" which
> both say:
> 
>   ip address del IFADDR dev IFNAME [ mngtmpaddr ]
> 
> The description does match the kernel behaviour for a given address
> family, which you can see by using ynl:
> 
> $ ip a show dev veth0
> 2: veth0@veth1: <BROADCAST,MULTICAST,M-DOWN> mtu 1500 qdisc noop state DOWN group default qlen 1000
>     link/ether 6a:66:c7:67:bc:81 brd ff:ff:ff:ff:ff:ff
>     inet 6.6.6.6/24 scope global fred
>        valid_lft forever preferred_lft forever
>     inet 2.2.2.2/24 scope global veth0
>        valid_lft forever preferred_lft forever
>     inet 4.4.4.4/24 scope global veth0
>        valid_lft forever preferred_lft forever
> 
> $ sudo ./tools/net/ynl/cli.py \
>   --spec Documentation/netlink/specs/rt_addr.yaml \
>   --do deladdr --json '{"ifa-family": 2, "ifa-index": 2}'
> None
> 
> $ ip a show dev veth0
> 2: veth0@veth1: <BROADCAST,MULTICAST,M-DOWN> mtu 1500 qdisc noop state DOWN group default qlen 1000
>     link/ether 6a:66:c7:67:bc:81 brd ff:ff:ff:ff:ff:ff
>     inet 2.2.2.2/24 scope global veth0
>        valid_lft forever preferred_lft forever
>     inet 4.4.4.4/24 scope global veth0
>        valid_lft forever preferred_lft forever
> 
> I guess it makes sense for "ip address del" to be stricter since 'first
> address' is quite arbitrary behaviour.

I wonder if it used to work long ago in some early version (like 2.4) and
got broken and no one ever noticed

Re: Is the manpage wrong for "ip address delete"?

[Donald Hunter]

Stephen Hemminger <stephen@networkplumber.org> writes:

> On Fri, 12 Jul 2024 11:33:45 +0100
> Donald Hunter <donald.hunter@gmail.com> wrote:
>
>> Adam Nielsen <a.nielsen@shikadi.net> writes:
>> 
>> > Hi all,
>> >
>> > I'm trying to remove an IP address from an interface, without having to
>> > specify it, but the behaviour doesn't seem to match the manpage.
>> >
>> > In the manpage for ip-address it states:
>> >
>> >     ip address delete - delete protocol address
>> >        Arguments: coincide with the arguments of ip addr add.  The
>> >        device name is a required  argument. The rest are optional.  If no
>> >        arguments are given, the first address is deleted.
>> >
>> > I can't work out how to trigger the "if no arguments are given" part:
>> >
>> >   $ ip address delete dev eth0
>> >   RTNETLINK answers: Operation not supported
>> >
>> >   $ ip address delete "" dev eth0
>> >   Error: any valid prefix is expected rather than "".
>> >
>> >   $ ip address dev eth0 delete
>> >   Command "dev" is unknown, try "ip address help".
>> >
>> > In the end I worked out that "ip address flush dev eth0" did what I
>> > wanted, but I'm just wondering whether the manpage needs to be updated
>> > to reflect the current behaviour?  
>> 
>> Yes, that paragraph of the manpage appears to be wrong. It does not
>> match the manpage synopsis, nor the usage from "ip address help" which
>> both say:
>> 
>>   ip address del IFADDR dev IFNAME [ mngtmpaddr ]
>> 
>> The description does match the kernel behaviour for a given address
>> family, which you can see by using ynl:
>> 
>> $ ip a show dev veth0
>> 2: veth0@veth1: <BROADCAST,MULTICAST,M-DOWN> mtu 1500 qdisc noop state DOWN group default qlen 1000
>>     link/ether 6a:66:c7:67:bc:81 brd ff:ff:ff:ff:ff:ff
>>     inet 6.6.6.6/24 scope global fred
>>        valid_lft forever preferred_lft forever
>>     inet 2.2.2.2/24 scope global veth0
>>        valid_lft forever preferred_lft forever
>>     inet 4.4.4.4/24 scope global veth0
>>        valid_lft forever preferred_lft forever
>> 
>> $ sudo ./tools/net/ynl/cli.py \
>>   --spec Documentation/netlink/specs/rt_addr.yaml \
>>   --do deladdr --json '{"ifa-family": 2, "ifa-index": 2}'
>> None
>> 
>> $ ip a show dev veth0
>> 2: veth0@veth1: <BROADCAST,MULTICAST,M-DOWN> mtu 1500 qdisc noop state DOWN group default qlen 1000
>>     link/ether 6a:66:c7:67:bc:81 brd ff:ff:ff:ff:ff:ff
>>     inet 2.2.2.2/24 scope global veth0
>>        valid_lft forever preferred_lft forever
>>     inet 4.4.4.4/24 scope global veth0
>>        valid_lft forever preferred_lft forever
>> 
>> I guess it makes sense for "ip address del" to be stricter since 'first
>> address' is quite arbitrary behaviour.
>
> I wonder if it used to work long ago in some early version (like 2.4) and
> got broken and no one ever noticed

It does work as described if you specify the family:

ip -family inet addr del dev veth0

It is documented well enough in the ip(8) manpage:

  -f, -family <FAMILY>
    Specifies the protocol family to use. The protocol family identifier
    can be one of inet, inet6, bridge, mpls or link. If this option is
    not present, the protocol family is guessed from other arguments. If
    the rest of the command line does not give enough information to
    guess the family, ip falls back to the default one, usually inet or
    any. link is a special family identifier meaning that no networking
    protocol is involved.

Re: Is the manpage wrong for "ip address delete"?

[Stephen Hemminger]

On Fri, 12 Jul 2024 11:33:45 +0100
Donald Hunter <donald.hunter@gmail.com> wrote:

> Adam Nielsen <a.nielsen@shikadi.net> writes:
> 
> > Hi all,
> >
> > I'm trying to remove an IP address from an interface, without having to
> > specify it, but the behaviour doesn't seem to match the manpage.
> >
> > In the manpage for ip-address it states:
> >
> >     ip address delete - delete protocol address
> >        Arguments: coincide with the arguments of ip addr add.  The
> >        device name is a required  argument. The rest are optional.  If no
> >        arguments are given, the first address is deleted.

That part is just wrong. Went back and looked at really old system
running 2.4 kernel and it failed there as well. Probably something
that got changed long long ago, and no one cared or noticed.

> >
> > I can't work out how to trigger the "if no arguments are given" part:
> >
> >   $ ip address delete dev eth0
> >   RTNETLINK answers: Operation not supported
> >
> >   $ ip address delete "" dev eth0
> >   Error: any valid prefix is expected rather than "".
> >
> >   $ ip address dev eth0 delete
> >   Command "dev" is unknown, try "ip address help".
> >
> > In the end I worked out that "ip address flush dev eth0" did what I
> > wanted, but I'm just wondering whether the manpage needs to be updated
> > to reflect the current behaviour?  
> 
> Yes, that paragraph of the manpage appears to be wrong. It does not
> match the manpage synopsis, nor the usage from "ip address help" which
> both say:
> 
>   ip address del IFADDR dev IFNAME [ mngtmpaddr ]

ip address allows address before or after device name. 
Both are the same:
   # ip address delete 1.1.1.1/24 dev eth0
   # ip address delete dev eth0 1.1.1.1/24


> 
> The description does match the kernel behaviour for a given address
> family, which you can see by using ynl:

Kernel ynl is new and different.