User Tools

Site Tools


Sidebar

Table Of Contents

endurox:v7.5.x:manuals:ndrxconfig.xml.5

ndrxconfig.xml

Name

ndrxconfig.xml — Enduro/X ATMI Application Domain configuration

Synopsis

<?xml version="1.0" ?>
<endurox>
    <appconfig>
        <sanity>SANITY_SECONDS</sanity>
        <checkpm>CHECKPM_STY</checkpm>
        <brrefresh>BRIDGE_REFRESH_TIME</brrefresh>
        <restart_min>MIN_RESTART_TIME</restart_min>
        <restart_step>RESTART_STEP</restart_step>
        <restart_max>MAX_RESTART_TIME</restart_max>
        <restart_to_check>NDRXD_RESTART_TO_CHECK</restart_to_check>
        <gather_pq_stats>NDRXD_GATHER_PQ_STATS</gather_pq_stats>
        <rqaddrttl>RQADDRTTL</rqaddrttl>
        <ddrreload>DDRRELOAD</ddrreload>
    </appconfig>
    <defaults>
        <min>MIN_SERVERS_DEFAULT</min>
        <max>MAX_SERVERS_DEFAULT</max>
        <mindispatchthreads>MIN_DISPTHREADS_DEFAULT</mindispatchthreads>
        <maxdispatchthreads>MAX_DISPTHREADS_DEFAULT</maxdispatchthreads>
        <autokill>AUTOKILL_DEFAULT</autokill>
        <env>ENV_OVERRIDE_DEFAULT</env>
        <start_max>MAX_STARTUP_TIME_DEFAULT</start_max>
        <pingtime>PING_EVERY_TIME_DEFAULT</pingtime>
        <ping_max>MAX_PING_TIME_DEFAULT</ping_max>
        <end_max>MAX_SERVER_SHUTDOWN_TIME_DEFAULT</end_max>
        <killtime>KILL_TIME_DEFAULT</killtime>
        <exportsvcs>EXPORT_SERVICES_DEFAULT</exportsvcs>
        <blacklistsvcs>BLACKLIST_SERVICES_DEFAULT</blacklistsvcs>
        <srvstartwait>NDRXD_SRV_START_WAIT_DEFAULT</srvstartwait>
        <srvstopwait>NDRXD_SRV_STOP_WAITT_DEFAULT</srvstopwait>
        <cctag>COMMON_CONFIG_TAG_DEFAULT</cctag>
        <protected>PROTECTED_SERVER_DEFAULT</protected>
        <reloadonchange>RELOAD_ON_CHANGE_DEFAULT</reloadonchange>
        <rssmax>RSSMAX_DEFAULT</rssmax>
        <vszmax>VSZMAX_DEFAULT</vszmax>
        <rqaddr>RQADDR_DEFAULT</rqaddr>
        <envs group="SVGRP_ENV_GROUP_NAME">
            <env name="SVGRP_ENV_VARIABLE_NAME">SVGRP_ENV_VARIABLE_VALUE</env>
            <env name="SVGRP_ENV_VARIABLE_NAME_1" unset="SVGRP_ENV_UNSET" />
            ...
            <env name="SVGRP_ENV_VARIABLE_NAME_N">SVGRP_ENV_VARIABLE_VALUE_N</env>
        </envs>
        ...
        <envs group="SVGRP_ENV_GROUP_NAME_N">
            ...
        </envs>
    </defaults>
    <servers>
        <server name="SERVER_BINARY_NAME">
            <min>MIN_SERVERS_SRV</min>
            <max>MAX_SERVERS_SRV</max>
            <mindispatchthreads>MIN_DISPTHREADS_SERVER</mindispatchthreads>
            <maxdispatchthreads>MAX_DISPTHREADS_SERVER</maxdispatchthreads>
            <autokill>AUTOKILL_SRV</autokill>
            <respawn>RESPAWN_SRV<respawn>
            <env>ENV_OVERRIDE_SRV</env>
            <start_max>MAX_STARTUP_TIME_SRV</start_max>
            <pingtime>PING_EVERY_TIME_SRV</pingtime>
            <ping_max>MAX_PING_TIME_SRV</ping_max>
            <end_max>MAX_SERVER_SHUTDOWN_TIME_SRV</end_max>
            <killtime>KILL_TIME_SRV</killtime>
            <sleep_after>SECONDS_TO_SLEEP_AFTER_SRV_START</sleep_after>
            <srvid>SERVER_ID</srvid>
            <sysopt>ATMI_SERVER_SYSTEM_OPTIONS</sysopt>
            <appopt>ATMI_SERVER_APPLICATION_OPTIONS</appopt>
            <exportsvcs>ATMI_SERVER_EXPORT_SERVICES</exportsvcs>
            <blacklistsvcs>ATMI_BLACKLIST_SERVICES</blacklistsvcs>
            <srvstartwait>NDRXD_SRV_START_WAIT</srvstartwait>
            <srvstopwait>NDRXD_SRV_STOP_WAITT</srvstopwait>
            <cctag>COMMON_CONFIG_TAG</cctag>
            <protected>PROTECTED_SERVER</protected>
            <reloadonchange>RELOAD_ON_CHANGE_SERVER</reloadonchange>
            <fullpath>ATMI_SERVER_FULL_PATH</fullpath>
            <cmdline>ATMI_SERVER_COMMAND_LINE</cmdline>
            <rssmax>ATMI_SERVER_RSSMAX</rssmax>
            <vszmax>ATMI_SERVER_VSZMAX</vszmax>
            <rqaddr>RQADDR</rqaddr>
            <envs>
                <usegroup>SVGRP_ENV_GROUP_NAME</usegroup>
                ...
                <usegroup>SVGRP_ENV_GROUP_NAME_N</usegroup>
                <env name="SVPROC_ENV_VARIABLE_NAME">SVPROC_ENV_VARIABLE_VALUE</env>
                <env name="SVPROC_ENV_VARIABLE_NAME_UNSET" unset="SVPROC_ENV_UNSET" />
                ...
                <env name="SVPROC_ENV_VARIABLE_NAME_N">SVPROC_ENV_VARIABLE_VALUE_N</env>
            </envs>
        </server>
        ...
        <server name="SERVER_BINARY_NAME_N">
            ...
        </server>
    </servers>
    <clients>
        <envs group="CLTGRP_ENV_GROUP_NAME">
            <env name="CLTGRP_ENV_VARIABLE_NAME">CLTGRP_ENV_VARIABLE_VALUE</env>
            <env name="CLTGRP_ENV_VARIABLE_NAME_UNSET" unset="CLTGRP_ENV_UNSET" />
            ...
            <env name="CLTGRP_ENV_VARIABLE_NAME_N">CLTGRP_ENV_VARIABLE_VALUE_N</env>
        </envs>
        ...
        <envs group="CLTGRP_ENV_GROUP_NAME_N">
            ...
        </envs>
        <client cmdline="CLT_COMMAND_LINE [${NDRX_CLTTAG} ${NDRX_CLTSUBSECT}]"
            log="CLT_LOG"
            stdout="CLT_STDOUT"
            stderr="CLT_STDERR"
            env="CLTGRP_ENV"
            cctag="CLT_CCTAG"
            wd="CLT_WD"
            klevel="CLT_KLEVEL"
            autostart="CLT_AUTOSTART"
            rssmax="CLT_RSSMAX"
            vszmax="CLT_VSZMAX"
            subsectfrom="CLT_SUBSECTFROM"
            subsectto="CLT_SUBSECTTO"
            >

            <envs>
                <usegroup>CLTGRP_ENV_GROUP_NAME</usegroup>
                ...
                <usegroup>CLTGRP_ENV_GROUP_NAME_N</usegroup>
                <env name="CLTPROC_ENV_VARIABLE_NAME">CLTPROC_ENV_VARIABLE_VALUE</env>
                <env name="CLTPROC_ENV_VARIABLE_NAME_UNSET" unset="CLTPROC_ENV_UNSET" />
                ...
                <env name="CLPROC_ENV_VARIABLE_NAME_N">CLTPROC_ENV_VARIABLE_VALUE_N</env>
            </envs>

            <exec tag="CLT_TAG_EXEC"
                subsect="CLT_SUBSECT_EXEC"
                log="CLT_LOG_EXEC"
                stdout="CLT_STDOUT_EXEC"
                stderr="CLT_STDERR_EXEC"
                env="CLTGRP_ENV_EXEC"
                cctag="CLT_CCTAG_EXEC"
                wd="CLT_WD_EXEC"
                autostart="CLT_AUTOSTART_EXEC"
                klevel="CLT_KLEVEL_EXEC"
                rssmax="CLT_RSSMAX_EXEC"
                vszmax="CLT_VSZMAX_EXEC"
                subsectfrom="CLT_SUBSECTFROM_EXEC"
                subsectto="CLT_SUBSECTTO_EXEC"
                />
            <exec tag="CLT_TAG_EXEC2"
                subsect="CLT_SUBSECT2_EXEC2"
                .../>
        </client>
        <client cmdline="BINARY2" ...>
            <exec tag="CLT_EXE_TAG2" .../>
        </client>
    <clients>
    <services>
        <defaults prio="SVC_PRIO_DEF"
                 routing="SVC_ROUTE_NAME_DEF"
                 autotran="SVC_AUTOTRAN_DEF"
                 trantime="SVC_TRANTIME_DEF"/>
        ...
        <service svcnm="SVC_SERVICE_NAME"
                 prio="SVC_PRIO"
                 routing="SVC_ROUTE_NAME"
                 autotran="SVC_AUTOTRAN"
                 trantime="SVC_TRANTIME"/>
        ...
    </services>
    <routing>
        <route routing="ROUTE_NAME">
            <field>ROUTE_FIELD</field>
            <ranges>ROUTE_RANGES</ranges>
            <buftype>ROUTE_BUFFER</buftype>
            <fieldtype>ROUTE_FIELDTYPE</fieldtype>
        </route>
        ...
    </routing>
