How to: Create and manage iRules on BIG-IP Next Central Manager

The following topics describe how to create, edit, or delete iRules using BIG-IP Next Central Manager.

The iRules are created using the programming language Tcl. To create or edit an iRule you need to have familiarity with Tcl and iRule commands.

For more information about iRule structure, uses, and traffic management customizations, see F5 iRule documentation.

You can use iRule versioning to test changes to an iRule and see if they meet the requirements of an application. If the changes do not meet the requirements, you can revert to an earlier version of the iRule.

Create an iRule

Create an iRule using the UI or API. Once you create an iRule, you can add it to one of your applications, or create a new application using an iRule application template.

See Example iRules provided in BIG-IP Next Central Manager.

Create an iRule

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. At the top of the screen, click Create.

  4. Type a Name for the iRule, and add an optional Description.

  5. Click on line 1 of the editor in the panel to start creating the iRule. The following is an example procedure for a simple iRule:

    Note: The UI includes inline syntax validation. The editor provides a list of allowed Tcl/iRule syntax as you add to the schema With any list-selected input, you can hover over the schema element to view details and use case examples for that selection. See a sample iRule procedure in the GIF below.

    1. Begin typing the iRule function and select from the provided list.

    2. Press the SPACE bar to view a list of all valid events. You can type key words to filter the event list.

    3. Enter the conditions and commands. The editor will auto-populate commands according to the iRule syntax.

  6. To copy the iRule click the copy button image to the top right of the editor.

  7. Click Save.

    The new iRule is added to the iRules list. To deploy iRules to a secure FAST application, see How to: Deploy iRules to an application on BIG-IP Next Central Manager.

Sample iRule in editor

Sample iRule creation

Create an iRule

Use the following procedure to create a new iRule.

  1. Send a POST request to create a new iRule.
    POST https://{{bigip_next_cm_mgmt_ip}}/api/v1/spaces/default/irules

  2. The body of the POST must include the following data, substituting appropriate values as required:

    • name: {{irule_name}}

    • content: iRule schema in Tcl, following is an example:

      # This is an example of an iRule that routes traffic to a page that shows some information about the client.
when HTTP_REQUEST {
   if { [HTTP::uri] eq "/example-client-info"} {
      set content "<!doctype html>\n<head lang=\"en\">\n<meta charset=\"utf-8\">\n<title>Example Client Info</title>\n</head>\n<body>\n  <h3>Example Client Info</h3>\n    <ul>\n      <li> Virtual server address: [IP::local_addr] </li>\n      <li> Client IP:port: [IP::client_addr]:[TCP::client_port]</li>\n    </ul>\n</body>\n</html>"
      HTTP::respond 200 content $content
   }
}

    • description: Optional - Additional information about the iRule.

    • staged: false

Clone an iRule

Clone an iRule to work with an existing iRules contents, without creating a new iRule from scratch using the BIG-IP Next Central Manager UI.

Clone an iRule

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu. A list of iRules displays.

  3. Select the checkbox next to the iRule name and click Clone.

  4. The Clone iRule panel opens. Name is automatically populated with original iRule’s name and the prefix clone.

  5. (Optional) Update the Name and add a Description.

  6. The editor contains the iRule script from the original iRule. Make necessary changes to the cloned iRule.

  7. Click Save.
    The cloned iRule is added to the iRules list.

Edit an iRule

To edit an iRule, you must stage an iRule version. Use the following procedures to make changes to an iRule, changes automatically creates a new iRule version. You can only stage one version of an iRule at a time.

Stage an iRule version

Create a stage version of a previously created iRule

Note: Each user login can create only 1 staged version per iRule. If multiple users can log in to your BIG-IP Next Central Manager environment, you may see more that one staged version. You can only edit staged iRules with your login version.

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. Click the iRule name.
    A panel for the iRule’s properties and content editor is displayed.

  4. Click the dropdown to the right of the iRule name at the top of the panel and select the version.

  5. Click the dropdown again and select Stage from this version. New staged version of the iRule is created.

    Note: In an iRule, you can only stage one version at a time.

    The iRule version is staged and available to make changes. To create a new version of iRule from staged version commit the changes, refer Create a new version of iRule from staged version

