Contents
This topic describes running StreamBase Server in background mode, describes how to configure the Apache Log4j logging mechanism enabled in that mode, and describes how to configure syslog on UNIX to receive messages from Log4j.
Run StreamBase Server in background mode by specifying the –b option on the sbd command line, or by running StreamBase Server as a Windows service. (TIBCO does not recommend running sbd -b at the StreamBase Command Prompt on Windows.)
In background mode, debug and console messages normally written to standard output using the embedded Logback mechanism are automatically redirected by default to an alternative embedded Apache Log4j logging mechanism. The reason for this automatic redirection is that Log4j provides a logging appender that can write to the Windows Event Log.
StreamBase logging in general is discussed in Using StreamBase Logging.
Use the -w or --working-directory options with the sbd command to specify a working directory for StreamBase Server when run in the background. The path specified with -w is not automatically on the module search path, which must be specified as usual.
When specifying a startup working directory, you can express paths to resource files relative to the root of the working directory, or you can specify full, absolute paths.
When using the -w or --working-directory options in conjunction with running a bundle file, the working directory you specify is where the bundle file is unzipped
before running its contents.
If you specify an empty directory with -w, it is treated as a temporary directory, and is automatically and silently deleted when sbd exits. The same behavior occurs when you run a bundle file without using -w, in which case an automatically determined temporary directory is created to hold the bundle contents and is deleted on sbd exit.
If you use -w, but specify a path to a directory with any existing contents, that directory is preserved on sbd exit. You can use the streambase.sbd.delete-working-bundle-dir system property to modify this delete-on-exit behavior. Set -Dstreambase.sbd.delete-working-bundle-dir=true to delete the working directory's contents even if you specify a non-empty path with -w. You can use the sbd command's -J option to specify the system property on the sbd command line.
When StreamBase Server starts in background mode without using the -w or --working-directory switch, its default working directory is the root of the file system, / on UNIX or %windir%\System32 on Windows. When using the default working directory, you must express the path to any file system resources used by the
server with full, absolute paths. Use full paths on the sbd command line and in the server configuration file.
Note
When using sbd -b on the command line, the launch of sbd fails if you specify a file system resource with a relative path. For example, the following commands work normally with
relative paths because -b is not used:
UNIX: sbd -f ./sbd.sbconf ./myapp.sbapp Windows: sbd -f sbd.sbconf myapp.sbapp
However, if you add -b to these commands, sbd fails to start, reporting the failure to the Event Log for Windows or to syslog for UNIX. To avoid this error, use full,
absolute paths, as shown in the following examples:
UNIX: sbd -b -f /home/sbuser/sbproj/sbd.sbconf /home/sbuser/sbproj/myapp.sbapp & Windows: sbd -b -f c:\sbproj\sbd.sbconf c:\sbproj\myapp.sbapp
Some of the file system resources that might be used by the server are described in the following table.
| File System Resource | Specifying with Server in Background Mode |
|---|---|
| server configuration file | Specify an absolute path to the configuration file with the -f option on the sbd command line.
|
| primary application file or bundle file to run | Specify an absolute path to the file, either as an argument on the sbd command line, or in a file attribute of an <application> element in the server configuration file. You can also create a StreamBase bundle for your application and specify the full path to the bundle file.
|
| custom function plug-ins | Specify an absolute path to a file with the file attribute, or an absolute path to a directory with the directory attribute, when using the <plugin>, <module-search>, or <operator-resource-search> elements in the <global> section of the server configuration file.
|
| Java resources | Specify absolute paths to a Java home directory, and to any JAR files or other resources required by custom Java-based adapters
and operators. For example, in the <java-vm> element of the server configuration file, specify absolute paths in:
|
| data directory for disk-based Query Tables | Specify an absolute path to a directory, whether specified with --datadir on the sbd command line, or in the STREAMBASE_DATA environment variable, or with the datadir attribute of the <server> element in the server configuration file.
|
| Authentication password database | Specify an absolute path to the sbpasswd file when using the filepath-value attributes of the <param> child element of the <authentication> element.
|
On supported UNIX platforms, StreamBase Log4j logging is configured by default to write to the UNIX syslog mechanism using the standard UDP port for syslog remote access. Syslog must be configured to listen on its standard port, as described in Syslog Configuration on UNIX.
Run the server in background mode with a command like the following example:
sbd -b -f /path/to/config/sbd.sbconf &
In the specified server configuration file, identify the absolute path to the primary application file to run, plus any container
information, TCP port to listen on, modules to load, and so on. You can set up a server to run automatically on host reboot
by using with a script managed by cron, or using the init.d mechanism installed by the StreamBase RPM installer (described in Installing StreamBase on Linux), or using another method you devise.
On Windows, TIBCO discourages using sbd –b at the StreamBase Command Prompt except for short-term testing. Instead, the –b option is designed to be used when specifying the command line for running StreamBase Server as a Windows service, as described
in Running StreamBase Server as a Windows Service.
When running in the context of a Windows service, StreamBase Server's Log4j logging is configured by default to write to the Windows Event Log. You can configure other logging options as described in the next section.
Note
If you run sbd –b at the StreamBase Command Prompt, the Server emits several benign console warning messages that complain about multiple SLF4J bindings. This is because the
StreamBase Command Prompt specifies a classpath that includes the default sbclient.jar, in which the SLF4J front end is configured to log to the Logback back end. But the sbd command itself, when used with -b, also internally references the SLF4J front end, this time configured to log to the Log4j back end.
Even though discouraged, it is still possible to run sbd –b at the StreamBase Command Prompt without warning messages by unsetting the CLASSPATH environment variable and following the other steps in Advanced: Replacing Logback with Log4J. For an example, see the batch file run-sbd-with-env.cmd in the logging-log4j sample.
Configure background mode's Log4j logging mechanism by editing its configuration file. For both UNIX and Windows platforms,
the StreamBase Log4j configuration file is installed by default in STREAMBASE_HOME/etc/log4j.configuration.
Your Log4j configuration can redirect the output to a file or can take advantage of any other valid Log4j mechanism. Refer to standard Log4j documentation for the various configuration options.
You can change the location or name of the Log4j configuration file by setting the log4j.configuration system property for the JVM running the server. Do this in the server configuration file, using either the <jvm-args> or <sysproperty> elements, like these examples:
<param name="jvm-args" value="-Xms128m -Xmx512m -Dlog4j.configuration="file:/c/sbproj/mylog4j.configuration" />
or
<sysproperty name="log4j.configuration"
value="file:/home/sbuser/sbproj/mylog4j.configuration" />Notice that the system property value is a Java URI, not a simple path name. See StreamBase Server Configuration File XML Reference for more on server configuration file elements.
Background mode's Log4j logging mechanism captures most, but not all debug and console messages from the running server. There are two sources of logging messages from StreamBase Server:
-
When running in background mode, the SLF4J back-end logging mechanism and the Log4j front end capture everything that runs in the server's Java virtual machine (JVM), including output from all running StreamBase applications, as well as much of the server infrastructure. The output from these components will conform to the configuration in the
log4j.configurationfile. -
StreamBase Server uses a small amount of native code for each platform to start and manage the JVM. Messages from this startup code includes information about server startup and shutdown, plus some miscellaneous output. These messages are not directed through SLF4J and Log4j, but are delivered directly to syslog for UNIX and to the Event Log for Windows.
On UNIX, you must configure the syslog daemon to listen for these startup messages, as described in the next section.
The syslog daemon receives messages in two ways, from programs making a system call that writes directly to syslog, or from programs that send messages to a known, standard UDP port. Messages sent from StreamBase Server's native startup code use the system call method, and do not require special configuration. However, messages sent from Log4j to syslog use the UDP port method, which must be enabled.
On Linux platforms, syslogd is typically installed but not configured to listen by default on its UDP port. Be aware that syslog logging is advisory only, and does not provide notification of dropped messages, which could happen when syslogd is not set up to listen for remote messages.
On Linux, the method to configure syslogd for remote access varies by Linux distribution. The following shows the steps for the Linux platforms supported by StreamBase.
-
For Red Hat Enterprise Linux version 6 and above, first, add (or uncomment) the following lines to
/etc/rsyslog.conf:$ModLoad imudp.so $UDPServerRun 514
Then, restart the rsyslog service:
/sbin/service rsyslog restart
-
For Red Hat Enterprise Linux versions 5 and earlier, add
-rto SYSLOGD_OPTIONS in/etc/sysconfig/syslog. Then stop and restart the syslog daemon by running the following command as root:/etc/init.d/syslog restart. -
For SUSE Linux Enterprise Server, uncomment the UDP line in
/etc/syslog-ng/syslog-ng.conf.in. Then run the following commands as root:/sbin/SuSEconfig --module syslog-nt /sbin/rcsyslog restart
On Solaris 10, remote access to syslogd may already be configured by default. If you need to enable it, use steps like the following, run as root:
svccfg -s system/system-log setprop config/log_from_remote = true svcadm refresh svc:/system/system-log
See the syslogd(8) documentation for details. Updates and service packs applied to Solaris and Linux may change the example commands shown here, so be sure to check the latest documentation for your Solaris or Linux installation.