</endurox>

DESCRIPTION

ndrxconfig.xml holds the application domain configuration. It describes the ATMI servers which needs to be started. Counts of the, how much to start. Also it describes sanity times i.e. period after which system sanity checks should be made. Also it describes time frames in which ATMI server should start or stop. Internal server ping can be configured here too.

PARAMETERS

SANITY_SECONDS
Number of seconds after which perform system sanity checks. This number should divide by environment variable value NDRX_CMDWAIT. As this actually is time by which ndrxd sleeps periodically.
CHECKPM_STY
This is number of sanity cycles into which check dead processes from the process model. This makes the actual checking of th PID existence system. Thus if ndrxd is started in learning mode and will not receive signals of the dead servers, then by setting it will discover exited processes.
BRIDGE_REFRESH_TIME
Number of sanity units in which tpbridge(8) refresh should be send to other node. If for example SANITY_SECONDS is set to 10, and BRIDGE_REFRESH_TIME is set to 2 then period between bridge refreshes will be 10*2 = 20 seconds. Default value is 0 - do not send full updates.
MIN_RESTART_TIME
Number of sanity units in which died server will be tried to start back. This is minimal time, means that this time is applied in case if server was running and died. If it is consecutive try, then RESTART_STEP is applied on this timer.
RESTART_STEP
Number to sanity units to apply on MIN_RESTART_TIME in case of consecutive server death. Meaning that next try of restart will tried later that previous by this number of sanity units.
MAX_RESTART_TIME
Max number of sanity units after which server will tried to restart. After each consecutive ATMI server death, next reboot is tried by MIN_RESTART_TIME+RESTART_STEP*try_count. If this goes over the MAX_RESTART_TIME then MAX_RESTART_TIME is used instead.
NDRXD_RESTART_TO_CHECK
Number of seconds for ndrxd to wait after daemon started in recovery mode. Within this time no sanity checks are perfomed, but instead "learning" mode is used. During this mode, ndrxd asks each ATMI server for it’s configuration. If in this time ATMI server does not responds, then ATMI server is subject of sanity checks.
NDRXD_GATHER_PQ_STATS
Settings for pq xadmin command. if set to Y, ndrxd will automatically collect stats for service queues. In future this might be used for automatic service starting and stopping.
RQADDRTTL
Used only when operating System V queues mode. Due to common queue for multiple services / basically all service queues are shared request addresses, the only zapping approach when there are no servers on queues, is to check that in service shared memory there are no linked request address queues, and at time perform unlink of the request address queue. But here we have a problem. The XATMI server might just started up, opened the RQADDR queue, but did not yet managed to install record in service shared memory. Thus ndrxd will unlink the RQADDR. To avoid this issue, with TTL slight delay is introduced, after which queue is unlinked. Basically when queue is open it’s change time is updated. And if current time minus change time is less than RQADDRTTL, then queue is not unlinked (in this time server will be able to add record to service shared memory). Also with this comes a fact that there must be no server processes without any service. For those request address queue will be unlinked. The value is in seconds. Checks are performed with SANITY_SECONDS intervals. Default value is 10 seconds.
DDRRELOAD
This setting identifies the number of sanity cycles used to wait for updating DDR routing tables on the fly with "xadmin reload" command. Default value is 60. This deferred approach is used for purpose, that it protects any processes which are in previous version of DDR routing tables and has not yet completed. Routing details are stored in double buffered routing pages for lock-less operations. If using smaller number of cycles, then it would increase the probability of corrupted routing, if administrator is doing config reload twice in a row with routing config changed. Thus these cycles give opportunity for any processes to complete routing. Overall chance that process will get corrupted pages with this approach is very low. As reload must be performed twice, and process shall be stalled for some reason in routing table, which by it self is very fast operation if ndrxd logging is turned off, as routing basically is CPU-RAM operation. Even if any such process was unable to complete the route, the error is detected and service call might return TPESYSTEM and corresponding ULOG message is written.
MIN_SERVERS_DEFAULT
Default minimum number of copies of the server which needs to be started automatically. This can be overridden by MIN_SERVERS_SRV per server.
MAX_SERVERS_DEFAULT
Max number of ATMI server copies per ATMI server entry. The difference between MIN and MAX servers means the number of standby servers configured. They can be started by hand without system re-configuration. But they are not booted automatically at system startup. You will have to start them with $ xadmin start -s <server_name> or by $ xadmin start -i <server_id>. This can be overridden by MAX_SERVERS_SRV.
MAX_DISPTHREADS_DEFAULT
This configures the maximum number of dispatch threads (workers) for XATMI servers dispatcher. Default value is 1. If set grater than 1, then XATMI server library booted in multi-thread mode and thread pool of workers is intialized. The number of workers threads is configured by MIN_DISPTHREADS_DEFAULT / MIN_DISPTHREADS_SERVER configuration values. If XATMI server is not built for multi-thread mode (flag -t was not passed to buildserver(8) or _tmbuilt_with_thread_option extern variable before XATMI server main routine start was not set to 1), the binary startup will fall-back to single-thread mode and warning is printed in ULOG.
MIN_DISPTHREADS_DEFAULT
This is actual number of dispatch threads (workers) used by XATMI server service dispatcher. By default this is 1. In case if <maxdispatchthreads> was set to 1 (default), then multi-thread is not used and the main thread is performing dispatch operations. The value of MIN_DISPTHREADS_DEFAULT may be overridden by MIN_DISPTHREADS_SERVER value. The MIN_DISPTHREADS_DEFAULT/ MIN_DISPTHREADS_SERVER must be less or equal to MAX_DISPTHREADS_DEFAULT/ MAX_DISPTHREADS_SERVER.
AUTOKILL_DEFAULT
Should server be automatically killed (by sequence signal sequence -2, -15, -9) in case if server have been starting up too long, or does not respond to pings too long, or it is performing shutdown too long. This can be overridden by AUTOKILL_SRV on per server basis.
ENV_OVERRIDE_DEFAULT
Full path to file containing environment variable overrides. see ex_envover(5) for more details. This can be overridden by per server basis by ENV_OVERRIDE_SRV. Both are optional settings.
MAX_STARTUP_TIME_DEFAULT
Max time (in sanity units) in which server should start up, i.e. send init info to ndrxd. If during this time server have not initialized, it is being restarted. This can be overridden by MAX_STARTUP_TIME_SRV.
PING_EVERY_TIME_DEFAULT
Number of sanity units in which perform periodical server pings. This can be overridden by PING_EVERY_TIME_SRV. Zero value disables ping.
MAX_PING_TIME_DEFAULT
Number of sanity units, time in which server must respond to ping requests. If there is no response from server within this time, then restart sequence is initiated. This can be overridden by MAX_PING_TIME_SRV.
MAX_SERVER_SHUTDOWN_TIME_DEFAULT
Maximum time in which shutdown of server must complete in sanity units. If in given time server is not shutdown, then forced shutdown sequence is started until server exits. This can be overridden by MAX_SERVER_SHUTDOWN_TIME_SRV on per server basis.
EXPORT_SERVICES_DEFAULT
Comma separated list of services to be applied to all binaries which means the list of services to be exported by tpbridge server to other cluster node. This can be overridden by ATMI_SERVER_EXPORT_SERVICES.
BLACKLIST_SERVICES_DEFAULT
Comma separated list of services to be applied to all server binaries which means the list of services that must not be exported by tpbridge server to other cluster node. ATMI_SERVER_BLACKLIST_SERVICES is first priority over the EXPORT_SERVICES_DEFAULT if service appears in both lists. BLACKLIST_SERVICES_DEFAULT can be overridden by ATMI_SERVER_BLACKLIST_SERVICES.
NDRXD_SRV_START_WAIT_DEFAULT
Number of seconds to wait for servers to boot. If not started in given time, then continue with next server. This can be overridden by NDRXD_SRV_START_WAIT. Default value for this is 30 seconds.
NDRXD_SRV_STOP_WAIT_DEFAULT
Number of seconds to wait for server to shutdown. If not started in given time, then continue with next server. This can be overridden by NDRXD_SRV_STOP_WAIT_DEFAULT. Default value for this is 30 seconds.
KILL_TIME_DEFAULT
Time in sanity units after which to progress from first signal -2 to next signal -15. And after -15 this time means when next -9 signal will be sent. This is used if forced restart of forced shutdown was initiated by ndrxd. This can be overridden by KILL_TIME_SRV.
COMMON_CONFIG_TAG_DEFAULT
Common configuration tag. Loaded into NDRX_CCTAG environment variable before process is spawned. This can be overridden by COMMON_CONFIG_TAG.
PROTECTED_SERVER_DEFAULT
Protected server is one that does not shutdown with stop with xadmin stop -k (keep ndrxd running). If doing standard xadmin stop parameter then server is shutdown as all others. It is possible stop stop it by xadmin stop -i <srvid> or by xadmin stop -s <servernm>. The xadmin restart does not accept -k parameter thus protected server will be stopped too. The idea behind this, is to avoid accidental stop of the critical servers, like bridge or something else which is involved into ndrxd daemon management it self. This can be overridden by PROTECTED_SERVER.
RELOAD_ON_CHANGE_DEFAULT
If set to Y or y the ndrxd daemon will scan the every binaries time stamp, and if it detects that time stamp is changed ndrxd will reload (stop/start) the XATMI servers one by one. The scanning will occur at every sanity cycle. This is recommended to be used only for development purposes. And must not be used on production servers! This can be overridden by RELOAD_ON_CHANGE_SERVER on per server basis.
RSSMAX_DEFAULT
Maximum Resident Set Size memory size after which ndrxd(8) process will issue server reload (sr) command (i.e. gracefully shutdown and start back) to server process if particular server process resident memory goes over this defined value. The value can be override by ATMI_SERVER_RSSMAX for particular server instance. This parameter is useful to be used to protect local machine against defective/binaries with memory leaks. The parameter value is expressed in bytes. Configuration file also accepts suffixes such as "T" or "t" for terrabytes, "G" or "g" for gigabytes, "M" or "m" for megabytes and "K" or "k" for kilobytes. For example "10M" would limit resident memory to 10 megabytes. The default value is -1, which means that functionality is not used.
VSZMAX_DEFAULT
Maximum Virtual Set Size memory size (the number bytes program have asked to OS kernel for memory, but does it does not mean it is physically used or initialized) after which ndrxd(8) process will issue server reload (sr) command (i.e. gracefully shutdown and start back) to server process if particular server’s process virtual memory goes over this defined value. The value can be override by ATMI_SERVER_VSZMAX for particular server instance. This parameter is useful to be used to protect local machine defective/binaries with memory leaks. The parameter value is expressed in bytes. Configuration file also accepts suffixes such as "T" or "t" for terrabytes, "G" or "g" for gigabytes, "M" or "m" for megabytes and "K" or "k" for kilobytes. For example "10M" would limit resident memory to 10 megabytes. The default value is -1, which means that functionality is not used.
RQADDR_DEFAULT
Request address (common service queue) used in System V mode. For other modes each service have it’s own queue, but due to limitations of the System V queues, for each XATMI server process have it’s own queue (built as process /exe name and service id) or processes can share the queue by having this request address, thus getting a one queue multiple servers mechanism for message dispatching. Also all servers attached on the same request address must advertise all the services from all servers attached on the same request address. If some server will miss a service, it might receive request for particular service, the error will be logged and message will be dropped, thus caller will get a timeout. If different request addresses are serving the same service, then request will be load balanced in round-robin mode. This can be overridden by RQADDR on per server basis. Request address cannot start with @ symbol. The max length of the request address is 30 chars.
SECONDS_TO_SLEEP_AFTER_SRV_START
Number of seconds to wait for next item to start after the server is launched. This is useful in cases when for example we start bridge server, let it for some seconds to connect to other node, then continue with other service startup.
SERVER_BINARY_NAME
ATMI server executable’s name. The executable must be in $PATH. This name cannot contain special symbols like path separator / and it cannot contains commas ,! Commas are used as internal queue separator combined with binary names.
RESPAWN_SRV
Do the automatic process re-spawning if process is died for some reason. The default value is Y, meaning that processes are automatically recovered. If set to N or n, then sanity checks will not automatically re-boot the process.
SERVER_ID
Server ID. It is internal ID for server instance. For each separate ATMI server the ID must be unique. Also special care should be take when MAX_SERVERS_SRV is greater than 1. In this case up till MAX servers, internally SERVER_ID is incremented. Thus for example if SERVER_ID is 200, and MAX_SERVERS_SRV is 5, then following server IDs will be reserved: 200, 201, 202, 203, 204. The maximum server id is set in $NDRX_SRVMAX environment variable. Minimal server id is 1.
ATMI_SERVER_SYSTEM_OPTIONS
Command line system options passed to ATMI server. Following parameters are used by Enduro/X ATMI servers: -N, boolean type. If present, then no services will be advertised by server. In this case only services specified by -s (service alias) or -S (function alias) flags will be advertised. For example if server advertises SERVICE1, SERVICE2, SERVICE3, but -N is specified, and -sSERVICE3 is specified, then only service SERVICE3 will be advertised. The -s argument also can contain aliases for services, for example -sOTHERSVC:SERVICE2, then new service OTHERSVC will be advertised which basically is the same SERVICE2 (same function used). -s, -S and -N can be mixed. -s can appear multiple times in system options. With one -s multiple services can be aliased to single existing service. The format is: -s<NEWSVC1>/<NEWSVC2>/../<NEWSVCN>:<EXISTINGSVC>. The , can be used as separator too, but for certain platforms it does not work, thus / is recommended. Services can be masked out from final advertise by by -n flag. For example -nSERVICE4 will not be advertised (no matter was it advertise or alias). -n can be repeated multiple times. When Enduro/X XATMI server is build with integration lib (libatmisrvinteg) user have ability to alias the functions to service names with -S<service_name1>/<service_name2>[:<function name>] flag. Functions are passed to buildserver(8) at build time or registered in tmdsptchtbl_t array passed to _tmstartserver(3). If <function name> is not specified, then service name is matched against function name. Firstly -S flags are processed, afterwards -s' flags are processed, meaning that it works as usual including to function aliased services by -S services. Server binaries output is controlled via -eLOG_FILE, which means that stdout & stderr of server is dumped to LOG_FILE. There are few internal parameters: parameter -k is just a random key for shell scripts. Another internal parameter is Server ID which is automatically passed to binary via -i SERVER_ID. Enduro/X supports automatic buffer conversion for ATMI servers. Currently supported modes are JSON2UBF, UBF2JSON, these modes are activated by -x parameter in system options. These modes are passed for server functions being advertised. For example if we have service functions (not services) UBF1FUNC, UBF2FUNC and JSONFUNC and we want to ensure that these receive converted messages even if caller to UBF service sends JSON and vice versa, then following options might be set to command line: -xUBF1FUNC,UBF2FUNC:JSON2UBF -xJSONFUNC:UBF2JSON. With flag -g<RTGRP> it is possible to define or override the env variable NDRX_RTGRP - routing group code. Use -G flag to configure that particular server shall include @<RTGRP> routing group suffix in service name received by service function (i.e. structure TPSVCINFO field name shall contain full service name with the group code, if call was routed to group), by default group name is not included even if service is routed to group.
ATMI_SERVER_APPLICATION_OPTIONS
Application specific command line options. This follows content after sys options as: system options — app options.
ATMI_SERVER_EXPORT_SERVICES
Enduro/X server specific list of services to be exported. This list is only for tpbridge servers.
ATMI_SERVER_BLACKLIST_SERVICES
Enduro/X server specific list of services that must not be exported. This list is only for tpbridge servers. Blacklist have higher priority over the Export list.
ATMI_SERVER_FULL_PATH
This is full path of the XATMI server binary. At the process startup this overrides the server binary name at SERVER_BINARY_NAME. ATMI_SERVER_FULL_PATH is used only for process startup. This is intended for testing, if server wrapper scripts needs to be started. But as the ndrxd will do the sanity checks against the process names, for time of the testing this needs to be disabled. Thus to do the testings with full path enabled, please increase the checkpm sanity unit time. As at the moment of process model checks, the ndrxd will find out that wrapped binary name does not contain the SERVER_BINARY_NAME, thus will reboot the process.
ATMI_SERVER_COMMAND_LINE
This is alternative command line build by user. From this command line the real process name is extracted as first executable (basename). When building custom command line, the env substitution is available at the stage with following processes based envs (not counting the globals): NDRX_SVSRVID - Enduro/X server id, NDRX_SVPROCNAME - server process name (defined in XML config as SERVER_BINARY_NAME value, NDRX_SVCLOPT - standard command line options used by Enduro/X. These options are used at stage with ATMI server library gets initialized, it will use in case ndrx_main() receives less than expected standard argument count. Basically this command line tag is suitable for interpreted languages, like Java, where interpreter needs to be started as stand alone binary, and the Enduro/X is initialized as a library within stand alone process.
SVGRP_ENV_GROUP_NAME
Environment variable group name for the servers section. Identifier max length is 30 chars. Same group can be used for different server processes. One server may import multiple groups. For client processes groups are defined CLTGRP_ENV_GROUP_NAME name at <clients> section. At process level groups can be imported by using tag <usegroup> and specifying the group name. At that moment all variables defined in group are import for process.
SVGRP_ENV_VARIABLE_NAME
This server server’s group environment variable name, that shall be set for process which uses this group. For client processes CLTGRP_ENV_VARIABLE_NAME set the variable name at group definition. Individual environment variables can be set at process level. For server processes that is set by SVPROC_ENV_VARIABLE_NAME and for client processes by CLTPROC_ENV_VARIABLE_NAME.
SVGRP_ENV_VARIABLE_VALUE
This is environment variable value to be set. For client process groups this is defined by CLTGRP_ENV_VARIABLE_VALUE. For individual processes value is defined by SVPROC_ENV_VARIABLE_NAME and CLTPROC_ENV_VARIABLE_NAME accordingly. The value is interpreted by variable substitution algorithm (see bellow). The value is interpreted at time when process is spawned (not defined), meaning that it have access to full process variables at startup moment.
SVGRP_ENV_UNSET
If set to y or Y then environment’s environment variable is unset (removed) from environment. This can be used if some specific variable for process is not needed. At client environment group level this can be set by CLTGRP_ENV_UNSET, at process levels this can be set by SVPROC_ENV_UNSET and CLTPROC_ENV_UNSET accordingly. If any value is present for this variable, it is ignored, as the main action of this tag is unset the value and only what matters here is the variable name.
CLT_COMMAND_LINE
Executable name and arguments for client program. Command line basically is a format for subsection substitution. Other env variables available here too.
CLT_LOG
Logfile to which stdout and stderr is logged. Can be overridden by CLT_LOG_EXEC for each individual process. Optional attribute.
CLT_STDOUT
File where to log stdout. Can be overridden by CLT_STDOUT_EXEC for each individual process. Optional attribute.
CLT_STDERR
File where to log stderr. Can be overridden by CLT_STDERR_EXEC for each individual process. Optional attribute.
CLTGRP_ENV
Environment override file. See ex_envover(5) for syntax. Can be overridden by CLTGRP_ENV_EXEC for each individual process. Optional attribute.
CLT_CCTAG
ATMI Client lib Common-Config tag. Can be overridden by CLT_CCTAG_EXEC for each individual process. Optional attribute.
CLT_WD
Working directory for the process. Can be overridden by CLT_WD_EXEC.
CLT_AUTOSTART
Should process be started automatically? Y or y means boot at start. Can be overridden by CLT_AUTOSTART_EXEC for each individual process. Optional attribute. Default n.
CLT_TAG_EXEC
Tagname to be set for process.
CLT_SUBSECT_EXEC
Subsection to be set for process. - used as default.
CLT_RSSMAX
Maximum Resident Set Size memory size after which cpmsrv(8) process will gracefully kill the client process by signals -2, -15, -9 if particular client process resident memory goes over this defined value. After killing, the cpmsrv at first check interval will detect that client is dead, and at next check interval it will be respawned. The value can be override by CLT_RSSMAX_EXEC. This parameter is useful to be used to protect local machine against defective/binaries with memory leaks. The parameter value is expressed in bytes. Configuration file also accepts suffixes such as "T" or "t" for terrabytes, "G" or "g" for gigabytes, "M" or "m" for megabytes and "K" or "k" for kilobytes. For example "10M" would limit resident memory to 10 megabytes. The default value is -1, which means that functionality is not used.
CLT_VSZMAX
Maximum Virtual Set Size memory size (the number bytes program have asked to OS kernel for memory, but does it does not mean it is physically used or initialized) after which cpmsrv(8) process will gracefully kill the client process by signals -2, -15, -9 if particular client process virtual memory goes over this defined value. After killing, the cpmsrv at first check interval will detect that client is dead, and at next check interval it will be respawned. The value can be override by CLT_RSSMAX_EXEC. This parameter is useful to be used to protect local machine against defective/binaries with memory leaks. The parameter value is expressed in bytes. Configuration file also accepts suffixes such as "T" or "t" for terrabytes, "G" or "g" for gigabytes, "M" or "m" for megabytes and "K" or "k" for kilobytes. For example "10M" would limit resident memory to 10 megabytes. The default value is -1, which means that functionality is not used.
CLT_SUBSECTFROM
If set, then used to auto-generate number subsections for particular client definition. In this case CLT_SUBSECT_EXEC parameter value is ignored. The loop must start with non negative number and must not be greater than integer (2147483647) and less or equal to CLT_SUBSECTTO. Default is undefined and not used. Can be overridden by CLT_SUBSECTFROM_EXEC. Must be used together with CLT_SUBSECTTO.
CLT_SUBSECTTO
If set, then used to auto-generate number subsections for particular client definition. In this case CLT_SUBSECT_EXEC parameter value is ignored. The loop must end with non negative number and must not be greater than integer (2147483647). Default is undefined and not used. Can be overriden by CLT_SUBSECTFROM_EXEC. Must be used together with CLT_SUBSECTFROM.
CLT_KLEVEL
Kill level of the client. 0 - do not kill child processes recursively of the client, 1 - do kill child processes only when performing SIGKILL (-9), 2 - do kill on SIGTERM and SIGINT child processes. The default is 0.
SVC_SERVICE_NAME
Service name for which settings are being defined. Max service length is 30 symbols.
SVC_PRIO
Service call default priority. If value is not set, then it it is loaded from default value SVC_PRIO_DEF. If default is not set, then value 50 is used in the Enduro/X system. Priority is valid to be set in range of 1..100. This is used for Linux and FreeBSD OS. Note that values 1..100 may be downscaled prior doing mq_send() Posix function call, if operating system has lesser number of priorities available. Consult with your operating system documentation, particularly constant MQ_PRIO_MAX.
SVC_ROUTE_NAME
Routing criterion name. Which must reference valid routing definition under the <routing>/<route>, value ROUTE_NAME. If value is not specified, value is taken from SVC_ROUTING_NAME_DEF. This parameter is optional. If not set, then no routing is performed for service and messages are sent to default service. Max routing name length is 15 symbols.
SVC_AUTOTRAN
Automatic transaction mode for service. If parameter is set to y or Y, then if XATMI service is invoked without global transaction, the XATMI server will start the transaction automatically. When server process performs tpreturn(3), transaction is committed in case if server returns TPSUCCESS otherwise transaction is aborted. If process performs tpforward(3), then receiving server becomes transaction owner. If parameter is not specified value is taken from previously defined SVC_AUTOTRAN_DEF value. If it was not set, then default is N (no auto global transactions used by server). Note that this setting is extracted by XATMI server processes at the startup time. If configuration is change, say from N to Y, particular XATMI server processes needs to be restarted in order to enable automatic transactions for particular XATMI servers.
SVC_TRANTIME
Automatic transaction life time. This parameter is used by XATMI servers starting when automatic transactions are started. If value is not specified, then value is taken from previously defined SVC_TRANTIME_DEF. If this value also is not defined, then default value is 30.
ROUTE_NAME
This is route name using for data-dependent-routing (DDR). Route name max length is 15 symbols.
ROUTE_FIELD
This is route field name. Currently Enduro/X only supports UBF buffer routing, thus this field must contain valid/resolvable UBF field definition. Field types accepted four routing are BFLD_SHORT, BFLD_CHAR, BFLD_LONG, BFLD_FLOAT, BFLD_DOUBLE, BFLD_STRING and BFLD_CARRAY.
ROUTE_RANGES
Route ranges definition. Which defines the ranges by which destination service group is selected. See section "DATA DEPENDENT ROUTING" bellow for syntax details.
ROUTE_BUFFER
Buffer type accepted for routing. Currently supported buffer type is UBF. When service call is performed and routing exists for service, lookup is performed by using key: ROUTE_NAME and ROUTE_BUFFER. Thus for one service several routes might be defined. When service call is made, and no matching route (if was defined any route) and/or no matching range is found, error TPESYSTEM is returned for tpcall(3), tpacall(3) and related service routines.
ROUTE_FIELDTYPE
This specified how field shall be used in routing. Supported values are SHORT, CHAR, LONG, FLOAT, DOUBLE, STRING. Where the SHORT are internally mapped to LONG range, FLOAT is mapped to DOUBLE, CHAR is mapped to STRING. For UBF routes, this field is optional, and if it is not specified, then field type is extracted from UBF field. Additionally any BFLD_CARRAY is mapped to STRING.

VARIABLE SUBSTITUTION

Several parameters in the ndrxconfig.xml file are processed via substitution engine. Engine processes puts the environment variables or special functions in the place-holders. Placeholder is defined as ${ENV_VARIABLE} for environment variables and ${FUNC=[PARAMETER]} for functions. The value can be escaped with \${some_value}.

Functions are processed in case if statement in brackets contains equal sign =. As the sign is not allowed for environment variables, Enduro/X uses it to distinguish between env variable and function.

Following FUNC (functions) are defined:

dec Decrypt base64 string in PARAMETER and replace the placeholder with the value. To get encrypted value, it is possible to use exencrypt(8) tool.

DATA DEPENDENT ROUTING

Enduro/X supports data dependent routing. There are three components which are required for routing:

  1. Server process shall be put in the group. This can be be assigning group code to the NDRX_RTGRP environment variable for particular server process. This variable might be set in CCTAG group for server process. Or it might be assigned for particular process by <envs>. Here not that any server process which advertises services, will additionally advertise each service with suffix "@<NDRX_RTGRP>". Thus NDRX_RTGRP shall use short values like 2-3 symbols long, as total service name length is limited to 30, and if routing group name is longer, server processes would not be able to advertise. Also note that if this environment is present for server process, then any advertise mechanism, either alias or compiled service name by buildserver(8) or tpadvertise(3) call will make two services to appear in the system - one is default without the suffix and other is with route group suffix. Only exception when working with route groups is that xadmin unadv and xadmin readsv would operate with single service name.
  2. Routing criterion i.e. SVC_ROUTE_NAME must be defined for service in <service /> tag.
  3. Routing criterion must be defined in <route/> tag.

When all above is defined, the routing will be activated, when client (or servers code) would issue:

Also affects any other Enduro/X APIs which internally uses tpcall/tpacall. Such as tpenqueue(3), tpdequeue(3), tpbegin(3), etc. but it is not recommended to configure routing for Enduro/X system servers or services (or at least with out advice from Mavimax).

Routing criterions by it self operate with three data types: LONG, DOUBLE and STRING.

Syntax for ROUTE_RANGES is following: <min_value_1>-<max_value_1>:<group_code_1>,…, <min_value_N>-<max_value_N>:<group_code_N>. Additional syntax is supported, such as:

  • Keyword MIN - this represent any absolute minimum value, thus if value is bellow <max_value>, then value is in the range.
  • Keyword MAX - this represent any absolute maximum value, thus if value is above the <min_value> then value is in the range.
  • Single value is supported.
  • Keyword * (asterisk) - this presents the any value and represents whole range. This keyword can also be used as group, which means - use default group (i.e. it is any service, service name without "@<GRP>" suffix).
  • Values and group names can be put in single string quotes ('). If such single quote is needed within the string, it can be escaped with backslash \. Double backslash \\ is translated to single backslash.
  • Ranges supports max_value as negative, in such case syntax as "-100 - -45:GRPN" is supported.

Ranges value are validated and processed as indicated by field typ. LONG is limited to:

^[+-]?([0-9])+$

DOUBLE type value shall be expressed as:

^[-+]?(([0-9]*[.]?[0-9]+([ed][-+]?[0-9]+)?))$

For DOUBLE decimal separator is .. Also to check the equality is checked with precision of 0.000001.

STRING values may contain any printable character including newline.

When processes is perform routing, first matched range is used to extract the group code. If range is not found or buffer type does not match with service for which routing is defined TPESYSTEM error is returned to caller. Range matching is performed form left to right order. Range include the range min/max values. When range is defined for STRING type, values are compared by strcmp() function.

Examples of valid routing configuration:

<?xml version="1.0" ?>
<endurox>
...

    <services>
            <defaults routing="RT1"/>
            <service svcnm="DEBITSVC" />
            <service svcnm="CREDIT" routing="RT2" />
            <defaults routing="RT3" />
            <service svcnm="TXHANDLER" />
    </services>
    <routing>

        <route routing="RT1">
            <field>T_LONG_FLD</field>
            <ranges>MIN-4:GRP1,100-200:GRP4,300:GRP6,1000-22100:GRP5,*:*</ranges>
            <buftype>UBF</buftype>
        </route>

        <route routing="RT2">
            <field>T_STRING_FLD</field>
            <ranges>
                    MIN-'AAA':GRP1
                    ,'AAB' - AAC:'GRP4'
                    ,'HELLO\'' - HELLO5:*
                    ,'Z' - MAX:GRP6
            </ranges>
            <buftype>UBF</buftype>
        </route>

        <!-- cast value from string to double -->
        <route routing="RT3">
            <field>T_STRING_FLD</field>
            <ranges>
                    MIN - -1.1:GRP1
                    ,-1 - 44:'GRP4'
                    ,'44.1' - 123.15:*
                    ,*:*
            </ranges>
            <buftype>UBF</buftype>
            <fieldtype>DOUBLE</fieldtype>
        </route>
    <routing>
...
</endurox>


Note that *DDR* settings can be changed on they fly with *xadmin reload*, but
changes are deferred to certain amount of time. See 'DDRRELOAD'.

COMMAND LINE ARGUMENT ESCAPE

Process command line arguments normally may contain spaces or tables in their values. As Enduro/X processes needs to prepare arguments for exec, at prepare phase clear distinguishing must be made between multiple arguments and argument values. Thus Enduro/X employs parser to split CLI strings into arguments. Blocks with spaces or tabs inside must be quoted. The logic is similar to way how shall performs quote processing.

Following rules applies :

  1. Blocks can be quoted either with single quote or double quote.
  2. Quote symbols are stripped from the start and the end of the value.
  3. To have quote symbol in block value, use backslash.
  4. To have backslash in any part of CLI string, use double backslash.
  5. If block is started with single quotes, and value contains backlash and double quotes then backlash and double quotes are put in value. This works in vice versa if starting value with double quotes and escaping single quotes.
  6. If quoted string contains non tab or space separated values before or after the quotes, then values are joined to block value. Leading and trailing quotes are stripped.
  7. Alone escape values between tab or space separators are eliminated from value.
  8. Unterminated quotes produces single value till the end of string.

Samples:

Example 1:
CLI Value: someproc 'HELLO\' WORLD' X"some value \'"X

Process would receive arguments:
1. someproc
2. HELLO' WORLD
3. Xsome value \'X

Example 1:
CLI Value: someproc HELLO \ 'SOMETHING

Process would receive arguments:
1. someproc
2. HELLO
3.
4. SOMETHING

Above applies to CLT_COMMAND_LINE, ATMI_SERVER_SYSTEM_OPTIONS and ATMI_SERVER_APPLICATION_OPTIONS.

XML INCLUDE

ndrxconfig.xml supports entity substitution, thus effectively, portions of XMLs may be included from other files.

For example having ndrxconfig.xml:

<?xml version="1.0" ?>
<!DOCTYPE doc [
<!ENTITY defaults SYSTEM "ndrxconfig.xml.defaults">
]>
<endurox>
    <appconfig>
        <sanity>10</sanity>
        <brrefresh>6</brrefresh>
        <restart_min>1</restart_min>
        <restart_step>1</restart_step>
        <restart_max>5</restart_max>
        <restart_to_check>20</restart_to_check>
    </appconfig>

    &defaults;

    <servers>
    </servers>
</endurox>

and

ndrxconfig.xml.defaults:

    <defaults>
        <min>1</min>
        <max>2</max>
    </defaults>

would make final config for ndrxd(8) and cpmsrv(8) look like:

<?xml version="1.0" ?>
<endurox>
    <appconfig>
        <sanity>10</sanity>
        <brrefresh>6</brrefresh>
        <restart_min>1</restart_min>
        <restart_step>1</restart_step>
        <restart_max>5</restart_max>
        <restart_to_check>20</restart_to_check>
    </appconfig>

    <defaults>
        <min>1</min>
        <max>2</max>
    </defaults>

    <servers>
    </servers>
</endurox>

EXAMPLE

Sample configuration:

<?xml version="1.0" ?>
<endurox>
    <appconfig>
        <sanity>10</sanity>
        <brrefresh>6</brrefresh>
        <restart_min>1</restart_min>
        <restart_step>1</restart_step>
        <restart_max>5</restart_max>
        <restart_to_check>20</restart_to_check>
    </appconfig>
    <defaults>
        <min>1</min>
        <max>2</max>
        <autokill>1</autokill>
        <start_max>2</start_max>
        <pingtime>1</pingtime>
        <ping_max>4</ping_max>
        <end_max>3</end_max>
        <killtime>1</killtime>
        <envs group="JAVAENV">
            <env name="_JAVA_OPTIONS">-Xmx1g</env>
        </envs>
    </defaults>
    <servers>
        <server name="tpevsrv">
            <srvid>14</srvid>
            <min>1</min>
            <max>1</max>
            <cctag>RM1</cctag>
            <env>${NDRX_HOME}/tpevsrv_env</env>
            <sysopt>-e /tmp/TPEVSRV -r</sysopt>
        </server>
        <server name="tpbridge">
            <max>1</max>
            <srvid>100</srvid>
            <sysopt>-e /tmp/BRIDGE -r</sysopt>
            <appopt>-n2 -r -i 0.0.0.0 -p 4433 -tA</appopt>
        </server>
        <server name="jserver2">
            <max>1</max>
            <srvid>200</srvid>
            <sysopt>-e /tmp/BRIDGE -r</sysopt>
            <envs>
                <usegroup>JAVAENV</usegroup>
                <env name="NDRX_RTGRP">GRP4</env>
                <env name="CLASSPATH">${CLASSPATH}:${NDRX_APPHOME}/libs/${NDRX_SVPROCNAME}.jar</env>
                <env name="CLASSPATH">${NDRX_APPHOME}/libs/somelib.jar</env>
            </envs>
            <cmdline>java</cmdline>
        </server>
        <server name="cpmsrv">
            <cctag>RM2</cctag>
            <srvid>9999</srvid>
            <sysopt>-e /tmp/cpmsrv.log -r -- -k3 -i1</sysopt>
        </server>
    </servers>
    <clients>
        <client cmdline="testbinary -t ${NDRX_CLTTAG} -s ${NDRX_CLTSUBSECT}" autostart="Y" cctag="RM4">
            <exec tag="TAG1" subsect="SUBSECTION1" log="${APP_LOG}/testbin1-1.log" cctag="RM5"/>
            <exec tag="TAG2" subsect="SUBSECTION2" log="${APP_LOG}/testbin1-2.log"/>
        </client>
        <client cmdline="testenv.sh" env="environment.override1" log="env1.log">
            <exec tag="TESTENV" autostart="Y"/>
        </client>
    </clients>
    <services>
            <defaults trantime="600" />
            <service svcnm="SERVICE1" prio="50" routing="RT1"     autotran="Y"  />
            <defaults autotran="Y" />
            <service svcnm="SERVICE2" prio="50" routing="RT2"     trantime="600" />
    </services>
    <routing>
        <route routing="RT1">
            <field>T_LONG_FLD</field>
            <ranges>MIN-4:GRP1,100-300:GRP4,1000-22100:GRP5,*:*</ranges>
            <buftype>UBF</buftype>
        </route>

        <route routing="RT2">
            <field>T_STRING_FLD</field>
            <ranges>MIN-AAA:GRP1,'AAB'-'AAD':'GRP4',*:*</ranges>
            <buftype>UBF</buftype>
        </route>

    </routing>
</endurox>

BUGS

Report bugs to support@mavimax.com

COPYING

© Mavimax, Ltd