aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/embedded/embedded_solaris.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 /system/doc/embedded/embedded_solaris.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'system/doc/embedded/embedded_solaris.xml')
-rw-r--r--system/doc/embedded/embedded_solaris.xml734
1 files changed, 734 insertions, 0 deletions
diff --git a/system/doc/embedded/embedded_solaris.xml b/system/doc/embedded/embedded_solaris.xml
new file mode 100644
index 0000000000..93532da8e6
--- /dev/null
+++ b/system/doc/embedded/embedded_solaris.xml
@@ -0,0 +1,734 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1997</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>Embedded Solaris</title>
+ <prepared>Fredrik Tillman</prepared>
+ <responsible></responsible>
+ <docno>ETX/B/SFP/TILLMAN:96-001</docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2000-10-17</date>
+ <rev>B</rev>
+ <file>embedded_solaris.xml</file>
+ </header>
+ <p>This chapter describes the OS specific parts of OTP which relate
+ to Solaris.
+ </p>
+
+ <section>
+ <title>Memory Usage</title>
+ <p>Solaris takes about 17 Mbyte of RAM on a system with 64 Mbyte of
+ total RAM. This leaves about 47 Mbyte for the applications. If
+ the system utilizes swapping, these figures cannot be improved
+ because unnecessary daemon processes are swapped out. However,
+ if swapping is disabled, or if the swap space is of limited
+ resource in the system, it becomes necessary to kill off
+ unnecessary daemon processes.
+ </p>
+ </section>
+
+ <section>
+ <title>Disk Space Usage</title>
+ <p>The disk space required by Solaris can be minimized by using the
+ Core User support installation. It requires about 80 Mbyte of
+ disk space. This installs only the minimum software required to
+ boot and run Solaris. The disk space can be further reduced by
+ deleting unnecessary individual files. However, unless disk
+ space is a critical resource the effort required and the risks
+ involved may not be justified.</p>
+ </section>
+
+ <section>
+ <title>Installation</title>
+ <p>This section is about installing an embedded system.
+ The following topics are considered,
+ </p>
+ <list type="bulleted">
+ <item>
+ <p>Creation of user and installation directory,</p>
+ </item>
+ <item>
+ <p>Installation of embedded system,</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,</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 who does not have super user
+ privileges.
+ </p>
+ <p>Throughout this section 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 an Embedded System</title>
+ <p>The procedure for installation of an embedded system does
+ not differ from that of an ordinary system (see the
+ <em>Installation Guide</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>
+ </section>
+
+ <section>
+ <title>Configuration for Automatic Start at Boot</title>
+ <p>A true embedded system has to start when the system
+ boots. This section accounts for the necessary configurations
+ needed to achieve that.
+ </p>
+ <p>The embedded system 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 Solaris documentation.
+ </p>
+ <pre>
+#!/bin/sh
+#
+# File name: S75otp.system
+# Purpose: Automatically starts Erlang and applications when the
+# system starts
+# 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 section <em>Starting Erlang</em> below. 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 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 (see also <em>Installation Problems</em> below).
+ </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 in the section, <em>Starting Erlang</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 section.
+ </p>
+ </section>
+
+ <section>
+ <title>Patches</title>
+ <p>For proper functioning of flushing file system data to disk on
+ Solaris 2.5.1, the version specific patch with number
+ 103640-02 must be added to the operating system. There may be
+ other patches needed, see the release README file
+ <c><![CDATA[<ERL_INSTALL_DIR>/README]]></c>.
+ </p>
+ </section>
+
+ <section>
+ <title>Installation of Module os_sup in Application OS_Mon</title>
+ <p>The following four installation procedures require super user
+ 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> do not suit
+ 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>
+
+ <section>
+ <title>Installation Problems</title>
+ <p>The hardware watchdog timer which is controlled by the
+ <c>heart</c> port program requires the <c>FORCEvme</c>
+ package, which contains the VME bus driver, to be
+ installed. This driver, however, may clash with the Sun
+ <c>mcp</c> driver and cause the system to completely refuse to
+ boot. To cure this problem, the following lines should be
+ added to <c>/etc/system</c>:
+ </p>
+ <list type="bulleted">
+ <item><c>exclude: drv/mcp</c></item>
+ <item><c>exclude: drv/mcpzsa</c></item>
+ <item><c>exclude: drv/mcpp</c></item>
+ </list>
+ <warning>
+ <p>It is recommended that these lines be added to avoid the
+ clash described, which may make it completely impossible to
+ boot the system.</p>
+ </warning>
+ </section>
+ </section>
+
+ <section>
+ <title>Starting Erlang</title>
+ <p>This section describes how an embedded system is started. There
+ are four programs involved, and they all normally reside in the
+ directory <c><![CDATA[<ERL_INSTALL_DIR>/bin]]></c>. The only exception is
+ the program <c>start</c>, which may be located anywhere, and
+ also is the only program that must be modified by the user.
+ </p>
+ <p>In an embedded system there usually is no interactive shell.
+ However, it is possible for an operator to attach to the Erlang
+ system by giving the command <c>to_erl</c>. He is then
+ connected to the Erlang shell, and may give ordinary Erlang
+ commands. All interaction with the system through this shell is
+ logged in a special directory.
+ </p>
+ <p>Basically, the procedure is as follows. The program
+ <c>start</c> is called when the machine is started. It calls
+ <c>run_erl</c>, which sets things up so the operator can attach
+ to the system. It calls <c>start_erl</c> which calls the
+ correct version of <c>erlexec</c> (which is located in
+ <c><![CDATA[<ERL_INSTALL_DIR>/erts-EVsn/bin]]></c>) with the correct
+ <c>boot</c> and <c>config</c> files.
+ </p>
+ </section>
+
+ <section>
+ <title>Programs</title>
+
+ <section>
+ <title>start</title>
+ <p>This program is called when the machine is started. It may
+ be modified or re-written to suit a special system. By
+ default, it must be called <c>start</c> and reside in
+ <c><![CDATA[<ERL_INSTALL_DIR>/bin]]></c>. Another start program can be
+ used, by using the configuration parameter <c>start_prg</c> in
+ the application <c>sasl</c>.</p>
+ <p>The start program must call <c>run_erl</c> as shown below.
+ It must also take an optional parameter which defaults to
+ <c><![CDATA[<ERL_INSTALL_DIR>/releases/start_erl.data]]></c>.
+ </p>
+ <p>This program should set static parameters and environment
+ variables such as <c>-sname Name</c> and <c>HEART_COMMAND</c>
+ to reboot the machine.
+ </p>
+ <p>The <c><![CDATA[<RELDIR>]]></c> directory is where new release packets
+ are installed, and where the release handler keeps information
+ about releases. See <c>release_handler(3)</c> in the
+ application <c>sasl</c> for further information.
+ </p>
+ <p>The following script illustrates the default behaviour of the
+ program.
+ </p>
+ <code type="none"><![CDATA[
+#!/bin/sh
+# Usage: start [DataFile]
+#
+ROOTDIR=/usr/local/otp
+
+if [ -z "$RELDIR" ]
+then
+ RELDIR=$ROOTDIR/releases
+fi
+
+START_ERL_DATA=${1:-$RELDIR/start_erl.data}
+
+$ROOTDIR/bin/run_erl /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl \\
+ $ROOTDIR $RELDIR $START_ERL_DATA" > /dev/null 2>&1 &]]></code>
+ <p>The following script illustrates a modification where the node
+ is given the name <c>cp1</c>, and the environment variables
+ <c>HEART_COMMAND</c> and <c>TERM</c> have been added to the
+ above script.
+ </p>
+ <code type="none"><![CDATA[
+#!/bin/sh
+# Usage: start [DataFile]
+#
+HEART_COMMAND=/usr/sbin/reboot
+TERM=sun
+export HEART_COMMAND TERM
+
+ROOTDIR=/usr/local/otp
+
+if [ -z "$RELDIR" ]
+then
+ RELDIR=$ROOTDIR/releases
+fi
+
+START_ERL_DATA=${1:-$RELDIR/start_erl.data}
+
+$ROOTDIR/bin/run_erl /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl \\
+ $ROOTDIR $RELDIR $START_ERL_DATA -heart -sname cp1" > /dev/null 2>&1 &]]></code>
+ <p>If a diskless and/or read-only client node is about to start the
+ <c>start_erl.data</c> file is located in the client directory at
+ the master node. Thus, the <c>START_ERL_DATA</c> line should look
+ like:
+ </p>
+ <code type="none">
+CLIENTDIR=$ROOTDIR/clients/clientname
+START_ERL_DATA=${1:-$CLIENTDIR/bin/start_erl.data}</code>
+ </section>
+
+ <section>
+ <title>run_erl</title>
+ <p>This program is used to start the emulator, but you will not
+ be connected to the shell. <c>to_erl</c> is used to connect to
+ the Erlang shell.
+ </p>
+ <code type="none">
+Usage: run_erl pipe_dir/ log_dir "exec command [parameters ...]"</code>
+ <p>Where <c>pipe_dir/</c> should be <c>/tmp/</c> (<c>to_erl</c>
+ uses this name by default) and <c>log_dir</c> is where the log
+ files are written. <c>command [parameters]</c> is executed,
+ and everything written to stdin and stdout is logged in the
+ <c>log_dir</c>.
+ </p>
+ <p>In the <c>log_dir</c>, log files are written. Each logfile
+ has a name of the form: <c>erlang.log.N</c> where N is a
+ generation number, ranging from 1 to 5. Each logfile holds up
+ to 100kB text. As time goes by the following logfiles will be
+ found in the logfile directory</p>
+ <code type="none">
+erlang.log.1
+erlang.log.1, erlang.log.2
+erlang.log.1, erlang.log.2, erlang.log.3
+erlang.log.1, erlang.log.2, erlang.log.3, erlang.log.4
+erlang.log.2, erlang.log.3, erlang.log.4, erlang.log.5
+erlang.log.3, erlang.log.4, erlang.log.5, erlang.log.1
+...</code>
+ <p>with the most recent logfile being the right most in each row
+ of the above list. That is, the most recent file is the one
+ with the highest number, or if there are already four files,
+ the one before the skip.
+ </p>
+ <p>When a logfile is opened (for appending or created) a time
+ stamp is written to the file. If nothing has been written to
+ the log files for 15 minutes, a record is inserted that says
+ that we're still alive.
+ </p>
+ </section>
+
+ <section>
+ <title>to_erl</title>
+ <p>This program is used to attach to a running Erlang runtime
+ system, started with <c>run_erl</c>.
+ </p>
+ <code type="none">
+Usage: to_erl [pipe_name | pipe_dir]</code>
+ <p>Where <c>pipe_name</c> defaults to <c>/tmp/erlang.pipe.N</c>.
+ </p>
+ <p>To disconnect from the shell without exiting the Erlang
+ system, type <c>Ctrl-D</c>.
+ </p>
+ </section>
+
+ <section>
+ <title>start_erl</title>
+ <p>This program starts the Erlang emulator with parameters
+ <c>-boot</c> and <c>-config</c> set. It reads data about
+ where these files are located from a file called
+ <c>start_erl.data</c> which is located in the <c><![CDATA[<RELDIR>]]></c>.
+ Each new release introduces a new data file. This file is
+ automatically generated by the release handler in Erlang.
+ </p>
+ <p>The following script illustrates the behaviour of the
+ program.
+ </p>
+ <code type="none">
+#!/bin/sh
+#
+# This program is called by run_erl. It starts
+# the Erlang emulator and sets -boot and -config parameters.
+# It should only be used at an embedded target system.
+#
+# Usage: start_erl RootDir RelDir DataFile [ErlFlags ...]
+#
+ROOTDIR=$1
+shift
+RELDIR=$1
+shift
+DataFile=$1
+shift
+
+ERTS_VSN=`awk '{print $1}' $DataFile`
+VSN=`awk '{print $2}' $DataFile`
+
+BINDIR=$ROOTDIR/erts-$ERTS_VSN/bin
+EMU=beam
+PROGNAME=`echo $0 | sed 's/.*\\///'`
+export EMU
+export ROOTDIR
+export BINDIR
+export PROGNAME
+export RELDIR
+
+exec $BINDIR/erlexec -boot $RELDIR/$VSN/start -config $RELDIR/$VSN/sys $*</code>
+ <p>If a diskless and/or read-only client node with the
+ <c>sasl</c> configuration parameter <c>static_emulator</c> set
+ to <c>true</c> is about to start the <c>-boot</c> and
+ <c>-config</c> flags must be changed. As such a client cannot
+ read a new <c>start_erl.data</c> file (the file is not
+ possible to change dynamically) the boot and config files are
+ always fetched from the same place (but with new contents if
+ a new release has been installed). The <c>release_handler</c>
+ copies this files to the <c>bin</c> directory in the client
+ directory at the master nodes whenever a new release is made
+ permanent.
+ </p>
+ <p>Assuming the same <c>CLIENTDIR</c> as above the last line
+ should look like:
+ </p>
+ <code type="none">
+exec $BINDIR/erlexec -boot $CLIENTDIR/bin/start \\
+ -config $CLIENTDIR/bin/sys $*</code>
+ </section>
+ </section>
+</chapter>
+