API Reference¶

f5-nodejs¶

This Node.js module is used to access the iRules LX features of BIG-IP. Use it to program the high-performance BIG-IP datapath from Node.js.

Introduction¶

iRules LX has two ways it can be used. The first method, introduced in BIG-IP TMOS 12.1.0, is via RPC where TCL is used to make a call to the Node.js process(es). The second method, introduced in BIG-IP TMOS 13.0.0, is via “streaming” where all data (by default) is sent over to the Node.js process(es).

iRules LX RPC¶

In iRules LX data can be sent to Node.js via RPC in iRules TCL. The following example shows the iRules TCL RPC over to Node.js as a simple echo server -

 when HTTP_REQUEST {
    set rpc_handle [ILX::init my_plugin my_extension]

    if { [HTTP::uri] eq "/echo" } {
        # returns "Hello World"
        set ilx_call [ILX::call $rpc_handle "echo" "Hello" "World"]
        HTTP::respond 200 content "$ilx_call\n"
    }
}

There is a 65K limit to the amount of data that can be sent via the

ILX::call

command. For more information on how to use the iRules TCL code for RPC operation, please see the ILX iRules command reference on DevCentral.

The following example shows the Node.js code that returns request parameters back in the response.

 var f5 = require('f5-nodejs');
var ilx = new f5.ILXServer();

ilx.addMethod('echo', function(req, res) {
    res.reply(req.params());
});

ilx.listen();

For more information about how to implement the Node.js API for RPC operation, please start with the ILXServer class.

iRules LX Streaming¶

With iRules LX streaming, all data by default is sent to the Node.js “plugin” and makes use of the Node.js streaming APIs so that there is not a 65K limit. Data is accessed via the F5 provided iRules LX streaming API and there is no need for TCL. If you desire, you can configure the plugin to receive only certain data streams and/or connection information so they stay in TMM (bypassing Node.js) to increase performance.

These are a few examples of when you might certain items to bypass Node.js -

Use Case: You only need to know source IP on a L4 virtual server to block a banned client.
- Plugin Settings: Server and client data streams can bypass Node.js.
Use Case: You need to make load balancing decisions based on client HTTP request headers.
- Plugin Settings: Server data stream, client data stream, and server HTTP response information can bypass Node.js.
Use Case: You need to receive binary data for a custom protocol implementation and parse it to determine if the client can connect to a pool member.
- Plugin Settings: The server data stream can bypass Node.js. The client can be prevented from connecting to the server until the check is performed.

Here are a few examples -

 // Block client whose IP is in data group on L4 virtual server
var f5 = require('f5-nodejs');
var plugin = new f5.ILXPlugin();

// Fetch the data group entries after plugin connects to TMM
var dg = {};
plugin.on('initialized', function () {
  dg = plugin.getDataGroup('/Common/some_dg');
})

plugin.on('connect', function(flow) {
  // Block the bad guy's IP
  if (dg.lookup(flow.client.remoteAddress)) {
    console.log('Blocked conflow from IP "' + flow.client.remoteAddress + '".');
    return flow.end();
  }
  flow.client.allow();
});

var options = new f5.ILXPluginOptions();
options.handleServerData = false;
options.handleClientData = false;
options.handleClientOpen = true;
plugin.start(options);

 // URI path based pool selection
var f5 = require('f5-nodejs');
var plugin = new f5.ILXPlugin();

plugin.on('connect', function(flow) {
  flow.client.on('requestComplete', function(request) {
    var otherPoolMatch = '/images/';
    // If path starts with "/images/"
    if (request.params.uri.slice(0, otherPoolMatch.length) === otherPoolMatch) {
      var options = new f5.ILXLbOptions();
      options.pool = '/Common/other_pool';
      flow.lbSelect(options);
    }
    flow.client.allow();
    request.complete();
  });

  flow.client.on('error', function(errorText) {
    console.log('client error event: ' + errorText);
  });
  flow.server.on('error', function(errorText) {
    console.log('server error event: ' + errorText);
  });
  flow.on('error', function(errorText) {
    console.log('flow error event: ' + errorText);
  });
});

var options = new f5.ILXPluginOptions();
options.handleServerData = false;
options.handleServerResponse = false;
options.handleClientData = false;
options.handleClientOpen = true;
plugin.start(options);

 // Hexdump all client data to stdout on L4 virtual server
var f5 = require('f5-nodejs');
var plugin = new f5.ILXPlugin();
var hexy = require('hexy');

plugin.on('connect', function(flow) {
  flow.client.on('data', function (data) {
    console.log(hexy.hexy(data));
    flow.server.write(data);
  })

  flow.client.on('error', function(errorText) {
    console.log('client error event: ' + errorText);
  });
  flow.server.on('error', function(errorText) {
    console.log('server error event: ' + errorText);
  });
  flow.on('error', function(errorText) {
    console.log('flow error event: ' + errorText);
  });
});

var options = new f5.ILXPluginOptions();
options.handleServerData = false;
plugin.start(options);

You can also use the iRules LX streaming as a web server as shown in this example -

 // As simple HTTP server
var f5 = require('f5-nodejs');
function httpRequest(req, res) {
  res.end("got it: " + req.method + " " + req.url + "\n", "ascii");
}
var plugin = new f5.ILXPlugin();
plugin.startHttpServer(httpRequest);

Because the ILXPlugin.startHttpServer method sends the standard

req

and

res

objects to the callback function, you can use almost any module based on Node.js http.Server. Here is an example with the popular Express web framework -

 // With Express.js
var f5 = require('f5-nodejs');
var express = require('express');
var app = express();

app.get('/', function (req, res) {
  res.status(200).send('<html><h1>Hello from express.</h1></html>');
});

var plugin = new f5.ILXPlugin();
plugin.startHttpServer(app);

For information about how to implement the Node.js API for streaming operation, please start with the ILXPlugin class.

License¶

No part of this software may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without express written permission of F5 Networks, Inc.

The BIG-IP API Reference documentation contains community-contributed content. F5 does not monitor or control community code contributions. We make no guarantees or warranties regarding the available code, and it may contain errors, defects, bugs, inaccuracies, or security vulnerabilities. Your access to and use of any code available in the BIG-IP API reference guides is solely at your own risk.

Previous Next