1 Embedded Solaris

This section describes the operating system-specific parts of OTP that relate to Solaris.

1.1 Memory Use

Solaris takes about 17 MB of RAM on a system with 64 MB of total RAM. This leaves about 47 MB for the applications. If the system uses 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.

1.2 Disk Space Use

The disk space required by Solaris can be minimized by using the Core User support installation. It requires about 80 MB 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 cannot be justified.

1.3 Installing an Embedded System

This section is about installing an embedded system. The following topics are considered:

• Creating user and installation directory
• Installing an embedded system
• Configuring automatic start at boot
• Making a hardware watchdog available
• Changing permission for reboot
• Setting TERM environment variable
• Adding patches
• Installing module os_sup in application os_mon

Several of the procedures in this section require expert knowledge of the Solaris operating system. For most of them super user privilege is needed.

Creating User and Installation Directory

It is recommended that the embedded environment is run by an ordinary user, that is, a user who does not have super user privileges.

In this section, it is assumed that the username is otpuser and that the home directory of that user is:

/export/home/otpuser

It is also assumed that in the home directory of otpuser, there is a directory named otp, the full path of which is:

/export/home/otpuser/otp

This directory is the installation directory of the embedded environment.

Installing an Embedded System

The procedure for installing an embedded system is the same as for an ordinary system (see Installation Guide), except for the following:

• The (compressed) tape archive file is to be extracted in the installation directory defined above.
• It is not needed to link the start script to a standard directory like /usr/local/bin.

Configuring Automatic Start at Boot

A true embedded system must start when the system boots. This section accounts for the necessary configurations needed to achieve that.

The embedded system and all the applications start automatically if the script file shown below is added to directory /etc/rc3.d. The file must be owned and readable by root. Its name cannot be arbitrarily assigned; the following name is recommended:

S75otp.system

For more details on initialization (and termination) scripts, and naming thereof, see the Solaris documentation.

#!/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

File /export/home/otpuser/otp/bin/start referred to in the above script is precisely the start script described in Starting Erlang. The script variable OTP_ROOT in that start script corresponds to the following example path used in this section:

/export/home/otpuser/otp

The start script is to be edited accordingly.

Use of the killproc procedure in the above script can be combined with a call to erl_call, for example:

$SOME_PATH/erl_call -n Node init stop

To take Erlang down gracefully, see the erl_call(1) manual page in erl_interface for details on the use of erl_call. However, that requires that Erlang runs as a distributed node, which is not always the case.

The killproc procedure is not to 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 is not to run.

Making Hardware Watchdog Available

For Solaris running on VME boards from Force Computers, the onboard hardware watchdog can be activated, provided a VME bus driver is added to the operating system (see also Installation Problems).

See also the heart(3) manual page in Kernel.

Changing Permissions for Reboot

If the HEART_COMMAND environment variable is to be set in the start script in Starting Erlang, and if the value is to be set to the path of the Solaris reboot command, that is:

HEART_COMMAND=/usr/sbin/reboot

then the ownership and file permissions for /usr/sbin/reboot must be changed as follows:

chown 0 /usr/sbin/reboot
chmod 4755 /usr/sbin/reboot

See also the heart(3) manual page in Kernel.

Setting TERM Environment Variable

When the Erlang runtime system is automatically started from the S75otp.system script, the TERM environment variable must be set. The following is a minimal setting:

TERM=sun

This is to be added to the start script.

Adding Patches

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. Other patches might be needed, see the release README file <ERL_INSTALL_DIR>/README.

Installing Module os_sup in Application os_mon

The following four installation procedures require super user privilege:

Installation

• Make a copy of the Solaris standard configuration file for syslogd:
  • Make a copy of the Solaris standard configuration file for syslogd. This file is usually named syslog.conf and found in directory /etc.
  • The filename of the copy must be syslog.conf.ORIG. The directory location is optional; usually it is /etc. A simple way to do this is to issue the following command:

    cp /etc/syslog.conf /etc/syslog.conf.ORIG

