tcpgatesv

Name

tcpgatesv — Enduro/X user programmable TCP/IP gateway (client/server roles, XATMI server).

Synopsis

tcpgatesv

DESCRIPTION

User programmable tcp gateway. This module gives programmer abstraction over of the TCP/IP socket to the next level - XATMI services. By using tpc gateway for programmer to send network message, it is sufficient for doing the standard XATMI service invocation (e.g. tpcall(3)) with specific UBF buffer, which containing the message to be sent to network. Network address is abstracted to XATMI service name. All other details technical details of socket operations are covered by tcpgatesv and mainly are set in the configuration file for the connection instance. Several processes may be started in the system, where each instance is configured by ini sub-section, and instance may cover different connection (port number, server/client roles).

tcpgatesv mostly covers all the functionality typically which is required for connecting Bank POS, ATM terminals, and handle different modes of ISO8583 connections. However tcpgatesv maybe useful in other custom protocol based connectivity applications.

The getaway is able to handle multiple simultaneous connections. The connections are identified by connection id, which consists of two parts - simple connection id (started from Nr. 1) and by compiled connection id, where part of the number contains the actual timestamp when connection is established.

Getaway can operate with persistent connections, so that tcpgatesv opens the number of connections, and callers (from both ends XATMI and network) can do the invocations synchronously or asynchronously. In async mode it is still possible to simulate synchronous service invocations, that is done in case if corr_svc parameter is set. This parameter indicates which service which to invoke for sending incoming message for parsing. The correlation service can parse the message, and respond with parsed correlation id (in EX_NETCORR). Then by this given correlation ID, the gateway server will lookup any XATMI callers in progress, if found, then they are replied with buffer coming from corr_svc. If correlation id is not parsed or no waiters in progress, then incoming_svc is called with given incoming/corr_svc response buffer.

Gateway can operate in one request/new connection mode from both ends, it can accept the request from network (in this case we must be passive (socket server) - wait for conn). And it can create new connection when doing the XATMI request to network. After receiving response from network or getting timeout, the connection is closed.

Module allows the system to track the status of the connections. When gateway boots, it sends disconnected status to target connection tracking server (status_svc service in ini config). When connection is established either in active or passive mode, the status of connection is sent to status service.

It is possible to configure gateway to send keep-a-live messages. The keep a live message is message with zero data length but with framing bytes. Such messages can be safely ignored by network target device. The same as tcpgatesv does.

tcpgatesv uses different message framing algorithms, to avoid partially read messages from network, which can occur if message size is larger than message transfer unit (MTU). Framing mode is controlled by framing parameter. Following options are supported:

  1. a+ - ASCII formatted string message length
  2. A+ - ASCII formatted string with message length, including the length bytes
  3. l+ - little endian byte order (from one to 8 bytes)
  4. L+ - little endian byte order (from one to 8 bytes), message length includes length bytes by it self
  5. b+ - big endian byte order (from one to 8 bytes)
  6. B+ - big endian byte order (from one to 8 bytes), message length includes length bytes
  7. p+ - packed BCD (from one to 8 bytes)
  8. P+ - packed BCD (from one to 8 bytes), message length includes length bytes
  9. d - Message end delimiter byte
  10. D - Message start and end delimiter byte

Note that if even bytes are used for connection length indication, it is possible, to swap them in half by using framing_half_swap parameter. This is suitable for connecting to VISA payment network, which uses little endian 4 bytes, which are swapped in big endian order by two halves.

The administrator can configure tcpgatesv for different roles:

  1. Tcp socket server - listener (passive mode)
  2. Tcp socket client - connects (active mode)

The tcpgateway can operate in different logical modes (type param):

  1. A - Active mode, our side initiate connection (tcp client)
  2. P - Passive mode, our side does listen on socket (tcp server)

The next sections will show samples for different framing methods, including settings of framing and framing_half_swap. The test message that will be demonstrated in bellow framing modes are: AHELLO WORLD\\10\\11\\12\\13TEST\\ff, the total number of bytes: 21.

Mode: framing = aa, framing_half_swap=0

framing = aa

  0000  32 31 48 45 4c 4c 4f 20 57 4f 52 4c 44 00 10 11  21HELLO WORLD...
  0010  12 13 54 45 53 54 ff                             ..TEST.

Mode: framing = AAAA, framing_half_swap=0

framing = AAAA

  0000  30 30 32 35 48 45 4c 4c 4f 20 57 4f 52 4c 44 00  0025HELLO WORLD.
  0010  10 11 12 13 54 45 53 54 ff                       ....TEST.

