Plugin Functionality and Service Chaining

Using plugins is advantageous for your application because the plugin architecture allows your code to combine (or chain) services with a single service set without needing to reserve a PIC to implement each service.

Using plugins also saves you code because the framework handles many aspects of packet processing for you, such as keeping policies and actions in a context structure; for an example, see The IP Reassembler and Passthru Plugin. The plugin model also gives you access to the flow and session toolkit, with session CPU affinity. (For details, see Flow, Thread, and Session Affinities.)

Basic Plugin Functionality

A plugin has both a control component and a data component. The data component handles raw packets and flows, interacting with the service layer and the data cores. The control component interacts with the policy database, communicates with the Routing Engine, and performs any operations requiring access to functionality on the control cores.

A plugin registers with the system (specifically, with the services framework) with a unique name and an event handler to handle events delivered by the system. The system dispatches an init event to the control interface, and it is then up to your code to set up additional events or open client and server connections to the Routing Engine as needed.

Service Set Processing and the Policy Database

On the Multiservices PIC, the Junos mspmand process receives a service set resolution blob (SSRB), which contains all the information configured for the service set except for plugin-specific configuration. mspmand then creates the service set. The service set remains in the inactive state and waits for the plugins to install their policies.

Plugins can add policies in two ways:

mspmand must see that all services in a service set have policy databases that are initialized and ready before traffic flow begins. For the service set a plugin works with to be activated, all plugins must have attached their policy databases to the service set; otherwise, traffic could be dropped.

The policy database can ultimately be used as a configuration guide to act upon traffic.

On the Multiservices PIC, the control handler, which is invoked in the code that registers the plugin, creates a server to listen and attach to the policy database by calling the function msp_policy_db_attach(). The handler passes data received from the management component, such as reliable configuration download blobs (see Reliable Configuration Download). For sample code that performs these tasks, see Attaching to the Policy Database. The control component updates the policy database as the management component sends configuration updates; the database can handle a lazy delete scheme that does not impact existing sessions.

The relevent functions are declared in the file sandbox/src/Junos/include/jnx/multi-svcs/msvcs_plugin.h in your backing sandbox.

Once all plugins have installed their policies, the service set becomes ACTIVE. Your code can now call functions to interface with the session and flow layers for packet processing.

Plugin Setup and Configuration

You write the plugin code in the src/lib/ directory of your development sandbox. You also create an XML configuration file in the src/etc/ directory. The basic XML configuration includes the plugin package name, the plugin shared-object filename with full path on the PIC, and the name of the plugin entry function. Optional configurations include the order to load plugins and shared libraries (dependencies) and any Routing Engine directories to mount on the PIC.

mspmand determines the services operational mode (standalone or plugin) by looking for a plugin configuration file (*.xml) once a package is downloaded to the Multiservices PIC.

For a detailed walkthrough of plugin configuration and development, see Writing a Plugin.

Plugin Initialization

Once mspmand has loaded the plugin as a shared object, it invokes the entry function specified in the plugin configuration file. The entry function runs in the context of the mspmand main process (internal user thread). The function registers the plugin name, control and data handlers, and so forth, and retrieves a plugin ID assigned by mspmand.

Plugin Event Handlers

The entry function that the system calls when the plugin loads registers event handlers. Plugins can handle control, data, and user-class events, as well as public requests for data. mspmand receives packets from the FIFO queue and dispatches them to all plugins' data handlers sequentially as a data event. User-class events must be published in the entry function.

The control handler is invoked when there is a control event coming to the plugin. Available system control events for external plugin are as follows:

The data handler is invoked when there is a data event coming to the plugin. This handler receives all system data events and subscribed events. Available system data events are as follows:

	MSVCS_DATA_EV_SM_INIT
	MSVCS_DATA_EV_INIT
	MSVCS_DATA_EV_FIRST_PKT_PROC
	MSVCS_DATA_EV_PKT_PROC
	MSVCS_DATA_EV_SESSION_OPEN
	MSVCS_DATA_EV_SESSION_CLOSE
	MSVCS_DATA_EV_SESSION_DESTROY
	MSVCS_DATA_EV_REQ_PUB_DATA

The data handler also handles user-class events.

Plugin Tasks

Typical tasks performed by plugins include the following:

Plugins can also operate on a per-packet level, without using sessions. For example, a simple COS plugin that needs to set the TOS bits on IP headers and obtain some per-service-set statistics might not need sessions.

Plugins should be made as independent as possible. Each one should perform a rule match on its own packet processing function, independent of other plugins, and save its state independently.

Service Chaining

Using plugins, you can chain multiple Junos or external services within one service set. Junos services and your own (external) services can be mixed. When external services are present, you must specify a service order, and you can have no more than two external services.

To use multiple services in one service set, the data component of the application on the Multiservices PIC is implemented as a plugin. That is, the data component is a shared object or library instead of a daemon. The Junos mspmand process runs on the PIC and loads all the services’ data components as plugins. The control component can be started on a new thread by mspmand or can be created as a separate daemon (or both). mspmand runs many data threads, each with its own chain. Only one packet at a time is processed in a given chain.

You configure the service chain using the service-order object:

service-set svc-set1 {
    extension-service newservice1 {
        new-service1-rules rule;
    }
    extension-service newservice2 {
        new-service2-rules rule;
    }
    service-order {
        forward-flow [newservice1 newservice2];
        reverse-flow [newservice2 newservice1];
    }
}

The system delivers service order information to the management component in the SSRB (see Service Set Processing Overview for an introduction to the SSRB).

Data Flow

When mspmand receives a packet that does not match a session that the plugin has seen, it assumes that this is the first packet of a new session and dispatches the packet to the data handler as the event MSVCS_DATA_EV_FIRST_PKT_PROC. The data handler must then look up the appropriate policy for the packet (service set) by calling functions in the libmsp-svcs library. The data handler code looks for the rule that applies to the session started by this packet, creates an action, and attaches the action to the session context using functions in src/Junos/include/jnx/multi-svcs.

For packets other than the first packet, the system delivers the session context automatically, retrieves the action from the session context, and applies the action(s) to the packets. The data handler does not need to walk through the policy database, so processing is expedited.

After the data handler processes a packet, the plugin can use one of the following return states:

Session Open and Close Events

The system dispatches a session-open event after the first packet has traversed and been accepted by all plugins. The session-close event is dispatched when the session is closed or if the open failed. Unestablished TCP or UDP sessions close after a 30-second timeout; established TCP sessions close after a one-hour timeout, plugin restart, or termination. The optional session-destroy event can be used to clean up local resources allocated for the current session context; this event indicates that the session is no longer in use by any services in the entire chain.

Public Data Request Event

A plugin can request “public” data from another plugin. The data handler receiving the event is running on the processor of the requestor’s thread. The handler code can pass a request type and parameters without making a copy; the receiver passes back the data and a return code.

Sample Plugin Code

See the following topics for sample code that uses plugins:


© 2007-2009 Juniper Networks, Inc. All rights reserved. The information contained herein is confidential information of Juniper Networks, Inc., and may not be used, disclosed, distributed, modified, or copied without the prior written consent of Juniper Networks, Inc. in an express license. This information is subject to change by Juniper Networks, Inc. Juniper Networks, the Juniper Networks logo, and JUNOS are registered trademarks of Juniper Networks, Inc. in the United States and other countries. All other trademarks, service marks, registered trademarks, or registered service marks are the property of their respective owners.
Generated on Sun May 30 20:26:47 2010 for Juniper Networks Partner Solution Development Platform JUNOS SDK 10.2R1 by Doxygen 1.4.5