.TH os_sup 3erl "os_mon 2.8.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
os_sup \- Interface to OS System Messages
.SH DESCRIPTION
.LP
\fIos_sup\fR\& 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 os_mon(7)\&. Available for Solaris and Windows\&.
.LP
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\&.
.SH "SOLARIS OPERATION"

.LP
The Solaris (SunOS 5\&.x) messages are retrieved from the syslog daemon, \fIsyslogd\fR\&\&.
.LP
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 \fIsyslogd\fR\&\&. When \fIos_sup\fR\& is terminated, the service must be disabled, meaning the original configuration must be restored\&. Enabling/disabling can be done either outside or inside \fIos_sup\fR\&\&. See Configuration below\&.
.LP

.RS -4
.B
Warning:
.RE
This process cannot run in multiple instances on the same hardware\&. OS_Mon must be configured to start \fIos_sup\fR\& on one node only if two or more Erlang nodes execute on the same machine\&.

.LP
The format of received events is not defined\&.
.SH "WINDOWS OPERATION"

.LP
The Windows messages are retrieved from the eventlog file\&.
.LP
The \fInteventlog\fR\& module is used to implement \fIos_sup\fR\&\&. See nteventlog(3erl)\&. Note that the start functions of \fInteventlog\fR\& does not need to be used, as in this case the process is started automatically as part of the OS_Mon supervision tree\&.
.LP
OS messages are formatted as a tuple \fI{Time, Category, Facility, Severity, Message}\fR\&:
.RS 2
.TP 2
.B
\fITime = {MegaSecs, Secs, MicroSecs}\fR\&:
A time stamp as returned by the BIF \fInow()\fR\&\&.
.TP 2
.B
\fICategory = string()\fR\&:
Usually one of \fI"System"\fR\&, \fI"Application"\fR\& or \fI"Security"\fR\&\&. 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\&.
.TP 2
.B
\fIFacility = string()\fR\&:
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"\&.
.TP 2
.B
\fISeverity = string()\fR\&:
One of \fI"Error"\fR\&, \fI"Warning"\fR\&, \fI"Informational"\fR\&, \fI"Audit_Success"\fR\&, \fI"Audit_Faulure"\fR\& or, in case of a currently unknown Windows NT version \fI"Severity_Unknown"\fR\&\&.
.TP 2
.B
\fIMessage = string()\fR\&:
Formatted exactly as it would be in the NT eventlog viewer\&. Binary data is not imported into Erlang\&.
.RE
.SH "CONFIGURATION"

.RS 2
.TP 2
.B
\fIos_sup_mfa = {Module, Function, Args}\fR\&:
The callback function to use\&. \fIModule\fR\& and \fIFunction\fR\& are atoms and \fIArgs\fR\& is a list of terms\&. When an OS message \fIMsg\fR\& is received, this function is called as \fIapply(Module, Function, [Msg | Args])\fR\&\&.
.RS 2
.LP
Default is \fI{os_sup, error_report, [Tag]}\fR\& which will send the event to the error logger using error_logger:error_report(Tag, Msg)\&. \fITag\fR\& is the value of \fIos_sup_errortag\fR\&, see below\&.
.RE

.TP 2
.B
\fIos_sup_errortag = atom()\fR\&:
This parameter defines the error report type used when messages are sent to error logger using the default callback function\&. Default is \fIstd_error\fR\&, which means the events are handled by the standard event handler\&.
.TP 2
.B
\fIos_sup_enable = bool()\fR\&:
Solaris only\&. Defines if the service should be enabled (and disabled) inside (\fItrue\fR\&) or outside (\fIfalse\fR\&) \fIos_sup\fR\&\&. For backwards compatibility reasons, the default is \fItrue\fR\&\&. The recommended value is \fIfalse\fR\&, as the Erlang emulator should normally not be run with \fIroot\fR\& privileges, as is required for enabling the service\&.
.TP 2
.B
\fIos_sup_own = string()\fR\&:
Solaris only\&. Defines the directory which contains the backup copy and the Erlang specific configuration files for \fIsyslogd\fR\&, and a named pipe to receive the messages from \fIsyslogd\fR\&\&. Default is \fI"/etc"\fR\&\&.
.TP 2
.B
\fIos_sup_syslogconf = string()\fR\&:
Solaris only\&. Defines the full name of the configuration file for \fIsyslogd\fR\&\&. Default is \fI"/etc/syslog\&.conf"\fR\&\&.
.RE
.SH EXPORTS
.LP
.B
enable() -> ok | {error, Res}
.br
.B
enable(Dir, Conf) -> ok | {error, Error}
.br
.RS
.LP
Types:

