...
Atheos Server must be updated to version xx.yy.zz
Update Create the new configuration file
Update the configuration of the component ??????????????????????
...
/etc/amadis/atheosgw++.conf
Keep the previous configuration file
These packages must be installed libboost-program-options1.65.1 and libboost-filesystem1.65.1
Atheos Server must be updated to version xx.yy.zz
This is pretty straight forward. It should be handled the same way as the previous updates. The changes introduced to support version 3 of the Gateway are listed in the Atheos Server release notes.
Update the configuration file
The default configuration distributed with the Gateway version 3 contains many comments. This section contains general information that describes the overall configuration file. The sample configuration file is given at the end of this section.
NOTE: The content of the configuration is case-sensitive.
Currently, the sections defined in the configuration are:
LogFile
MessagesRepositories
Connectivity
ServerSSLCertificate
ServerSSLPrivateKey
Security Provider sections
OpenSSL
Performance
Nexo
PoiConfigurations
LogFile
The log file was defined in previous versions using only the parameter LogFile. It is now a section which contains the following parameters:
...
Parameter
...
Previous parameter
...
URI
...
LogFile
...
DirectoriesPermissions
...
n/a
...
FilePermissions
...
n/a
The URI parameter define the file that will be used for the log file. A fully qualified file name is required. It must comply to the following format: file://fully-qualified-filename. As an example, if the log file to be used is /var/log/amadis/atheosgw.log, the parameter should be:
Code Block | ||
---|---|---|
| ||
URI = file:///var/log/amadis/atheosgw.log |
Any missing directories in the log file path will be created with the permissions specified by the parameter DirectoriesPermissions.
The log file permissions will be set to the value of the parameter FilePermissions.
The permission values must be numerical. As an example, the permission rw-r--r shall be given as 0644. The leading zero is important which explicitly qualify an octal value.
Parameters that are no longer in the configuration file
These parameters must be moved into the specific configuration files
MOVED
ASFileUploadSignatureKey
NexoMessagesUploadURL
GatewayId
DELETED
DebugDumpMessages
...
Command line parameters
This version supports the following command line parameters:
Parameters | Description |
---|---|
-c arg or --config arg | Configuration file. By default, /etc/amadis/atheosgw++.conf is used. |
-d | Adds to the log some debug information |
Update the configuration file
The default configuration distributed with the Gateway version 3 contains many comments. This section contains general information that describes the overall configuration file. The sample configuration file is given at the end of this section.
NOTE: The content of the configuration is case-sensitive.
Currently, the sections defined in the configuration are:
LogFile
MessagesRepositories
Connectivity
ServerSSLCertificate
ServerSSLPrivateKey
Performance
PoiConfigurations
Nexo
Security Provider sections
OpenSSL
HSM
LogFile
The log file was defined in previous versions using only the parameter LogFile. It is now a section which contains the following parameters:
Parameters | Previous parameters |
---|---|
URI | LogFile |
DirectoriesPermissions | n/a |
FilePermissions | n/a |
The URI parameter define the file that will be used for the log file. A fully qualified file name is required. It must comply to the following format: file://fully-qualified-filename. As an example, if the log file to be used is /var/log/amadis/atheosgw.log, the parameter should be:
Code Block | ||
---|---|---|
| ||
URI = file:///var/log/amadis/atheosgw.log |
Any missing directories in the log file path will be created with the permissions specified by the parameter DirectoriesPermissions. So, Atheos Gateway must have the rights to create the directories. If it is not the case, the directories must be created using another method.
The log file permissions will be set to the value of the parameter FilePermissions. For example, 0755. The leading zero is required.
The permission values must be numerical. As an example, the permission rw-r--r shall be given as 0644. The leading zero is important which explicitly qualify an octal value.
MessagesRepositories
The exchanged messages between the POI and the Gateway are stored temporarily in a directory structure before being uploaded to the Atheos Server. The related parameters are:
Parameters | Previous Parameters |
---|---|
BaseDirectory | FileRepositoryBaseDir |
DirectoriesPermissions | n/a |
FilePermissions | n/a |
The base directory is given by the parameter BaseDirectory. This parameter must be a fully qualified filename. As an example:
Code Block |
---|
BaseDirectory = /home/amadis/files |
Any missing directories in the path will be created with the permissions specified by the parameter DirectoriesPermissions. So, Atheos Gateway must have the rights to create the directories. If it is not the case, the directories must be created using another method.
The sub-structure required in this directory will be created and assigned the permissions given by DirectoriesPermissions. For example, 0755. The leading zero is required.
The permissions of the files containing the messages will be set to the value of the parameter FilePermissions.
The permission values must be numerical. As an example, the permission rw-r--r shall be given as 0644. The leading zero is important which explicitly qualify an octal value.
Connectivity
The network connectivity parameters are specified in this section. They are:
Parameters | Previous parameters |
---|---|
ListeningPort | ServerPort |
BindingAddress | BindingAddress |
The parameter ListeningPort is the port onto which the Gateway will listen for incoming connections.
The BindingAddress is the address onto which the Gateway will listen for incoming connections. Setting it to 0.0.0.0 will make the Gateway listen to any network interface on the server.
ServerSSLCertificate
This section specifies the certificate that will be used to authenticate itself to the POI.
Parameters | Previous parameters |
---|---|
CryptographicProvider | n/a |
Type | n/a |
Format | n/a |
URI | ServerCertificateFile |
The CryptographicProvider qualifies the provider that will provide the required resource. The parameters Type, Format and URI depends on the provider. They may be used or not. More information is given in the Cryptographic Providers of this page. As of version 03.00.00, only OpenSSL is supported.
ServerSSLPrivateKey
This section specifies the private key related to the certificate given in section ServerSSLCertificate that will be used to authenticate itself to the POI.
Parameters | Previous parameters |
---|---|
CryptographicProvider | n/a |
Type | n/a |
Format | n/a |
URI | ServerPrivateKey for a private key contained in a file. |
The CryptographicProvider qualifies the provider that will provide the required resource. The parameters Type, Format and URI depends on the provider. They may be used or not. More information is given in the Cryptographic Providers section of this page. As of version 03.00.00, only OpenSSL and HSM’s are supported.
Performance
This section contains various parameters that will have an influence on the performance of the Gateway. If you are in doubt about the the consequences that a parameter value may have, contact the technical support.
Parameters | Previous parameters | Level |
---|---|---|
MaximumConnections | MaximumConnections | Normal |
PendingConnectionQueueLength | PendingConnectionQueueLength | Normal |
ListeningMaximumWaitTime | ListenPollingPeriod | Advanced |
SocketSelectMaximumWaitTime | SSLReadWaitTimeSec and SSLReadWaitTimeuSec | Advanced |
SSLTimeout | SSLTimeout | Normal |
ShutdownDelay | ShutdownDelay | Normal |
NexoMessageInitialBufferSize | n/a | Advanced |
NexoBuilderBufferSize | n/a | Advanced |
NexoBuilderErrorMessagesBufferSize | n/a | Advanced |
MaximumConnections
Maximum number of concurrent connections the server will handle before queuing the other ones. Up to 10000 connections can be handle simultaneously by a single server. This parameter should be below 9000 to stay on the safe side. It is an operating system limit.
PendingConnectionQueueLength
Size of the queue if the MaximumConnections has been reached. If the queue is empty, the other connections will be refused.
ListeningMaximumWaitTime
Maximum number of microseconds the listening thread will be blocked before doing an house keeping cycle. Typically, 100000 microseconds is a sweet spot.
SocketSelectMaximumWaitTime
Maximum number of microseconds the socket event manager will be blocked before doing an house keeping cycle. Typically, 100000 microseconds is a sweet spot.
SSLTimeout
Maximum time in seconds the connection with a POI will be kept open without receiving any data. Passed this threshold, the connection with the POI will be terminated. In normal operation condition, 60 seconds is a prefered value.
ShutdownDelay
Maximum time in seconds that the server will wait for the currently active connections to terminate when it received a shutdown (HUP) event. Beyond this delay, any non normally closed connection will be terminated.
NexoMessageInitialBufferSize
Initial buffer size in bytes used to parse the received Nexo messages. This value shall be modified if recommended by the technical support.
NexoBuilderBufferSize
Buffer size in bytes used to build outgoing Nexo messages. This value shall be modified if recommended by the technical support.
NexoBuilderErrorMessagesBufferSize
Buffer size used to store error messages while building or parsing Nexo messages. This value shall be modified if recommended by the technical support.
PoiConfigurations
This section relates to the directory structure used to store the POI configurations. The parameter are:
Parameters | Previous parameters |
---|---|
BaseDirectory | POIDataRoot |
DirectoriesPermissions | n/a |
BaseDirectory is the top directory where the POI configuration will be stored. There will be one sub-directory for each POI that has a configuration defined named after the POI ID.
If the BaseDirectory does not exists, it will be created and will have its permissions assigned to the value of the parameter DirectoriesPermissions. For example, 0755. The leading zero is required.
Nexo
This section contains parameters that will be embedded into the configuration sent to the POI’s.
Parameters | Previous parameters |
---|---|
ProtocolVersion | NexoTMSProtocolVersion |
TerminalManagerId | TerminalManagerId |
ProtocolVersion refers to the supported Nexo version. Currently, it is 6.0.
TerminalManagerId is the terminal id that will be embedded into the configuration messages sent to the POI’s.
Parameters that are no longer in the configuration file
These parameters must be moved into the specific configuration files .
MOVED
ASFileUploadSignatureKey
NexoMessagesUploadURL
GatewayId
User
Group
DELETED
DebugDumpMessages
Sample Configuration
Code Block |
---|
############################################################################### # # Atheos Gateway V3 Configuration File # # Copyright ©2005-2021 - 9164-4187 QUEBEC INC (“AMADIS”), All Rights Reserved # ############################################################################### # [LogFile] # Log file location. A fully qualified file name must be supplied. URI = file:///var/log/amadis/atheosgw.log # Directories permissions DirectoriesPermissions = 0770 # File permissions FilePermissions = 0640 [MessagesRepositories] # Base directory where the messages received and sent to the POI are saved. # Previously FileRepositoryBaseDir BaseDirectory=/home/amadis/files # Directories permissions for the message repositories DirectoriesPermissions = 0770 |
...
# |
...
File |
...
permissions |
...
for the |
...
message |
...
repositories |
...
FilePermissions |
...
= 0640 |
...
|
...
[Connectivity] |
...
# |
...
Server incoming connection port. Previously ServerPort ListeningPort = 55554 # Address on which the server |
...
will |
...
bind (listen) |
...
to. |
...
BindingAddress |
...
old file
...
= 0.0.0.0 # Server certificate used [ServerSSLCertificate] CryptographicProvider = OpenSSL Type = X509Certificate Format = PEM URI = file://server.crt # Private key for the server certificate. Password protected keys are not # supported yet. [ServerSSLPrivateKey] CryptographicProvider = OpenSSL Type = PrivateKey Format = PEM URI=file://server.unprotected.key #[ServerSSLPrivateKey] #CryptographicProvider = hsm1 #Type = PrivateKey #URI = pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=abe6ed66024f38b2;token=claude;id=%40%00;object=serverkey;type=private;pin-value=4321 [hsm1] # Engine type (internal or HSM) Type = PKCS11HSM # Engine ID ID=pkcs11 # Engine library path SOPath=/usr/lib/x86_64-linux-gnu/engines-1.1/libpkcs11.so # Engine module path as required by the engine shared object library. ModulePath=/usr/lib/softhsm/libsofthsm2.so # Engine PIN PIN=4321 [OpenSSL] Type = OpenSSL Version = 1.0.0 [Performance] # Maximum number of concurrent connections the server will |
...
handle before # |
...
queuing |
...
the |
...
other |
...
ones. MaximumConnections |
...
= |
...
10 # |
...
Pending |
...
connections |
...
queue |
...
length. |
...
|
...
If MaximumConnections is reached, up to # PendingConnectionQueueLength connections will be queued before rejecting # them. PendingConnectionQueueLength = 200 # Maximium wait time while listening for a new connection in microseconds. ListeningMaximumWaitTime = 100000 # Time in seconds the server will wait before terminating # active connections. ShutdownDelay = 60 # Timeout in seconds of a connection with a POI. SSLTimeout = 60 # Maximum wait time when waiting for an event on a socket. SocketSelectMaximumWaitTime = 100000 # Nexo message initial input buffer size in bytes. This value shall not be # lower than 2000 bytes. NexoMessageInitialBufferSize = 48000 # Nexo Builder Buffer size in bytes. NexoBuilderErrorMessagesBufferSize bytes # are reverved as the error message buffer. NexoBuilderBufferSize = 48000 # How much space to reserve in the Nexo Builder Buffer for error messages. # It must be lower than 3072. NexoBuilderErrorMessagesBufferSize = 1024 [Nexo] # Nexo protocol version included in the Nexo messages ProtocolVersion = 6.0 # Terminal Manager Id |
...
included |
...
in |
...
the |
...
Nexo |
...
messages
TerminalManagerId=ATHEOS-TMS01
[PoiConfigurations]
# Base directory root where the configuration files and
# the management plans for the POIs are located.
BaseDirectory = /home/amadis/poi
# Directories permissions for the POI configuration repositories
DirectoriesPermissions = 0770 |