diff options
Diffstat (limited to 'system/doc/embedded/embedded_solaris.xml')
| -rw-r--r-- | system/doc/embedded/embedded_solaris.xml | 734 |
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 +# 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" != "" ] && 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" & + ;; +'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> + |