.RS 3
Dir = Conf = Res = string()
.br
.RE
.RE
.RS
.LP
Enables the \fIos_sup\fR\& service\&. Needed on Solaris only\&.
.LP
If the configuration parameter \fIos_sup_enable\fR\& is \fIfalse\fR\&, this function is called automatically by \fIos_sup\fR\&, using the values of \fIos_sup_own\fR\& and \fIos_sup_syslogconf\fR\& as arguments\&.
.LP
If \fIos_sup_enable\fR\& is \fItrue\fR\&, this function must be called \fIbefore\fR\& OS_Mon/\fIos_sup\fR\& is started\&. \fIDir\fR\& defines the directory which contains the backup copy and the Erlang specific configuration files for \fIsyslogd\fR\&, and a named pipe to receive the messages from \fIsyslogd\fR\&\&. Defaults to \fI"/etc"\fR\&\&. \fIConf\fR\& defines the full name of the configuration file for \fIsyslogd\fR\&\&. Default is \fI"/etc/syslog\&.conf"\fR\&\&.
.LP
Results in a OS call to:
.LP
.nf

<PRIVDIR>/bin/mod_syslog otp Dir Conf
        
.fi
.LP
where \fI<PRIVDIR>\fR\& is the \fIpriv\fR\& directory of OS_Mon, \fIcode:priv_dir(os_mon)\fR\&\&.
.LP
Returns \fIok\fR\& if this yields the expected result \fI"0"\fR\&, and \fI{error, Res}\fR\& if it yields anything else\&.
.LP

.RS -4
.B
Note:
.RE
This function requires root privileges to succeed\&.

.RE

.LP
.B
disable() -> ok | {error, Res}
.br
.B
disable(Dir, Conf) -> ok | {error, Error}
.br
.RS
.LP
Types:

.RS 3
Dir = Conf = Res = string()
.br
.RE
.RE
.RS
.LP
Disables the \fIos_sup\fR\& service\&. Needed on Solaris only\&.
.LP
If the configuration parameter \fIos_sup_enable\fR\& is \fIfalse\fR\&, this function is called automatically by \fIos_sup\fR\&, using the same arguments as when \fIenable/2\fR\& was called\&.
.LP
If \fIos_sup_enable\fR\& is \fItrue\fR\&, this function must be called \fIafter\fR\& OS_Mon/\fIos_sup\fR\& is stopped\&. \fIDir\fR\& defines the directory which contains the backup copy and the Erlang specific configuration files for \fIsyslogd\fR\&, and a named pipe to receive the messages from \fIsyslogd\fR\&\&. Defaults to \fI"/etc"\fR\&\&. \fIConf\fR\& defines the full name of the configuration file for \fIsyslogd\fR\&\&. Default is \fI"/etc/syslog\&.conf"\fR\&\&.
.LP
Results in a OS call to:
.LP
.nf

<PRIVDIR>/bin/mod_syslog nootp Dir Conf
        
.fi
.LP
where \fI<PRIVDIR>\fR\& is the \fIpriv\fR\& directory of OS_Mon, \fIcode:priv_dir(os_mon)\fR\&\&.
.LP
Returns \fIok\fR\& if this yields the expected result \fI"0"\fR\&, and \fI{error, Res}\fR\& if it yields anything else\&.
.LP

.RS -4
.B
Note:
.RE
This function requires root privileges to succeed\&.

.RE

.SH "SEE ALSO"

.LP
error_logger(3erl), os_mon(3erl)
.LP
\fIsyslogd(1M)\fR\&, \fIsyslog\&.conf(5)\fR\& in the Solaris documentation\&.
.LP