ipadm (and IPMP on Solaris 11)
30 April 2012

The ipadm command is new in Solaris 11 and the Illumos derived distributions. It’s a different way of handling IP interfaces, replacing ifconfig and a lot of /etc file manipulation.

IP interfaces

Creating an Interface

The first, most basic operation for which to use ipadm is the creation of a new IP interface. You need an existing datalink to create an interface on - note I say datalink, not NIC. That’s a good job, because I don’t have any free physical NICs on this box, so I’ll have to create a virtual NIC on top of atge0 and use that.

# dladm create-vnic -l atge0 test0
# ipadm create-ip test0

The ipadm command may seem like a pointless step. What, really, is an “interface”? It doesn’t have an address or any useful properties, so it doesn’t really do anything. Why can’t you just assign the address, netmask etc. to the link, like you always used to? Well, though I created a (typical) IP interface, you can also create VNI interfaces and IPMP groups with create-vni and create-ipmp respectively. (More of the latter will follow.) So, we had to tell ipadm what class of link we wanted to make. You can see all the interfaces, and their classes, with

# ipadm show-if
lo0        loopback ok       yes    --
atge0      ip       ok       yes    --
test0      ip       down     no     --

Assigning an Address

So there’s my new interface. It’s not a lot of good though, is it? It’s “down” and not “active”, and it doesn’t have an address. Let’s create a static IP address on the new interface.

# ipadm create-addr -T static -a local= test0/addr