Deploy a staged iRule version

Use this procedure to deploy a staged iRule version. Ensure that at least one application is attached to the iRule.

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. Click the iRule name. A panel for the iRule’s properties and content editor is displayed.

  4. Click the dropdown to the right of the iRule name at the top of the panel and select the staged version.

  5. Click iRule under Configuration and verify the iRule content in the editor.

  6. Click Deploy Changes to deploy the staged version without creating a new iRules version.

Convert the staged version of an iRule to a new version

Note: Each user login can create only 1 staged version per iRule. If multiple users can log in to your BIG-IP Next Central Manager environment, you may see more that one staged version. You can only edit staged iRules with your login version.

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. Click the iRule name.
    A panel for the iRule’s properties and content editor is displayed.

  4. Click the dropdown to the right of the iRule name at the top of the panel and select the staged version.

  5. Click iRule under Configuration and verify the iRule content in the editor.

  6. Click Commit Changes. A pop-up displays with following options, select the appropriate option and click Yes, Commit.

    • Commit staged version and include all attached applications.

    • Commit and attach all applications that have any version of this iRule.

    • Commit without any attached applications.

    A new version of iRule is created.

    Note: You can revert a staged iRule version. After the staged version is committed and a new iRule version is created you cannot delete the new version, you can only delete the complete iRule.

Revert a staged version of an iRule

Use this procedure to revert or delete a staged version of an iRule. The applications using the staged version will revert to using their previous version of the same iRule. If any application does not have previous version of iRule, then staged version will not be deleted and the application will continue to use the staged version.

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. Click the iRule name. A panel for the iRule’s properties and content editor is displayed.

  4. Click the dropdown to the right of the iRule name at the top of the panel and select the staged version.

  5. Click Revert. A pop-up displays for confirmation, click Yes, Continue.
    The iRule staged version is deleted.

Create a stage version of a previously created iRule

Use the following procedure to create a staged version of an iRule.

  1. Send a POST request to create a stage version of an iRule.

    POST https://{{CM_IP}}/api/v1/spaces/default/irules

    The body of the POST must include the following data, substituting appropriate values as required:

    • name: {{irule_name}}

    • content: iRule schema in Tcl, following is an example:

      # This is an example of an iRule that routes traffic to a page that shows some information about the client.
when HTTP_REQUEST {
   if { [HTTP::uri] eq "/example-client-info"} {
      set content "<!doctype html>\n<head lang=\"en\">\n<meta charset=\"utf-8\">\n<title>Example Client Info</title>\n</head>\n<body>\n  <h3>Example Client Info</h3>\n    <ul>\n      <li> Virtual server address: [IP::local_addr] </li>\n      <li> Client IP:port: [IP::client_addr]:[TCP::client_port]</li>\n    </ul>\n</body>\n</html>"
      HTTP::respond 401 content $content
   }
}

    • description: This is a new staged version from the previously created iRule.

    • staged: true

    • staged_version: 1

    • new_version: true

  2. Send a GET request to receive the contents of a staged version of the iRule.

    GET https://{{CM_IP}}/api/v1/spaces/default/irules/{{irule_name}}/version/staged/content?filter=modified_by eq '{{user_id}}'

  3. Send a POST request to edit contents of a staged version of the iRule.

    POST https://{{CM_IP}}/api/v1/spaces/default/irules

    The body of the POST must include the following data, substituting appropriate values as required:

    • name: {{irule_name}}

    • content: iRule schema in Tcl, following is an example:

      # This is an example of an iRule that routes traffic to a page that shows some information about the client.
when HTTP_REQUEST {
   if { [HTTP::uri] eq "/example-client-info"} {
      set content "<!doctype html>\n<head lang=\"en\">\n<meta charset=\"utf-8\">\n<title>Example Client Info</title>\n</head>\n<body>\n  <h3>Example Client Info</h3>\n    <ul>\n      <li> Virtual server address: [IP::local_addr] </li>\n      <li> Client IP:port: [IP::client_addr]:[TCP::client_port]</li>\n    </ul>\n</body>\n</html>"
      HTTP::respond 403 content $content
   }
}

    • description: This is a new staged version from the previously created iRule.

    • staged: true

    • staged_version: 1

    • new_version: true

