Sun Java Real-Time System 2.0_01 Installation Guide

Installation Guide

Sun Java Real-Time System 2.0_01

Introduction

Installing the Java RTS Virtual Machine

Installing the Kernel Modules

Uninstalling Java RTS

Upgrading Java RTS

Granting Privileges to Java RTS Users

[Readme File] [Release Notes] [Compilation Guide] [Garbage Collection Guide] [Technical Information] [Java RTS DTrace Provider] [Practical Introduction to Achieving Determinism]

Introduction

This set of HTML files comprises the documentation for the delivery of Sun Java™ Real-Time System 2.0_01 (Java RTS). This delivery consists of a set of Solaris™ packages containing 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 kernel modules that are necessary to run Java RTS.

The Java RTS Virtual Machine 2.0_01, which is based on the Java Platform, Standard Edition version 5 (Update 13), accepts a number of options and properties that are specific to the Java RTS release.

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/).

[Contents]

Installing the Java RTS Virtual Machine

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.0_01.

If Solaris 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 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 Privileges to Java RTS Users below 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 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

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 version of the Solaris Operating System. If you attempt to install a package on a version of Solaris 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 OS version may adversely affect the behavior of the operating system.

[Contents]

Uninstalling Java RTS

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

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]

Granting Privileges to Java RTS Users

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

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

This is typically achieved by means of a specific rights profile, that is, a collection of commands with security attributes. Rights profiles are usually included in an administrative role, and the role is then assigned to a user. Direct assignment of rights profiles to a user is also possible. In that latter case, this user must use a profile shell such as pfsh(1) or pfcsh(1) for the commands with security attributes to succeed.

Rights profiles can be managed using the Solaris Management Console, smc(1), a graphical user interface that provides access to Solaris system administration tools.

To invoke the Solaris Management Console, type the following command:

# /usr/sbin/smc

The 'Java Real-Time System User' rights profile can also 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.

This rights profile can also be directly assigned to a Solaris user by using:

# /usr/sbin/usermod -P "Java Real-Time System User" <username>

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

Alternatively, you can decide not to use the Java RTS profile and assign additional rights directly to the Java RTS users. In the latter 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 rights.

Rights management is implemented on Solaris 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.

If you decide to bypass the Java RTS rights profile, then the Java RTS users must be granted at least the following privileges, for them 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.

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). To assign privileges to a non-local user, add the following line to the /etc/user_attr file:

<username>::::type=normal;profiles=Basic Solaris User;
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.

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]