Installation Guide

Sun Java Real-Time System 2.1

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

The Java RTS Virtual Machine 2.1 is based on the Java Platform, Standard Edition version 5 (update 16).

Java RTS implements the 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/).

Readme File: Links to all the Java RTS technical documents

Installation of Java RTS for Solaris OS

Installing the 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 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.

[Contents]

Installing the 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.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 300 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_13_Java-RTS-2.0_01-b07_RTSJ-1.0.2,REV=2007.10.23.18.39
  Copyright 2007 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 the following section for a description of their installation procedure.

[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) 
  1.0.0,REV=2007.11.07.14.31
  Copyright 2007 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 follows:

# /usr/sbin/pkgrm 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 SUNWrtjv SUNWrtjc

[Contents]

Installation of Java RTS for Linux OS

Java RTS 2.1 for Linux is provided as a tarball. You can install it 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 Java RTS (Linux OS)

Change to the directory where you wish to install Java RTS and execute the following command:

tar xvzf java_rts-2.1.tgz

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 on SUSE Linux Enterprise Real Time 10 Service Pack 2 (SLERT SP2), 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.

Note: Users must execute the Java RTS binaries in a shell that is privilege-aware.

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]