Configuration Settings

Message Server Configuration, Configurations Dialog


Although all configuration settings are stored in a message server’s configuration file, some settings are mirrored in the registry for ease of access by message generators. Changes to registry settings that are used by generators will only take effect after all generators and the message server have been shut down (i.e. reboot). Changes to settings used only by the message server can be implemented by stopping and starting it. Reboot and/or restart can be effected remotely with the message viewer.


Name: IPC buffer directory
Required: Yes
Used by: Generators and message server
Default: <Program Files Dir>\Paul Bunyan

Specifies the directory where the memory mapped file for the IPC buffer resides. All log message generators and the message server need read/write access to this directory or at least to the file itself. Since the message server uses this file, it must reside on a local drive. The default location is read from the registry entry

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ProgramFilesDir by the setup app.

There must also be enough space in this directory to create a file of the size specified by the "IPC buffer size" setting.

Name: IPC buffer size
Required: No
Used by: Generators and message server
Minimum: 10,000
Maximum: 100,000,000
Default: 1,000,000

Specifies the size (in bytes) of the memory-mapped file used by the IPC buffer. This provides the ability to adjust memory usage up if log messages are being lost or down for extremely resource critical environments. Regarding increasing the size, users have found that 50% is typically an effective safety margin for the IPC buffer’s capacity and as such the message server will log event number 420 and send out notification message 1017 if memory usage hits 50%. It is recommended to leave this value at the default unless the notification is received or extreme spikes in logging memory usage are anticipated. In either case, if a message is lost due to insufficient memory a notification of that occurrence will be generated.

Name: Server name
Required: No
Used by: Message server
Default: Name returned by the GetComputerName Win32 API function.

Specifies the text string that log messages generated on this computer will use for the Machine name field instead of the actual operating system name of the computer. This is provided to allow development staff to assign more user friendly names to computers independent of the network administrators’ often necessarily cryptic naming conventions.

Name: Server cache directory
Required: No
Used by: Message server
Default: <Program files dir>\Paul Bunyan

Species the disk location where the message server will save its cache of log messages at shutdown. Must specify a valid, local directory that is accessible to the system account. Since the cache will be read at system startup, the path cannot contain any mapped drives. If this value is not specified, the installation directory for the message server will be used.

Name: Average server mem
Required: No
Used by: Message server
Minimum: 500,000
Maximum: 200,000,000
Default: 2,000,000

Specifies how much memory (in bytes) the message server uses for its cache on average. This is simply a target memory usage that the server maintains by deleting older log messages as new ones are received. Note that messages are not deleted until they have been presented to all connected viewers and registered message handlers and that this activity as well as the purging itself is carried out by the same low priority threads as everything else in the server. As such, it is possible for memory usage to temporarily spike to a level considerably above this desired value during times of heavy CPU activity. This value governs desired average memory usage; to set an absolute ceiling use the "Max server mem" setting.

Name: Max server mem
Required: No
Used by: Message server
Minimum: 1,000,000 or twice the value of "Average server mem," whichever is greater.
Maximum: 400,000,000
Default: Four times the value of "Average server mem."

Specifies the maximum amount of memory (in bytes) the message server uses for all its data handling. The server in normal operation mode will try to maintain its memory consumption at the value specified by the "Average server mem" setting by deleting older log messages as new ones are received. However, because of the way the server adjusts thread priorities to handle the retrieval and dispatch of messages it is possible for a period of heavy CPU activity or a burst of logging activity to result in a starved server that accrues messages and uses up memory indefinitely. This setting is provided to limit memory usage in that scenario. If the maximum memory value is reached then the server will suspend message retrieval until enough messages have been dispatched and purged to start the retrieval process again while staying under the memory usage cap. During this time of suspended retrieval messages will simply pile up in the IPC buffer, and message servers will not forward to the overloaded server. It is entirely possible that the temporary shutdown will not result in any lost log messages but that depends on how much logging is going on during that time. If, however, intense logging caused the heavy CPU activity in the first place then it is likely that some will be lost. In either case, the server will issue notifications if the memory cap is reached and/or if any messages are lost because of this.

Name: IP address
Required: No
Used by: Viewer and message server
Default: Empty string (ultimately passes NULL to Bind())

Specifies the IP address that the message server will listen on for incoming TCP/IP connection requests. It is not necessary to provide this value unless the computer has more than one IP address and the non-default value must be used.

Name: Port
Required: Yes
Used by: Viewer and message server
Default: 54022

Specifies the port that the message server will listen on for incoming TCP/IP connection requests. This number does not need to be changed unless the computer has other software running on it that requires the same port. Care must be taken when changing the listening port as there are standard TCP/IP ports that are used for email servers, FTP servers, and numerous other facilities.

Name: Max TCP/IP stream size
Required: No
Used by: Message server
Minimum: 25,000
Maximum: 4,000,000
Default: 500,000

Specifies a maximum size (in bytes) for data streams sent over the TCP/IP socket. This is provided to accommodate memory usage constraints with the current Winsock implementation. Larger values slightly speed up initial downloads of large numbers of log messages but run the risk of failing due to lack of memory. Smaller values can be used on machines where memory is at a premium. This value is essentially an internal setting that is published simply to cut down on tech support calls and should not be adjusted unless necessary. It is not necessary until a socket connection is lost due to this anomaly in which case the message server will issue a notification saying that it is necessary. See error/notification 1104 in the Error Codes and Notifications appendix.