omniNotify Logo Free High Performance CORBA Notification Service
from AT&T Laboratories		 ATT logo omniORB Home
AT&T Research
Home SF Project Features Release
Notes		 Download Instal-
lation		 Documen-
tation		 Patch &
Bug List		 More
Info		 Keep in
Touch

Back to Documentation Home

Configuring the omniNotify Service Daemon

An omniNotify server uses a number of configuration parameters during its start-up process. The values of these parameters influence the performance and default QoS properties of every event channel created by the server. Currently, the following alternatives are provided for the configuration of an omniNotify   server:

If none of these alternatives is used or a subset of the supported configuration parameters is provided, omniNotify uses default values for the missing parameters.

Note: The order of precedence for the different parameter setting mechanisms is as follows:
  1. Command-line flags have highest priority, and override all other mechanisms.
  2. Environment-variable settings have next-highest priority, and override configuration file settings and default settings.
  3. When a configuration file is specified, the values provided in the file override default settings.
  4. Each built-in default setting (described below) is only used if no override is present.

The names of the environment variables should be the same as the names of the supported configuration parameters.

Command Line Arguments

A omniNotify notification server can be started with the following command line arguments:

    notifd [ -i ] [ -h ] [ -v ] [ -n ] [ -c name ] [ CFGFLAGS ] [ ORBFLAGS ]

Argument Explanation
-i Enables interactive mode of operation. Here, commands can be entered in the window where the server is running.   There are a number of new interactive mode features; use 'help' for a full list of available commands.
-h Displays usage information.
-v Displays the current version of the omniNotify software release.
-n Disables the use of the Naming Service for registering the default event channel factory and event channel created by the server.
-c name The relative/absolute path to a configuration file to be read during initialization.
CFGFLAGS     These flags contain one or more components having the following format (no spaces before and after = should be used)

                         -Dparam_name=param_value

The name of param_name should belong to the list of configuration parameters which are supported by omniNotify. The supported configuration parameters are presented below, during the description of the configuration file contents.
ORBFLAGS These flags are ORB specific and should be used with care. Please read the configuration related section of the ORB documentation for the list of supported parameters and their  semantics.

 

Configuration Properties

The tables below contains the configuration properties supported by omniNotify. An explanation for each property is provided, together with the default value that is used when the property is not present in the configuration file nor provided as a command line argument.  

Misc. Startup Properties


These should be ServerQoS properties, but are not currently implemented that way.
Property Explanation Default
ChannelFactoryName The name assigned to the channel factory object created by the omniNotify   server. ChannelFactory 
DefaultChannelName The name assigned to default event channel created by the omniNotify server using the above channel factory. EventChannel
FactoryIORFileName The relative/absolute path name of the file where the string representation of the channel factory IOR is stored. /tmp/rdifact.ior
ChannelIORFileName The relative/absolute path name of the file where the string representation of the default event channel IOR is stored. /tmp/rdichan.ior
DebugLofFile If a pathname is given, the debug log is written to that file.  stdout and stderr can also be specified.

The debug flags below control what is written to the debug log.

 stderr 
ReportLogFile If a pathname is given, the report log is written to that file.  stdout and stderr can also be specified.

The report flags below control what is written to the report log.

 stdout 

Debug Flags:  0 is "off", 1 is "on"
DebugChannelFactory 0
DebugDaemon   0
DebugFilter 0
DebugChannel 0
DebugConsumerAdmin 0
DebugSupplierAdmin 0
DebugConsumerProxy 0
DebugSupplierProxy 0
DebugEventQueue 0
DebugRDIEvent 0
DebugFilterAdmin 0
DebugFilterEval 0
DebugCosConsumerProxies 0
DebugCosSupplierProxies 0
DebugNotifQoS 0
DebugAdminQoS 0
DebugNotifQueue 0

Report Flags:  0 is "off", 1 is "on"
ReportChannelStats 1
ReportQueueSizeStats 1
ReportConnectedConsumers 1
ReportConnectedSuppliers 1
ReportConnectedFilters 1
ReportUnconnectedFilters 1
ReportEventRejections 1
ReportEventDrops 1
ReportNotifQoS 1
ReportAdminQoS 1
ReportServerQoS 1

