ApplicGate Message Queue (AGMQ):
AGMQ allows sending of messages and files asynchronously with follwing features:
Overview:
- Distributed messaging system, no central instance
- Timestamp (UTC) generation to uniquely identify a message
-- A timestamp (format "$yyyyMMddHHmmssfffF", e.g. $20230703090616000F) will be appended to the message name
-- fff is a serial number to force uniqueness of the timestamp
- Based on integrated web server
- REST interface via http(s) GET, POST and DELETE
- Configurable security via user certificates and source IP addresses
- Optional central status and management web page
To monitor and operate (pause and resume) message queues click here.
Structure:
- A message queue is defined as a subdirectory of a web server.
- A message queue can be defined as local or remote.
- The subdirectories are created by the keyword AGMQ (see below).
- For local and remote queues acceptence of messages can be disabled (paused) and enabled (resumed).
- For remote queues separate threads to send the messages to the remote destination systems will be created.
-- Sender threads can be paused and resumed and retry intervals can be configured.
-- The network address (URL) for the remote queue is resolved and configured via configuration file AGMQdest.csv (see below).
Routing entry for (local) client access:
- GatewayIP2=web
- Keyword AGMQ:loc1|loc2...~rem1|rem2...
-- Defines local (loc1...) and remote or destination queues (rem1...)
- Keyword DELETE ... allows deletion of messages (files)
Optional keywords:
- Keyword DIR:webroot ... webroot is the root directory of the web server, default is the subdirectory "store" of the default directory.
- Keyword DIRLIST:parameter ... support of directory listing
- Keywords SSL and CCR ... for https support and authentication via certificates
- Keyword PASSW:password ... password, must match value of received http header "Password".
Example: SourceIP ;GatewayIP ;GatewayPort;GatewayIP2 ;DestinationIP;DestinationPort;Expiration;Type ;UID;Comment ;eMail
* ;127.0.0.1 ;777 ;web ;* ;* ; ;AGMQ:AS1~AS2, DELETE ;MQ1;myMQ ;mike@x.com
In this example a client can
- post messages via http://127.0.0.1:777/AS2/MessageName to the remote queue AS2
- get the first message via http://127.0.0.1:777/AS1?first from the local queue AS1 and delete the message.
-- To delete the received message: Issue a DELETE request using the name returned in the http header ContentLocation at the GET request.
- A client can wait for incoming messages by adding the query parameter "wait":
-- http://127.0.0.1:777/AS1?first&wait
-- Optional specification of wait time in seconds, e.g.
-- http://127.0.0.1:777/AS1?first&wait=600 ... wait 10 minutes
For definition of additional query parameters see here.
Routing entry to receive messages from remote message queue systems:
- GatewayIP2=web
- Keyword AGMQ:loc1|loc2 ... Defines local queues
Optional keywords:
- Keyword DIR:webroot ... webroot is the root directory of the web server, default is the subdirectory "store" of the default directory.
- Keywords SSL and CCR ... for https support and authentication via certificates
- Keyword PASSW:password ... password, must match value of received http header "Password".
Example: SourceIP;GatewayIP;GatewayPort;GatewayIP2;DestinationIP;DestinationPort;Expiration;Type ;UID;Comment ;eMail
* ;* ;778 ;web ;* ;* ; ;AGMQ:AS2, SSL:comp1.cer, CCR:*.mq@x.com ;MQR;MQ Receiver ;mike@x.com
In this example a remote system can
- post messages via http://dnsname:778/AS2/MessageName to the local queue AS2
- A client certificate is necessary where the email matches *.mq@x.com (e.g. comp1.mq@x.com).
Remark:
If AS2 in the example above is a remote queue, the messages will be forwarded. Therefore message forwarding can be delivered via multiple hops.
Configuration file AGMQdest.csv (stored in the default directory):
This file is a comma separated file with following header:
Queue ;Address ;Certificate ;Retry ;Comment
- Queue ... Name of queue (Destination Application System)
- Address ... [http[s]://]DNSname[:port], default is https://...
- Certificate ... optional reference to a client certificate, for certificate loading see here.
- Password ... optional password, will be transmitted in the http header "Password" and must match the value of keyword PASSW at the receiver side.
- Retry ... time span in seconds to automatically resume sender threads. Default is 60 seconds.
- Timeout ... Sender timout in seconds. Default is 60 seconds.
- ServerCertValidation ... Server certificate validation, "True" of "False". Default is "True".
- Comment ... your comment
Example:
Queue ;Address ;Certificate ;Password ;Retry ;Timeout ;ServerCertValidation ;Comment
AS2 ;comp1.applicgate.com:778 ;myCert.cer ;myPass ;120 ;60 ;True ;Test AGMQ
Lines starting with # are treated as comments and are not processed.
At startup the file AGMQdest.csv will be loaded automatically.
Management of queue content
Following keywords may be specified for "manage", "status", "reverselogon" and "autologon" routing entries:
DIRLIST:parameter ... list message queue content
DELETE:EmailAddresses ... allow deletion of messages
Central Management
Message queue status is reported to a central server and management by the central server is allowed, see example (status is sent every 30 seconds):
SourceIP ;GatewayIP;GatewayPort;GatewayIP2 ;DestinationIP;DestinationPort;Expiration;Type ;UID;Comment;eMail
autologon;mgmt ; ; ;x.mycomp.com ;446 ; ;SSLTARGET:x.mycomp.com!!c@mycomp.com.cer,UPDATE,RTUPD,GRPUPD,DIRLIST:DelB,DELETE,RETRY:1,TTL:330s;LOG; ;
Central management server receives message queue status and can manage the remote servers, see example:
SourceIP ;GatewayIP;GatewayPort;GatewayIP2 ;DestinationIP;DestinationPort;Expiration;Type ;UID;Comment;eMail
* ;*,:: ;446 ;reverselogon;mgmt ; ; ;SSL:x.mycomp.com.cer, CCR:*@mycomp.com ;MQS; ;
Via the central management server all message queue parameters can be configured, message queue content can be read and deleted.
If only the message queue status should be sent (no remote management allowed): replace "mgmt" by "mqlg" in the routing entries above.
Hint: If a message name has no extension, enter "..unspecified text/plain" or "..unspecified text/plain;charset=UTF-8" into MediaType.txt in order to show the content of the message in the browser windows (no download).
.
Extensions:
With proper selection of message names a more detailed addressing schema can be implemented:
For example if the message name format DAS!DPN_SAS!SPN is chosen, where
- DAS ... Destination Application System (should be the name of the message queue)
- DPN ... Destination Program Name (for selection of messages at the destination
- SAS ... Source Application System
- SPN ... Source Program Name
Now the first message in the queue DAS for the destination program DPN can be retrieved via http://127.0.0.1:port/DAS?first&s=DAS!DPN_*
For definition of the query parameter "s" see here.
