View Source Embedded Solaris
This section describes the operating system-specific parts of OTP that relate to Solaris.
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.
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.
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: 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
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
$OTPROOT
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
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
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 namedsyslog.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 commandman 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 ofLEVEL
, seesyslog.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 filessyslog.conf.ORIG
andsyslog.conf.OTP
. The filename must besyslog.otp
.If the directory for the files
syslog.conf.ORIG
andsyslog.conf.OTP
is/etc
, the line insyslog.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
andsyslog.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:<$OTPROOT>/lib/os_mon-<REV>/priv/bin/mod_syslog
Example: If the path to
otp-root
is/usr/otp
, then the path to theos_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 thesetuid
bit of the user must be set.A simple way to do this is to issue the following commands:
cd <$OTPROOT>/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 theos_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:
<$OTPROOT>/lib/os_mon-<REV>/ebin/os_mon.app.
Example: If the path to
otp-root
is/usr/otp
, then the path to theos_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:
Parameter | Function | Standard value |
---|---|---|
start_os_sup | Specifies if os_sup is to be started or not. | true for the first instance on the hardware; false for the other instances |
os_sup_own | The directory for (1) back-up copy and (2) 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 |
Table: Configuration Parameters
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 application, the application
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
Warning
It is recommended to add these lines to avoid a clash. The clash can make it impossible to boot the system.
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 oferlexec
(which is located in<ERL_INSTALL_DIR>/erts-EVsn/bin
) with the correctboot
andconfig
files.
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
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
andstdout
is logged inlog_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 $*