Initial ServerQoS Properties
Property Explanation Default
OutgoingTimeout Timeout in milliseconds for outgoing calls (such as push calls to connected push consumers, or try_pull calls to connected pull suppliers). If the roundtrip time for a call takes longer than this time, the call is terminated and the client is marked as disconnected by its proxy. At this point the client must connect using a DIFFERENT proxy if it wants to restore push/pull activity. (If 0 is specified, then no timeout is used.)

The default of 10000 (10 seconds) may need to be changed to reflect your operating environment. You may, for example, have push consumers that take a very long time to consume each event, in which case you may need to increase the value, or you may know that all calls should complete in less than .5 seconds, in which case you might want to set the value to, e.g., 1000 (1 second).

 2
OutgoingTimeout Timeout in milliseconds for outgoing calls (such as push calls to connected push consumers, or try_pull calls to connected pull suppliers). If the roundtrip time for a call takes longer than this time, the call is terminated and the client is marked as disconnected by its proxy. At this point the client must connect using a DIFFERENT proxy if it wants to restore push/pull activity. (If 0 is specified, then no timeout is used.)

The default of 10000 (10 seconds) may need to be changed to reflect your operating environment. You may, for example, have push consumers that take a very long time to consume each event, in which case you may need to increase the value, or you may know that all calls should complete in less than .5 seconds, in which case you might want to set the value to, e.g., 1000 (1 second).

 2

NOTE for above

 For omniORB3, which only does timeouts using seconds, a non-zero millisecond value is converted to the closest number of non-zero seconds (a non-zero value less than 1 is always rounded to 1, never to 0).  You should be using omniORB 4 anyway!  
NumAdminGroups ConsumerAdmin and SupplierAdmin objects created by an event channel are assigned to groups, and each such group is handled by a single thread. This parameter is intended for performance tuning only. It should not be changed without understanding the impact on resources and performance. 2
NumAdminThreads The number of threads created by an event channel to process the administrative groups. This number must be less than the number of groups, and it should not be changed without understanding the impact on resources and performance. 2
NumProxyThreads omniNotify may split the filter evaluation process into two steps. In this case, a second thread pool is created for evaluating the filters attached to the proxy objects connected to consumers. The size of this pool is controlled by the value of this parameter. This  parameter is intended for performance tuning only. It should not be changed without understanding the impact on resources and performance. 0
NumPushThreads Pushing events which pass the appropriate filters to consumers can be done by either using a pool of threads or dedicating one thread to each push consumer. When this value is set to 0, the latter approach is used. This  parameter is intended for performance tuning only. It should not be changed without understanding the impact on resources and performance. 4
NumPullThreads Pulling events from pull suppliers can be done by either using a pool of threads or dedicating one thread to each pull supplier. When this value is set to 0, the latter approach is used. This  parameter is intended for performance tuning only. It should not be changed without understanding the impact on resources and performance. 2
NumOChangeThreads offer_change messages are sent to connected consumers, except for those that have turned off this mechanism (see Section 3.4.2.5 of the CosNotification specification), by a pool of one or more 'OChange' threads.  This parameter sets the number of threads in this pool.  It is intended for performance tuning only, and should not be changed without understanding the impact on resources and performance.   CAREFUL: Setting NumOChangeThreads to 0 DISABLES all offer_change messages! 1
NumSChangeThreads subscription_change messages are sent to connected suppliers, except for those that have turned off this mechanism (see Section 3.4.1.3 of the CosNotification specification), by a pool of one or more 'SChange' threads.  This parameter sets the number of threads in this pool.  It is intended for performance tuning only, and should not be changed without understanding the impact on resources and performance.   CAREFUL: Setting NumSChangeThreads to 0 DISABLES all subscription_change messages! 1
PullEventPeriod The time period in seconds between successive event pulls from the same pull supplier. This  parameter is intended for performance tuning only. It should not be changed without understanding the impact on resources and performance. 100
ReportingInterval The time period in seconds between successive 'delta' reports written the report log by a reporting thread.  (Thus the default of 300 is a 5 minute interval.)  The value 0 is used to disable 'delta' reports.   300

