1 Embedded Solaris

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.

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.

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

Creation of user and installation directory,

Installation of embedded system,

Configuration for automatic start at reboot,

Making a hardware watchdog available,

Changing permission for reboot,

Patches,

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 who does not have super user
privileges.

Throughout this section 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 an Embedded System

The procedure for installation of an embedded system does
not differ from that of an ordinary system (see the
Installation Guide),
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.

Configuration for Automatic Start at Boot

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

The embedded system 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 Solaris documentation.

The file /export/home/otpuser/otp/bin/start referred to
in the above script, is precisely the script start
described in the section Starting Erlang below. 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 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 Installation Problems below).

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 in the section, Starting Erlang, 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 section.

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

Installation of Module os_sup in Application OS_Mon

The following four installation procedures require super user
privilege.

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.

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.

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.

The tag for the messages that are sent to the error logger in the Erlang runtime system.

std_error

Table
1.1:
Configuration Parameters

If the values listed in the os_mon.app do not suit
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.

See also the os_mon(3), application(3) and
erl(1) reference manual pages.

Installation Problems

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

exclude: drv/mcp

exclude: drv/mcpzsa

exclude: drv/mcpp

Warning

It is recommended that these lines be added to avoid the
clash described, which may make it completely impossible to
boot the system.

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

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

Basically, the procedure is as follows. The program
start is called when the machine is started. It calls
run_erl, which sets things up 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.

start

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 start and reside in
<ERL_INSTALL_DIR>/bin. Another start program can be
used, by using the configuration parameter start_prg in
the 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 should 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. See release_handler(3) in the
application sasl for further information.

The following script illustrates the default behaviour of the
program.

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

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

In the log_dir, log files are written. Each logfile
has a name of the form: erlang.log.N 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

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.

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.

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]

Where 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 called
start_erl.data which is located in the <RELDIR>.
Each new release introduces a new data file. This file is
automatically generated by the release handler in Erlang.

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 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 release_handler
copies this files to the bin directory in the client
directory at the master nodes whenever a new release is made
permanent.