The R13B03 release.OTP_R13B03

1 files changed, 414 insertions, 0 deletions

diff --git a/system/doc/embedded/target.xml b/system/doc/embedded/target.xml
new file mode 100644
index 0000000000..4408e6ee48
--- /dev/null
+++ b/system/doc/embedded/target.xml
@@ -0,0 +1,414 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <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>Installation of Embedded Environment</title>
+    <prepared>Peter H&ouml;gfeldt</prepared>
+    <responsible>Peter H&ouml;gfeldt</responsible>
+    <docno></docno>
+    <approved>(Peter H&ouml;gfeldt</approved>
+    <checked></checked>
+    <date>1997-05-26</date>
+    <rev>C</rev>
+    <file>target.sgml</file>
+  </header>
+  <p>This chapter is about installing a Embedded Environment. Solaris 
+    2.5.1 is the only UNIX operating system supported for embedded systems. 
+    The following topics are considered,</p>
+  <list type="bulleted">
+    <item>
+      <p>Creation of user and installation directory,</p>
+    </item>
+    <item>
+      <p>Installation of Embedded Environment,</p>
+    </item>
+    <item>
+      <p>Configuration for automatic start at reboot,</p>
+    </item>
+    <item>
+      <p>Making a hardware watchdog available,</p>
+    </item>
+    <item>
+      <p>Changing permission for reboot,</p>
+    </item>
+    <item>
+      <p>Patches for Solaris 2.5.1,</p>
+    </item>
+    <item>
+      <p>Configuration of the os_mon application.</p>
+    </item>
+  </list>
+  <p>Several of the procedures described below require expert knowledge of
+    the Solaris 2 operating system. For most of them super user privilege is 
+    needed.</p>
+
+  <section>
+    <title>Creation of user and installation directory</title>
+    <p>It is recommended that the Embedded Environment is run by an ordinary
+      user, i.e. a user which does not have super user privileges. </p>
+    <p>Throughout this chapter we assume that the user name is <c>otpuser</c>,
+      and that the home directory of that user is,</p>
+    <pre>
+/export/home/otpuser    </pre>
+    <p>Furthermore, we assume that in the home directory of <c>otpuser</c>,
+      there is a directory named <c>otp</c>, the full path of which is,</p>
+    <pre>
+/export/home/otpuser/otp    </pre>
+    <p>This directory is the <em>installation directory</em> of the Embedded 
+      Environment.</p>
+  </section>
+
+  <section>
+    <title>Installation of Embedded Environment</title>
+    <p>The procedure for installation of a Embedded Environment does not differ
+      from that of a Development Environment (see the chapter <em>Installation of Development Environment</em>), except for the following,</p>
+    <list type="bulleted">
+      <item>
+        <p>the (compressed) tape archive file should be extracted in 
+          the installation directory as defined above, and,</p>
+      </item>
+      <item>
+        <p>there is no need to link the start script to a standard directory
+          like <c>/usr/local/bin</c>.</p>
+      </item>
+    </list>
+    <p>The details for extracting the tape archive file is not repeated here.</p>
+  </section>
+
+  <section>
+    <title>Configuration for Automatic Start at Boot</title>
+    <p>A true Embedded Environment has to start when the system boots. This 
+      section accounts for the necessary configurations needed to achieve
+      that.</p>
+    <p>The embedded environment and all the applications will  start automatically
+      if the script file shown below is added to the <c>/etc/rc3.d</c> directory.
+      The file must be owned and readable by <c>root</c>, and its name cannot
+      be arbitrarily assigned. The following name is recommended,</p>
+    <pre>
+S75otp.system    </pre>
+    <p>For further details on initialization (and termination) scripts, and
+      naming thereof, see the file <c>/etc/init.d/README</c> on a Solaris
+      2.5.1 system.</p>
+    <pre>
+#!/bin/sh
+#  
+#  File name:  S75otp.system
+#  Purpose:    Automatically starts Erlang and applications when the 
+#              system starts
+#  Author:     [email protected]
+#  Resides in: /etc/rc3.d
+#
+
+if [ ! -d /usr/bin ]
+then                    # /usr not mounted
+        exit
+fi
+
+killproc() {            # kill the named process(es)
+        pid=`/usr/bin/ps -e |
+             /usr/bin/grep -w $1 |
+             /usr/bin/sed -e 's/^  *//' -e 's/ .*//'`
+        [ "$pid" != "" ] &amp;&amp; kill $pid
+}
+
+# Start/stop processes required for Erlang
+
+case "$1" in
+'start')
+        # Start the Erlang emulator
+        #
+        su - otpuser -c "/export/home/otpuser/otp/bin/start" &amp;
+        ;;
+'stop')
+        killproc beam
+        ;;
+*)
+        echo "Usage: $0 { start | stop }"
+        ;;
+esac    </pre>
+    <p>The file <c>/export/home/otpuser/otp/bin/start</c> referred to in the 
+      above script, is precisely the script <c>start</c> described in the next
+      chapter of this guide, <em>Starting an Embedded System</em>. The script 
+      variable <c>OTP_ROOT</c> in that <c>start</c> script corresponds to 
+      the example path </p>
+    <pre>
+/export/home/otpuser/otp    </pre>
+    <p>used in this section. The <c>start</c> script should be edited
+      accordingly.</p>
+    <p>Use of the <c>killproc</c> procedure in the above script could
+      be combined with a call to <c>erl_call</c>, e.g.</p>
+    <pre>
+  $SOME_PATH/erl_call -n Node init stop    </pre>
+    <p>in order to take Erlang down gracefully (see the <c>erl_call(1)</c> 
+      reference manual page for further details on the use of <c>erl_call</c>).
+      That however requires that Erlang runs as a distributed node which is 
+      not always the case.</p>
+    <p>The <c>killproc</c> procedure should not be removed: the purpose is
+      here to move from run level 3 (multi-user mode with networking resources)
+      to run level 2 (multi-user mode without such resources), in which Erlang
+      should not run.</p>
+  </section>
+
+  <section>
+    <title>Hardware Watchdog</title>
+    <p>For Solaris 2.5.1 running on VME boards from Force Computers, there
+      is a possibility to activate the onboard hardware watchdog, provided a
+      VME bus driver is added to the operating system. For further details
+      see the <em>Embedded Systems</em> documentation.</p>
+    <p>See also the <c>heart(3)</c> reference manual page in <em>Kernel</em>.</p>
+  </section>
+
+  <section>
+    <title>Changing permissions for reboot</title>
+    <p>If the <c>HEART_COMMAND</c> environment variable is to be set in
+      the <c>start</c> script of the next chapter, <em>Starting an Embedded System</em>, and if the value shall be set to the path of the Solaris 
+      <c>reboot</c> command, i.e.</p>
+    <pre>
+HEART_COMMAND=/usr/sbin/reboot    </pre>
+    <p>the ownership and file permissions for <c>/usr/sbin/reboot</c> must
+      be changed as follows,</p>
+    <pre>
+chown 0 /usr/sbin/reboot
+chmod 4755 /usr/sbin/reboot    </pre>
+    <p>See also the <c>heart(3)</c> reference manual page in <em>Kernel</em>.</p>
+  </section>
+
+  <section>
+    <title>The TERM environment variable</title>
+    <p>When the Erlang runtime system is automatically started from the 
+      <c>S75otp.system</c> script the <c>TERM</c> environment variable
+      has to be set. The following is a minimal setting,</p>
+    <pre>
+TERM=sun    </pre>
+    <p>which should be added to the <c>start</c> script described in the
+      next chapter.</p>
+  </section>
+
+  <section>
+    <title>Patches for Solaris 2.5.1</title>
+    <p>For proper functioning of flushing file system data to disk, the
+      Solaris 2.5.1 specific patch with number 103640-02 must be added
+      to the operating system.</p>
+  </section>
+
+  <section>
+    <title>Installation of module os_sup in application os_mon</title>
+    <p>The following four installation procedures requires superuser privilege.</p>
+
+    <section>
+      <title>Installation</title>
+      <list type="ordered">
+        <item>
+          <p><em>Make a copy the Solaris standard configuration file for syslogd.</em></p>
+          <list type="bulleted">
+            <item>
+              <p>Make a copy the Solaris standard configuration file for syslogd.
+                This file is usually named <c>syslog.conf</c> and found in the <c>/etc</c>
+                directory.</p>
+            </item>
+            <item>
+              <p>The file name of the copy must be <c>syslog.conf.ORIG</c> but the 
+                directory location is optional. Usually it is <c>/etc</c>.
+                </p>
+              <p>A simple way to do this is to issue the command</p>
+              <code type="none">
+    cp /etc/syslog.conf /etc/syslog.conf.ORIG</code>
+            </item>
+          </list>
+        </item>
+        <item>
+          <p><em>Make an Erlang specific configuration file for syslogd.</em></p>
+          <list type="bulleted">
+            <item>
+              <p>Make an edited copy of the back-up copy previously made.</p>
+            </item>
+            <item>
+              <p>The file name must be <c>syslog.conf.OTP</c> and the path 
+                must be the same as the back-up copy.</p>
+            </item>
+            <item>
+              <p>The format of the configuration file is found in the man page for
+                <c>syslog.conf(5)</c>, by issuing the command <c>man syslog.conf</c>.</p>
+            </item>
+            <item>
+              <p>Usually a line is added which should state:</p>
+              <list type="bulleted">
+                <item>
+                  <p>which types of information that will be supervised by Erlang,</p>
+                </item>
+                <item>
+                  <p>the name of the file (actually a named pipe) that should receive
+                    the information.</p>
+                </item>
+              </list>
+            </item>
+            <item>
+              <p>If e.g. only information originating from the unix-kernel should
+                be supervised, the line should begin with <c>kern.LEVEL</c> (for the 
+                possible values of <c>LEVEL</c> see <c>syslog.conf(5)</c>).</p>
+            </item>
+            <item>
+              <p>After at least one tab-character, the line added should contain
+                the full name of the named pipe where syslogd writes its information. The
+                path must be the same as for the <c>syslog.conf.ORIG</c> and
+                <c>syslog.conf.OTP</c> files. The file name must be <c>syslog.otp</c>.</p>
+            </item>
+            <item>
+              <p>If the directory for the <c>syslog.conf.ORIG</c> and
+                <c>syslog.conf.OTP</c> files is <c>/etc</c> the line in
+                <c>syslog.conf.OTP</c> will look like:</p>
+              <code type="none">
+   kern.LEVEL                /etc/syslog.otp              </code>
+            </item>
+          </list>
+        </item>
+        <item>
+          <p><em>Check the file privileges of the configuration files.</em></p>
+          <list type="bulleted">
+            <item>
+              <p>The configuration files should have <c>rw-r--r--</c> file 
+                privileges and be owned by root.</p>
+            </item>
+            <item>
+              <p>A simple way to do this is to issue the commands</p>
+              <code type="none">
+  chmod 644 /etc/syslog.conf
+  chmod 644 /etc/syslog.conf.ORIG
+  chmod 644 /etc/syslog.conf.OTP              </code>
+            </item>
+            <item>
+              <p><em>Note:</em> If the <c>syslog.conf.ORIG</c> and 
+                <c>syslog.conf.OTP</c> files are not in the <c>/etc</c> directory, 
+                the file path in the second and third command must be modified.</p>
+            </item>
+          </list>
+        </item>
+        <item>
+          <p><em>Modify file privileges and ownership of the mod_syslog utility.</em></p>
+          <list type="bulleted">
+            <item>
+              <p>The file privileges and ownership of the <c>mod_syslog</c> utility
+                must be modified.</p>
+            </item>
+            <item>
+              <p>The full name of the binary executable file is derived from the 
+                position of the <c>os_mon</c> application if the file system by adding 
+                <c>/priv/bin/mod_syslog</c>. The generic full name of the binary executable
+                file is thus</p>
+              <code type="none"><![CDATA[
+  <OTP_ROOT>/lib/os_mon-<rev>/priv/bin/mod_syslog              ]]></code>
+              <p><em>Example:</em> If the path to the otp-root is
+                <c>/usr/otp</c>, thus the path to the <c>os_mon</c> application is 
+                <c>/usr/otp/lib/os_mon-1.0</c> (assuming revision 1.0) and the full name 
+                of the binary executable file is 
+                <c>/usr/otp/lib/os_mon-1.0/priv/bin/mod_syslog</c>.</p>
+            </item>
+            <item>
+              <p>The binary executable file must be owned by root, have 
+                <c>rwsr-xr-x</c> file privileges, in particular the setuid bit of
+                user must be set.</p>
+            </item>
+            <item>
+              <p>A simple way to do this is to issue the commands</p>
+              <code type="none"><![CDATA[
+  cd <OTP_ROOT>/lib/os_mon-<rev>/priv/bin/mod_syslog
+  chmod 4755 mod_syslog
+  chown root mod_syslog              ]]></code>
+            </item>
+          </list>
+        </item>
+      </list>
+    </section>
+
+    <section>
+      <title>Testing the application configuration file</title>
+      <p>The following procedure does not require root privilege.</p>
+      <list type="bulleted">
+        <item>
+          <p>Ensure that the configuration parameters for the <c>os_sup</c>
+            module in the <c>os_mon</c> application are correct.</p>
+        </item>
+        <item>
+          <p>Browse the application configuration file (do <em>not</em> edit
+            it). The full name of the application configuration file is derived
+            from the position of the os_mon-application if the file system by adding
+            <c>/ebin/os_mon.app</c>.</p>
+          <p>The generic full name of the file is thus</p>
+          <code type="none"><![CDATA[
+   <OTP_ROOT>/lib/os_mon-<rev>/ebin/os_mon.app.          ]]></code>
+          <p><em>Example:</em> If the path to the otp-root is <c>/usr/otp</c>,
+            thus the path to the <c>os_mon</c> application is <c>/usr/otp/lib/os_mon-1.0</c> (assuming revision 1.0) and the full name of the binary executable file
+            is <c>/usr/otp/lib/os_mon-1.0/ebin/os_mon.app</c>.</p>
+        </item>
+        <item>
+          <p>Ensure that the following configuration parameters are bound to
+            the correct values.</p>
+        </item>
+      </list>
+      <table>
+        <row>
+          <cell align="left" valign="top"><em>Parameter</em></cell>
+          <cell align="left" valign="top"><em>Function</em></cell>
+          <cell align="left" valign="top"><em>Standard value</em></cell>
+        </row>
+        <row>
+          <cell align="left" valign="middle">start_os_sup</cell>
+          <cell align="left" valign="middle">Specifies if os_sup will be started or not.</cell>
+          <cell align="left" valign="middle"><c>true</c>for the first instance on the hardware; <c>false</c>for the other instances.</cell>
+        </row>
+        <row>
+          <cell align="left" valign="middle">os_sup_own</cell>
+          <cell align="left" valign="middle">The directory for (1)the back-up copy, (2) the Erlang specific configuration file  for syslogd.</cell>
+          <cell align="left" valign="middle"><c>"/etc"</c></cell>
+        </row>
+        <row>
+          <cell align="left" valign="middle">os_sup_syslogconf</cell>
+          <cell align="left" valign="middle">The full name for the  Solaris standard configuration file for syslogd </cell>
+          <cell align="left" valign="middle"><c>"/etc/syslog.conf"</c></cell>
+        </row>
+        <row>
+          <cell align="left" valign="middle">error_tag</cell>
+          <cell align="left" valign="middle">The tag for the messages that are sent to the error logger in the Erlang runtime system.</cell>
+          <cell align="left" valign="middle"><c>std_error</c></cell>
+        </row>
+        <tcaption>Configuration Parameters</tcaption>
+      </table>
+      <p>If the values listed in the <c>os_mon.app</c> does not suite your 
+        needs, you should <c>not</c> edit that file. Instead you should
+        <em>override</em> values in a <em>system configuration file</em>, the
+        full pathname of which is given on the command line to <c>erl</c>.</p>
+      <p><em>Example:</em> The following is an example of the contents of an
+        application configuration file.</p>
+      <p></p>
+      <pre>
+[{os_mon, [{start_os_sup, true}, {os_sup_own, "/etc"}, 
+ {os_sup_syslogconf, "/etc/syslog.conf"}, {os_sup_errortag, std_error}]}].      </pre>
+    </section>
+
+    <section>
+      <title>Related documents</title>
+      <p>See also the <c>os_mon(3)</c>, <c>application(3)</c> and <c>erl(1)</c>
+        reference manual pages.</p>
+    </section>
+  </section>
+</chapter>
+