Mode: framing = llll, framing_half_swap=1

framing = llll

  0000  00 15 00 00 48 45 4c 4c 4f 20 57 4f 52 4c 44 00  ....HELLO WORLD.
  0010  10 11 12 13 54 45 53 54 ff                       ....TEST.

Mode: framing = LLLLLL, framing_half_swap=0

framing = LLLLLL

  0000  00 00 00 00 00 1b 48 45 4c 4c 4f 20 57 4f 52 4c  ......HELLO WORL
  0010  44 00 10 11 12 13 54 45 53 54 ff                 D.....TEST.

Mode: framing = bbbb, framing_half_swap=0

framing = bbbb

  0000  15 00 00 00 48 45 4c 4c 4f 20 57 4f 52 4c 44 00  ....HELLO WORLD.
  0010  10 11 12 13 54 45 53 54 ff                       ....TEST.

Mode: framing = BBBBBBBB, framing_half_swap=1

framing = BBBBBBBB

  0000  00 00 00 00 1d 00 00 00 48 45 4c 4c 4f 20 57 4f  ........HELLO WO
  0010  52 4c 44 00 10 11 12 13 54 45 53 54 ff           RLD.....TEST.

Mode: framing = pp, framing_half_swap=0

framing = pp

  0000  00 21 48 45 4c 4c 4f 20 57 4f 52 4c 44 00 10 11  .!HELLO WORLD...
  0010  12 13 54 45 53 54 ff                             ..TEST.

Mode: framing = PPPP, framing_half_swap=0

framing = PPPP

  0000  00 00 00 25 48 45 4c 4c 4f 20 57 4f 52 4c 44 00  ...%HELLO WORLD.
  0010  10 11 12 13 54 45 53 54 ff                       ....TEST.

Mode: framing = d, framing_half_swap=N/A

framing = d

Using default message delimiter 0x03 (delim_stop).

  0000  48 45 4c 4c 4f 20 57 4f 52 4c 44 00 10 11 12 13  HELLO WORLD.....
  0010  54 45 53 54 ff 03                                TEST..

Mode: framing = D, framing_half_swap=N/A

framing = D

Using default message marker delim_start=0x02 and default message end marker delim_stop=0x03.

  0000  02 48 45 4c 4c 4f 20 57 4f 52 4c 44 00 10 11 12  .HELLO WORLD....
  0010  13 54 45 53 54 ff 03                             .TEST..

SERVICE API INTERFACE

TCP Gateway is programmed by using UBF buffers. Buffers contains specific fields including CARRAY (BLOB) message that needs to be delivered or is received from network.

In case of sending data to network standard tpcall(3) or tpacall(3) are used. The target service of invocation is configured in gateway parameter, that is advertised by tpcgatewsv.

When message is received from network, with incoming data, the corr_svc will be invoked if configured. Finally message is delivered to incoming_svc, the invocation by tcpgatesv will be done synchronously or asynchronously depending on configuration parameters and message specification.

Sending message to network - request

To send message to network in use following UBF buffer (tpcall(3)):

EX_NETDATA - The BLOB/CARRAY data to delivery to target connection

EX_NETCONNID - connection id either compiled or simple. The compiled connection id can be used when generating response back to network. The connection id is composed of 64bit integer, where first 24 bits are connection id, and oldest 39bits are set to UTC epoch milliseconds since start of 1970. The compiled id can be used for doing reply to exact connection.

EX_NETCORR - Optional Correlator string, used for synchronous connections.

Response from gateway service

EX_NERROR_CODE - Error code, can be one of followings:

atmi.NEMANDATORY (6) - Mandatory field is missing (EX_NETDATA)

atmi.NETOUT (8) - timeout waiting on reply

atmi.NENOCONN (9) - Connection not found by EX_NETCONNID or no connection established.

atmi.NELIMIT (10) - Connection count limit reached

EX_NERROR_MSG - Corresponding error message.

Network endpoints identification

When connection is established, and when Enduro/X sends incoming data buffer to XATMI target or correlation service, the UBF buffer includes following meta-data:

  1. EX_NETOURIP - IP Address of our/local side (either we are client or server).
  2. EX_NETOURPORT - Port of the our/local side.
  3. EX_NETTHEIRIP - Remote IP address.
  4. EX_NETTHEIRPORT - Remote port.
  5. EX_NETCONMODE - Connection mode. A - means local is client. P - means local is server.

The identification data is available for established connections. When reporting connection statuses, and connection is down (disconnected), then fields are optional. In case if included, then data is from last established connection.

Sync service req/reply - example

