iControl REST Cookbook - Virtual Server Profile (LTM Virtual Profiles)

This cookbook lists selected ready-to-use iControl REST curl commands for virtual server profile related resources (the tmsh command

xxx ltm virtual <vs> profiles

not

xxx ltm profile

). Each recipe consists of the curl command, it's tmsh equivallent, and sample output (default hidden: toggle "Expand to see sample output" (may not work on some browsers)).

Please refer to iControl REST Cookbook - Virtual Server (ltm virtual) for the list of curl options.

Get the profiles of the virtual <vss>

list ltm virtual <vss> profiles 

curl -sku admin:admin https://<host>/mgmt/tm/ltm/virtual/<vss>/profiles

Expand to see sample output (may not work on some browsers)

{
    "items": [
        {
            "context": "all",
            "fullPath": "/Common/http",
            "generation": 405,
            "kind": "tm:ltm:virtual:profiles:profilesstate",
            "name": "http",
            "partition": "Common",
            "selfLink": "https://localhost/mgmt/tm/ltm/virtual/vss/profiles/~Common~http?ver=13.1.0"
        },
        {
            "context": "all",
            "fullPath": "/Common/tcp",
            "generation": 405,
            "kind": "tm:ltm:virtual:profiles:profilesstate",
            "name": "tcp",
            "partition": "Common",
            "selfLink": "https://localhost/mgmt/tm/ltm/virtual/vss/profiles/~Common~tcp?ver=13.1.0"
        }
    ],
    "kind": "tm:ltm:virtual:profiles:profilescollectionstate",
    "selfLink": "https://localhost/mgmt/tm/ltm/virtual/vss/profiles?ver=13.1.0"
}

Show only the specific profile <profile> of the virtual <vss>

list ltm virtual <vss> profiles { <profile> }

curl -sku admin:admin https://<host>/mgmt/tm/ltm/virtual/<vss>/profiles/<profile>

Expand to see sample output (may not work on some browsers)

{
    "context": "all",
    "fullPath": "http",
    "generation": 454,
    "kind": "tm:ltm:virtual:profiles:profilesstate",
    "name": "http",
    "selfLink": "https://localhost/mgmt/tm/ltm/virtual/vss/profiles/http?ver=13.1.0"
}

Add the profile <profile> to the virtual <vss>

modify ltm virtual <vss> profiles add { <profile> }

curl -sku admin:admin https://<host>/mgmt/tm/ltm/virtual/<vss>/profiles \
  -X POST -H "Content-Type: application/json" \
  -d '{"name":"<profile>"}'

Expand to see sample output (may not work on some browsers)

{
    "context": "clientside",
    "fullPath": "clientssl",
    "generation": 409,
    "kind": "tm:ltm:virtual:profiles:profilesstate",
    "name": "clientssl",
    "selfLink": "https://localhost/mgmt/tm/ltm/virtual/vss/profiles/clientssl?ver=13.1.0"
}

You will get an error if the specified profile is not compatible with the existing ones. For example, you cannot add

clientssl

to a virtual with

fastL4

(if you have created a virtual without explicitly specifying the profiles, it defaults to fastL4).

Expand to see sample output (may not work on some browsers)

{
  "code":400,
  "message":"01070734:3: Configuration error: Found disallowed profile on /Common/vss: Not Any Of (FastL4 Profile, FastHTTP Profile)",
  "errorStack":[],"apiError":3
}

Replace all the existing profiles of the virtual <vss>

Unlike the above, the endpoint is not

.../<vss>/profiles

but

.../<vss>. 

The method is PATCH because you are overwriting the existing components of the virtual. The data is nested deeply: Each profile is represented as an object {key:value, ...}; the profiles are stored in a list []; and the profiles list is the value for the key 'items' in the 'profilesReference'.

modify ltm virtual <vss> profiles replace-all-with { clientssl http }

curl -sku admin:admin https://<host>/mgmt/tm/ltm/virtual/<vss> \
  -X PATCH -H "Content-Type: application/json" \
  -d '{"profilesReference":{"items":[{"name":"clientssl"}, {"name":"http"}]}}'

Expand to see sample output (may not work on some browsers)