• Make an Erlang-specific configuration file for syslogd:
  • Make an edited copy of the backup copy previously made.
  • The filename must be syslog.conf.OTP. The path must be the same as the backup copy.
  • The format of the configuration file is found in the syslog.conf(5) manual page, by issuing the command man syslog.conf.
  • Usually a line is added that is to state:
    • Which types of information that is to be supervised by Erlang
    • The name of the file (actually a named pipe) that is to receive the information
  • If, for example, only information originating from the UNIX kernel is to be supervised, the line is to begin with kern.LEVEL. For the possible values of LEVEL, see syslog.conf(5).
  • After at least one tab-character, the line added is to contain the full name of the named pipe where syslogd writes its information. The path must be the same as for the files syslog.conf.ORIG and syslog.conf.OTP. The filename must be syslog.otp.
  • If the directory for the files syslog.conf.ORIG and syslog.conf.OTP is /etc, the line in syslog.conf.OTP is as follows:

    kern.LEVEL                /etc/syslog.otp

• Check the file privileges of the configuration files:
  • The configuration files is to have rw-r--r-- file privileges and be owned by root.
  • A simple way to do this is to issue these commands:

    chmod 644 /etc/syslog.conf
    chmod 644 /etc/syslog.conf.ORIG
    chmod 644 /etc/syslog.conf.OTP

  • Notice that if the files syslog.conf.ORIG and syslog.conf.OTP are not in directory /etc, the file path in the second and third command must be modified.
• Modify file privileges and ownership of the mod_syslog utility:
  • The file privileges and ownership of the mod_syslog utility must be modified.

  • The full name of the binary executable file is derived from the position of application os_mon in the file system by adding /priv/bin/mod_syslog. The generic full name of the binary executable file is thus:

    <OTP_ROOT>/lib/os_mon-<REV>/priv/bin/mod_syslog

    Example: If the path to otp-root is /usr/otp, then the path to the os_mon application is /usr/otp/lib/os_mon-1.0 (assuming revision 1.0) and the full name of the binary executable file is /usr/otp/lib/os_mon-1.0/priv/bin/mod_syslog.

  • The binary executable file must be owned by root, have rwsr-xr-x file privileges, in particular the setuid bit of the user must be set.

  • A simple way to do this is to issue the following commands:

    cd <OTP_ROOT>/lib/os_mon-<REV>/priv/bin/mod_syslog
    chmod 4755 mod_syslog
    chown root mod_syslog

Testing the Application Configuration File

The following procedure does not require root privilege:

• Ensure that the configuration parameters for the os_sup module in the os_mon application are correct.

• Browse the application configuration file (do not edit it). The full name of the application configuration file is derived from the position of the os_mon application in the file system by adding /ebin/os_mon.app.

  The generic full name of the file is thus:

  <OTP_ROOT>/lib/os_mon-<REV>/ebin/os_mon.app.

  Example: If the path to otp-root is /usr/otp, then the path to the os_mon application is /usr/otp/lib/os_mon-1.0 (assuming revision 1.0) and the full name of the binary executable file is /usr/otp/lib/os_mon-1.0/ebin/os_mon.app.

• Ensure that the following configuration parameters have correct values:

If the values listed in os_mon.app do not suit your needs, do not edit that file. Instead override the values in a system configuration file, the full pathname of which is given on the command line to erl.

Example: Contents of an application configuration file:

[{os_mon, [{start_os_sup, true}, {os_sup_own, "/etc"}, 
{os_sup_syslogconf, "/etc/syslog.conf"}, {os_sup_errortag, std_error}]}].

Related Documents

See the os_mon(3) application, the application(3) manual page in Kernel, and the erl(1) manual page in ERTS.

Installation Problems

The hardware watchdog timer, which is controlled by the heart port program, requires package FORCEvme, which contains the VME bus driver, to be installed. However, this driver can clash with the Sun mcp driver and cause the system to refuse to boot. To cure this problem, the following lines are to be added to /etc/system:

