Command Line access to IPC interfaces

• Home
• Introduction
• Getting information about interfaces and plug-ins
• Invoking interface functions
• Parameters serialization
• Custom interfaces support
• Restrictions

Introduction

 

Agent SDK and the Agent itself offers a possibility to debug and test behavior of IPC plug-ins without a need to write any extra code. This is achieved by allowing invocation of IPC interface functions through a command line interface provided by the aex-helper tool.

 

The functionality is available in the core Agent installation, so it may be used for debugging in customers' environments. The feature is available only for root users and only if the debugging mode is enabled. To enable debugging mode, run (assuming the bash shell):

 

root@computer# export AEX_DEV_MODE=1

 

After the AEX_DEV_MODE variable is set, aex-helper starts providing some additional advanced functionality, which is meant solely for development and debugging purposes. No customer support is available for this feature.

 

One of the features now available to you is the possibility to call interface functions and pass their parameters through command line. The return values and output parameters are printed to the standard output.

Getting information about interfaces and plug-ins

 

In the debugging mode, aex-helper would provide users with information about interfaces that support invocation through command line. The list of interfaces may be obtained using the agent's comminfo sub-command:

 

root@computer# aex-helper agent comminfo
AgentSDK::Interfaces::IAeXClientScheduleTaskHandler
AgentSDK::Interfaces::IAeXClientScheduler
AgentSDK::Interfaces::IAeXClientTransport
AgentSDK::Interfaces::IAeXMachineID
AgentSDK::Interfaces::IAeXMaintenanceWindows
AgentSDK::Interfaces::IAeXNSManager
AgentSDK::Interfaces::IAeXNTracker
AgentSDK::Interfaces::IAeXNetworkManager
AgentSDK::Interfaces::IAeXNfySvrClientAgent
AgentSDK::Interfaces::IAeXNfySvrClientEvent
AgentSDK::Interfaces::IAeXNotificationManager
AgentSDK::Interfaces::IAeXObject
AgentSDK::Interfaces::IAeXPackageDelivery
AgentSDK::Interfaces::IAeXPkgDeliveryNotification
AgentSDK::Interfaces::IAeXPkgServerClientAgent
AgentSDK::Interfaces::IAeXPluginManager
AgentSDK::Interfaces::IAeXPolicyManager
AgentSDK::Interfaces::IAeXSWDAgent
AgentSDK::Interfaces::IAeXScheduledTaskHandler
AgentSDK::Interfaces::IAeXTaskScheduler
AgentSDK::Interfaces::IAeXTickleAgent
AgentSDK::Interfaces::IAeXUserLogonManager
ClientTaskAgentSDK::Interfaces::IAeXClientTaskAgent
ClientTaskAgentSDK::Interfaces::IAeXClientTaskAlertHelper
ClientTaskAgentSDK::Interfaces::IAeXClientTaskNotification
ClientTaskAgentSDK::Interfaces::IAeXClientTaskPolicyHelper
ClientTaskAgentSDK::Interfaces::IAeXTaskHandler

 

The list basically outlines fully-qualified names of the interfaces as defined by the corresponding IDLs.

 

It is possible to get additional information about a specific interface and the functions that it exposes:

 

root@computer# aex-helper agent comminfo AgentSDK::Interfaces::IAeXObject

 @ingroup mod_nsagent agent_ipc agentfunc
 @brief This is the common interface for all modules.

Functions:
        ObjectDebugInfo
        NotifyObject

 

Furthermore, it is possible to get information about an individual function and the arguments it expects:

 

root@computer# aex-helper agent comminfo AgentSDK::Interfaces::IAeXObject ObjectDebugInfo

 This method is only for internal use and will return debugging/status information.

 @param strInfo debug information

Return type: BaseSDK::AError
Parameters:
        BaseSDK::AString   strInfo

 

Having information about an interface and the function that you wish to invoke is not enough. The interface invocation needs to be addressed to a specific Agent's plug-in. For that a class ID is required, whereas the list of plug-ins with their corresponding IDs is available through aex-helper as well:

 

root@computer# aex-helper list plugins
Altiris.ClientTaskAgent
Altiris.CTSchedulingAgent
Altiris.AlertUserTaskAgent
Altiris.ScriptTaskAgent
Altiris.PowerControlTaskAgent
Altiris.ServiceControlTaskAgent
Altiris.WebServiceTaskAgent
Altiris.ResetTaskAgent
Altiris.AgentControlTask
Altiris.AeXClientTransport
Altiris.AeXNfySvrClientEvent
Altiris.AeXMachineID
Altiris.MaintenanceWindowAgent
Altiris.AeXPolicyManager
Altiris.AeXNSClientConfigUpdate
Altiris.AeXTaskScheduler
Altiris.SWD
Altiris.SWDAgent
Altiris.SWDTaskProcessor
Altiris.AeXPackageDelivery
Altiris.AeXTickleAgent
Altiris.AeXNSManager
Altiris.NotificationManager
Altiris.ClientScheduler

 

There is no way to find out which interfaces are implemented by a specific plug-in or which plug-in implements a specific interface. However, this information is typically available to developers anyway.

Invoking interface functions

 

Once all of the information is available, invoking an interface function becomes an easy task. This is done through aex-helper using the agent's comm sub-command:

 

