| .\" Copyright (c) 1998, 2020, 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 15" "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 |
| \f[B]Deprecation Notice:\f[R] The rmid tool and the RMI Activation |
| mechanism have been deprecated and may be removed from a future version |
| of the platform. |
| See \f[B]JEP 385\f[R] [https://openjdk.java.net/jeps/385] for further |
| information. |
| .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 (LINUX ONLY) |
| .PP |
| An alternative to starting \f[CB]rmid\f[R] from the command line is to |
| configure \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]Linux:\f[R] |
| .RS 2 |
| .IP |
| .nf |
| \f[CB] |
| grant\ { |
| \ \ \ \ permission\ com.sun.rmi.rmid.ExecPermission |
| \ \ \ \ \ \ \ \ "/files/apps/java/jdk1.7.0/linux/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] (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] |
| (Linux) 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 |