F5 Programmability for Eclipse - Installation Instructions

It’s been a long time coming, but I’m pleased to announce a brand new editor for your iRules: F5 Programmability for Eclipse! This editor supports iRules & iRules LX in its initial release, but stay tuned for more features down the road. One of the cool features from my quick glance this afternoon is simultaneous multi-system support.

F5 Programmability for Eclipse

F5 Programmability for Eclipse version 1.0 allows you to use the Eclipse IDE to manage iRules and iRuleLX development. By using Eclipse, you can connect to one or more BIG-IP devices to view, modify or create iRules or iRuleLX workspaces. The editor functionality includes TCL/iRules and JavaScript language syntax highlighting, code completion, and hover documentation for the iRules API.

Note: This tool is provided via DevCentral as a free tool to help you better leverage iRules, and is in no way officially supported by F5 or F5 Professional Services. All support, questions, comments or otherwise for this editor should be submitted in the Q&A section of DevCentral. Please make sure to tag irules and/or iruleslx, as well as adding a custom editor tag.

System Requirements

The system requirements for the F5 Programmability for Eclipse are:

• Eclipse installed – Minimum version: Luna (v4.4) Recommended: Mars (v4.5) or Neon (v4.6)

• Java version 1.7 or later installed

• Network access to one or more F5 Networks BIG-IP systems (TMOS version 12.1+)

Verified Software Combinations

F5 Programmability for Eclipse, version 1.0, has been tested for compatibility with the following configurations:

Installation

To install the F5 Programmability for Eclipse plug-in,

1. Start the version of Eclipse that you installed.

2. Click on Help > Install New Software…

3. Verify that the Mars or Neon release URL is listed in the Works with drop down. If you are running the Luna version, or the release URL is not listed,

   • Click Add…

   • Type the text “http://download.eclipse.org/releases/mars” into the Location field (omit the quotation marks)

   • Click OK

4. Add a repository for the F5 plug-in

   • Click Add…

   • Type the text “http://cdn.f5.com/product/f5-eclipse/v1.0.0” into the Location field (omit the quotation marks)

   • Click OK

5. After you add the repository, F5 Networks or F5 Programmability for Eclipse should apppear in the Available Software dialog. Check the box next to the F5 item.

6. Check the Contact all update sites box and click Next

7. After you review the installation items, click Next.

8. Read the License Agreement, check I accept the terms of the license agreement, and click Finish

9. When prompted to restart Eclipse, click Yes

Common tasks

Select the F5 perspective

To use the F5 plug-in, you must activate the F5 perspective. In Eclipse,

1. Click on Window > Perspective > Open Perspective > Other…

2. Find and select the F5 perspective

3. Click OK

Connect to a BIG-IP system

In the F5 perspective you chose there are three views: Explorer pane on the left hand side, Editor pane on the right hand side, and a Log panel along the bottom. The Explorer pane includes a toolbar with 3 buttons. On the iRules & iRuleLX tab,

1. Click the New BIG-IP Connection toolbar button (at the top of the Explorer pane)

2. When prompted, provide the IP address and credentials for the BIG-IP system. You may store your credentials in a secure store. If you use the secure store, you must enter a master password for each session.

3. Click Finish

When you connect to a BIG-IP system, all LTM iRules, GTM iRules, and iRuleLX workspaces are loaded. The process may take a few seconds. When the process completes, you can expand the connection folder and subfolders. You can connect to multiple BIG-IP systems simultaneously. Note that folders exist for provisioned product modules on the BIG-IP system to which you connected. If you have not provisioned GTM or iRuleLX, no folder appears for that module.

Note: To access a Big-IP system remotely via Eclipse, the user account must have been assigned a role of administrator. Every Big-IP system includes a user with the name admin which has an administrator role. For creating additional users with an administrator role, refer to the BIG-IP guide for User Account Administration.

Change the BIG-IP partition

The default partition Common is loaded when you connect to a BIG-IP system. If you would like to use a different partition,

1. In the Explorer, select the BIG-IP Connection

