1 Embedded Solaris
This chapter describes the OS specific parts of OTP which relate to embedded Solaris.
1.1 Introduction
The current status of embedded Solaris is that it reduces disk usage, but does not reduce the memory footprint of Solaris.
1.2 Memory Usage
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 following start-scripts can be deleted to prevent unnecessary daemons from starting:
/etc/rc2.d/S72autoinstall
/etc/rc2.d/S74autofs
/etc/rc2.d/S76nscd
/etc/rc2.d/S80PRESERVE
/etc/rc2.d/S80lp
/etc/rc2.d/S88sendmail
/etc/rc2.d/S92volmgt
/etc/rc2.d/S93cacheos.finish
/etc/rc3.d/S15nfs.server
More information is expected from Sun on how to modify the kernel in order to reduce the memory consumption. This will be performed by modifying the
/etc/system
file.1.3 Disk Space Usage
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.
1.4 Installation
This section is about installing an 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.
1.4.1 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/otpuserFurthermore, we assume that in the home directory of
otpuser
, there is a directory namedotp
, the full path of which is,/export/home/otpuser/otpThis directory is the installation directory of the Embedded Environment.
1.4.2 Installation of Embedded Environment
The procedure for installation of an 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.
1.4.3 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 byroot
, and its name cannot be arbitrarily assigned. The following name is recommended,S75otp.systemFor 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 jam45 ;; *) echo "Usage: $0 { start | stop }" ;; esacThe file
/export/home/otpuser/otp/bin/start
referred to in the above script, is precisely the scriptstart
described in the section Starting an Embedded System. The script variableOTP_ROOT
in thatstart
script corresponds to the example path/export/home/otpuser/otpused 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 toerl_call
, e.g.$SOME_PATH/erl_call -n Node init stopIn order to take Erlang down gracefully see the
erl_call(1)
reference manual page for further details on the use oferl_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.1.4.4 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.1.4.5 Changing permissions for reboot
If the
HEART_COMMAND
environment variable is to be set in thestart
script in the section, Starting an Embedded System, and if the value shall be set to the path of the Solarisreboot
command, i.e.HEART_COMMAND=/usr/sbin/rebootthe ownership and file permissions for
/usr/sbin/reboot
must be changed as follows,chown 0 /usr/sbin/reboot chmod 4755 /usr/sbin/rebootSee also the
heart(3)
reference manual page in Kernel.1.4.6 The TERM environment variable
When the Erlang system is automatically started from the
S75otp.system
script theTERM
environment variable has to be set. The following is a minimal setting,TERM=sunwhich should be added to the
start
script described in the section.1.4.7 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.
1.4.8 Installation of module os_sup in application os_mon
The following four installation procedures require super user privilege.
1.4.8.1 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 commandman 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 ofLEVEL
seesyslog.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
andsyslog.conf.OTP
files. The file name must besyslog.otp
.
- If the directory for the
syslog.conf.ORIG
andsyslog.conf.OTP
files is/etc
the line insyslog.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
andsyslog.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_syslogExample: If the path to the otp-root is/usr/otp
, thus 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 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_syslog1.4.8.2 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 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 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 are bound to the correct values.
Parameter Function Standard value start_os_sup Specifies if os_sup will be started or not. true
for the first instance on the hardware;false
for 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 system. std_error
Configuration Parameters If the values listed in the
os_mon.app
do not suit your needs, you shouldnot
edit that file. Instead you should override values in a system configuration file, the full pathname of which is given on the command line toerl
.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}]}].1.4.8.3 Related documents
See also the
os_mon(3)
,application(3)
anderl(1)
reference manual pages.1.4.9 Installation Problems
The hardware watchdog timer which is controlled by the
heart
port program requires theFORCEvme
package, which contains the VME bus driver, to be installed. This driver, however, may clash with the Sunmcp
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
It is recommended that these lines be added to avoid the clash described, which may make it completely impossible to boot the system.
1.5 Starting Erlang
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 programstart
, 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 callsrun_erl
, which sets things up so the operator can attach to the system. It callsstart_erl
which calls the correct version oferlexec
(which is located in<ERL_INSTALL_DIR>/erts-EVsn/bin
) with the correctboot
andconfig
files.1.6 Programs
1.6.1 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 parameterstart_prg
in the applicationsasl
.The start program must call
run_erl
as shown below. It must also take an optional parameter which defaults to<ERL_INSTALL_DIR>/bin/start_erl.data
.This program should set static parameters and environment variables such as
-sname Name
andHEART_COMMAND
to reboot the machine.The
<RELDIR>
directory is where new release packets are installed, and where the release handler keeps information about releases. Seerelease_handler(3)
in the applicationsasl
for further information.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 the environment variablesHEART_COMMAND
andTERM
have been added to the above 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 the
start_erl.data
file is located in the client directory at the master node. Thus, theSTART_ERL_DATA
line should look like:CLIENTDIR=$ROOTDIR/clients/clientname START_ERL_DATA=${1:-$CLIENTDIR/bin/start_erl.data}1.6.2 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) andlog_dir
is where the log files are written.command [parameters]
is executed, and everything written to stdin and stdout is logged in thelog_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 directoryerlang.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 ...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.
1.6.3 to_erl
This program is used to attach to a running Erlang 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
.1.6.4 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 calledstart_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.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=jam46 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 parameterstatic_emulator
set totrue
is about to start the-boot
and-config
flags must be changed. As such a client cannot read a newstart_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). Therelease_handler
copies this files to thebin
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 should look like:exec $BINDIR/erlexec -boot $CLIENTDIR/bin/start @@@ -config $CLIENTDIR/bin/sys $*1.7 Other Issues
Future releases of OTP will include more information on how Solaris can be configured for use with embedded systems to get maximum performance. Issues which will be investigated include:
- how disabling swapping affects the system
- how locking processes in memory may yield performance benefits.