Request/reply example (from client perspective - in this example server process does change the data bytes doing +1 over the data starting from position 5):

$ ud < test.ud
SENT pkt(1) is :
EX_NETCONNID    1
EX_NETCORR      AELL
EX_NETDATA      AELLO WORLD\00\10\11\12\13TEST\ff

RTN pkt(1) is :
EX_NERROR_CODE  0
EX_NETCONNID    6481138401960525826
EX_NERROR_MSG   SUCCEED
EX_NETGATEWAY   TCP_P_ASYNC_P
EX_NETCORR      AELL
EX_NETDATA      AELLP!XPSME\01\11\12\13\14UFTU\00
EX_NETOURPORT   53972
EX_NETTHEIRPORT 29999
EX_NETCONMODE   A
EX_NETOURIP     127.0.0.1
EX_NETTHEIRIP   127.0.0.1

Incoming request at correlation service (other end reads network and sends data to (corr_svc), at the destination with no reply waiter, it will just invoke the incoming service (see after this dump).

EX_NETCONNID    6481138401943748609
EX_NETGATEWAY   TCP_P_ASYNC_A
EX_NETDATA      AELLO WORLD\00\10\11\12\13TEST\ff
EX_NETOURPORT   29999
EX_NETTHEIRPORT 53972
EX_NETCONMODE   A
EX_NETOURIP     127.0.0.1
EX_NETTHEIRIP   127.0.0.1

Incoming request at server (incoming_svc):

EX_NETCONNID    6481138401943748609
EX_NETGATEWAY   TCP_P_ASYNC_A
EX_NETCORR      AELL
EX_NETDATA      AELLO WORLD\00\10\11\12\13TEST\ff
EX_NETOURPORT   29999
EX_NETTHEIRPORT 53972
EX_NETCONMODE   A
EX_NETOURIP     127.0.0.1
EX_NETTHEIRIP   127.0.0.1

Note that when message is received back from other host, it is sent for correlation service so that we can match the response. For this particular case the invocation did look like:

N:NDRX:5:26407:7f21c98357c0:000:20170131:010926331:_tplog.c:0099:CORSVC: Incoming request:
EX_NETCONNID    6481138401960525826
EX_NETGATEWAY   TCP_P_ASYNC_P
EX_NETDATA      AELLP!XPSME\01\11\12\13\14UFTU\00
EX_NETOURPORT   29999
EX_NETTHEIRPORT 53972
EX_NETCONMODE   A
EX_NETOURIP     127.0.0.1
EX_NETTHEIRIP   127.0.0.1
t:USER:4:26407:7f21c98357c0:000:20170131:010926331:estsv.go:0081:Extracted correlator: [AELL]
N:NDRX:5:26407:7f21c98357c0:000:20170131:010926331:_tplog.c:0099:Reply buffer afrer correl
EX_NETCONNID    6481138401960525826
EX_NETGATEWAY   TCP_P_ASYNC_P
EX_NETCORR      AELL
EX_NETDATA      AELLP!XPSME\01\11\12\13\14UFTU\00
EX_NETOURPORT   29999
EX_NETTHEIRPORT 53972
EX_NETCONMODE   A
EX_NETOURIP     127.0.0.1
EX_NETTHEIRIP   127.0.0.1

Example connection status buffer

The connection 2 is disconnected.

EX_NETCONNID    2
EX_NETGATEWAY   TCP_P_SYNC_A
EX_NETFLAGS     D

Note that connection related fields: EX_NETOURPORT/EX_NETTHEIRPORT/ EX_NETCONMODE/EX_NETOURIP/EX_NETTHEIRIP are present always when connection is established. In case if connection is closed, then these fields are optional and may not be present.

CONFIGURATION

The configuration is written in CCONFIG ini file. The section for tcp gateway is [@tcpgate/CCTAG]. The CCTAG is optional. Following parameters are available for tcp gateway:

gencore = GENERATE_OS_CORE_DUMPS
If set to 1, for signals 6 (abort), 11 (segmentation fault) default Operating System handlers will be restored instead of go handlers. This can be suitable when debugging cgo code. Default is 0.
workers_out = NUMBER_OF_XATMI_SESSIONS_FOR_OUTGOING_MESSAGES
Number of worker sessions for dispatching message to network on doing reply back to XATMI service caller. This basically is how many go threads will process the incoming requests. If system is short of the threads, the main XATMI thread waiting for incoming messages, will be suspended on waiting the free worker. In case of req_reply mode 3 (XATMI service sends to network by opening new connection and then closing), the workers_out must be bigger or equal number to max_connections. The recommendation is to use max_connections = workers_out*2 for this scenario. Default is 5.
workers_in = NUMBER_OF_XATMI_SESSIONS_FOR_INCOMING_MESSAGES
Number of XATMI and go thread workers processing the incoming messages. The pool of worker is used in case when connection receives data from network. The workers are used for invocation of incoming_svc. Default is 5.
gateway = TCP_GATEWAY_SERVICE_NAME
Gateway service name. This is service name which is advertised by the tcpgatesv for accessing the outgoing message facility. Default is TCPGATE.
framing = FRAMING_MODE
Framing mode code. This tells in what format message length is encoded. Described above. Shortly:

l+ - little endian byte order, does not include length of it self

L+ - little endian byte order, include length of it self

b+ - big endian byte order, does not include length of it self

B+ - big endian byte order, include length of it self

a+ - ASCII text byte order, does not include length by it self

A+ - ASCII text byte order, does include length by it self

p+ - packed BCD, does not include length by it self

P+ - packed BCD, does include length by it self

d - Use message stop indicator (set by delim_start)

D - Use message start & stop indicators (set by delim_stop)

framing_half_swap = 'SWAP_FRAMING_BYTES
If set to 1, framing length bytes will be swapped in middle. The framing bytes length must be even length. This affects l,L,b,B,a,A formats. This is suitable for connecting for payment networks like VISA Net. For example if we use format llll, and the message length in decimal is 217321, then in hex it will be 0x00,0x03,0x50,0xe9 by applying this parameter, the bytes that will be sent to network will be in following order: 0x50,0xe9,0x00,0x03. Default is 0
max_msg_len = 'MAX_MESSAGE_LENGTH
If set above 0, then parameter indicates max message length. This does not include framing bytes. If the incoming message goes over this number, the message is dropped and connection is restarted, because there might be error in framing byte readings by corrupted data. The default is 0.
delim_start = 'MESSAGE_START_DELIMITER
If using framing format D, the this paramter indicates the start of the incoming message. This basically is extra field which is tested when message is received. If the start of the message does not match the delimiter, the message is dropped and connection restarted. The syntac for the field is in hex format byte, e.g. "0x02". The default is 0x02 STX symbol.
delim_stop = 'MESSAGE_STOP_DELIMITER
If using framing format d or D this byte will indicate the message terminator symbol. The syntax for the field is in hex for .e.g "0x03". The default value is 0x03 ETX symbol.
framing_keephdr = MESSAGE_KEEP_HEADER
If set to y or Y indicates that received message should be delivered to target service as is with message length prefix included. Also this means that if message is send to network, then tcpgatesv shall receive full message length (at-least) with message length bytes included, which might be dummy as tpc gateway will re-write len indicator. Default is n.
framing_offset = MESSAGE_FRAMING_OFFSET
Number of bytes to skip in header to search for the message length bytes. If value is greater than zero, then framing_keephdr is automatically enabled. Also with this mode it is required that full message (including offset data and length bytes (which can be dummy)) must be present when sending message out. tcpgatesv will overwrite the bytes at offset to with calculated message length according to framing scheme. In case of periodic zero messages, the offset which is not the length part is filled with zero 0x00 bytes. Default is 0 - no offset used.
type = ACTIVE_PASSIVE_MODE
Gateway operation mode either it is passive (P) - waiting for incoming TCP connection, or it is active (A) - tcp client doing connection to network. In Case of active mode, it will try to open connections to network. If configured for persistent connections, then gateway will try to keep the max number of connections open. In case of passive mode, it will accept the max number of connections, set by max_connections parameter. The default is P - Passive.
ip = IP_ADDRESS
In case of active mode (type = A), this is ip address or network host name of the remote server. In case of passive mode (type = P), this indicates the binding ip address (or binding network host name) - on which tcpgatesv binary shall listen for incoming connections. The default is 0.0.0.0.
port = TCP_PORT_NUMBER
In case of active mode (type = A), this is port number to connect to. In case of passive mode (type = P), this is port number to listen on for incoming connections. The default is 7921.
incoming_svc = INCOMING_XATMI_SERVICE
Incoming service name to call when there is incoming message, that does not correspond to any caller waiting for answer. This is incoming message for which there is no correlation id (the corr_svc is not set or corr_svc service did not return EX_NETCORR field.
incoming_svc_sync = INCOMING_SVC_SYNC
Optional, if set to Y or y then it indicates that when there is incoming message the incoming_svc is invoked in synchronous way (tpcall()). If service response succeed (TPSUCCESS), then the return buffer with EX_NETDATA field is sent to network to the same connection from which incoming message was received. This mode alters the req_reply mode 0 (full async) and mode 1, by making invocations synchronous.
periodic_zero_msg = PERIODIC_ZERO
Number of seconds after which send to network zero length message for keeping connection alive. Used if number is greater that zero. Parameter is not suitable for non-persistent connections. I.e. it is not possible to use this paramter with req_reply modes 3 and 4. The default is 0.
in_idle_max = IN_IDLE_MAX
Max time in seconds after which connections with out any incoming network traffic will be reset. Thus if both ends of TCP connection are configured to send the periodic zero messages (or some other traffic), then connection is not reset. The tcpgate will monitor those connections, and if found that there are no inbound traffic for IN_IDLE_MAX time, then connection is closed. This works for active and passive connections. The default is 0 meaning functionality is disabled. If feature is enabled the it must be configured with in_idle_check parameter.
in_idle_check = IN_IDLE_CHECK
Number of seconds within scan_time to perform Inbound idle connection tests (in_idle_max) and connection reset if needed. If configured then in_idle_max must be set too. Also if Heartbeat is enabled (hb_mode=1), parameter is required. Default value is 0 - meaning disable inbound traffic check.
status_svc = STATUS_SERVICE_NAME
Name of the service which receives connection status updates. Parameter is optional, and if not set, then connection status updates will not be issued.
status_refresh = STATUS_REFRESH_SECONDS
Number of seconds to periodically send full connection status (disconnected/connected) to status_svc. Enabled if number is greater that 0. Parameter > 0 is valid only for persistent connection modes, i.e. req_reply values 0, 1, 2. And the status_svc must be defined. If condition is not met then tcpgatesv will not boot and print error in logfile. The default is 0.
max_connections = MAX_NR_OF_CONNECTIONS
Max number of simultaneous connections supported by gateway. In case of active mode and using persistent connections, this is the number of connects gateway will try to keep open (reconnect if needed). In case of non-persistent mode (ex-to-net, req_reply=3), the max_connections must be greater than workers_out. Recommended is max_connections twice as workers_out. In case of passive mode, this is max number of open incoming connections. If the incoming connections gets bigger number that this, the incoming connection will be closed. The default is 5.
req_reply = REQUEST_MODE
Request reply mode. This basically tells the tcpgatesv role and the mode in which gateway will operate. Default is 0. Following modes are defined:

0 - Persistent connection mode, asynchronous messages, including sync with correlation. Supported connection type active (A) and passive (P). In active mode gateway will try to establish the max number of connections. In passive mode gateway waits for max number of incoming connections.

When XATMI client invokes the gateway service, the service waits for outgoing (workers_out) XATMI context object. If object is acquired, the message is submitted to free network connection thread for further processing. If the connection id is specified by EX_NETCONNID, then connection is searched, if not found reject is generated, if found the message is enqueued. At this point response is generated and send back to caller either success (message sent to network thread) or error.

When message is received from network, and correlation service corr_svc returns EX_NETCORR field, then reply waiter (XATMI request object waiting for reply) is located, if found, then reply is passed back to caller. If reply is not found or EX_NETCORR does not exists in UBF buffer, then incoming message is passed to incoming_svc. The invocation is done with tpacall(3), TPNOREPLY mode. Meaning that no answer is waited back from target server back to tcpgatesv.

In correlated connections, the time-out waiting on network is determined by req_reply_timeout parameter in seconds.

1 - Persistent, sync by connection, Enduro/X sends to Network. No matter of the role from active or passive (both are supported in this mode). The connection will be opened as in req_reply mode 0 (above). But the difference is that each invocation will be done in synchronous way, meaning that for each connection only one request can be be sent at the same time. When the response is received from network, the waiter is looked up by connection id. If waiter is found then answer is delivered to waiter with tpreturn(3). If waiter is not found, then target service incoming_svc is called in asynchronous way with out waiting a reply. This can be suitable for cases to detect any late response messages. The service name can be set to dummy one. If service invocation generates error, it will be logged in logfile and connection will continue to serve.

In correlated connections, the time-out waiting on network is determined by req_reply_timeout parameter in seconds.

2 - Persistent, sync by connection, Network sends to Enduro/X. The role of connection type active or passive does not matter here. The connection establishment will be done according to req_reply mode 0 and 1. In this mode, connection receives request it waits for free workers_in XATMI object. Once incoming object is got, the service incoming_svc is invoked with tpcall(3). If response is received and EX_NETDATA is present, the answer is sent to network back. If service call did succeed, but EX_NETDATA is not present, connection is restarted. If service invocation did not succeed, the call is ignored. The timeout for service invocation is standard XATMI timeout flag (NDRX_TOUT environment or [@global] section parameter).

3 - Non-persistent, sync each request - new connection, Enduro/X sends to Net. In this mode for each of the requests, new connection is created. Once response is received, connection is closed. For this mode, type must be A - active, in order to establish a connection.

The time-out waiting on network is determined by req_reply_timeout parameter in seconds.

4 - In this mode Enduro/X receives connection from network and invokes target service incoming_svc. The invocation is done with tpcall(3). If call does not succeed, the error is ignored. If call succeeds but EX_NETDATA is not present connection is closed. If call did succeed and EX_NETDATA is present, the response message is prepared and sent back to network and then connection is closed.

The incoming_svc service invocation timeout is governed by NDRX_TOUT parameter.

In this mode the gateway must be configured in passive mode (waiting for connection), i.e. type=P.

req_reply_timeout = REQUEST_TIMEOUT
Request time-out in seconds. This parameter is used for monitoring outgoing connection’s synchronous messaging. When the incoming requester did tpcall(3) of the advertised gateway service, and the EX_NETCORR was present or the connection mode was 1 or 3. The calls are put in waiter lists. Gateway periodically scans the connection waiter lists (period is set by scan_time parameter). If the reply time is reached with no response, the caller will get back UBF response with EX_NERROR_CODE=8 (timeout). The default is 60 seconds.
scan_time = SCAN_TIME
The number of seconds where main Enduro/X dispatcher thread is interrupted in order to run time-out scans. For outgoing correlated connections (either by correlator id or by connection). The default is 1 - every second.
conn_wait_time = CONNECTION_WAIT_TIME
This is time-out time in seconds waiting for connection from connection pool (when connection is not identified by EX_NETCONNID. The parameter is effective only form req_reply modes 0 and 1. In case if timeout is reached, the error NENOCONN error 9 will be generated. The default is 60 seconds.
corr_svc = CORRELATION_SERVICE
Correlation service to invoke for incoming requests. This parameter is optional. The correlation service will not be used in parameter is not. The service is must have in order to work in req_reply mode 0 and have synchronous connections, because of missing correlation service, the gateway will be unable to find the reply waiter object. For other connection req_reply modes this is informative service that can populate the EX_NETCORR for incoming messages. NOTE that corr_svc have a rights to change the EX_NETDATA in reply so that when request or reply is coming in from network, the already parsed data can be delivered to incoming_svc. The default value for this field is unset (i.e. empty parameter - not used).
debug = DEBUG_STRING
Enduro/X standard debug string, see ndrxdebug.conf(5) manpage. The sample value could look like: 
[@tcpgate]
...
debug=ndrx=5 ubf=0 tp=5 file=/tmp/tcpgatesv.log

Meaning that Enduro/X internal ATMI level logging (ndrx setting) is set to 5 - debug, and user logging tp (tcpgatesv binary) logging also is set to 5 - debug. Output file will be set to /tmp/tcpgatesv.log. UBF logging is set to none.

seqin = SEQIN
If set to 1 dispatch incoming messages from network to XATMI service in one thread mode. Thus ensuring the order of the messages to be according to the message order in socket. The default is 0 - disabled, meaning that incoming messages are processed in out of order manner (processed by multiple threads).
seqout = SEQOUT
If set to 1, send outgoing messages in guaranteed fifo order aggregated by EX_NETCONNID. EX_NETCONNID can be compiled or simple id. The fifo will be performed by this number. It is up to programmer to ensure that same class of IDs are used, otherwise two competing queues can be create and fifo order will be disrupted. The default value is 0 - disabled, meaning that outgoing messages are processed in out of order manner (by multiple concurrent threads).
linger = LINGER_SECONDS
When socket is shut down, this is number of seconds to wait for unsent or unacknowledged to be processed on connection close. If set to 0, then operating system discards any such data on shutdown. If set above (>) 0, this is number of seconds to wait for data to be processed before discarding. If set less (<) than 0, then operating system default policy is used. Default is -1. This setting is not effective if tls_enable is set to 1.
tls_enable = TLS_SETTING
If set to 1, Transport Layer Security Mode is enabled. Default is 0 - not enabled.
tls_skip_verify = TLS_VERIFY_SETTING
In TLS mode, if set to 1, then client (active tcpgates) will ignore invalid server certificate. The default is 0 - server must be verified.
tls_cert_file = TLS_CERT_FILENAME
This is peer certificate/public key filename for TLS session. For passive tcpgatesv roles (server), this is mandatory setting. For active (client) tcpgatesv roles, this is optional. Certificate file must be in X.509 format.
tls_key_file = TLS_KEY_FILENAME
This is peer certificate private key filename for TLS session. For passive tcpgatesv roles (server), this is mandatory setting. For active (client) tcpgatesv roles, this is optional. Key file must be in X.509 format.
tls_ca_roots = TLS_CA_ROOTS_FILES
This list of Root Certificate Authority certificate chains, used for client/server certificate validation. Certificates must be in X.509 format. This is optional, if not specified system CA roots are used for certificate validation.
tls_client_auth = TLS_CLIENT_AUTH_SETTING
If value is set to 1, passive (server) tcpgatesv will validate incoming client certificate against CA roots, if client certificate is invalid, connection will be rejected/closed. Default value is 0 - do not validate client certificate.
tls_min_version = TLS_MIN_VERSION_SETTING
For TLS mode this indicates minimum TLS protocol version used for sessions. Valid values are TLS10 - TLS 1.0, TLS11 - TLS 1.1 and TLS12 - TLS 1.2. Default value is not specified, so peers will negotiate the protocol.
hb_mode = HEARTBEAT_MODE
If set to value 1 - this enables Heartbeat mode 1. See description bellow. Default value is 0 - disabled.

Heartbeat modes:

1 - Performs specific data block (configured in hb_data) sending to peer and waiting for the response. If response is not received in configured time (hb_rsp_timeout), connection is restarted. The mode may perform periodic Heartbeat sending (configured in hb_periodic_time) or idle time (configured in hb_idle_time), one or another strategy must be configured, but not both. Idle time messages are generated in case, if for given time period, no incoming traffic is received. Heartbeat processing uses tcpgatesv command framework. Heartbeat reply messages are recognized in incoming messages by the cmd_hb1 parameter (hex bytes) at the configured offset cmd_offset. To perform reply to the peer traffic, command framework is used and recognized command/data is configured in cmd_echo. To avoid sending such Heartbeat peer traffic to the incoming_svc, such commands shall be configured in cmd_nofwd (comma separated hex strings). To avoid echo of the received own responses, cmd_no_echo shall contain the command+data to which echo shall not be generated (which is configured automatically to cmd_hb1+hb_data in case if cmd_no_echo is empty).

Following is minimum sample configuration for Visa Extended Access Server – Centralized (EAS-C), for handling Heartbeat and Shutdown notification messages. VISA generated Heartbeat and Shutdown notification messages are echoed back. tcpgatesv would generate idle time Heartbeat messages. Session to application is open only after successful first Heartbeat message from our node.

[@tcpgate]
...
hb_mode=1
hb_session_init=1
# Originator ID for data
hb_data=F0F0F0F0F0F0F0F0
# Echo Heartbeat and Shutdown messages back to peer
cmd_echo=0020C8C2,0020E2C4
# Do not want to received at incoming_svc session control msgs
cmd_nofwd=0020
# Ignore incoming idle time messages, if any
cmd_nofwd_empty=0000
# Heartbeat command is 0020+HB
cmd_hb1=0020C8C2
# Command length - 2 bytes (VMLH byte 3 and byte 4)
cmd_nrbytes=2
in_idle_check=1

Sample settings for

hb_session_init = HEARTBEAT_SESSION_INIT
If set to value 1 - when connection is established, initial heart beat message is sent to the peer and only once the reply is received, the established connection status (EX_NETFLAGS=C) is reported to the status_svc. Default value is 0 - disabled. Used by Heartbeat mode 1.
hb_periodic_time = HEARTBEAT_PERIODIC_TIME
Number of seconds in which periodically send Heartbeat messages. Default is 0 - disabled. Used by Heartbeat mode 1. This flag is exclusive to hb_idle_time.
hb_idle_time = HEARTBEAT_IDLE_TIME
Number of seconds in which if no data was received from peer, the Heartbeat request would be made. Default value is 10. Used by Heartbeat mode 1. This flag is exclusive to hb_periodic_time. Value 0 disables functionality.
hb_rsp_timeout = HEARTBEAT_RESPONSE_TIMEOUT
Number of seconds in which reply is expected of our side issued Heartbeat. In case if response time is overreached, connection is restarted (i.e. closed and shall be open by our end or peer, depending on type flag). Default value is 2. Used by Heartbeat mode 1.
hb_data = HEARTBEAT_HEX_DATA
Hex string containing Heartbeat data to best to the peer. Used by Heartbeat mode 1. Field is mandatory to be set. Example value "C8C2F0F0F0F0F0F0F0F0".
cmd_echo = COMMAND_ECHO
Comma separated list of hex byte strings, for which commands found in incoming (from network) messages, echo shall be performed back. Commands are matched by the given hex bytes against the message received, starting from the cmd_offset. To match, data at offset shall fully start with any configured hex string Sample value "0020C8C2,0020E2C4". Default value is empty list.
cmd_no_echo = COMMAND_NO_ECHO
In case cmd_echo match, this is list comma separated hex byte string, for which echo is not performed. The match principles are the same as for cmd_echo. For Heartbeat mode 1, if parameter is not configured or empty, cmd_no_echo value is set to cmd_hb1+hb_data (to avoid Heartbeat echo on response messages).
cmd_notify = COMMAND_NOTIFY
Comma separated hex strings of binary data for commands (with following portions of data) to match on incoming message at cmd_offset, and if any matched, send notification to status_svc. In such case, EX_NETFLAGS would be set to M=<message in hex>. Default value is empty list.
cmd_nofwd = COMMAND_NOFWD
Comma separated hex strings of binary data for commands (with following portions of data) to match on incoming message at cmd_offset, and if any matched, do not send incoming message to incoming_svc. Default is empty list.
cmd_nofwd_empty = COMMAND_NOFWD_EMPTY
Comma separated hex strings of binary data for commands to match on incoming message at cmd_offset, and if any matched, and there are no more message bytes after the cmd_offset+cmd_nrbytes - do not send such incoming message to incoming_svc. Default is empty list. Maybe used for idle time / zero length message commands.
cmd_hb1 = COMMAND_HB1
Hex string of binary data for Heartbeat mode 1 command (with following portions of data) to match on incoming message at cmd_offset. If matched, Heartbeat mode 1 would be enabled. Required if hb_mode is set to 1. Default value is empty.
cmd_nrbytes = CMD_NUMBER_OF_BYTES
Number of bytes used for command codes in the message. Default is 0. If using Heartbeat, the value must be greater than 0.
cmd_offset = CMD_OFFSET
Command code bytes offset in message. Value must be non negative number. Default is 0. If using offset > 0, cmd_keep must be set to 1.
cmd_incl_len = CMD_INCL_LEN
If set to 1, indicates that command bytes are included in message length. Default is 0, meaning that message framing bytes does not include command bytes of the message.
cmd_keep = CMD_KEEP
If set to 1, indicates that messages sent to tcpgatesv from user application and receiving incoming messages (sent to incoming_svc), does include command bytes. Default is 0, meaning that final messages does not include command bytes.
cmd_default = CMD_DEFAULT
Hex string of command bytes, pre-pended to outgoing messages. In case if cmd_nrbytes is > 0 and this parameter is set, then value is configured to number of cmd_nrbytes zero bytes (0x00).

EXIT STATUS

0
Success
1
Failure

EXAMPLE

To see the usage different usage settings, see tests/02_tcpgatesv/runtime/conf/tcpgate.ini'.

Typical configuration would look like:

[@tcpgate]
gateway=TESTSVC
incoming_svc=INCSVC
type=P
framing=ll
periodic_zero_msg=60
ip=0.0.0.0
port=9999
max_connections=10

BUGS

Report bugs to support@mavimax.com

Golang compiler problems:

go1.14 introduced use of SIGURG for internal purposes of the language runtime. This causes Enduro/X Unix system calls to interrupt with EINTR, which can lead to incorrect work of the binary using Enduro/X Go bindings.

The bug is reported here: https://github.com/golang/go/issues/50521

While this bug is not fixed, the tcpgatesv shall be started with following environment variable set:

export GODEBUG="asyncpreemptoff=1"

The setting may be applied to app.ini in [@global] section as:

[@global]
...
GODEBUG=asyncpreemptoff=1

Issues with MacOS:

In case if running software for MacOS, it might be required to set:

# defaults write NSGlobalDomain NSAppSleepDisabled -bool YES

Otherwise tcpgatesv binary might receive Go panics. Otherwise in high processing intensity, system warns user in dmesg with:

process tpcgatesv[43069] caught causing excessive wakeups. Observed wakeups rate...

And in this result, seems like Go binary is interrupted by OS, which causes Go binary to corrupt its internal scheduler.

Also problems is found with MacOS only when background processes (with out TTY) are running. If user logins in shell and executes the tcpgatesv tests, then problems does not appear.

SEE ALSO

restincl(8) restoutsv(8).

COPYING

© Mavimax Ltd