Creating iRules LX via iControl REST

Introduction

iRules LX is a BIG-IP programmability feature introduced in 12.1.0 [1, 2]. It allows you to extend the BIG-IP functionalities by attaching custom scripts to virual servers. For example, character code conversion (say, EBCDIC to ASCII), intelligent logging, or user information query from a backend database server. Sounds familiar? Yes, it is in essence a new generation of the good old iRules [3]. The major difference is that, while iRules use TCL, iRules LX uses Node.js and TCL (in the RPC mode). Please read "Getting Started Guide" [1] to learn more and experience.

To configure iRules LX, you need to follow these steps:

1. Create a workspace ... A placeholder for the custom codes. Let's say the name of the workspace is Test in the examples.
2. Create an extension ... The Node.js codes are collectively called an extension and it processes the traffic. Our example name is TestExt.
3. Create iRule codes ... The TCL codes that will be attached to a virtual (just like iRules). The example name is TestRule.
4. Create the plugin ... A set of production codes generated from the workspace. It will be run on the Node.js engine(s). TestPlugin.
5. Attach the plugin to a virtual ... Just like iRules. The virtual name is vs here.

Creating iRules LX using tmsh

The Configuration Utility (GUI) provides an easy-to-use mechanism to achieve the above confuguration steps: They can also be done via tmsh.

1. tmsh create ilx workspace Test
2. tmsh create ilx workspace Test extension TestExt
3. tmsh create ilx workspace Test rule TestRule
4. tmsh create ilx plugin TestPlugin from-workspace Test
5. tmsh modify ltm virtual vs rules { TestPlugin/TestRule }

 

Steps 2 and 3 require you to edit the codes manually using vi. If you do not edit and quit immediately, they are populated with the template codes.

Creating iRules LX using iControl REST

With iControl REST [4, 5], you can do the configuration remotely, however, the procedure is not exactly the same. Because Steps 2 and 3 require editing and iControl REST is not designed for interactive human operations, we need to edit the code files locally and transfer them to the appropriate locations on the BIG-IP box. Other steps are straight forwards.

The examples below uses curl. You usually specify -s (suppress progress bar), -k (permit insecure HTTPS) and -u (user name and password: e.g., admin:pass). They ("-sku admin:pass") are omitted here.

1. curl https://<host>/mgmt/tm/ilx/workspace \
     -X POST -H "Content-type: application/json" \
     -d '{"name":"Test"}'
2. curl https://<host>/mgmt/tm/ilx/workspace?options=extension,TestExt \
     -X POST -H "Content-type: application/json" \
     -d '{"name":"Test"}'
3. curl https://<host>/mgmt/tm/ilx/workspace?options=rule,TestRule \
     -X POST -H "Content-type: application/json" \
     -d '{"name":"Test"}'
4. curl https://<host>/mgmt/tm/ilx/plugin \
     -X POST -H "Content-type:application/json" \
     -d '{"name":"TestPlugin", "fromWorkspace":"/Common/Test"}' \
5. curl https://<host>/mgmt/tm/ltm/virtual/vs \
     -X PATCH -H "Content-type:application/json" \
     -d '{"rules":[ "/Common/TestPlugin/TestRule" ] }'

Before moving on to Step 4, you need to write runnable rule/extension files.

Updating the rule/extension files - File transfer

Steps 2 and 3 create the template files for extension and rule respectively because they run as if vi was terminated without editing. You need to overwrite the files by transferring your local files. The DevCentral article "Demystifying iControl REST Part 5: Transferring Files" [6] discusses two methods to upload a file: Here I chose the /mgmt/shared/file-transfer/uploads/ endpoint.

First, create the rule and extension files locally. Then, upload the files one by one. The example below uploads the local LocalExt.js file (extension) and save it as /var/config/rest/downloads/LocalExt.

curl https://<host>/mgmt/shared/file-transfer/uploads/LocalExt \
  -X POST -H "Content-type: application/octet-stream" \
  -H "Content-range: 0-181/182" --data-binary @LocalExt.js

Do the same for the rule file. Note that you need to know the size of the file (here 182 bytes) before executing.

The template extension/rule files are already created in the workspace. The next step is to overwrite the template files by the uploaded files. The template files are stored in here.

• Extension: /var/ilx/workspaces/Common/Test/extensions/TestExt/index.js
• Rule: /var/ilx/workspaces/Common/Test/rules/TestRule.tcl

Note that the extension file name is always index.js (if there is only one Node.js file) under the extension directory (extensions/TestExt here). Also the file extension .tcl is automatically appended to the rule name (TestRule) and the file is stored under Rule directory (rules).

To overwrite these files, you can run cat command through the /mgmt/tm/util/bash endpoint. For example, to overwrite the rule file, run the following curl command:

curl https://<host>/mgmt/tm/util/bash \
  -X POST -H "Content-type: application/json" \
  -d "{\"command\":\"run\", \
  \"utilCmdArgs\":\"-c \\\"cat /var/config/rest/downloads/ruleCode >/var/ilx/workspaces/Common/Test/rules/TestRule.tcl\\\"\"}"

Be careful with the nested escaping (e.g., triple backslash plus double quote) is interpretted as \" on the wire, and interpretted as " when handed over to the bash that executes this command).

Do the same for the extension code, and go back to Step 4 and 5 to create the plugin and to attach the plugin rule to a virtual.

Summary

You can create and configure iRules LX objects completeley remotely in 5 steps (plus 2 additional steps for file transfers for each file) using iControl REST. Yes, it is a bit laborius because rule/extension file editing is involved in the process. If your only desire is to copy the existing workspace (with rules and extensions) to another platform, then you should consider using the iRules LX archive file.

References

[1] Getting Started with iRules LX

[2] BIG-IP iRulesLX User Guide, Version 13.0.0, DevCentral (PDF document)

[3] Getting Started with iRules,

[4] iControl REST Home, @Clouddocs.f5.com

[5] iControl REST User Guide Version 13.1 (PDF document)

[6] Demystifying iControl REST Part 5: Transferring Files