Commit applications of a staged iRule to the newer iRule version specified

Use the following procedure to commit applications of a staged iRule to a newer iRule version.

  1. Send a POST request using the iRule.

    POST https://{{CM_IP}}/api/v1/spaces/default/irules/tasks

  2. The body of the POST must include the following data, substituting appropriate values as required:

    • name: {{irule_name}}

    • irule_version:2

    • staged: false

    • user_id: {{user_id}}

    • attach_applications: STAGED

    • request_type: COMMIT

Convert the staged version of an iRule to a new version

Use the following procedure to create a staged version of an iRule.

  1. Send a POST request using the iRule.

    POST https://{{CM_IP}}/api/v1/spaces/default/irules

  2. The body of the POST must include the following data, substituting appropriate values as required:

    • name: {{irule_name}}

    • content: iRule schema in Tcl, following is an example:

      # This is an example of an iRule that routes traffic to a page that shows some information about the client.
when HTTP_REQUEST {
   if { [HTTP::uri] eq "/example-client-info"} {
      set content "<!doctype html>\n<head lang=\"en\">\n<meta charset=\"utf-8\">\n<title>Example Client Info</title>\n</head>\n<body>\n  <h3>Example Client Info</h3>\n    <ul>\n      <li> Virtual server address: [IP::local_addr] </li>\n      <li> Client IP:port: [IP::client_addr]:[TCP::client_port]</li>\n    </ul>\n</body>\n</html>"
      HTTP::respond 403 content $content
   }
}

    • new_version: true

    • staged_version: 1

    • staged: false

Commit all applications from all versions of the iRule to a newer iRule version

Use the following procedure to commit all applications from all versions of the iRule to a newer iRule version.

  1. Send a POST request using the iRule.

    POST https://{{CM_IP}}/api/v1/spaces/default/irules/tasks

  2. The body of the POST must include the following data, substituting appropriate values as required:

    • name: {{irule_name}}

    • irule_version:2

    • staged: false

    • user_id: {{user_id}}

    • attach_applications: ALL

    • request_type: COMMIT

Revert a staged version of an iRule

Use the following procedure to revert a staged version of an iRule.

  1. Send a POST request using the iRule.

    POST https://{{CM_IP}}/api/v1/spaces/default/irules/tasks

  2. The body of the POST must include the following data, substituting appropriate values as required:

    • irule_name: {{irule_name}}

    • irule_version:1

    • staged: true

    • user_id: {{user_id}}

    • request_type: REVERT

Attach or detach an iRule version

Note: Attach or detach of application to an iRule version is only applicable to FAST applications, it is not supported for AS3 applications. For AS3 applications, directly edit AS3 declaration with new iRule version in the application settings and redeploy the application.

Attach applications to a version of an iRule

An iRule version lists all the applications to which it has been added, see Add iRules to an application. For example, if iRule version v1 is added to an application, then in the iRules space, the application will be listed only under that specific version (v1) of the iRule. Use this procedure to attach applications to a different versions of the same iRule.

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. Click the iRule name.
    A panel for the iRule’s properties and content editor is displayed.

  4. Click the dropdown menu to the right of the iRule name at the top of the panel and select the version to which an application must be attached.

  5. In the Attached Applications section:

    • If no application is attached, click Attach Applications.

    • If there are existing applications listed, click Attach to access other available applications. Click the checkbox next to the application and click Attach.

  6. Click Deploy Changes. A confirmation pop-up displays, click Yes to proceed.

Detach applications from a version of an iRule