2. Click either the Gears toolbar button, or use the context menu (right click) to open the Project Properties dialog.

3. Select a new partition

4. Click OK. Content will be loaded from the BIG-IP partition you selected.

Open an iRule or iRuleLX file to view or edit

1. Click Open in the context menu, or double-click on the file in the Explorer. The content is pulled from the BIG-IP and an edit tab is created. This step creates a file on the local filesystem.

Add or delete iRules, ILX workspaces, extensions, and files

1. Use the context menu (right click) for Add and Delete menu items. These items are available in folders that contain iRules and iRuleLX resources.

Saving an iRule or iRuleLX file

1. Use File > Save, the Save button on the toolbar, or type Ctrl-S. Any of these actions save the file locally and pushes the changes to the BIG-IP system.

Reloading an iRules or iRuleLX file

1. Each file has a Reload context menu selection. Click Reload to reload the edit buffer and sync the changes with the BIG-IP system.

Reloading all BIG-IP content

1. To reload all content from each connected BIG-IP system, click Reload All toolbar button in the Explorer. This action closes all open editors after prompting you to save any unsaved changes.

General information about iRule editing features

The editor used for editing iRules includes code completion and hover documentation for iRule commands and events. Consistent with the default Eclipse behavior, typing Ctrl-Space will check for available completion proposals for the current word being type. Also, completions will be invoked after adding a colon (“:”) to a word. This is handy for completions of namespaced iRule commands, e.g. TCP::. The same completion popup documentation can be seen by hovering over an iRule command or event.

The F5 plug-in does not include the man pages for the standard Tcl commands. To enable hover documentation for those standard Tcl commands, you can download the man pages and link them in to the Tcl and iRule editors. The manual pages can be downloaded from here: Tcl. Once uncompressed, the containing directory can be linked to Eclipse via the global preferences dialog (Window > Preferences for Linux and Windows, Eclipse > Preferences for MacOS). Under the Tcl > Man Pages section, click Configure…, then click Add. Specify a name of your choosing for the documentation set and add the file path to the local directory which contains the docs.

JavaScript editing

Opening a JavaScript file within an iRuleLX project will invoke a specific JavaScript editor (from the JSDT plug-in). This editor includes syntax highlighting, validation, completions, etc. The editing features can be configured via the global preferences dialog under the JavaScript section (Window > Preferences for Linux and Windows, Eclipse > Preferences for MacOS).

File editing

File types other than iRule or JavaScript will be opened with the editor identified by Eclipse to be appropriate. Depending on the file associations you have configured for your operating system, Eclipse may decide to open an external editor. To override this and choose the editor type of your own choosing, you can define a file association via the global preferences dialog under the General > Editors > File Associations section.

Known Issues

• ID 592459 F5 Perspective Dialogs do not include Help button content.
• ID 594055 The formatter page within the Project Properties dialog can cause an error: “The currently displayed page contains invalid values”. The Eclipse bug is tracked here: https://bugs.eclipse.org/bugs/show_bug.cgi?id=476261
• ID 594413 Code folding within an iRule ‘when’ block only works for contained comment blocks, not code blocks.
• ID 598035 iRule command completion does not work with Tcl execute statements. The workaround is to compose the statement outside the context of square brackets, then add the brackets later.
• ID 599573 Specific standard Tcl commands which are disabled for iRules (exit, exec, etc.) are highlighted/completed as if they are supported commands for iRules.
• ID 599574 A connection failure during a file Save operation leaves the file appearing that it’s saved (* decorator removed) when in fact it’s out of sync with the corresponding content on the Big-IP. If a file save is unsuccessful, the user should try to determine the cause of the failure: check the connection, status of the Big-IP, etc. Once that issue is resolved, re-initiating the file save, if successful, will then leave both copies of the file in sync. Until a successful save is accomplished the file on the local disk will be maintained, even if Eclipse is shutdown, so the edits aren’t lost, just not in sync.
• ID 600422 Eclipse running on Windows, will not escape a “\” line continuation character which may cause validation errors upon saving an iRule. The workaround is to avoid line continuations within iRules.