os_sup(3erl)

1os_sup(3)                  Erlang Module Definition                  os_sup(3)
2
3
4

NAME

6       os_sup - Interface to OS System Messages
7

DESCRIPTION

9       os_sup  is a process providing a message passing service from the oper‐
10       ating system to the error logger in the Erlang runtime  system.  It  is
11       part  of  the  OS_Mon application, see os_mon(6). Available for Solaris
12       and Windows.
13
14       Messages received from the operating system results in an user  defined
15       callback function being called. This function can do whatever filtering
16       and formatting is necessary and then deploy any type of  logging  suit‐
17       able for the user's application.
18

SOLARIS OPERATION

20       The  Solaris (SunOS 5.x) messages are retrieved from the syslog daemon,
21       syslogd.
22
23       Enabling the service includes actions which  require  root  privileges,
24       such as change of ownership and file privileges of an executable binary
25       file, and creating a modified copy of the configuration file  for  sys‐
26       logd.  When os_sup is terminated, the service must be disabled, meaning
27       the original configuration must be restored. Enabling/disabling can  be
28       done either outside or inside os_sup. See Configuration below.
29
30   Warning:
31       This  process  cannot  run  in multiple instances on the same hardware.
32       OS_Mon must be configured to start os_sup on one node only  if  two  or
33       more Erlang nodes execute on the same machine.
34
35
36       The format of received events is not defined.
37

WINDOWS OPERATION

39       The Windows messages are retrieved from the eventlog file.
40
41       The  nteventlog  module is used to implement os_sup. See nteventlog(3).
42       Note that the start functions of nteventlog does not need to  be  used,
43       as  in  this  case  the process is started automatically as part of the
44       OS_Mon supervision tree.
45
46       OS messages are formatted as a tuple {Time, Category, Facility,  Sever‐
47       ity, Message}:
48
49         Time = {MegaSecs, Secs, MicroSecs}:
50           A time stamp as returned by the BIF now().
51
52         Category = string():
53           Usually one of "System", "Application" or "Security". Note that the
54           NT eventlog viewer has another notion of category,  which  in  most
55           cases  is  totally  meaningless and therefore not imported into Er‐
56           lang. What is called a category here is one of the main three types
57           of events occurring in a normal NT system.
58
59         Facility = string():
60           The source of the message, usually the name of the application that
61           generated it. This could be almost any string. When  matching  mes‐
62           sages from certain applications, the version number of the applica‐
63           tion may have to be accounted for. This is what the NT event viewer
64           calls "source".
65
66         Severity = string():
67           One  of  "Error", "Warning", "Informational", "Audit_Success", "Au‐
68           dit_Faulure" or, in case of a currently unknown Windows NT  version
69           "Severity_Unknown".
70
71         Message = string():
72           Formatted  exactly as it would be in the NT eventlog viewer. Binary
73           data is not imported into Erlang.
74

CONFIGURATION

76         os_sup_mfa = {Module, Function, Args}:
77           The callback function to use. Module and  Function  are  atoms  and
78           Args  is  a list of terms. When an OS message Msg is received, this
79           function is called as apply(Module, Function, [Msg | Args]).
80
81           Default is {os_sup, error_report, [Tag]} which will send the  event
82           to  the error logger using error_logger:error_report(Tag, Msg). Tag
83           is the value of os_sup_errortag, see below.
84
85         os_sup_errortag = atom():
86           This parameter defines the error report type used when messages are
87           sent  to  error logger using the default callback function. Default
88           is std_error, which means the events are handled  by  the  standard
89           event handler.
90
91         os_sup_enable = bool():
92           Solaris  only.  Defines  if the service should be enabled (and dis‐
93           abled) inside (true) or outside (false) os_sup. For backwards  com‐
94           patibility  reasons,  the default is true. The recommended value is
95           false, as the Erlang emulator should normally not be run with  root
96           privileges, as is required for enabling the service.
97
98         os_sup_own = string():
99           Solaris  only. Defines the directory which contains the backup copy
100           and the Erlang specific configuration  files  for  syslogd,  and  a
101           named pipe to receive the messages from syslogd. Default is "/etc".
102
103         os_sup_syslogconf = string():
104           Solaris  only.  Defines the full name of the configuration file for
105           syslogd. Default is "/etc/syslog.conf".
106

EXPORTS

108       enable() -> ok | {error, Res}
109       enable(Dir, Conf) -> ok | {error, Error}
110
111              Types:
112
113                 Dir = Conf = Res = string()
114
115              Enables the os_sup service. Needed on Solaris only.
116
117              If the configuration  parameter  os_sup_enable  is  false,  this
118              function  is called automatically by os_sup, using the values of
119              os_sup_own and os_sup_syslogconf as arguments.
120
121              If os_sup_enable is true, this function must  be  called  before
122              OS_Mon/os_sup  is  started. Dir defines the directory which con‐
123              tains the backup copy  and  the  Erlang  specific  configuration
124              files for syslogd, and a named pipe to receive the messages from
125              syslogd. Defaults to "/etc". Conf defines the full name  of  the
126              configuration file for syslogd. Default is "/etc/syslog.conf".
127
128              Results in a OS call to:
129
130              <PRIVDIR>/bin/mod_syslog otp Dir Conf
131
132
133              where    <PRIVDIR>    is   the   priv   directory   of   OS_Mon,
134              code:priv_dir(os_mon).
135
136              Returns ok if this yields the expected result "0",  and  {error,
137              Res} if it yields anything else.
138
139          Note:
140              This function requires root privileges to succeed.
141
142
143       disable() -> ok | {error, Res}
144       disable(Dir, Conf) -> ok | {error, Error}
145
146              Types:
147
148                 Dir = Conf = Res = string()
149
150              Disables the os_sup service. Needed on Solaris only.
151
152              If  the  configuration  parameter  os_sup_enable  is false, this
153              function is called automatically by os_sup, using the same argu‐
154              ments as when enable/2 was called.
155
156              If  os_sup_enable  is  true,  this function must be called after
157              OS_Mon/os_sup is stopped. Dir defines the directory  which  con‐
158              tains  the  backup  copy  and  the Erlang specific configuration
159              files for syslogd, and a named pipe to receive the messages from
160              syslogd.  Defaults  to "/etc". Conf defines the full name of the
161              configuration file for syslogd. Default is "/etc/syslog.conf".
162
163              Results in a OS call to:
164
165              <PRIVDIR>/bin/mod_syslog nootp Dir Conf
166
167
168              where   <PRIVDIR>   is   the   priv   directory    of    OS_Mon,
169              code:priv_dir(os_mon).
170
171              Returns  ok  if this yields the expected result "0", and {error,
172              Res} if it yields anything else.
173
174          Note:
175              This function requires root privileges to succeed.
176
177

NAME

DESCRIPTION

SOLARIS OPERATION

WINDOWS OPERATION

CONFIGURATION

EXPORTS

SEE ALSO