path: root/system/doc/embedded/target.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1996</year><year>2013</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>