 |
Helper Applications |
|||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
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 CommuniGatePro 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:
nnnnnn INTF serverInterfaceVersion
where:
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.
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:
nnnnnn VRFY (mode) name@domain password [loginAddress]
where:
When a user should be authenticated using a secure SASL method, the following command is sent:
nnnnnn SASL(method) (mode) name@domain password key [loginAddress]
where:
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"
Sample session (I: - server commands sent to the program standard input, O: - responses the program writes to its standard output):
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:
nnnnnn NEW name@domain relayType
where:
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:
nnnnnn ROUTE <address> relayType
where:
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:
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.
The External RADIUS Interface protocol is based on the generic Helper Protocol.
This manual describes the External RADIUS Interface Version 1.
If the External RADIUS program is enabled, it is used after the user password is verified.
The Server sends it the following command:
nnnnnn LOGIN name@domain attributes settings
where:
If the login request is accepted, the Helper program should return a positive response:
nnnnnn ACCEPT attributes
where:
If the password was not accepted, a negative response should be returned:
nnnnnn REJECT optional-error-message
If the External RADIUS program is enabled, it is used to process the Start, Stop, and Interim-Update
accounting requests. The Server sends the following command:
nnnnnn ACCNT command name@domain attributes
where:
The Helper program should return a positive response:
nnnnnn OK
where:
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 not passed to the Helper and are ignored in Helper responses:
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 User-Name string attribute is passed to the Helper, but it is ignored in Helper responses.
Accounting requests also have a numeric attribute 0 - the RADIUS protocol request ID. It can be used to detect retransmitted packets (duplicate requests).
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.
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:
nnnnnn CDR cdr_data
where:
when the record is processed, the program should return a positive response:
nnnnnn OK
