All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Macros | Typedefs
Turbulence Module Def: Type and handler definitions for turbulence modules

Data Structures

struct  _TurbulenceModDef
 

Macros

#define TBC_MOD_PREPARE(_ctx)   do{ctx = _ctx;}while(0)
 

Typedefs

typedef void(* ModCloseFunc )(TurbulenceCtx *ctx)
 
typedef axl_bool(* ModInitFunc )(TurbulenceCtx *ctx)
 
typedef axl_bool(* ModPPathSelected )(TurbulenceCtx *ctx, TurbulencePPathDef *ppath_selected, VortexConnection *conn)
 
typedef void(* ModReconfFunc )(TurbulenceCtx *ctx)
 
typedef void(* ModUnloadFunc )(TurbulenceCtx *ctx)
 
typedef struct _TurbulenceModDef TurbulenceModDef
 

Detailed Description

Macro Definition Documentation

#define TBC_MOD_PREPARE (   _ctx)    do{ctx = _ctx;}while(0)

Allows to prepare de module with the turbulence context (and the vortex context associated).

This macro must be called inside the module init, before any operation is done.

Parameters
_ctxThe context received by the module at the init functio.

Typedef Documentation

typedef void(* ModCloseFunc)(TurbulenceCtx *ctx)

Public definition for the close function that must implement all operations required to unload and terminate a module.

The function doesn't receive and return any data.

Parameters
ctxThe turbulence context where the close operation is taking place.
typedef axl_bool(* ModInitFunc)(TurbulenceCtx *ctx)

Public definition for the init function that must implement a turbulence module.

The module must return axl_true to signal the modules was properly initialized so turbulence can register it as usable.

This handler is called only once at turbulence startup and when a child process is created (separate="yes" directive inside profile path configuration, see 3.4 Turbulence execution model (process security) and 3.1 Profile path configuration).

To know if current init call is for a child process you can use:

// reinitialize
} else {
// normal init
}

Keep in mind child creation is implemented using fork() call (without further exec()). This means you may require reinitialize some structures (like mutex).

Parameters
ctxThe turbulence context where the init operation is taking place.
Returns
axl_true if the module is usable or axl_false if not. Returning axl_false caused the module to be not loaded.
typedef axl_bool(* ModPPathSelected)(TurbulenceCtx *ctx, TurbulencePPathDef *ppath_selected, VortexConnection *conn)

Allows to notify the module that a profile path was selected for a connection.

The ppath_selected function is used by turbulence to signal modules that a connection was finally configured under the provided profile path. This is important because a profile path defines how the connection will be limited and configured to accept profiles, configuring process permission and so on.

It is also useful because at the time a profile path is selected, serverName name is available, allowing the module to take especial actions.

This module function is called just after a profile path is selected for a connection, on first channel request received, (according to serverName, src connection, etc). In the case the profile path request a child process to handle the connection, the module function is called after creating the child process and after the child process implements optional chroot and optional user:group change.

In the case the profile path do not request to create a child process, the handler is called on first channel request received on a connection.

Note that, unlike init, this method is called for each connection received for which a profile path is selected.

Security: Important note about serverName

When a profile path is selected it is done according to preliminary data provided by remote peer. In this context the module programmer must see the serverName as a requested value but still not the final serverName accepted.

The serverName will only be definitive only if all profile path handlers accept it and a channel with that serverName is created.

In this context, to get the serverName requested by remote peer you can use:

Parameters
ctxThe turbulence context where the profile path is being selected.
ppath_selectedThe profile path selected. Reference to the object representing the profile path selected. See Turbulence Profile Path: API for handling and retrieving information associated to a profile path policy.
connThe connection where the profile path was selected. The VortexConnection object that was configured with the provided profile path.
Returns
Like init function, if this handler returns axl_false the connection is closed. Keep in mind returning axl_false will terminate current process.
typedef void(* ModReconfFunc)(TurbulenceCtx *ctx)

Public definition for the reconfiguration function that must be implemented to receive notification if the turbulence server configuration is reloaded (either because a signal was received or because some module has called turbulence_reload_config).

Parameters
ctxThe turbulence context where the reconf operation is taking place.
typedef void(* ModUnloadFunc)(TurbulenceCtx *ctx)

A reference to the unload method that must implement all unload code required in the case turbulence ask the module to stop its function.

Unload function is only called in the context of child process created by turbulence to isolate some requests (modules and profiles) to be handled by a low permissions user.

Parameters
ctxThe turbulence context where the close operation is taking place.

Public definition for the main entry point for all modules developed for turbulence.

This structure contains pointers to all functions that may implement a turbulence module.

See how to create Turbulence modules.