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:
The Attach Manager needs the following:
An active task registered at the Broker. As of EntireX 9.9, the ATM task is no longer launched automatically on each computer where EntireX is installed. See Setting up the Attach Manager for how to start the Attach Manager automatically or manually.
A list of services the ATM is responsible for, and information on how
to start the corresponding server for a particular service. The Attach Manager
can start only processes that are local to where it is running, that is, the
process that is attached will be run from the command line. There is no
restriction, however, on what the started command-line process does, including
starting a remote process on another system that will
REGISTER
as the server that satisfies the attach
request.
A configuration file that contains the service list the ATM is responsible for, information on how to start the corresponding server and additional configuration parameter to control the ATM functionality.
If you do not need the ATM for your own services, you do not need to perform any configuration for the ATM. For the default configuration EXXATM, a default configuration file EXXATM.cfg comes with the EntireX installation and contains the necessary configuration to start the EntireX sample servers. The file is located in directory EntireX/config/service/appl.EXXATM.
Notes:
etbsrv
uses the default section defined in the configuration file.
To launch the Attach Manager automatically
Activate automatic start after a reboot or after a restart of the Broker Adminstrator Service with the following command:
etbsrv SERVICE ATTR <configuration name> AUTOSTART=YES
For example:
etbsrv SERVICE ATTR EXXATM AUTOSTART=YES
With the next reboot, ATM is then launched automatically. The working directory is EntireX/config/service/appl.EXXATM. All log files are written to this directory. It also contains the configuration file EXXATM.cfg of the Attach Manager. See Configuration File Syntax.
To deactivate automatic start of the Attach Manager
Enter command:
etbsrv SERVICE ATTR <configuration name> AUTOSTART=NO
To check the status of the Attach Manager
Enter command:
etbsrv SERVICE STATUS <configuration name>
To start and stop the Attach Manager
Enter one of the following commands:
etbsrv SERVICE START <configuration name>
etbsrv SERVICE RESTART <configuration name>
etbsrv SERVICE STOP <configuration name>
To show the current status
Enter command:
etbsrv SERVICE STATUS
To set 'Run as' User
On Windows systems you can specify the credentials to start the Attach Manager under the specified user ID:
etbsrv RUN-AS-USER ENABLE <configuration name> <user> <password>
Note:
The user name and the encrypted password of 'Run as' user are written to the Attach Manager configuration file.
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. 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.
If you need multiple ATM instances, we recommend using a separate ATM configuration.
To create an Attach Manager configuration
Enter the following command:
etbsrv SERVICE CREATE <configuration name>
Note:
The created configuration is located in EntireX directory config/service/appl.<configuration name>
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 ATM section to configure a particular ATM instance. The ATM section with the name "Default" is the default section. If no section with the name "Default" is found, the first ATM section in the file is the default section. Each ATM section contains the configuration parameters of the corresponding ATM instance and has one related Service List section, which refers to the services that this ATM supports. Each ATM section needs exactly one ATM server attaching the related servers if requested.
The Service List section contains a list of names of Service sections. The name of the Service List section is the name of the related ATM section appended by "_Services".
The Service section configures a service, which consists of the service name and how to start the corresponding server.
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
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 broker ID 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.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
|
|||||
Password= |
Password for the user ID. | A32 |
Password=atman |
|||||
PwdEncrypted= |
Encrypted password for the user ID. If keyword PwdEncrypted is specified, keyword Password (containing the clear text password) can be omitted.If both keywords ( PwdEncrypted and Password ) are specified, the value PwdEncrypted is used.
|
A256 |
PwdEncrypted=1B6C607893FB89D... |
You can generate the encrypted password with command
etbnattr --echo_password_only -w clear_text_password |
||||
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 |
WaitTime=5M |
Identical to Broker control block WAIT parameter. Default=60S.
|
||||
RecvLength= |
Size of the buffer that is available for receiving orders. | I4
|
RecvLength=12000 |
Identical to Broker control block RECEIVE-LENGTH parameter. 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 |
|||||
DailyLogFile |
Split LogFile on a daily basis.
|
Y |
DailyLogFile=Y |
If more than one split mode is specified, the following logic is used:
|
||||
MonthlyLogFile |
Split LogFile on a monthly basis.
|
Y |
MonthlyLogFile=Y |
|||||
MaxSizeLogFile |
Split LogFile based on the configured file size (KB/MB/GB/TB/PB).
|
A32 |
MaxSizeLogFile=16GB or MaxSizeLogFile=10000 |
|||||
MaxTraceFiles |
Maximum number of backup files. | I4 |
MaxTraceFiles=3 |
Default=0 |
||||
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=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. | Values:
|
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]
.
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 keywords can be used:
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.
Note:
A sample configuration file is provided in the
\config folder 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=myservera -c<ServerClass> -s<ServerName> -v<Service> -b<BrokerID> -i500 ; [BServer] ServerClass=BCLASS ServerName=BSERVER Service=BSERVICE Min=1 Max=1 Increment=1 Command=myserverb -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=myserverc -c<ServerClass> -s<ServerName> -v<Service> -b<BrokerID> -i1000
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:
To start an Attach Manager
Enter command:
etbsrv SERVICE <configuration name>
Note:etbsrv
starts with the default section defined in the configuration file.
Or:
Either from the bin directory of EntireX
(or from any directory if the bin directory is in the PATH), enter the following command:
exxatm -F<full-path of Configuration file> -N<AttachManager1> -N<AttachManager2> ...
Notes:
-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.
-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.
To stop an Attach Manager
Use the script etbsrv
.
Or:
Use the command-line utility etbcmd
.
Or:
Press .
The ATM log file and a history file are defined by the ATM configuration parameters. For each order to launch a service, the ATM writes a record into the history file. The history record has the following format:
date and time
the service name as defined in the ATM config file
server name, server class and service
number of active replicates (this number is greater than 0 only if all running replicates are busy while a new client requests the service
number of server lookups, that is, the number of clients requesting a new replicate of the server; this is greater than 1 only if two clients request a service in parallel
replicate increment as defined in the ATM config file
number of replicates actually launched; this differs from the increment only if the high watermark is exceeded
Attach Manager registers with Broker, indicating that it will attach named services. These are called attach-managed services. | |
Client requests a service that is attach-managed. Server may or may not be active. If it is not, a server will be started (attached). | |
Attach request comes from the Broker. | |
Attach Manager issues command to start the server application. | |
Server application issues a LOGON to the Broker, then issues
REGISTER and RECEIVE . It gets message from client, processes the message, and
responds.
|
|
Response from server is received by the client application. |