root@computer# aex-helper agent comm AgentSDK::Interfaces::IAeXObject Altiris.AeXTaskScheduler ObjectDebugInfo ""
Return Value = 0
strInfo = Currently running tasks:
 CS01
 CTA01
 CTA02
 CTA03
 MID01
 PD01
 PD02
 PM01
 PM02


Task processing is enabled.

 

Basically, what's needed for a successful invokation is:

• fully-qualified interface class name
• target plug-in class ID
• function name
• all function parameters serialized in string format

 

The output will outline the return value of the function as well as values for OUT and IN/OUT parameters serialized to string format.

Parameters serialization

 

The data passed to and from the invoked function needs to be in a serialized format. First, the values for input parameters are provided by user through command line and thus need to be in a plain-text format, even if the parameter has some complex type. Additionally, the output and return values need to be presented to the user in some way as well.

 

Command line interfaces support implies that every type of function argument has a corresponding serialization/deserialization pair of functions available for it:

• ADoCliDeserialize - read object's data from a string provided by user
• ADoCliSerialize - represent object in a user-friend text format

 

The functions need to reside in the same namespace as the type itself. The result of serialization does not need to be deserializable.

 

Here is a basic sample of the custom type serialization:

 

// Namespace for holding the custom parameter type.
// The serializers should reside in the same namespace.
namespace CustomNamespace
{

// Custom function argument type.
struct ProductInventory
{
        BaseSDK::AString product_name;
        unsigned quantity;
};

// Represent the parameter in a user-readable format.
// This function will be used to print out the parameter
// to standard output.
BaseSDK::AError ADoCliSerialize(const ProductInventory &BaseSDK::AString &out)
{
        out = obj.product_name + "\n\tquantity = " + AString().SetNum(obj.quantity);
        return E_OK;
}
// Parse the parameter value from a string.
// This function will be used to parse the value provided
// for the parameter in command line.
BaseSDK::AError ADoCliDeserialize(ProductInventory &obj, const BaseSDK::AString &in)
{
        // Expect ~-separated input.
        BaseSDK::AStringTokenizer st(in, "~");
        obj.product_name  = st[0];
        bool ok = false;
        obj.quantity = st[1].ToUInt(&ok);
        return ok ? E_OK : E_INVAL;
}

}

 

At this point, there is no specific standard for the user's input. The only recommendation is to use XML for allowing inputting values of complex types.

Custom interfaces support

 

If a solution provides custom IPC interfaces, it may integrate with aex-helper to let it know how to invoke their functions. This is done using CLI plug-ins.

 

Building a CLI plug-in requires access to the IDL files. The plug-in is basically a dynamically loadable object containing some static initializers that take care of communicating to aex-helper. Agent SDK provides facilities that hide all of the details from the developer.

 

To build a plug-in, create an empty directory and add a makefile to it. The contents of the makefile should be similar to the one below:

 

# Location of the solution's build root
BUILDROOT = ..

# Include common flags (should lead to loading Agent SDK build flags)
include $(BUILDROOT)/buildFlags

# The target binary to build. Agent plugins must always have .so extension
TARGET = aex-mysolution-cli.so

# Specify that we are building a plugin for custom interfaces access through CLI
IS_PLUGIN = 1

# List the IDL files describing inter-plugin communication interfaces
CLINT_IDLS = $(wildcard $(BUILDROOT)/MySolutionLib/Interfaces/*.idl)

# Custom includes and libraries that provide the IPC interfaces
CXXFLAGS += $(INC_MYSOLUTION)
LINKLIBS += $(LIB_MYSOLUTION)

# Additional custom object files (if necessary)
OBJS =

# Default target: build the plugin
all : $(TARGET)

# Common build rules (should lead to loading Agent SDK build rules)
include $(BUILDROOT)/buildCommon

 

The makefile is pretty standard. The only important variables are:

• IS_PLUGIN - set this to 1 to indicate that a dynamically loadable object needs to be built
• CLINT_IDLS - list the IDL files (thus IPC interfaces) to be included in the plug-in
• CXXFLAGS and LINKLIBS - make sure these contain instructions for locating the include files and for linking with the shared libraries providing the custom interfaces

 

Note that in case your interfaces are using some non-standard types for function arguments, there need to be the corresponding serialization routines provided for them.

 

In order to let aex-helper load the newly built plug-in, you will have to register it:

 

root@computer# aex-helper register cliplugin /full/path/to/aex-mysolution-cli.so

 

To unregister the CLI plug-in after it is no longer necessary, run:

 

root@computer# aex-helper unregister cliplugin aex-mysolution-cli

 

See Agent Command Line Interfaces (CLI) Plug-ins for more information.

 

Whether to include the CLI plug-in along with the solution's package is up to the developer. There are three available strategies here:

• do not ship the plug-in at all; upload and register it as needed
• ship the plug-in with the solution, but register it manually if needed
• ship the plug-in and register/unergister it as part of the solution's package installation process

 

The Altiris Agent ships the CLI plug-ins for its custom interfaces and registers/unregisters them automatically during install/uninstall.

Restrictions

 

The command line interfaces access feature has some limitations:

• it works only for the root user and only in the debugging mode
• the Agent process must be running and the communication socket should be available
• it is not possible to invoke interface functions that require local IPC call context
• input of binary or large data for parameter values is not possible
• parameters string representation is not formalized and formats differ across types