411 lines
16 KiB
Groff
411 lines
16 KiB
Groff
.\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
|
|
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
.\"
|
|
.\" This code is free software; you can redistribute it and/or modify it
|
|
.\" under the terms of the GNU General Public License version 2 only, as
|
|
.\" published by the Free Software Foundation.
|
|
.\"
|
|
.\" This code is distributed in the hope that it will be useful, but WITHOUT
|
|
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
.\" version 2 for more details (a copy is included in the LICENSE file that
|
|
.\" accompanied this code).
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public License version
|
|
.\" 2 along with this work; if not, write to the Free Software Foundation,
|
|
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
.\"
|
|
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
.\" or visit www.oracle.com if you need additional information or have any
|
|
.\" questions.
|
|
.\"
|
|
.\" Automatically generated by Pandoc 2.3.1
|
|
.\"
|
|
.TH "RMID" "1" "2020" "JDK 14" "JDK Commands"
|
|
.hy
|
|
.SH NAME
|
|
.PP
|
|
rmid \- start the activation system daemon that enables objects to be
|
|
registered and activated in a Java Virtual Machine (JVM)
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[CB]rmid\f[R] [\f[I]options\f[R]]
|
|
.TP
|
|
.B \f[I]options\f[R]
|
|
This represent the command\-line options for the \f[CB]rmid\f[R] command.
|
|
See \f[B]Options for rmid\f[R].
|
|
.RS
|
|
.RE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \f[CB]rmid\f[R] command starts the activation system daemon.
|
|
The activation system daemon must be started before objects that can be
|
|
activated are either registered with the activation system or activated
|
|
in a JVM.
|
|
.PP
|
|
Start the daemon by executing the \f[CB]rmid\f[R] command and specifying a
|
|
security policy file, as follows:
|
|
.RS
|
|
.PP
|
|
\f[CB]rmid\ \-J\-Djava.security.policy=rmid.policy\f[R]
|
|
.RE
|
|
.PP
|
|
When you run Oracle\[aq]s implementation of the \f[CB]rmid\f[R] command,
|
|
by default you must specify a security policy file so that the
|
|
\f[CB]rmid\f[R] command can verify whether or not the information in each
|
|
\f[CB]ActivationGroupDesc\f[R] is allowed to be used to start a JVM for an
|
|
activation group.
|
|
Specifically, the command and options specified by the
|
|
\f[CB]CommandEnvironment\f[R] and any properties passed to an
|
|
\f[CB]ActivationGroupDesc\f[R] constructor must now be explicitly allowed
|
|
in the security policy file for the \f[CB]rmid\f[R] command.
|
|
The value of the \f[CB]sun.rmi.activation.execPolicy\f[R] property
|
|
dictates the policy that the \f[CB]rmid\f[R] command uses to determine
|
|
whether or not the information in an \f[CB]ActivationGroupDesc\f[R] can be
|
|
used to start a JVM for an activation group.
|
|
For more information see the description of the
|
|
\f[CB]\-J\-Dsun.rmi.activation.execPolicy=policy\f[R] option.
|
|
.PP
|
|
Executing the \f[CB]rmid\f[R] command starts the \f[CB]Activator\f[R] and an
|
|
internal registry on the default port 1098 and binds an
|
|
\f[CB]ActivationSystem\f[R] to the name
|
|
\f[CB]java.rmi.activation.ActivationSystem\f[R] in this internal registry.
|
|
.PP
|
|
To specify an alternate port for the registry, you must specify the
|
|
\f[CB]\-port\f[R] option when you execute the \f[CB]rmid\f[R] command.
|
|
For example, the following command starts the activation system daemon
|
|
and a registry on the registry\[aq]s default port, 1099.
|
|
.RS
|
|
.PP
|
|
\f[CB]rmid\ \-J\-Djava.security.policy=rmid.policy\ \-port\ 1099\f[R]
|
|
.RE
|
|
.SH START RMID ON DEMAND (ORACLE SOLARIS AND LINUX ONLY)
|
|
.PP
|
|
An alternative to starting \f[CB]rmid\f[R] from the command line is to
|
|
configure \f[CB]inetd\f[R] (Oracle Solaris) or \f[CB]xinetd\f[R] (Linux) to
|
|
start \f[CB]rmid\f[R] on demand.
|
|
.PP
|
|
When RMID starts, it attempts to obtain an inherited channel (inherited
|
|
from \f[CB]inetd\f[R]/\f[CB]xinetd\f[R]) by calling the
|
|
\f[CB]System.inheritedChannel\f[R] method.
|
|
If the inherited channel is null or not an instance of
|
|
\f[CB]java.nio.channels.ServerSocketChannel\f[R], then RMID assumes that
|
|
it wasn\[aq]t started by \f[CB]inetd\f[R]/\f[CB]xinetd\f[R], and it starts
|
|
as previously described.
|
|
.PP
|
|
If the inherited channel is a \f[CB]ServerSocketChannel\f[R] instance,
|
|
then RMID uses the \f[CB]java.net.ServerSocket\f[R] obtained from the
|
|
\f[CB]ServerSocketChannel\f[R] as the server socket that accepts requests
|
|
for the remote objects it exports: The registry in which the
|
|
\f[CB]java.rmi.activation.ActivationSystem\f[R] is bound and the
|
|
\f[CB]java.rmi.activation.Activator\f[R] remote object.
|
|
In this mode, RMID behaves the same as when it is started from the
|
|
command line, except in the following cases:
|
|
.IP \[bu] 2
|
|
Output printed to \f[CB]System.err\f[R] is redirected to a file.
|
|
This file is located in the directory specified by the
|
|
\f[CB]java.io.tmpdir\f[R] system property (typically \f[CB]/var/tmp\f[R] or
|
|
\f[CB]/tmp\f[R]) with the prefix \f[CB]rmid\-err\f[R] and the suffix
|
|
\f[CB]tmp\f[R].
|
|
.IP \[bu] 2
|
|
The \f[CB]\-port\f[R] option isn\[aq]t allowed.
|
|
If this option is specified, then RMID exits with an error message.
|
|
.IP \[bu] 2
|
|
The \f[CB]\-log\f[R] option is required.
|
|
If this option isn\[aq]t specified, then RMID exits with an error
|
|
message
|
|
.SH OPTIONS FOR RMID
|
|
.TP
|
|
.B \f[CB]\-C\f[R]\f[I]option\f[R]
|
|
Specifies an option that\[aq]s passed as a command\-line argument to
|
|
each child process (activation group) of the \f[CB]rmid\f[R] command when
|
|
that process is created.
|
|
For example, you could pass a property to each virtual machine spawned
|
|
by the activation system daemon:
|
|
.RS
|
|
.RS
|
|
.PP
|
|
\f[CB]rmid\ \-C\-Dsome.property=value\f[R]
|
|
.RE
|
|
.PP
|
|
This ability to pass command\-line arguments to child processes can be
|
|
useful for debugging.
|
|
For example, the following command enables server\-call logging in all
|
|
child JVMs.
|
|
.RS
|
|
.PP
|
|
\f[CB]rmid\ \-C\-Djava.rmi.server.logCalls=true\f[R]
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-J\f[R]\f[I]option\f[R]
|
|
Specifies an option that\[aq]s passed to the Java interpreter running
|
|
RMID command.
|
|
For example, to specify that the \f[CB]rmid\f[R] command use a policy file
|
|
named \f[CB]rmid.policy\f[R], the \f[CB]\-J\f[R] option can be used to
|
|
define the \f[CB]java.security.policy\f[R] property on the \f[CB]rmid\f[R]
|
|
command line, for example:
|
|
.RS
|
|
.RS
|
|
.PP
|
|
\f[CB]rmid\ \-J\-Djava.security.policy\-rmid.policy\f[R]
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-J\-Dsun.rmi.activation.execPolicy=\f[R]\f[I]policy\f[R]
|
|
Specifies the policy that the RMID command employs to check commands and
|
|
command\-line options used to start the JVM in which an activation group
|
|
runs.
|
|
This option exists only in Oracle\[aq]s implementation of the Java RMI
|
|
activation daemon.
|
|
If this property isn\[aq]t specified on the command line, then the
|
|
result is the same as though
|
|
\f[CB]\-J\-Dsun.rmi.activation.execPolicy=default\f[R] were specified.
|
|
.RS
|
|
.PP
|
|
The possible values of \f[I]policy\f[R] can be \f[CB]default\f[R],
|
|
\f[I]policyClassName\f[R], or \f[CB]none\f[R].
|
|
.IP \[bu] 2
|
|
\f[CB]default\f[R]
|
|
.RS 2
|
|
.PP
|
|
The \f[CB]default\f[R] or unspecified value \f[CB]execPolicy\f[R] allows the
|
|
\f[CB]rmid\f[R] command to execute commands with specific command\-line
|
|
options only when the \f[CB]rmid\f[R] command was granted permission to
|
|
execute those commands and options in the security policy file that the
|
|
\f[CB]rmid\f[R] command uses.
|
|
Only the default activation group implementation can be used with the
|
|
default execution policy.
|
|
.PP
|
|
The \f[CB]rmid\f[R] command starts a JVM for an activation group with the
|
|
information in the group\[aq]s registered activation group descriptor,
|
|
\f[CB]ActivationGroupDesc\f[R].
|
|
The group descriptor specifies an optional
|
|
\f[CB]ActivationGroupDesc.CommandEnvironment\f[R] that includes the
|
|
command to execute to start the activation group and any command\-line
|
|
options to be added to the command line.
|
|
By default, the \f[CB]rmid\f[R] command uses the \f[CB]java\f[R] command
|
|
found in \f[CB]java.home\f[R].
|
|
The group descriptor also contains properties overrides that are added
|
|
to the command line as options defined as:
|
|
\f[CB]\-D\f[R]\f[I]property\f[R]\f[CB]=\f[R]\f[I]value\f[R].
|
|
The \f[CB]com.sun.rmi.rmid.ExecPermission\f[R] permission grants the
|
|
\f[CB]rmid\f[R] command permission to execute a command that\[aq]s
|
|
specified in the group descriptor\[aq]s \f[CB]CommandEnvironment\f[R] to
|
|
start an activation group.
|
|
The \f[CB]com.sun.rmi.rmid.ExecOptionPermission\f[R] permission enables
|
|
the \f[CB]rmid\f[R] command to use command\-line options, specified as
|
|
properties overrides in the group descriptor or as options in the
|
|
\f[CB]CommandEnvironment\f[R] when starting the activation group.
|
|
When granting the \f[CB]rmid\f[R] command permission to execute various
|
|
commands and options, the permissions \f[CB]ExecPermission\f[R] and
|
|
\f[CB]ExecOptionPermission\f[R] must be granted to all code sources.
|
|
.PP
|
|
\f[CB]ExecPermission\f[R] class: Represents permission for the
|
|
\f[CB]rmid\f[R] command to execute a specific command to start an
|
|
activation group.
|
|
.PP
|
|
\f[CB]ExecPermission\f[R] syntax: The name of \f[CB]ExecPermission\f[R] is
|
|
the path name of a command to grant the \f[CB]rmid\f[R] command permission
|
|
to execute.
|
|
.PP
|
|
A path name that ends in a slash (\f[CB]/\f[R]) and an asterisk
|
|
(\f[CB]*\f[R]) indicates that all of the files are contained in that
|
|
directory where the slash is the file\-separator character,
|
|
\f[CB]File.separatorChar\f[R].
|
|
.PP
|
|
A path name that ends in a slash (\f[CB]/\f[R]) and a minus sign
|
|
(\f[CB]\-\f[R]) indicates that all files and subdirectories are contained
|
|
in that directory (recursively).
|
|
.PP
|
|
A path name that consists of the special token \f[CB]<<ALL\ FILES>>\f[R]
|
|
matches any file.
|
|
.PP
|
|
A path name that consists of an asterisk (\f[CB]*\f[R]) indicates that all
|
|
the files are in the current directory.
|
|
.PP
|
|
A path name that consists of a minus sign (\f[CB]\-\f[R]) indicates that
|
|
all the files are in the current directory and (recursively) all files
|
|
and subdirectories are contained in the current directory.
|
|
.PP
|
|
\f[CB]ExecOptionPermission\f[R] class: Represents permission for the
|
|
\f[CB]rmid\f[R] command to use a specific command\-line option when
|
|
starting an activation group.
|
|
The name of \f[CB]ExecOptionPermission\f[R] is the value of a
|
|
command\-line option.
|
|
.PP
|
|
\f[CB]ExecOptionPermission\f[R] syntax: Options support a limited wild
|
|
card scheme.
|
|
An asterisk signifies a wild card match, and it can appear as the option
|
|
name itself (matches any option), or an asterisk (*) can appear at the
|
|
end of the option name only when the asterisk (\f[CB]*\f[R]) follows a dot
|
|
(\f[CB]\&.\f[R]) or an equals sign (\f[CB]=\f[R]).
|
|
.PP
|
|
For example: \f[CB]*\f[R] or \f[CB]\-Dmydir.*\f[R] or \f[CB]\-Da.b.c=*\f[R] is
|
|
valid, but \f[CB]*mydir\f[R] or \f[CB]\-Da*b\f[R] or \f[CB]ab*\f[R] isn\[aq]t
|
|
valid.
|
|
.PP
|
|
\f[B]Policy file for rmid\f[R]
|
|
.PP
|
|
When you grant the \f[CB]rmid\f[R] command permission to execute various
|
|
commands and options, the permissions \f[CB]ExecPermission\f[R] and
|
|
\f[CB]ExecOptionPermission\f[R] must be granted to all code sources
|
|
(universally).
|
|
It is safe to grant these permissions universally because only the
|
|
\f[CB]rmid\f[R] command checks these permissions.
|
|
.PP
|
|
An example policy file that grants various execute permissions to the
|
|
\f[CB]rmid\f[R] command is:
|
|
.IP \[bu] 2
|
|
\f[B]Oracle Solaris:\f[R]
|
|
.RS 2
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
grant\ {
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecPermission
|
|
\ \ \ \ \ \ \ \ "/files/apps/java/jdk1.7.0/solaris/bin/java";
|
|
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecPermission
|
|
\ \ \ \ \ \ \ \ "/files/apps/rmidcmds/*";
|
|
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecOptionPermission
|
|
\ \ \ \ \ \ \ \ "\-Djava.security.policy=/files/policies/group.policy";
|
|
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecOptionPermission
|
|
\ \ \ \ \ \ \ \ "\-Djava.security.debug=*";
|
|
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecOptionPermission
|
|
\ \ \ \ \ \ \ \ "\-Dsun.rmi.*";
|
|
};
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[B]Windows:\f[R]
|
|
.RS 2
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
grant\ {
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecPermission
|
|
\ \ \ \ \ \ \ \ "c:\\\\files\\\\apps\\\\java\\\\jdk1.7.0\\\\win\\\\bin\\\\java";
|
|
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecPermission
|
|
\ \ \ \ \ \ \ \ "c:\\\\files\\\\apps\\\\rmidcmds\\\\*";
|
|
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecOptionPermission
|
|
\ \ \ \ \ \ \ \ "\-Djava.security.policy=c:\\\\files\\\\policies\\\\group.policy";
|
|
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecOptionPermission
|
|
\ \ \ \ \ \ \ \ "\-Djava.security.debug=*";
|
|
|
|
\ \ \ \ permission\ com.sun.rmi.rmid.ExecOptionPermission
|
|
\ \ \ \ \ \ \ \ "\-Dsun.rmi.*";
|
|
};
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.PP
|
|
The first permission granted allows the \f[CB]rmid\f[R] command to execute
|
|
the 1.7.0 release of the \f[CB]java\f[R] command, specified by its
|
|
explicit path name.
|
|
By default, the version of the \f[CB]java\f[R] command found in
|
|
\f[CB]java.home\f[R] is used (the same one that the \f[CB]rmid\f[R] command
|
|
uses), and doesn\[aq]t need to be specified in the policy file.
|
|
The second permission allows the \f[CB]rmid\f[R] command to execute any
|
|
command in either the directory \f[CB]/files/apps/rmidcmds\f[R] (Oracle
|
|
Solaris, Linux, and macOS) or the directory
|
|
\f[CB]c:\\files\\apps\\rmidcmds\\\f[R] (Windows).
|
|
.PP
|
|
The third permission granted, \f[CB]ExecOptionPermission\f[R], allows the
|
|
\f[CB]rmid\f[R] command to start an activation group that defines the
|
|
security policy file to be either \f[CB]/files/policies/group.policy\f[R]
|
|
(Oracle Solaris) or \f[CB]c:\\files\\policies\\group.policy\f[R]
|
|
(Windows).
|
|
The next permission allows the \f[CB]java.security.debug\ property\f[R] to
|
|
be used by an activation group.
|
|
The last permission allows any property in the
|
|
\f[CB]sun.rmi\ property\f[R] name hierarchy to be used by activation
|
|
groups.
|
|
.PP
|
|
To start the \f[CB]rmid\f[R] command with a policy file, the
|
|
\f[CB]java.security.policy\f[R] property needs to be specified on the
|
|
\f[CB]rmid\f[R] command line, for example:
|
|
.PP
|
|
\f[CB]rmid\ \-J\-Djava.security.policy=rmid.policy\f[R].
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[I]policyClassName\f[R]
|
|
.RS 2
|
|
.PP
|
|
If the default behavior isn\[aq]t flexible enough, then an administrator
|
|
can provide, when starting the \f[CB]rmid\f[R] command, the name of a
|
|
class whose \f[CB]checkExecCommand\f[R] method is executed to check
|
|
commands to be executed by the \f[CB]rmid\f[R] command.
|
|
.PP
|
|
The \f[CB]policyClassName\f[R] specifies a public class with a public,
|
|
no\-argument constructor and an implementation of the following
|
|
\f[CB]checkExecCommand\f[R] method:
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
\ public\ void\ checkExecCommand(ActivationGroupDesc\ desc,\ String[]\ command)
|
|
\ \ \ \ \ \ \ \ throws\ SecurityException;
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Before starting an activation group, the \f[CB]rmid\f[R] command calls the
|
|
policy\[aq]s \f[CB]checkExecCommand\f[R] method and passes to it the
|
|
activation group descriptor and an array that contains the complete
|
|
command to start the activation group.
|
|
If the \f[CB]checkExecCommand\f[R] throws a \f[CB]SecurityException\f[R],
|
|
then the \f[CB]rmid\f[R] command doesn\[aq]t start the activation group
|
|
and an \f[CB]ActivationException\f[R] is thrown to the caller attempting
|
|
to activate the object.
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CB]none\f[R]
|
|
.RS 2
|
|
.PP
|
|
If the \f[CB]sun.rmi.activation.execPolicy\f[R] property value is
|
|
\f[CB]none\f[R], then the \f[CB]rmid\f[R] command doesn\[aq]t perform any
|
|
validation of commands to start activation groups.
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-log\f[R] \f[I]dir\f[R]
|
|
Specifies the name of the directory that the activation system daemon
|
|
uses to write its database and associated information.
|
|
The log directory defaults to creating a log, in the directory in which
|
|
the \f[CB]rmid\f[R] command was executed.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-port\f[R] \f[I]port\f[R]
|
|
Specifies the port that the registry uses.
|
|
The activation system daemon binds \f[CB]ActivationSystem\f[R], with the
|
|
name \f[CB]java.rmi.activation.ActivationSystem\f[R], in this registry.
|
|
The \f[CB]ActivationSystem\f[R] on the local machine can be obtained using
|
|
the following \f[CB]Naming.lookup\f[R] method call:
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
import\ java.rmi.*;
|
|
import\ java.rmi.activation.*;
|
|
|
|
ActivationSystem\ system;\ system\ =\ (ActivationSystem)
|
|
Naming.lookup("//:port/java.rmi.activation.ActivationSystem");
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-stop\f[R]
|
|
Stops the current invocation of the \f[CB]rmid\f[R] command for a port
|
|
specified by the \f[CB]\-port\f[R] option.
|
|
If no port is specified, then this option stops the \f[CB]rmid\f[R]
|
|
invocation running on port 1098.
|
|
.RS
|
|
.RE
|