iControl REST 101: Modifying Objects

So far in this series we’ve shown you how to connect to iControl REST via cURL, how to list objects on the device (which is probably the most used command for most APIs, including ours), and how to add objects. So you’re currently able to get a system up and running and configure new services on your BIG-IP. What if, however, you want to modify things that are already running? For that, you need a modify command.

Enter PUT.

Remember that in REST based architectures the API is able to determine what type of action you’re performing, and thereby the arguments and structure it should expect to parse coming in, based on the type of HTTP(S) transaction. For us a GET is a list, a POST is an add, and to modify things, you use PUT. This allows the system to understand that you’re going to reference an object that already exists, and modify some of the contents.

It is important that the API back end can tell the difference. If you just tried to do another POST with only the arguments you wanted to change, it would fail because you wouldn’t meet the minimum requirements. Without a PUT, you’d have to do a list on the object, save all the configuration options already on the system for that object, modify just the one you wanted to change in your memory structure, delete the object on the system, and then POST all of that data, including the one or two modified fields, back to the device. That’s way too much work.

Instead, let’s just learn how to modify, shall we? Fortunately it’s simple. All you need to do is format your cURL request with a PUT and the data you want to modify, and you’re all set.

First let’s list the object we want to modify, so you can see what it looks like as it sits on the box currently. For that we go back to our list command:

 

curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/cw_test2 | jq .

So that’s what the object looks like Now what if we want to simply make that existing self IP address available for more than one port? We can use the “allowService” flag to do this. By setting it to “all” we’ll allow that IP to answer on any port, rather than just a specific one, thereby opening up our config a bit.

So we have the object we want to modify as well as the attribute we want to modify for that object. All we need now is to send the command to do the work. Fortunately this is pretty easy, as I mentioned before. You use the same cURL structure as always with the –sk and user:pass supplied. This will look nearly identical to the add command with the changes being that we use the “PUT” method instead of “POST” and we only supply the one item we’re modifying about the object. It looks like this:

 

curl -sk -u admin:admin https://dev.rest.box/mgmt/tm/net/self/cw_test2 -H "Content-Type: application/json" -X PUT -d "{\"allowService\":\"all\"}" | jq .

 

Notice that I’m still piping the output to jq here. This is because the response from the API when running most commands such as POST and PUT is actually quite useful. Here’s what I get when I run the above command:

As you can see this returns the entire, new output of the object, including the piece that got modified. In this case it’s the sixth line of output, including the brace lines. What used to be the line defining the vlan is now "allowService": "all", just like we wanted.

So there you have it, modifying objects on the BIG-IP remotely doesn’t get much easier than that. Armed with this knowledge on top of what we’ve covered in previous installments you’ll be able to tackle 90% of the challenges you might encounter. For our next and penultimate edition of this series we’ll cover the delete command, which should round out the methods you’ll need for the general application of the new iControl REST API.

Published Mar 13, 2014
Version 1.0

Was this article helpful?

8 Comments

  • I love these articles, but two points: 1) The embedded examples are ASM related, not self-IP related. 2) You will only see the allowService option if it is set to something other than 'Allow none', where 'Allow none' is the default value if creating a self-ip on a vlan other than 'internal' or 'external'.
  • Yeah, the screenshots don't match the description for it. Also, at least in version 12.0, you can now use PATCH method to change just one attribute from an object, leaving the other attributes for it untouched.
  • JerryMac_150114's avatar
    JerryMac_150114
    Historic F5 Account
    Thanks Robert for pointing this out. I started at it for sometime before realizing the example has nothing to do with modifying self-ip which is why I wound up here.
  • JerryMac I think you are looking for something along these lines: curl -k -u admin:admin https://172.29.86.62/mgmt/tm/net/self/ -H "Content-Type: application/json“ \ -X POST -d "{\"name\":\"internal_self2\",\"address\":\"10.81.60.2/8\",\"vlan\":\"internal\"}" {"kind":"tm:net:self:selfstate","name":"internal_self2","generation":0,"lastUpdatedMicros":0, "selfLink":"https://localhost/mgmt/tm/net/self/internal_self2","partition":"/Common/", "address":"10.81.60.2/8","floating":"disabled","inheritedTrafficGroup":"false", "trafficGroup":"traffic-group-local-only","unit":0,"vlan":"internal"} tmsh list net self internal_self2 net self internal_self2 { address 10.81.60.2/8 traffic-group traffic-group-local-only vlan internal } --- curl -k -u admin:admin https://172.29.86.62/mgmt/tm/net/self/internal_self2 \ -H "Content-Type: application/json" -X PUT -d "{\"allowService\":\"all\"}" {"kind":"tm:net:self:selfstate", "name":"internal_self2","generation":0, "lastUpdatedMicros":0, "selfLink":"https://localhost/mgmt/tm/net/self/internal_self2", "partition":"/Common/", "address":"10.81.60.2/8", "floating":"disabled", "inheritedTrafficGroup":"false", "trafficGroup":"traffic-group-local-only", "unit":0,"vlan":”internal"} tmsh list net self internal_self2 net self internal_self2 { address 10.81.60.2/8 allow-service all traffic-group traffic-group-local-only vlan internal }
  • JerryMac, sorry the comments interface killed my formatting. After the triple hyphen is the modify command, before is the create command.
  • Andrei_379458's avatar
    Andrei_379458
    Historic F5 Account

    just to address some of the comments above. "all-properties" will show all (including default) properties available, including "allowService" (which in the GUI is under SelfIPs->cw_test2->PortLockdown. Below command lists all properties:

    (tmos) list net self cw_test2 all-properties
    net self cw_test2 {
    address 10.1.10.123/24
    address-source from-user
    allow-service none
    app-service none
    description none
    floating disabled
    fw-enforced-policy none
    fw-staged-policy none
    inherited-traffic-group false
    partition Common
    service-policy none
    traffic-group traffic-group-local-only
    unit 0
    vlan external    
    `
    
    
    Below worked for me to modify the allowService property:
    

    curl -sku admin:admin https://192.168.168.65/mgmt/tm/net/self/cw_test2 -H "Content-Type: application/json" -X PATCH -d "{\"allowService\":\"all\"}" | jq

    or: 
    

    curl -sku admin:admin https://192.168.168.65/mgmt/tm/net/self/cw_test2 -H "Content-Type: application/json" -X PATCH -d '{"allowService":"all"}' | jq

    which was run on:
    
    `(tmos) show /sys version
    
    Sys::Version
    Main Package
      Product     BIG-IP
      Version     13.1.1.3
      Build       0.0.1
      Edition     Point Release 3
      Date        Wed Nov 28 18:50:45 PST 2018
    
    
    thanks