Garbage Collection Notes

 N.B.: If omniNotify is compiled with -DNO_OBJ_GC, then no object garbage collection is performed and the following parameters are not available.

The channel, admin, proxy, and filter objects that are constructed by notifd sometimes become garbage: applications stop using them without properly destroying them. E.g., a client could create an admin and a proxy and then crash before it has a chance to use or destroy these objects. Unlike event queue garbage collection, it is hard or impossible for the notifd to know that an object is garbage: in some application scenarios, an object that is not used for more than 10 minutes should be considered garbage, while for other applications there might be valid objects that are only used once every 3 days. Each channel has an object garbage collection thread that is controlled by the following parameters.

 ObjectGCPeriod: period in seconds between object garbage collection steps. Set to 0 to disable.

 DeadChanInterval, DeadAdminInterval, DeadConProxyInterval, DeadOtherProxyInteral, DeadFilterInterval: if non-zero, these intervals (in seconds) specify how much time must pass since the last 'use' of one of these types of objects before the object can be considered garbage. For proxies, DeadConProxyInterval specifies the interval to use for connected proxies, and DeadOtherProxyInterval specifies the interval to use for other proxies. A proxy is not connected if (a) it has never been connected or (b) there has been a communication failure between the proxy and its connected supplier or consumer.

Rules for object garbage collection:

1. The default channel is never destroyed by the object garbage collector.

2. The default admins of the default channel are never destroyed by the object garbage collector.

3. A proxy is destroyed by the object garbage collector if all of the following hold:
     A. EITHER it is connected and has not been used for more than DeadConProxyInterval seconds
         OR it is not connected and has not been used for more than DeadOtherProxyInterval seconds.

         Note: if DeadConProxyInterval is set to zero, no connected proxies will be garbage collected.
        If DeadOtherProxyInterval is set to zero, no non-connected proxies will be garbage collected.

4. A non-default admin is destroyed by the object garbage collector if all of the following hold:
    A. It has not been used for more than DeadAdminInterval seconds.
    B. It has no connected proxies.
 
    Note: if DeadAdminInterval is set to zero, no admins will be garbage collected.
    Also note that garbage collection of proxies will enable garbage collection
    of admins, so turning off proxy GC can disable some admin GC.

5. A non-default channel, together with its default admins, is destroyed by the object garbage collector if all of the following hold:
    A. The channel has not been used for more than DeadChanInterval seconds.
    B. Neither default admin has been used for more than DeadAdminInterval seconds.
    C. Neither default admin has any connected proxies.
    D. There are no non-default admins.

        Note: if DeadAdminInterval or DeadChanInterval is set to zero, no
        channels will be garbage collected. Also note that garbage
        collection of admins will enable garbage collection of channels, so
        turning off admin GC can disable some channel GC.

6. A filter is destroyed by the object garbage collector if all of the following hold:
       A. It has not been used for more than DeadFilterInterval seconds.
       B. It is not attached to any proxy or admin objects.

        Note: if DeadFilterInterval is set to zero, no filters will be
        garbage collected. Also note that garbage collection of proxies and
        admins will enable garbage collection of filters, so turning off
        proxy or admin GC can disable some filter GC.

Note: 600 below =>ten minutes, 0 below => disabled

  
ObjectGCPeriod (see above) 600
DeadChanInterval (see above) 0
DeadAdminInterval (see above) 0
DeadConProxyInterval (see above) 0
DeadOtherProxyInterval (see above) 600
DeadFilterInterval (see above) 0

