EntireX Version 9.7
 —  Administration under UNIX  —

Administering the Attach Manager under UNIX

EntireX includes an Attach Manager (ATM) for UNIX and Windows. This is used to start servers if a client requests a particular service from the Broker, but a server for that service is not active.

This document covers the following topics:


Prerequisites

The Attach Manager needs the following:

Top of page

Setting up the Attach Manager

If you do not need the ATM for your own services, you do not need to perform any configuration for the ATM. A default configuration file AtmDefault.cfg.txt comes with the EntireX installation and contains the necessary configuration to start the EntireX sample servers. The file is located in the EntireX config directory. In the current version of EntireX, the ATM is not launched automatically by default. If you want to activate an automatic launch, just rename the configuration file AtmDefault.cfg.txt to AtmDefault.cfg With the next reboot ATM is then launched automatically.

The Attach Manager is located in the bin subdirectory under the installed EntireX directory. The name of the executable is exxatm.exe. If you need to start an ATM manually for any reason, start it using this executable. You can start multiple ATMs, for example to run them under different accounts. But all ATM instances should share the same configuration file. The configuration file is organized in so-called sections to support multiple ATM instances. Without further command line arguments, the ATM uses the default section within the default configuration file. See Operating the Attach Manager for possible command line arguments.

The syntax of the text-based configuration file is simple and is very similar to a Windows INI file.

Syntax Element Description
; Lines beginning with a semicolon are comment lines.
[ ] Lines that contain text in square brackets are section headers.
Keyword=Value Lines that are of the form Keyword=Value are keyword lines.

Note:
Any of the values of the keywords in the configuration file can be set as environment variables.

There are three different types of sections in the configuration file:

The general structure of the configuration file is the following:

[Default]
;  The parameters of the Default ATM
[Default_Services]
SERVICE1=
SERVICE2=
[SERVICE1]
;  The parameters for SERVICE1
[SERVICE2]
;  The parameters for SERVICE1

Parameters of the ATM Section

These sections define the Attach Manager itself and contain the keywords indicated in this table. There can be up to 16 of these sections.

Keyword Definition and Value Format Example Notes
BrokerID= The Broker that ATM will communicate with and answer attach requests. Any valid ACI BROKERID value is allowed. A32 BrokerID=server1:1971:TCP  
SSLParms= Secure Sockets Layer Parameters for Brokers that use SSL Transport. A512 SSLParms=VERIFY_ SERVER= N&TRUST_STORE= C:\\Temp\\ExxCACert.pem  

ServerClass=

ServerName=

Service=

The CLASS/SERVER/SERVICE names that can be used by ATM to send commands to ATM. (See details of this feature.)
The CLASS/SERVER/SERVICE name needs to be defined in the Broker Attributes.
A32

[for all keywords]

ServerClass=System

ServerName=DefaultMain

Service=Command

 
UserID= The User ID of the ATM. A32 UserID=atman  
Token= The Token of the ATM (used for unique identification of the User ID). There is a special value of {GeneratedToken} which will generate a unique 32-byte value for the ATM. A32 Token=atm
Token={GeneratedToken}
 
Password= Password for the User ID. A32 Password=atman  
WaitTime= During the specified time, the Attach Manager waits for a response. After expiration of the time, the Attach Manager receives a timeout. This is used as the WAIT time on the ATM's RECEIVE call. A8
[identical to Broker control block WAIT parameter]
WaitTime=5M
Default: 60S
 
RecvLength= Size of the buffer that is available for receiving orders. I4

[identical to Broker control block RECEIVE-LENGTH parameter]

RecvLength=12000
Default: 8000
 
HistoryFile= File name for logging orders that have been received for restarting. If this keyword is not specified, no file is written. This can be any valid file name. Valid path name for dependent platform. See example. HistoryFile=%TEMP%\
Default.his
 
HistoryFileMode= When starting the Attach Manager, you can decide here whether the current file is to be overwritten or not. w or a+t HistoryFileMode=w File is newly opened for writing; the old file is deleted.
HistoryFileMode=a+t Writing of the old file is continued.
LogFile= Log information is logged here about the current status of the Attach Manager. If this keyword is not specified, no file is written. Valid path name for dependent platform. See example. LogFile=%TEMP%\
Default1.log
 
LogFileMode= When starting the Attach Manager, the administrator can decide whether the current file is to be overwritten or not.
The file can get very large.
w or a+t LogFileMode=w File is newly opened for writing; the old file is deleted.
LogFileMode=a+t Writing of the old file is continued.
Sleep= If the Attach Manager cannot register successfully during startup, or if a connection is broken, the Attach Manager waits this specified time in seconds and then tries again. You can limit the number of connection attempts, using the keyword Retries=n. I4 Sleep=120  
Retries= If registration fails, the number of subsequent registration attempts can be limited. the keyword Sleep determines the wait time before a new registration attempt. Setting Retries=0 deactivates this functionality. I4 Retries=0 Default value is 0.
ShutdownByUserRequest= When set to 1, the ATM can be stopped when a command is sent to it to shut down. If it is set to zero, it will restart automatically. See example. Values:

0: Attach Manager restarts. The configuration file is read anew.

1: Attach Manager terminates itself.

 

Parameters of the Service List Section

