Installation Guide

Sun Java Real-Time System 2.2 Update 1

This document describes the installation of Sun Java™ Real-Time System (Java RTS) 2.2 Update 1, both for Solaris™ Operating System (Solaris OS) and for Linux Operating System.

The Java RTS Virtual Machine 2.2 Update 1 is based on the Java Platform, Standard Edition version 5 (update 22).

Java RTS implements the Real-Time Specification for Java (RTSJ) version 1.0.2. For detailed information, consult the HTML version of the RTSJ specification. See also the Java Community Process^SM (JCP) web site (http://www.jcp.org/) and the RTSJ web site (http://www.rtsj.org/).

Technical Documentation: Links to all the Java RTS technical documents

Installation of Java RTS for Solaris OS

Installing the 32-Bit Java RTS Virtual Machine

Installing the 64-Bit Java RTS Virtual Machine

Installing the Kernel Modules

Granting Resource Access Privileges to Java RTS Users

Uninstalling Java RTS

Upgrading Java RTS

Installation of Java RTS for Linux OS

System Configuration

Installing 32-Bit and 64-Bit Java RTS

Granting Resource Access Privileges to Java RTS Users

Installation of Java RTS for Solaris OS

The Solaris OS packages contain the following:

Binaries of the Java RTS runtime environment, including the Java Virtual Machine (JVM™) software and the Java library for the Real-Time Specification for Java (RTSJ).
Binaries of Solaris OS kernel modules that are necessary to run Java RTS.

Java RTS can run on 32-bit or 64-bit processors. Therefore, two different packages are provided:

SUNWrtjv.zip for 32-bit Java RTS on either 32-bit or 64-bit processors
SUNWrtjvx.zip for 64-bit Java RTS on 64-bit processors (add-on package: requires SUNWrtjv to be installed)

Only a single package for the Solaris OS kernel modules is needed. This package is named SUNWrtjc.

[Contents]

Installing the 32-Bit Java RTS Virtual Machine (Solaris OS)

Note: Shell command lines that are shown with a '#' are meant to be executed while you are logged in as the superuser (root).

Refer to the Release Notes for information concerning operating system support for Java RTS 2.2 Update 1.

If Solaris OS is not yet installed on your machine, refer to the Solaris OS Hardware Compatibility Lists to determine if your system and peripherals are compatible with Solaris OS.

Java RTS requires about 400 MB of free disk space. We recommend installing this product in the Sun-standard /opt directory if space permits. However, if the required storage space is not available under /opt, Java RTS can be installed in any other location.

The installation process also sets new Solaris OS tunables and optionally creates a new Java RTS rights profile. This rights profile can then be assigned by the system administrator to Java RTS users, allowing them to execute the Java RTS with the privilege level required to achieve predictable temporal performance. Refer to section Granting Resource Access Privileges to Java RTS Users for further details.

To install the Java RTS Virtual Machine, execute the following commands. In this example, the original Java RTS package SUNWrtjv.zip was copied to the /tmp directory and is being installed on a SPARC® processor.

Note: If this package has been previously installed in this location, uninstall it as described in the section Uninstalling Java RTS.

# cd /tmp
# /usr/bin/unzip SUNWrtjv.zip
     Archive:  SUNWrtjv.zip
     creating: SUNWrtjv/
     inflating: SUNWrtjv/pkgmap
     inflating: SUNWrtjv/pkginfo     
     creating: SUNWrtjv/reloc/
  [...]
     inflating: SUNWrtjv/install/postinstall
     inflating: SUNWrtjv/install/postremove
     inflating: SUNWrtjv/install/request

# /usr/sbin/pkgadd -d /tmp SUNWrtjv

Processing package instance <SUNWrtjv> from </tmp>

Java Real-Time System runtime environment(sparc)
1.5.0_20_Java-RTS-2.2_fcs-b19_RTSJ-1.0.2,REV=2009.09.20.12.06
Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.

Where should this package be installed? (/opt):

To achieve predictable temporal behavior, the Java Real-Time
System must be granted access to a number of privileged Solaris
resources. By default, access to these privileged resources is
only granted to the superuser (root). They can also be granted
to additional users by creating a rights profile, that is, a
collection of authorizations, that can later be assigned to an
administrative role or directly to a user.

As part of this package installation, a local 'Java Real-Time 
System User' rights profile can be created on this machine.
This rights profile should NOT be created if such an action
conflicts with your computer security management policies. 
If unsure, contact your system administrator or your computer 
security manager. Also refer to the product's release notes 
for further details regarding the privileges required by the 
Java Real-Time System.

Should a local 'Java Real-Time System User' rights profile 
be created? [y,n] (no): y

Where should this package be installed? [/opt]: /opt
Using </opt> as the package base directory.
## Processing package information.
## Processing system information.
## Verifying package dependencies.
## Verifying disk space requirements.
## Checking for conflicts with packages already installed.
## Checking for setuid/setgid programs.

This package contains scripts which will be executed with 
super-user permission during the process of installing this 
package.

Do you want to continue with the installation of <SUNWrtjv>? 
[y,n] y

## Installing part 1 of 1.
/opt/SUNWrtjv/COPYRIGHT
/opt/SUNWrtjv/LICENSE
/opt/SUNWrtjv/README.html
[...]
/opt/SUNWrtjv/sample/nio/server/URLDumper.java
/opt/SUNWrtjv/src.zip
[ verifying class <none> ]
## Executing postinstall script.

Creating the 'Java Real-Time System User' rights profile.

Refer to the 'System Administration Guide: Security Services'
documentation for further information regarding the way to assign
the 'Java Real-Time System User' rights profile to users, groups,
or administrative roles using the Solaris Management Console,
smc(1M), or the usermod(1M), groupmod(1M), and rolemod(1M)
commands.

Setting kernel tunable 'timer_max' to '4096'.
/: not a GRUB boot OS instance

Please reboot your system for changes to take effect.

Installation of <SUNWrtjv> was successful.

Java RTS uses a number of Solaris OS resources whose usage is usually restricted to privileged processes. In order to execute the Java RTS Virtual Machine, users must be explicitly granted these privileges.

If you plan to use the 'Java Real-Time System User' rights profile optionally created during the installation of the SUNWrtjv package, then you now have to explicitly assign this new profile to the Java RTS users using the Solaris Management Console, smc(1M), or the usermod(1M) and rolemod(1M) commands. Refer to section Granting Privileges to Java RTS Users below for further details.

Alternatively, if security is not a concern, you can simply run the Java RTS Virtual Machine as the 'root' superuser.

Finish by setting the PATH environment variable to point to <Java RTS install dir>/SUNWrtjv/bin.

Java RTS is delivered with kernel modules that must be installed on the target machine prior to the use of the Java RTS Virtual Machine. See section Installing the Kernel Modules for a description of their installation procedure.

[Contents]

Installing the 64-Bit Java RTS Virtual Machine (Solaris OS)

Note: Shell command lines that are shown with a '#' are meant to be executed while you are logged in as the superuser (root).

The 64-bit Java RTS Virtual Machine is provided in the SUNWrtjvx add-on package. Before installing this package, make sure that the 32-bit Java RTS package SUNWrtjv has already been installed, as the add-on package installs its files into the same directories used by SUNWrtjv.

To install the 64-bit Java RTS Virtual Machine, execute the following commands. In this example, the original 64-bit Java RTS package SUNWrtjvx.zip was copied to the /tmp directory and is being installed on an AMD64 processor . The SUNWrtjv package was previously installed in /opt.

Note: If this package has been previously installed in this location, uninstall it as described in the section Uninstalling Java RTS.

# cd /tmp
# /usr/bin/unzip SUNWrtjvx.zip
     Archive:  SUNWrtjvx.zip
     inflating: SUNWrtjvx/pkgmap
     inflating: SUNWrtjvx/pkginfo
  [...]
     inflating: SUNWrtjvx/install/postinstall
     inflating: SUNWrtjvx/install/postremove
     inflating: SUNWrtjvx/install/request

# /usr/sbin/pkgadd -d /tmp SUNWrtjvx
Processing package instance <SUNWrtjvx> from </tmp>

Java Real-Time System 64-bit runtime environment(amd64) 
1.5.0_20_Java-RTS-2.2_fcs-b19_RTSJ-1.0.2,REV=2009.09.20.12.06
Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
## Executing checkinstall script.
Using </opt> as the package base directory.
## Processing package information.
## Processing system information.
## Verifying package dependencies.
## Verifying disk space requirements.
## Checking for conflicts with packages already installed.
## Checking for setuid/setgid programs.

Installing Java Real-Time System 64-bit runtime environment as <SUNWrtjvx>

## Installing part 1 of 1.
/opt/SUNWrtjv/bin/amd64/appletviewer
/opt/SUNWrtjv/bin/amd64/appletviewer_g
/opt/SUNWrtjv/bin/amd64/apt
 [...]
/opt/SUNWrtjv/jre/lib/amd64/xawt/libmawt.so
/opt/SUNWrtjv/jre/lib/amd64/xawt/libmawt_g.so
[ verifying class <none> ]

Installation of <SUNWrtjvx> was successful.

Executing the 64-Bit VM (Solaris OS)

After installation, /opt/SUNWrtjv contains both the 32-bit and 64-bit Java RTS Virtual Machines. By default the executable commands in /opt/SUNWrtjv/bin will invoke the 32-bit Virtual Machine. You can use these commands to execute the 64-bit Virtual Machine by passing the -d64 option. For example:

/opt/SUNWrtjv/bin/java -d64 <class> <args>

If you are invoking a command that in turn executes the Java RTS Virtual Machine, you can use the option for that command which passes arguments through to the Virtual Machine. For example:

/opt/SUNWrtjv/bin/javac -J-d64 <args>

Alternatively, 64-bit versions of some of the commands are available in the /opt/SUNWrtjv/bin/<64-bit-arch>/ directory, where the 64-bit-arch is either amd64 for 64-bit x86 systems, or sparcv9 for 64-bit SPARC systems. For example:

/opt/SUNWrtjv/bin/amd64/java
/opt/SUNWrtjv/bin/amd64/javac

[Contents]

Installing the Kernel Modules (Solaris OS)

Note: Shell command lines that are shown with a '#' are meant to be executed while you are logged in as the superuser (root).

On a sun4v machine featuring the new UltraSPARC-T1 processor or UltraSPARC-T2 processor, install the SUNWrtjc.v.zip package. Otherwise, install the SUNWrtjc.zip package.

To install the Java RTS kernel modules, execute the following commands. In this example, the original Java RTS package SUNWrtjc.zip was copied to the /tmp directory and is being installed on a SPARC processor.

Note: If this package has been previously installed in this location, uninstall it as described in the section Uninstalling Java RTS.

# /usr/bin/unzip SUNWrtjc.zip
     Archive:  SUNWrtjc.zip
     creating: SUNWrtjc/
     inflating: SUNWrtjc/pkgmap    
     inflating: SUNWrtjc/pkginfo
  [...]
     creating: SUNWrtjc/reloc/platform/sun4u/kernel/drv/sparcv9/
     SUNWrtjc/reloc/platform/sun4u/kernel/drv/sparcv9/cyclic
    
# /usr/sbin/pkgadd -d /tmp SUNWrtjc
Processing package instance <SUNWrtjc> from </tmp>
    
Java Real-Time System cyclic driver(sparc) 2.2,REV=2009.08.11.08.19
Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
## Executing checkinstall script.
Using </> as the package base directory.
## Processing package information.
## Processing system information.
5 package pathnames are already properly installed.
## Verifying package dependencies.
## Verifying disk space requirements.
## Checking for conflicts with packages already installed.
## Checking for setuid/setgid programs.
    
This package contains scripts which will be executed with 
super-user permission during the process of installing this 
package. 
    
Do you want to continue with the installation of <SUNWrtjc>? 
[y,n] y
    
Installing Java Real-Time System cyclic driver as <SUNWrtjc>
    
## Installing part 1 of 1.
/platform/sun4u/kernel/drv/cyclic
/platform/sun4u/kernel/drv/cyclic.conf
/platform/sun4u/kernel/drv/sparcv9/cyclic
[ verifying class <none> ]
## Executing postinstall script.
    
Installation of <SUNWrtjc> was successful.

Note: Drivers are specific to a particular update release of the Solaris 10 Operating System. If you attempt to install a package on a version of Solaris 10 OS where it is not certified, you will receive a warning message. You can continue the installation with that package, but such an installation constitutes an unsupported configuration. In this case, incompatibilities in the cyclic driver package and Solaris 10 OS version may adversely affect the behavior of the operating system.

After installing Java RTS, make sure that users will be able to gain access to system resources, as described in the next section.

For information about compiling and executing applications, refer to the Technical Information document.

[Contents]

Granting Resource Access Privileges to Java RTS Users (Solaris OS)

The Java Real-Time System uses a number of Solaris OS resources, such as the real-time scheduling class, whose usage is restricted to privileged processes. Therefore, in order to ensure predictable timing of operations, the Java RTS Virtual Machine must either be run as the superuser (root) or be explicitly granted additional rights by the system administrator.

Solaris OS supports role-based access control (RBAC), which enforces security policy at a more fine-grained level than the conventional superuser security model. This enables a user to be assigned the precise level of privilege that is necessary to execute the Java RTS binaries.

This security mechanism is typically achieved by means of a specific rights profile, that is, a collection of commands with security attributes. The Java RTS rights profile exists for this purpose.

Rights profiles are usually included in an administrative role, and the role is then assigned to a user.

It is also possible to assign rights profiles directly to a user. In this case, this user must use a privilege-aware profile shell such as pfsh(1) or pfcsh(1) to execute the Java RTS binaries, or use the pfexec(1) utility.

Rights management is implemented on Solaris OS through privileges, that is, discrete rights required to perform particular operations. Privileges decrease the security risk that is associated with one user or one process having full superuser capabilities on a system.

Rights profiles and privileges can be managed using the Solaris Management Console, smc(1), a graphical user interface that provides access to Solaris OS system administration tools. To invoke the Solaris Management Console, type the following command:

# /usr/sbin/smc

You can also use specific commands to manage profiles and privileges, as described in the following paragraphs.

Assigning the Java RTS Rights Profile to a Role

The 'Java Real-Time System User' rights profile can be assigned to an administrative role using the following command:

# /usr/sbin/rolemod -P "Java Real-Time System User" <role>
The value of <role> is an existing role account.

Note: The rolemod command shown above sets the available profiles to be only that of the "Java Real-time System User"; if you wish to add this profile to the set of existing profiles, then you will need to provide a comma-separated list of all the profile names. See the rolemod man page for details.

Assigning the Java RTS Rights Profile Directly to a User

The Java RTS rights profile can be directly assigned to a Solaris OS user by using:

# /usr/sbin/usermod -P "Java Real-Time System User" <username>
The value of <username> is an existing, local user name.

Note: The usermod command shown above sets the available profiles to be only that of the "Java Real-time System User"; if you wish to add this profile to the set of existing profiles, then you will need to provide a comma-separated list of all the profile names. See the usermod man page for details.

Note: As mentioned above, a user to whom the Java RTS rights profile has been assigned must execute the Java RTS binaries either from within a privilege-aware profile shell such as pfsh(1) or pfcsh(1), or the pfexec(1) utility. For convenience, the SUNWrtjv/bin/java.sh script uses pfexec to invoke the Java RTS VM for you.

Assigning Privileges Directly to a User

Alternatively, you can decide not to use the Java RTS profile and assign additional privileges directly to the Java RTS users. In this case, be aware that all the processes created by such Java RTS users (that is, not only the Java RTS Virtual Machine) will be granted these additional privileges.

If you decide to bypass the Java RTS rights profile, then the Java RTS users must be granted at least the following privileges to be able to run properly the Java RTS Virtual Machine:

sys_res_config: Allows a process to create and delete processor sets, assign CPUs to processor sets, and change the operational status of CPUs in the system.
proc_priocntl: Allows a process to elevate its priority above its current level and change its scheduling class to any scheduling class, including the RT class.
proc_lock_memory: Allows a process to lock pages in physical memory.
proc_clock_highres: Allows a process to use high resolution timers.

To assign the above set of privileges directly to a Java RTS user, use the Solaris Management Console, smc(1), or type the following command:

# /usr/sbin/usermod -K \
  defaultpriv=basic,sys_res_config,proc_priocntl, \
  proc_lock_memory,proc_clock_highres \
  <username>

The value of <username> is an existing, local user name.

Assigning Privileges to Non-Local Users

The usermod(1M) command does not allow privileges to be assigned to non-local users (that is, to users who do not appear in the local /etc/passwd file). You can assign privileges to a non-local user with the defaultpriv field in the /etc/user_attr file, as in the following example:

<username>::::type=<type>;profiles=<profiles>;
defaultpriv=basic,sys_res_config,proc_priocntl,
proc_lock_memory,proc_clock_highres
(Note that the above is one line, that is, one entry, in the file.)
The value of <username> is an existing, non-local user name. The values of <type> and <profiles> depend on your settings.

Additional Information

Note: You might need to relogin for the privilege settings to take effect.

Contact your system administrator or your computer security manager for guidelines regarding the setup of rights profiles, roles, and privileges that are compatible with your local computer security management policies.

For further information regarding rights profiles, roles, and privileges, refer to the Solaris System Administration Guide: Security Services documentation and related man pages.

[Contents]

Uninstalling Java RTS (Solaris OS)

Note: Shell command lines that are shown with a '#' are meant to be executed while you are logged in as the superuser (root).

To uninstall the Java RTS product, remove the installed packages, as in the following example:

# /usr/sbin/pkgrm SUNWrtjvx SUNWrtjv SUNWrtjc

The uninstall operation also removes the Java RTS rights profile that was optionally created during the product installation. The Solaris OS tunables that were set at install time are also restored to their default value, unless they have been since edited.

Reboot your system for these changes to take effect.

[Contents]

Upgrading Java RTS (Solaris OS)

Note: Shell command lines that are shown with a '#' are meant to be executed while you are logged in as the superuser (root).

If you have previously installed the Java RTS product and this distribution contains updated packages, first remove the currently installed packages as described in the previous section.

Then install the latest version of the packages. Note that you may be required to reboot your machine after the installation of the new kernel modules.

You can check the current version of packages with the following command:

# /usr/bin/pkginfo -l SUNWrtjvx SUNWrtjv SUNWrtjc

[Contents]

Installation of Java RTS for Linux OS

Java RTS 2.2 Update 1 for Linux is provided as a tarball. Java RTS requires about 400 MB of free disk space. You can install the tar file in any location you choose. If you are installing an evaluation version of Java RTS, it must be installed into a file system that will be writable by the end users.

System Configuration (Linux OS)

For improved determinism, the /tmp directory, where Java RTS keeps some of its temporary files, should be mounted with an in-memory file system such as tmpfs.

Installing 32-Bit and 64-Bit Java RTS (Linux OS)

The 32-bit and 64-bit versions of Java RTS are provided as complete, and independent, tarballs.

Change to the directory where you wish to install Java RTS and untar the downloaded tarball, as in the following example:

tar xvzf jrts-2.2-linux-i586-eval90days.tgz

If you wish to install both the 32-bit and 64-bit versions of Java RTS then you will need to untar them in different directories.

After installing Java RTS, make sure that users will be able to gain access to system resources, as described in the next section.

For information about compiling and executing applications, refer to the Technical Information document.

Granting Resource Access Privileges to Java RTS Users (Linux OS)

To run deterministically, a real-time application must be granted unrestricted access to a number of resources (for example, processor cycles, real-time priorities) that are not fully available to regular processes. For Linux, this can be achieved by properly configuring the resource limits of the pluggable authentication modules (PAM) of the system.

Adding the following lines to the /etc/security/limits.conf file grants the required resources to members of the realtime group:

@realtime       soft    cpu             unlimited
@realtime       -       rtprio          100
@realtime       -       nice            40
@realtime       -       memlock         unlimited

The realtime group must exist on the system, and users of Java RTS must be added to this group.

On Red Hat Enterprise MRG 1.0 and later and on SUSE Linux Enterprise Real Time 10 Service Pack 2 (SLERT SP2) and later, the PAM configuration for the realtime group is done at operating system installation time. The only configuration step required is to add the users to the realtime group.

Note: You might need to relogin for the privilege settings to take effect.

Contact your system administrator or your computer security manager for guidelines regarding the setup of privileges that are compatible with your local computer security management policies.

[Contents]