Version 5.1
Applications |
|---|
| ||||||||||
|
|
Version 5.1 |
||||||||||||||||||||||||||||||||
|
|
When the Helper program is launched, the Server sends commands to the Helper process via the process standard input. The Server reads the program responses from the process standard output.
Commands and responses are text lines, ending with the EOL symbol(s) used in the Server OS.
Each command starts with a sequence number, and the response produced with the Helper program starts with the same number. This method allows the Helper program to process several requests simultaneously, and it can return responses in any order.
The Helper program can send information responses at any time. An information response starts with the asterisk (*) symbol. The Server ignores information responses, but they can be seen in the Server Log.
The response lines generated with a Helper program should not be larger than 4096 bytes.
Note: communication between the Server and an Helper program takes place via OS pipes, and many programming libraries buffer output data sent to pipes. Check that your Helper program uses some form of the flush command after it sends a response to its standard output, otherwise the response will not reach the Server.
Helper programs are started with the CommuniGate Pro base directory as their current directory.
Helper programs should not write anything to their standard error streams, unless they want to report a reason for the failure before quitting. CommuniGate Pro reads the program standard error stream only after the program has terminated, and if the program writes into that stream while processing Server commands, the program will be suspended by the OS when the standard error pipe buffer is full.
The Interface Version command is used to provide compatibility between different versions of Helper programs and different versions of the CommuniGate Pro Server. The Server sends this command specifying the protocol version it implements:The Helper program should return the INTF response and the supported protocol version.
nnnnnn INTF programInterfaceVersion
If the returned number is smaller than the Server protocol version, the Server will use this (older) protocol version.
When the Server shuts down or when it needs to stop the Helper program, it sends the QUIT command, and then closes the process standard input. The Helper program should send the OK response and it should quit within 5 seconds.
Sample session (I: - server commands sent to the program standard input, O: - responses the program writes to its standard output, COMMAND - a Helper-specific command):The sample above shows that the Server does not wait for a response before it sends the next command, and that it can accept responses for several pending commands in any order - as long as each command receives a response within the specified time limit.
External Authenticator programs can be used to provide authentication, provisioning, and routing services using external data sources.
The External Authenticator Interface protocol is based on the generic Helper Protocol.
This manual describes the External Authenticator Interface Version 7.
When a user should be authenticated using the clear text method, the Server sends the following command:If the password is accepted, the External Authernticator should return a positive response:
nnnnnn OK
If the password was not accepted, a negative response should be returned:
nnnnnn ERROR optional-error-message
If the password is accepted, and there is an authentication response to be returned to the
client, a positive response with a quoted string should be returned:
nnnnnn RETURN "authentication-response"
SASL password verification requires that the External Authenticator program correctly implements
all supported SASL methods and algorithms. Alternatively, the External Authenticator program can return
the user plain text password, making the Server verify the password and calculate necessary authentication responses.
The user plain text password should be returned as a quoted string:
nnnnnn PLAIN "plain-text-password"
The External Authentication program can be used to process unknown names, too. For example, the program can consult an external database, check if the user exists in that database, create an Account, Alias, Group, Mailing List, or Forwarder using the CommuniGate Pro CLI/API, and return a positive response to the Server. In this case, CommuniGate Pro will re-try to open a domain object with the specified name.
To check an unknown name, the Server sends the following command:If the program sends the OK response, the Server tries to find the name object in the domain Domain again.
If the program sends the ROUTED address response, the Server takes the supplied address response and restarts the Router procedure with this address. The routed address gets a "can Relay" attribute, unless it is specified with the [NORELAY] prefix.
If the program sends the FAILURE response, the Server Router returns a "temporary internal error" code (this code causes the SMTP module to return a 4xx error code, not a permanent 5xx error code).
If the program sends any other response, the Server Router returns the "unknown user account" error.
Sample session:The Consult External Authenticator Domain Setting tells the Server to use the External Authenticator program when an unknown name is addressed.
The External Authentication program can be used to assist in address Routing. If an address is routed to the @external domain, the address "local part" is passed to the External Authentication program using the ROUTE command:If the program sends the ROUTED address response, the Server takes the supplied address response and restarts the Router procedure with this address. The routed address gets a "can Relay" attribute if the address is specified with the [RELAY] prefix.
If the program sends the FAILURE response, the Server Router returns a "temporary internal error" code (this code causes the SMTP module to return a 4xx error code, not a permanent 5xx error code).
If the program sends any other response, the Server Router returns the "cannot route the address" error.
Sample session:External Message Filter programs are used for content filtering (anti-virus and anti-spam filtering).
The External Filter Interface protocol is based on the generic Helper Protocol.
This section describes the External Filter protocol version 3.
If the external program crashes, CommuniGate Pro suspends the Enqueuer process until the external program is restarted.
External RADIUS programs can be used to provide additional checks for authentication operations performed via the RADIUS module, as well as to add additional attributes into RADIUS responses.
The External RADIUS Interface protocol is based on the generic Helper Protocol.
This manual describes the External RADIUS Interface Version 2.
If the password was not accepted, a negative response should be returned:
nnnnnn REJECT optional-error-message
The attributes in dictionaries should use the attribute type numeric values as keys (for example 27 for Session-Timeout).
The following attributes are interpreted as 32-bit integer values and they are encoded
as numeric strings in dictionaries:
NAS-Port, Service-Type, Framed-Protocol, Framed-Routing, Framed-MTU,
Framed-Compression, Login-Service, Login-TCP-Port, Framed-IPX-Network, Session-Timeout,
Idle-Timeout, Termination-Action, Framed-AppleTalk-Link, Framed-AppleTalk-Network, Event-Timestamp,
NAS-Port-Type, Port-Limit, ARAP-Zone-Access, Password-Retry, Prompt,
Tunnel-Type, Tunnel-Medium-Type, Tunnel-Preference, Acct-Interim-Interval,
Acct-Delay-Time, Acct-Input-Octets, Acct-Output-Octets, Acct-Authentic,
Acct-Session-Time, Acct-Input-Packets, Acct-Output-Packets, Acct-Terminate-Cause,
Acct-Link-Count, Acct-Input-Gigawords, Acct-Output-Gigawords.
The following attributes are interpreted as 32-bit IP addresses and they are encoded
as aaa.bbb.ccc.ddd strings in dictionaries:
NAS-IP-Address, Framed-IP-Address, Framed-IP-Netmask, Login-IP-Host.
The following attributes are ignored in Helper responses:
User-Name, User-Password, CHAP-Password, State, Proxy-State, EAP-Message,
Message-Authenticator, Acct-Status-Type.
All other attribute values are encoded either as a String or
as DataBlocks. The Server uses the DataBlocks format for those
attribute values that contain bytes outside the hexadecimal 0x20-0x7F range.
The DataBlock format must be used if the value contains binary zero bytes.
If an attribute has multiple values, the attribute value is encoded as an Array.
The following attributes are added to the attribute dictionaries passed to the Helper:The Vendor-specific attributes are presented using keys with negative numeric values. The key absolute value is the "VendorID" value. For each VendorID, the associated element is a dictionary. This dictionary keys are Vendor-specific "vendor types", with associated "specific attributes". The "specific attributes" values can be stored as String, DataBlocks, Number, or Arrays of Strings, DataBlocks, and/or Numbers.
Sample session (I: - server commands sent to the program standard input, O: - responses the program writes to its standard output):Note: the Server can send several concurrent requests for the same target Account.
Note: the External RADIUS program is called when the target Account is open. In a Dynamic Cluster system this means that External RADIUS programs should run on backend servers, and that External RADIUS programs running on different backend servers will never get requests for the same Account at the same time.
External CDR Processor programs can be used to process CDRs (Call Detail Records) generated with the Signal component when a call is attempted, established, or tiered down. They can also process CDR records generated with CG/PL applications.
The External CDR Processor Interface protocol is based on the generic Helper Protocol.
This manual describes the External CDR Processor Interface Version 1.
If the External CDR Processor program is enabled, the Signal module generated CDRs and sends them to the program.
When a CDR is composed, the Server sends the following command:when the record is processed, the program should return a positive response:
nnnnnn OK