The create-addr part is fairly obvious - we’re creating an address. -T is the type of address we’re creating, in this case, static (it can also be addrconf if you’re using IPv6, which I’m guessing you probably aren’t, or dhcp if you want to automatically configure your manually configured IP address.) The -a option sets the address, which can be local, as ours is, or remote. (remote is for point-to-point connections, where you have to specify the remote and local endpoints as local=,remote= If you’re just creating a “normal” local interface, you can omit local=. You can leave out the netmask /24 in our example as well, assuming you’ve got suitably configured /etc/netmasks file, and if you have a suitable entry in hosts it’s even possible to use a hostname instead of an IP address.

The final argument, net0/addr is the “address object”. An interface can have multiple address objects associated with it, but often will have just one - the IPv4 address. You can examine addresses with ipadm show-addr, and use the address object name to be specific.

# ipadm show-addr test0/addr
ADDROBJ           TYPE     STATE        ADDR
test0/addr        static   ok 

That looks pretty much configured to me. Let’s quickly check it with ifconfig (I won’t tell Oracle if you don’t.)

$ ifconfig test0
test0: flags=1000843<UP,BROADCAST,RUNNING,MULTICAST,IPv4> mtu 1500 index 3
        inet netmask ffffff00 broadcast
	    ether 2:8:20:7f:7d:a4

Note that the interface is UP. This is the default, and if you want it DOWN, throw -d into the create-addr command. If you don’t want the address to persist (i.e. it only lasts until the next reboot) add in -t, like you do with svcadm.

I don’t know about you, but I rather liked that as a way of configuring an interface. It seems very clean and simple. show-addr even notifies you of IP address collisions by putting duplicate in the STATE field! The only oddity is that “address object” we have to keep tagging on the end. That was weird, and pointless, right?

Well, no. For a start, the address object name gives you a way to refer to the address. Say you wanted to delete the IP address, but not go so far as blowing away the VNIC, you’d specify the object:

# ipadm delete-addr test0/addr

There’s nothing magical about the word addr either.

# ipadm create-addr -T static -a test0/live

is perfectly valid, and perhaps tells us that interface is on the “live” VLAN. (I’m very big on self-documenting naming schemes.) Or perhaps if you were to have IPv4 and IPv6 on the same interface, you might call them net0/v4 and net0/v6 or something?

Address object names also allow you to give sensible names to virtual IP addresses when using shared IP instances for zones. (Though you probably won’t use shared IP instances in Solaris 11, as the exclusive instance configuration is so good.)

All of the above works in OpenIndiana too. If you’re using Solaris 11, you’re into the hell of configuring your DNS via SMF. If not, lucky you!

Setting a Default Route

To continue the theme of not editing files in /etc we define our default router through a command now as well:

# route -p add default

We’ve had route -p for a while now I think, since fairly early on in the Solaris 10 cycle, so that’s probably worked for ages.

Managing and Tuning Interfaces

Want to briefly take an interface down, then bring it back up? Easy.

# ipadm down-addr test0/live
$ ping 1
no answer from
# ipadm up-addr test0/live
$ ping is alive

You can disable and re-enable the interface itself just as efficiently with the disable-if and enable-if subcommands.

Have you ever had to tune your TCP stack? Writing rc.d scripts that fiddled with ndd every reboot never seemed right, did it? Try running

# ipadm show-prop

And there are all the tunables, nicely laid out and easy to read and manipulate. Just want the TCP properties? No problem:

# ipadm show-prop tcp

It even shows you allowable ranges and values! Want to increase your receive buffer size until next reboot?

# ipadm set-prop -t -p recv_buf=300000 tcp

This gets better all the time doesn’t it? To make the change persist across reboot (i.e. not transient), omit -t.

We’ve just been looking at interface properties. Address objects have properties too, and

# ipadm show-addrprop

will show you them for all objects. To query a single object, out comes the object name again:

# ipadm show-addrprop test0/live

There is a third set of properties which can be viewed and manipulated with ipadm, and they belong to the datalinks, both physical and virtual.

# ipadm show-ifprop

Want to change the IPv4 metric on atge0?

# ipadm set-ifprop -p metric=1 -m ipv4 atge0

What, that’s broken all your networking and want to change it back to the default?

# ipadm reset-ifprop -p metric -m ipv4 atge0

Hopefully by now you’ll have realized that ipadm is a Good Thing, pulling together stuff that was previously scattered all over Solaris, and putting a good clean front end on it. It even produces colon-separated machine-parseable output with the -c and -o options. I don’t know if it’s the same people who did dladm, but it’s an equally good bit of design and implementation.

Getting Rid of an Address

You can delete an interface even if it has live addresses.

# ipadm show-addr  test0/addr
ADDROBJ           TYPE     STATE        ADDR
test0/addr        static   ok 
# ipadm delete-ip test0
# ipadm show-addr  test0/addr
ipadm: address object not found


I said earlier that an interface can be IP, VNI, or IPMP. I’ve never used a VNI link, so I don’t feel qualified to talk about that, but I do use IPMP, and I always felt the way you managed it in previous versions of Solaris was something of a mess. Here’s where we genuinely do need a new command, and that command is, of course, ipadm.

For the sake of illustration I’m going to create an IPMP pair using two VNICs on the same physical interface. Obviously that’s pointless and stupid in real life, but it’ll do here.

# dladm create-vnic -l atge0 path0 dladm create-vnic -l atge0 path1

You need an IP interface on both of those paths:

# ipadm create-ip path0
# ipadm create-ip path1

Then you can create your IPMP group using those interfaces.

# ipadm create-ipmp -i path0,path1 ipmp0
# ipadm show-if ipmp0
ipmp0      ipmp     down     no     path0 path1

Now you can treat ipmp0 (you could have called it anything you wanted) as if it were any other interface. So let’s give it an address:

# ipadm create-addr -T static -a ipmp0/v4
$ ping is alive

You can view and change the properties of that address just as if it were a “normal” SPOF interface. And, of course, that IPMP group will still be there if we reboot. Ridiculously simple isn’t it? You know what, I don’t think I trust that two-path group. Let’s add another.

# dladm create-vnic -l atge0 path2
# ipadm create-ip path2
# ipadm add-ipmp -i path2 ipmp0
# ipadm show-if ipmp0
ipmp0      ipmp     ok       yes    path0 path1 path2

On second thoughts, maybe that’s overkill. To remove “the third way”:

# ipadm remove-ipmp -i path2 ipmp0

To digress slightly, there’s also a command called ipmpstat which can give you more information on things like the health of the group (with -g), the frequency and routing of probes (-p), and the test addresses those probes use.

# ipmpstat -t
path1       disabled   --                  --
path0       disabled   --                  --

Clearly, the group we set up doesn’t use test addresses, so it’s not the safest form of IPMP. We can add test addresses like so:

# ipadm create-addr -T static -a path1/testv4
# ipadm create-addr -T static -a path0/testv4
# ipmpstat -nt
path1       routes
path0       routes

Note how I chose to use a descriptive address object name, which I think is good practice. The -n flag in the ipmpstat command forces addresses to be printed as numbers. Otherwise lookups are done and hostnames are printed. I thought that output was less clear for my example.

Removing IPMP interfaces

You can’t just blow away an IPMP interface like you can a normal IP interface

# ipadm delete-ipmp ipmp0
ipadm: cannot delete IPMP interface ipmp0: IPMP group is not empty

We need to remove the interfaces from the IPMP group:

# ipmpstat -t
path2       disabled   --                  --
path1       routes       router
# ipadm remove-ipmp -i path1,path2 ipmp0
# ipadm delete-ipmp ipmp0

And for the sake of tidiness, remove those interfaces too.

# ipadm delete-ip path1
# ipadm delete-ip path2

So that’s the new way of doing network interfaces and IPMP. Good, isn’t it?