An iRule version lists all the applications to which it has been added, see Add iRules to an application. Use this procedure to detach applications from a versions of the iRule.

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. Click the iRule name.
    A panel for the iRule’s properties and content editor is displayed.

  4. Click the dropdown menu to the right of the iRule name at the top of the panel and select the version to which an application must be detached.

  5. In the Attached Applications section, select the checkbox next to the application and click Detach. The applications will be reattached to the version given in Previous iRule Version column. If the Previous iRule Version is empty, then the Detach is disabled.

  6. Click Deploy Changes. A confirmation pop-up displays, click Yes to proceed.

Attach applications to a version of an iRule

Use the following procedure to attach applications to a version of an iRule.

  1. Send a POST request using the iRule.

    POST https://{{CM_IP}}/api/v1/spaces/default/irules/tasks

  2. The body of the POST must include the following data, substituting appropriate values as required:

    • name: {{irule_name}}

    • irule_version:1

    • staged: false

    • user_id: {{user_id}}

    • aplication_ids_to_attach: []string{application_ids..}

    • request_type: DEPLOY

Detach applications from a version of an iRule

Use the following procedure to attach applications to a version of an iRule.

  1. Send a POST request using the iRule.

    POST https://{{CM_IP}}/api/v1/spaces/default/irules/tasks

  2. The body of the POST must include the following data, substituting appropriate values as required:

    • name: {{irule_name}}

    • irule_version:1

    • staged: false

    • user_id: {{user_id}}

    • aplication_ids_to_detach: []string{application_ids..}

    • request_type: DEPLOY

Delete an iRule

You can remove an iRule. Ensure that you have removed the iRule from any attached applications. You can only delete one iRule at a time.

Delete an iRule–UI

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. Click checkbox next to the iRule name.

  4. Click Delete.
    The iRule is deleted from the iRules list.

Delete an iRule

Use the following procedure to delete an iRule.

  1. Send a GET request to retrieve all iRules names.

    GET https://{{CM_IP}}/api/v1/spaces/default/irules

  2. Record the name of the iRule that you want delete.

  3. Send a DELETE request using the iRule.

    DELETE https://{{CM_IP}}/api/v1/spaces/default/irules/{{irule_name}}

Compare iRules

You can compare two different versions of the same iRule or compare versions of two different iRules.

See version history of an iRule and compare versions

Use this procedure to see all versions of an iRule and compare two different versions of the iRule.

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. Click the iRule name. A panel for the iRule’s properties and content editor is displayed.

  4. Click the dropdown to the right of the iRule name at the top of the panel and select Show version history. A new panel displays with a list of iRule versions.

  5. Select the check box next to the versions and click Compare.
    The editor highlights differences between the two selected iRule versions.

Compare iRule content of two different iRules

Use this procedure to compare versions of two different iRules and decide whether to edit or attach/detach applications.

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click iRules from the left menu.

  3. Click the iRule name. A panel for the iRule’s properties and content editor is displayed.

  4. Click iRule from the panel menu.

  5. Select Compare (Diff) from Mode.

  6. From Compare to iRule select an iRule, and select a Version to compare.

    The editor highlights differences between the two selected iRules.

Deploy an iRule

Add iRules to an application

Use this procedure to add iRules to an application. An iRule can be added to multiple applications. In the Applications > iRules space, an iRule lists all the applications to which it has been added.

  1. Click the Workspace icon next to the F5 icon, and click Applications.

  2. Click My Application Services from the left menu.

  3. Click the application name. A panel displays with the application details.

  4. Click the Edit icon at the top of the panel.

  5. In the Virtual Servers section, click the Edit icon under iRules. The iRules panel displays.

  6. Enable the Use iRules.

  7. Click Add. A panel displays with list of available iRules. To create a new iRule or clone an existing iRule, refer Create an iRule or Clone an iRule.

  8. Select the check box next to the iRules you want to attach to the application.

  9. Click Add.

  10. Verify the selected iRules, change the versions of the iRule as required.

  11. Select the check box next to the iRule and use the up or down arrow to change the priority order. The iRules are executed in the listed order, the first iRule in the list is executed first.

  12. lick Save.

  13. Click Review & Deploy.

  14. Verify the details in the Summary section and click Validate All.

  15. Click Deploy Changes. A pop-up displays for confirmation, click Yes, Deploy.