{
    "addressStatus": "yes",
    "autoLasthop": "default",
    "cmpEnabled": "yes",
    "connectionLimit": 0,
    "destination": "/Common/192.168.184.242:80",
    "enabled": true,
    "fullPath": "vss",
    "generation": 422,
    "gtmScore": 0,
    "ipProtocol": "tcp",
    "kind": "tm:ltm:virtual:virtualstate",
    "mask": "255.255.255.255",
    "mirror": "disabled",
    "mobileAppTunnel": "disabled",
    "name": "vss",
    "nat64": "disabled",
    "policiesReference": {
        "isSubcollection": true,
        "link": "https://localhost/mgmt/tm/ltm/virtual/~Common~vss/policies?ver=13.1.0"
    },
    "pool": "/Common/CentOS-all80",
    "poolReference": {
        "link": "https://localhost/mgmt/tm/ltm/pool/~Common~CentOS-all80?ver=13.1.0"
    },
    "profilesReference": {
        "isSubcollection": true,
        "link": "https://localhost/mgmt/tm/ltm/virtual/~Common~vss/profiles?ver=13.1.0"
    },
    "rateLimit": "disabled",
    "rateLimitDstMask": 0,
    "rateLimitMode": "object",
    "rateLimitSrcMask": 0,
    "selfLink": "https://localhost/mgmt/tm/ltm/virtual/vss?ver=13.1.0",
    "serviceDownImmediateAction": "none",
    "source": "0.0.0.0/0",
    "sourceAddressTranslation": {
        "type": "automap"
    },
    "sourcePort": "preserve",
    "synCookieStatus": "not-activated",
    "translateAddress": "enabled",
    "translatePort": "enabled",
    "vlansDisabled": true,
    "vsIndex": 44
}

You can add more fields to the request. e.g., context and partition.

{"name":"clientssl", "context":"clientside", "partition":"Common"}

Changing the protocol and profile of the virtual <vss>

To change either protocol or profile, you need to change both in one shot because some profiles are not compatible with some protocols (

ip-protocol

in tmsh; e.g., Any, TCP or UDP).

modify ltm virtual <vss> ip-protocol udp profiles replace-all-with { fastL4 }

curl -sku admin:admin https://<host>/mgmt/tm/ltm/virtual/<vss> \
  -X PATCH -H "Content-Type: application/json" \
  -d '{"ipProtocol":"udp", "profilesReference":{"items":[{"name":"fastL4"}]}}'

Expand to see sample output (may not work on some browsers)

{
    "addressStatus": "yes",
    "autoLasthop": "default",
    "cmpEnabled": "yes",
    "connectionLimit": 0,
    "destination": "/Common/192.168.184.242:80",
    "enabled": true,
    "fullPath": "vss",
    "generation": 448,
    "gtmScore": 0,
    "ipProtocol": "udp",
    "kind": "tm:ltm:virtual:virtualstate",
    "mask": "255.255.255.255",
    "mirror": "disabled",
    "mobileAppTunnel": "disabled",
    "name": "vss",
    "nat64": "disabled",
    "policiesReference": {
        "isSubcollection": true,
        "link": "https://localhost/mgmt/tm/ltm/virtual/~Common~vss/policies?ver=13.1.0"
    },
    "pool": "/Common/CentOS-all80",
    "poolReference": {
        "link": "https://localhost/mgmt/tm/ltm/pool/~Common~CentOS-all80?ver=13.1.0"
    },
    "profilesReference": {
        "isSubcollection": true,
        "link": "https://localhost/mgmt/tm/ltm/virtual/~Common~vss/profiles?ver=13.1.0"
    },
    "rateLimit": "disabled",
    "rateLimitDstMask": 0,
    "rateLimitMode": "object",
    "rateLimitSrcMask": 0,
    "selfLink": "https://localhost/mgmt/tm/ltm/virtual/vss?ver=13.1.0",
    "serviceDownImmediateAction": "none",
    "source": "0.0.0.0/0",
    "sourceAddressTranslation": {
        "type": "automap"
    },
    "sourcePort": "preserve",
    "synCookieStatus": "not-activated",
    "translateAddress": "enabled",
    "translatePort": "enabled",
    "vlansDisabled": true,
    "vsIndex": 44
}

Deleting the profile <profile> from the virtual <vss>

modify ltm virtual <vss> delete { <profile> }

curl -sku admin:admin https://<host>/mgmt/tm/ltm/virtual/<vss>/profiles/<profile> -X DELETE

Expand to see sample output (may not work on some browsers)

No output

Remove all the profiles from the virtual <vss>

There is no 'all' keyword in iControl REST. Use an empty object to indicate 'no data'. In this case, the profiles are represented as a list, so use the empty list [].

modify ltm virtual <vss> delete { all }

curl -sku admin:admin https://<host>/mgmt/tm/ltm/virtual/<vss> \
  -X PATCH -H "Content-Type: application/json" \
  -d '{"profiles":[]}}'

Note that the call will leave one profile because a virtual should have at least one profile.