This section names the Service sections that will be used to define the services that will be attached. The prefix of the name of the section must match a specific instance of the AttachManager(n) sections.

Example: Assume there are three services to be attached. They can be logically defined as follows:

Default_Services]
payroll=
inventory=
qualitycontrol=

Therefore, there will be three optional sections following: [payroll], [inventory], and [qualitycontrol].

Parameters of the Service Section

There can be any number of Service sections attached to an ATM by means of its corresponding Service List section. The Service sections are used to define the actual commands that will be issued by ATM to attach servers to respond to Broker requests

The following are the keywords that can be used:

Keyword Definition Format Example

ServerClass=

ServerName=

Service=

The CLASS/SERVER/SERVICE name of the service to be attached. A32

ServerClass=ACLASS

ServerName=ASERVER

Service=ASERVICE

Min= The minimum number of servers that should be active. I4 Min=3
Max= The maximum number of servers that should be active. I4 Max=7
Increment= The number that should be started when a request is made, up to the number indicated by Max= I4 Increment=1
Command= Command-line command to be issued that will start the service. Specifies (a) the fully qualified path to the location of the executable to be run and (b) the options for that executable. See example. Command=c:\server\bcos32.exe

Example from table above: If there are no instances of the service ACLASS:ASERVER;ASERVICE REGISTERED, the command indicated in the Command= keyword will be issued three times.

Top of page

Sample Configuration File

Note:
A sample configuration file is provided in the /config directory of EntireX. This sample defines two ATMs: Default and AttachManager2. The default ATM supports only the services related to Default.

[Default]
;
; Specify the broker to which the Attach Manager attaches and
; the channel on which the Attach Manager listens for command
; requests.
;
BrokerID=localhost:1971:TCP
ServerClass=System
ServerName=DefaultMain
Service=Command
UserID=%USERNAME%
Token={GeneratedToken}
Password=Hugo
WaitTime=30s
RecvLength=12000

; Activities will be written to the history file (optional)
HistoryFile=%TEMP%\Default.his
HistoryFileMode=a+t

; Log messages will be written to the log file (optional)
LogFile=%TEMP%\Default.log
; Append to an existing file
;LogFileMode=a+t
; Create a new file
LogFileMode=w

Sleep=10
Retries=0

ShutdownByUserRequest=1

;
;
; Default's services
;
[Default_Services]
AServer=
BServer=
;
[AServer]
ServerClass=ACLASS
ServerName=ASERVER
Service=ASERVICE
Min=2
Max=3
Increment=1
Command=bcos32 -c<ServerClass> -s<ServerName> -v<Service> -b<BrokerID> -i500
;
[BServer]
ServerClass=BCLASS
ServerName=BSERVER
Service=BSERVICE
Min=1
Max=1
Increment=1
Command=bcos32 -c<ServerClass> -s<ServerName> -v<Service> -b<BrokerID> -i750
[AttachManager2]
;
; Specify the broker to which the Attach Manager attaches and
; the channel on which the Attach Manager listens for command
; requests.
;
BrokerID=localhost:1971:TCP
ServerClass=System
ServerName=AttachManager2Main
Service=Command
UserID=%USERNAME%
Token={GeneratedToken}
Password=Hugo
WaitTime=30s
RecvLength=12000

; Activities will be written to the history file (optional)
HistoryFile=%TEMP%\AttachManager2.his
HistoryFileMode=a+t

; Log messages will be written to the log file (optional)
LogFile=%TEMP%\AttachManager2.log
; Append to an existing file
;LogFileMode=a+t
; Create a new file
LogFileMode=w

Sleep=10

ShutdownByUserRequest=1
;
; AttachManager2's services
;
[AttachManager2_Services]
CServer=
;
[CServer]
ServerClass=CCLASS
ServerName=CSERVER
Service=CSERVICE
Min=1
Max=1
Increment=1
Command=bcos32 -c<ServerClass> -s<ServerName> -v<Service> -b<BrokerID> -i1000

Top of page

Operating the Attach Manager under UNIX

Under normal circumstances, no manual operation is not necessary if the default ATM satisfies your needs. However, if you need to run multiple ATMs in your environment, this section describes how to perform the necessary operations. This section covers the following topics:

Starting the Attach Manager

Start of instruction setTo start an Attach Manager

Notes:

  1. With the -N argument you specify the ATM section for which the Attach Manager is responsible for. If this argument is omitted the attach manager is responsible for the default section.
  2. With the -F argument you specify the location of the configuration file. If this argument is omitted, the Attach Manager uses the default configuration file. All ATM instances should use the same configuration file, so we recommend you use the default file for the default ATM.
  3. The Attach Manager writes output to stdout. If you start the Attach Manager as a background process, stdout must be redirected to a file.

Stopping the Attach Manager

Start of instruction setTo stop an Attach Manager

Logging the Attach Manager

The ATM log file is defined by the ATM configuration parameter LogFile. If the Attach Manager is launched automatically, it writes additional log information to file exxatm.out in the EntireX subdirectory config\etb\ETBSRV.

In addition to the ATM log file, a history file is defined by the ATM configuration parameter HistoryFile. For each order to launch a service, the ATM writes a record into the history file. The history record has the following format:

Attach Manager Processing

Key

Top of page