1996 2009 Ericsson AB. All Rights Reserved.
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.

Installation of Embedded Environment

Peter Högfeldt Peter Högfeldt (Peter Högfeldt
1997-05-26
C target.sgml

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,

Creation of user and installation directory,

Installation of Embedded Environment,

Configuration for automatic start at reboot,

Making a hardware watchdog available,

Changing permission for reboot,

Patches for Solaris 2.5.1,

Configuration of the os_mon application.

Several of the procedures described below require expert knowledge of the Solaris 2 operating system. For most of them super user privilege is needed.

## Creation of user and installation directory

It is recommended that the Embedded Environment is run by an ordinary user, i.e. a user which does not have super user privileges.

Throughout this chapter we assume that the user name is otpuser, and that the home directory of that user is,

    /export/home/otpuser

Furthermore, we assume 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.

## Installation of Embedded Environment

The procedure for installation of a Embedded Environment does not differ from that of a Development Environment (see the chapter Installation of Development Environment), except for the following,

the (compressed) tape archive file should be extracted in the installation directory as defined above, and,

there is no need to link the start script to a standard directory like /usr/local/bin.

The details for extracting the tape archive file is not repeated here.

## Configuration for Automatic Start at Boot

A true Embedded Environment has to start when the system boots. This section accounts for the necessary configurations needed to achieve that.

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

    S75otp.system

For further details on initialization (and termination) scripts, and naming thereof, see the file /etc/init.d/README on a Solaris 2.5.1 system.

    #!/bin/sh
    #
    #  File name:  S75otp.system
    #  Purpose:    Automatically starts Erlang and applications when the
    #              system starts
    #  Author:     janne@erlang.ericsson.se
    #  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

The file /export/home/otpuser/otp/bin/start referred to in the above script, is precisely the script start described in the next chapter of this guide, Starting an Embedded System. The script variable OTP_ROOT in that start script corresponds to the example path

    /export/home/otpuser/otp

used in this section. The start script should be edited accordingly.

Use of the killproc procedure in the above script could be combined with a call to erl_call, e.g.

      $SOME_PATH/erl_call -n Node init stop

in order to take Erlang down gracefully (see the erl_call(1) reference manual page for further details on the use of erl_call). That however requires that Erlang runs as a distributed node which is not always the case.

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

## Hardware Watchdog

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 Embedded Systems documentation.

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

## Changing permissions for reboot

If the HEART_COMMAND environment variable is to be set in the start script of the next chapter, Starting an Embedded System, and if the value shall be set to the path of the Solaris reboot command, i.e.

    HEART_COMMAND=/usr/sbin/reboot

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) reference manual page in Kernel.

## The TERM environment variable

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

    TERM=sun

which should be added to the start script described in the next chapter.

## Patches for Solaris 2.5.1

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.

## Installation of module os_sup in application os_mon

The following four installation procedures requires superuser privilege.

### Installation

Make a copy the Solaris standard configuration file for syslogd.

Make a copy the Solaris standard configuration file for syslogd. This file is usually named syslog.conf and found in the /etc directory.

The file name of the copy must be syslog.conf.ORIG but the directory location is optional. Usually it is /etc.

A simple way to do this is to issue the command

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

Make an Erlang specific configuration file for syslogd.

Make an edited copy of the back-up copy previously made.

The file name must be syslog.conf.OTP and the path must be the same as the back-up copy.

The format of the configuration file is found in the man page for syslog.conf(5), by issuing the command man syslog.conf.

Usually a line is added which should state:

which types of information that will be supervised by Erlang,

the name of the file (actually a named pipe) that should receive the information.

If e.g. only information originating from the unix-kernel should be supervised, the line should begin with kern.LEVEL (for the possible values of LEVEL see syslog.conf(5)).

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 syslog.conf.ORIG and syslog.conf.OTP files. The file name must be syslog.otp.

If the directory for the syslog.conf.ORIG and syslog.conf.OTP files is /etc the line in syslog.conf.OTP will look like:

`kern.LEVEL /etc/syslog.otp`

Check the file privileges of the configuration files.

The configuration files should have rw-r--r-- file privileges and be owned by root.

A simple way to do this is to issue the commands

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

Note: If the syslog.conf.ORIG and syslog.conf.OTP files are not in the /etc directory, 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 the os_mon application if 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 the otp-root is /usr/otp, thus 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 user must be set.

A simple way to do this is to issue the 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 if 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 the otp-root is /usr/otp, thus 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 are bound to the correct values.

Parameter Function Standard value
start_os_sup Specifies if os_sup will be started or not. truefor the first instance on the hardware; falsefor the other instances.
os_sup_own The directory for (1)the back-up copy, (2) the Erlang specific configuration file for syslogd. "/etc"
os_sup_syslogconf The full name for the Solaris standard configuration file for syslogd "/etc/syslog.conf"
error_tag The tag for the messages that are sent to the error logger in the Erlang runtime system. std_error
Configuration Parameters

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

Example: The following is an example of the 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 also the os_mon(3), application(3) and erl(1) reference manual pages.