aboutsummaryrefslogtreecommitdiffstats
path: root/lib/os_mon/doc/src/os_sup.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/os_mon/doc/src/os_sup.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/os_mon/doc/src/os_sup.xml')
-rw-r--r--lib/os_mon/doc/src/os_sup.xml241
1 files changed, 241 insertions, 0 deletions
diff --git a/lib/os_mon/doc/src/os_sup.xml b/lib/os_mon/doc/src/os_sup.xml
new file mode 100644
index 0000000000..792d18ba14
--- /dev/null
+++ b/lib/os_mon/doc/src/os_sup.xml
@@ -0,0 +1,241 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>os_sup</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>os_sup</module>
+ <modulesummary>Interface to OS System Messages</modulesummary>
+ <description>
+ <p><c>os_sup</c> is a process providing a message passing service
+ from the operating system to the error logger in the Erlang
+ runtime system. It is part of the OS_Mon application, see
+ <seealso marker="os_mon_app">os_mon(6)</seealso>. Available for
+ Solaris and Windows.</p>
+ <p>Messages received from the operating system results in an
+ user defined callback function being called. This function can do
+ whatever filtering and formatting is necessary and then deploy any
+ type of logging suitable for the user's application.</p>
+ </description>
+
+ <section>
+ <title>Solaris Operation</title>
+ <p>The Solaris (SunOS 5.x) messages are retrieved from
+ the syslog-daemon, <c>syslogd</c>.</p>
+ <p>Enabling the service includes actions which require root
+ privileges, such as change of ownership and file privileges of an
+ executable binary file, and creating a modified copy of
+ the configuration file for <c>syslogd</c>. When <c>os_sup</c> is
+ terminated, the service must be disabled, meaning the original
+ configuration must be restored. Enabling/disabling can be done
+ either outside or inside <c>os_sup</c>, see
+ <seealso marker="#config">Configuration</seealso> below.</p>
+ <warning>
+ <p>This process cannot run in multiple instances on the same
+ hardware. OS_Mon must be configured to start <c>os_sup</c> on
+ one node only if two or more Erlang nodes execute on the same
+ machine.</p>
+ </warning>
+ <p>The format of received events is not defined.</p>
+ </section>
+
+ <section>
+ <title>Windows Operation</title>
+ <p>The Windows messages are retrieved from the eventlog file.</p>
+ <p>The <c>nteventlog</c> module is used to implement <c>os_sup</c>.
+ See <seealso marker="nteventlog">nteventlog(3)</seealso>. Note
+ that the start functions of <c>nteventlog</c> does not need to be
+ used, in this case the process is started automatically as part of
+ the OS_Mon supervision tree.</p>
+ <p>OS messages are formatted as a tuple
+ <c>{Time, Category, Facility, Severity, Message}</c>:</p>
+ <taglist>
+ <tag><c>Time = {MegaSecs, Secs, MicroSecs}</c></tag>
+ <item>
+ <p>A time stamp as returned by the BIF <c>now()</c>.</p>
+ </item>
+ <tag><c>Category = string()</c></tag>
+ <item>
+ <p>Usually one of <c>"System"</c>, <c>"Application"</c> or
+ <c>"Security"</c>. Note that the NT eventlog viewer has
+ another notion of category, which in most cases is totally
+ meaningless and therefore not imported into Erlang. What is
+ called a category here is one of the main three types of
+ events occurring in a normal NT system.</p>
+ </item>
+ <tag><c>Facility = string()</c></tag>
+ <item>
+ <p>The source of the message, usually the name of
+ the application that generated it. This could be almost any
+ string. When matching messages from certain applications,
+ the version number of the application may have to be
+ accounted for. This is what the NT event viewer calls
+ "source".</p>
+ </item>
+ <tag><c>Severity = string()</c></tag>
+ <item>
+ <p>One of <c>"Error"</c>, <c>"Warning"</c>,
+ <c>"Informational"</c>, <c>"Audit_Success"</c>,
+ <c>"Audit_Faulure"</c> or, in case of a currently unknown
+ Windows NT version <c>"Severity_Unknown"</c>.</p>
+ </item>
+ <tag><c>Message = string()</c></tag>
+ <item>
+ <p>Formatted exactly as it would be in the NT eventlog viewer.
+ Binary data is not imported into Erlang.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <marker id="config"></marker>
+ <title>Configuration</title>
+ <taglist>
+ <tag><c>os_sup_mfa = {Module, Function, Args}</c></tag>
+ <item>
+ <p>The callback function to use. <c>Module</c> and
+ <c>Function</c> are atoms and <c>Args</c> is a list of terms.
+ When an OS message <c>Msg</c> is received, this function is
+ called as <c>apply(Module, Function, [Msg | Args])</c>.</p>
+ <p>Default is <c>{os_sup, error_report, [Tag]}</c> which will
+ send the event to the error logger using
+ <seealso marker="kernel:error_logger#error_report/2">error_logger:error_report(Tag, Msg)</seealso>. <c>Tag</c> is the value of
+ <c>os_sup_errortag</c>, see below.</p>
+ </item>
+ <tag><c>os_sup_errortag = atom()</c></tag>
+ <item>
+ <p>This parameter defines the error report type used when
+ messages are sent to error logger using the default callback
+ function. Default is <c>std_error</c>, which means the events
+ are handled by the standard event handler.</p>
+ </item>
+ <tag><c>os_sup_enable = bool()</c></tag>
+ <item>
+ <p>Solaris only. Defines if the service should be enabled (and
+ disabled) inside (<c>true</c>) or outside (<c>false</c>)
+ <c>os_sup</c>. For backwards compatibility reasons,
+ the default is <c>true</c>. The recommended value is
+ <c>false</c>, as the Erlang emulator should normally not be
+ run with <c>root</c> privileges, as is required for enabling
+ the service.</p>
+ </item>
+ <tag><c>os_sup_own = string()</c></tag>
+ <item>
+ <p>Solaris only. Defines the directory which contains
+ the backup copy and the Erlang specific configuration files
+ for <c>syslogd</c>, and a named pipe to receive the messages
+ from <c>syslogd</c>. Default is <c>"/etc"</c>.</p>
+ </item>
+ <tag><c>os_sup_syslogconf = string()</c></tag>
+ <item>
+ <p>Solaris only. Defines the full name of the configuration file
+ for <c>syslogd</c>. Default is <c>"/etc/syslog.conf"</c>.</p>
+ </item>
+ </taglist>
+ </section>
+ <funcs>
+ <func>
+ <name>enable() -> ok | {error, Res}</name>
+ <name>enable(Dir, Conf) -> ok | {error, Error}</name>
+ <fsummary>Enable the service (Solaris only)</fsummary>
+ <type>
+ <v>Dir = Conf = Res = string()</v>
+ </type>
+ <desc>
+ <p>Enables the <c>os_sup</c> service. Needed on Solaris only.</p>
+ <p>If the configuration parameter <c>os_sup_enable</c> is
+ <c>false</c>, this function is called automatically by
+ <c>os_sup</c>, using the values of <c>os_sup_own</c> and
+ <c>os_sup_syslogconf</c> as arguments.</p>
+ <p>If <c>os_sup_enable</c> is <c>true</c>, this function must
+ be called <em>before</em> OS_Mon/<c>os_sup</c> is started.
+ <c>Dir</c> defines the directory which contains the backup
+ copy and the Erlang specific configuration files for
+ <c>syslogd</c>, and a named pipe to receive the messages
+ from <c>syslogd</c>. Defaults to <c>"/etc"</c>. <c>Conf</c>
+ defines the full name of the configuration file for
+ <c>syslogd</c>. Default is <c>"/etc/syslog.conf"</c>.</p>
+ <p>Results in a OS call to:</p>
+ <code type="none"><![CDATA[
+<PRIVDIR>/bin/mod_syslog otp Dir Conf
+ ]]></code>
+ <p>where <c><![CDATA[<PRIVDIR>]]></c> is the <c>priv</c> directory of
+ OS_Mon, <c>code:priv_dir(os_mon)</c>.</p>
+ <p>Returns <c>ok</c> if this yields the expected result
+ <c>"0"</c>, and <c>{error, Res}</c> if it yields anything
+ else.</p>
+ <note>
+ <p>This function requires root privileges to succeed.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>disable() -> ok | {error, Res}</name>
+ <name>disable(Dir, Conf) -> ok | {error, Error}</name>
+ <fsummary>Disable the service (Solaris only)</fsummary>
+ <type>
+ <v>Dir = Conf = Res = string()</v>
+ </type>
+ <desc>
+ <p>Disables the <c>os_sup</c> service. Needed on Solaris only.</p>
+ <p>If the configuration parameter <c>os_sup_enable</c> is
+ <c>false</c>, this function is called automatically by
+ <c>os_sup</c>, using the same arguments as when
+ <c>enable/2</c> was called.</p>
+ <p>If <c>os_sup_enable</c> is <c>true</c>, this function must
+ be called <em>after</em> OS_Mon/<c>os_sup</c> is stopped.
+ <c>Dir</c> defines the directory which contains the backup
+ copy and the Erlang specific configuration files for
+ <c>syslogd</c>, and a named pipe to receive the messages
+ from <c>syslogd</c>. Defaults to <c>"/etc"</c>. <c>Conf</c>
+ defines the full name of the configuration file for
+ <c>syslogd</c>. Default is <c>"/etc/syslog.conf"</c>.</p>
+ <p>Results in a OS call to:</p>
+ <code type="none"><![CDATA[
+<PRIVDIR>/bin/mod_syslog nootp Dir Conf
+ ]]></code>
+ <p>where <c><![CDATA[<PRIVDIR>]]></c> is the <c>priv</c> directory of
+ OS_Mon, <c>code:priv_dir(os_mon)</c>.</p>
+ <p>Returns <c>ok</c> if this yields the expected result
+ <c>"0"</c>, and <c>{error, Res}</c> if it yields anything
+ else.</p>
+ <note>
+ <p>This function requires root privileges to succeed.</p>
+ </note>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>See also</title>
+ <p><seealso marker="kernel:error_logger">error_logger(3)</seealso>,
+ <seealso marker="os_mon_app">os_mon(3)</seealso></p>
+ <p><c>syslogd(1M)</c>, <c>syslog.conf(4)</c> in the Solaris
+ documentation.</p>
+ <p></p>
+ </section>
+</erlref>
+