Initial Default AdminQoS Properties
Property Explanation Default
MaxQueueLength Default maximum number of events that may be buffered by an event channel at any time. When set to 0, the only limit imposed is that of the virtual memory of the machine where the omniNotify server is running. 0
MaxConsumers Default maximum number of consumers that may be connected to an event channel at one time. When set to 0, no upper limit is imposed by the channel. 0
MaxSuppliers Default maximum number of suppliers that may be connected to an event channel at one time. When set to 0, no upper limit is imposed by the channel. 0
RejectNewEvents Boolean value. When set to TRUE (1), events received by an event channel that has reached the MaxQueueLength limit are discarded. When set to FALSE (0), already queued events are discarded according to DiscardPolicy when an event channel has reached the MaxQueueLength limit. 1
LocalClockInaccLo/ LocalClockInaccHi Local clock inaccuracy in units of 100ns (specify with up to 32 low-order bits for LocalClockInaccHi and 16 high-order bits for LocalClockInaccHi). 0 / 0
LocalClockTDF Local time zone expressed in minutes west of greenwhich meridian; 300 = Eastern time zone, USA. 300

Initial Default NotifQoS Properties
Property Explanation Default
EventReliability The event reliability QoS property supported by an event channel.
    0:  Best Effort (CosNotification::BestEffort)
    1:  Persistent (CosNotification::Persistent)
Note: Only best effort is supported by the current release.		 0
ConnectionReliability The reliability QoS property of the connections between an event channel and the clients connected to this channel.
    0:  Best Effort (CosNotification::BestEffort)
    1:  Persistent (CosNotification::Persistent)
Note: Only best effort is supported by the current release.		 0
Priority The default priority assigned to events received by an event channel. 0
Timeout The default relative expiry time in seconds assigned to events received by an event channel. When set to 0, events do not expire. 0
StartTimeSupported A Boolean flag indicating whether the setting of StartTime QoS property on a per-event basis is supported by an event channel. FALSE corresponds to a value of 0 and TRUE corresponds to a value of 1.
Note: Only FALSE is supported by the current release.		 0
StopTimeSupported A Boolean flag indicating whether the setting of StopTime QoS property on a per-event basis is supported by an event channel. FALSE corresponds to a value of 0 and TRUE corresponds to a value of 1.
Note: Only FALSE is supported by the current release.		 0
OrderPolicy The policy used to deliver buffered events to consumers. The policies that could be used are:
    0: Any Order (CosNotification::AnyOrder)
    1: FIFO Order (CosNotification::FifoOrder)
    2: Priority Order (CosNotification::PriorityOrder)
    3: Deadline Order (CosNotification::DeadlineOrder)
    4: LIFO Order (CosNotification::LifoOrder)		 0
DiscardPolicy The policy used to discard buffered events when the buffer overflows. The policies that could be used are:
    0: Any Order (CosNotification::AnyOrder)
    1: FIFO Order (CosNotification::FifoOrder)
    2: Priority Order (CosNotification::PriorityOrder)
    3: Deadline Order (CosNotification::DeadlineOrder)		 0
PacingInterval Default maximum interval in seconds between deliveries of events to consumer clients that receive event batches. This value is set in conjunction with the MaxBatchSize parameter. When set to 0, only the value of MaxBatchSize is used. 1000
MaxEventsPerConsumer  Default maximum number of events that may be buffered by an event channel for each consumers. When set to 0, the only limit imposed is that of the virtual memory of the machine where the omniNotify server is running. 0
MaximumBatchSize Default maximum number of events to be queued before delivered to a consumer client that accepts event batches. This parameter is used in conjunction with the PacingInterval parameter. 8

Configuration Files

As of omniNotify 1.1, two configuration files are provided in the top directory of the omniNotify release: channel.cfg contains the defaults as given above, while standard.cfg contains defaults which follow the CosNotification specification.  Thus, you can start the daemon with -c standard.cfg to obtain the OMG-ordained default settings.   In practice, you can start with either file and edit it to suit your own needs.  The difference between the two is small but important:  while the standard specifies that the default MaximumEventBatch should be 1 and the default pacing interval should be zero, channel.cfg uses a batch size of eight and a pacing interval of 1 second (specified as 1000 milliseconds in channel.cfg).

The configuration file contains one or more lines. These lines belong to the following three categories:

Back to Documentation Home

For comments, feedback, etc, please see the 'Keep in touch' page.