• exclude: drv/mcp
• exclude: drv/mcpzsa
• exclude: drv/mcpp

1.4 Starting Erlang

This section describes how an embedded system is started. Four programs are involved and they normally reside in the directory <ERL_INSTALL_DIR>/bin. The only exception is the start program, which can be located anywhere, and is also the only program that must be modified by the user.

In an embedded system, there is usually no interactive shell. However, an operator can attach to the Erlang system by command to_erl. The operator is then connected to the Erlang shell and can give ordinary Erlang commands. All interaction with the system through this shell is logged in a special directory.

Basically, the procedure is as follows:

• The start program is called when the machine is started.
• It calls run_erl, which sets up things so the operator can attach to the system.
• It calls start_erl, which calls the correct version of erlexec (which is located in <ERL_INSTALL_DIR>/erts-EVsn/bin) with the correct boot and config files.

1.5 Programs

start

This program is called when the machine is started. It can be modified or rewritten to suit a special system. By default, it must be called start and reside in <ERL_INSTALL_DIR>/bin. Another start program can be used, by using configuration parameter start_prg in application SASL.

The start program must call run_erl as shown below. It must also take an optional parameter, which defaults to <ERL_INSTALL_DIR>/releases/start_erl.data.

This program is to set static parameters and environment variables such as -sname Name and HEART_COMMAND to reboot the machine.

The <RELDIR> directory is where new release packets are installed, and where the release handler keeps information about releases. For more information, see the release_handler(3) manual page in SASL.

The following script illustrates the default behaviour of the program:

#!/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 &

The following script illustrates a modification where the node is given the name cp1, and where the environment variables HEART_COMMAND and TERM have been added to the previous script:

#!/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 &

If a diskless and/or read-only client node is about to start, file start_erl.data is located in the client directory at the master node. Thus, the START_ERL_DATA line is to look like:

CLIENTDIR=$ROOTDIR/clients/clientname
START_ERL_DATA=${1:-$CLIENTDIR/bin/start_erl.data}

run_erl

This program is used to start the emulator, but you will not be connected to the shell. to_erl is used to connect to the Erlang shell.

Usage: run_erl pipe_dir/ log_dir "exec command [parameters ...]"

Here:

• pipe_dir/ is to be /tmp/ (to_erl uses this name by default).
• log_dir is where the log files are written.
• command [parameters] is executed.
• Everything written to stdin and stdout is logged in log_dir.

Log files are written in log_dir. Each log file has a name of the form erlang.log.N, where N is a generation number, ranging from 1 to 5. Each log file holds up to 100 kB text. As time goes by, the following log files are found in the log file directory:

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
...

The most recent log file is the rightmost in each row. 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.

When a log file 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 are still alive.

to_erl

This program is used to attach to a running Erlang runtime system, started with run_erl.

Usage: to_erl [pipe_name | pipe_dir]

Here pipe_name defaults to /tmp/erlang.pipe.N.

To disconnect from the shell without exiting the Erlang system, type Ctrl-D.

start_erl

This program starts the Erlang emulator with parameters -boot and -config set. It reads data about where these files are located from a file named start_erl.data, which is located in <RELDIR>. Each new release introduces a new data file. This file is automatically generated by the release handler in Erlang.

The following script illustrates the behaviour of the program:

#!/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 $*

If a diskless and/or read-only client node with the SASL configuration parameter static_emulator set to true is about to start, the -boot and -config flags must be changed.

As such a client cannot read a new start_erl.data file (the file cannot be changed 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 release_handler copies these files to the bin directory in the client directory at the master nodes whenever a new release is made permanent.

Assuming the same CLIENTDIR as above, the last line is to look like:

exec $BINDIR/erlexec -boot $CLIENTDIR/bin/start \ 
     -config $CLIENTDIR/bin/sys $*