| .\" Copyright (c) 2004, 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 "JSTATD" "1" "2021" "JDK 17" "JDK Commands" |
| .hy |
| .SH NAME |
| .PP |
| jstatd \- monitor the creation and termination of instrumented Java |
| HotSpot VMs |
| .SH SYNOPSIS |
| .PP |
| \f[B]Note:\f[R] This command is experimental and unsupported. |
| .PP |
| \f[CB]jstatd\f[R] [\f[I]options\f[R]] |
| .TP |
| .B \f[I]options\f[R] |
| This represents the \f[CB]jstatd\f[R] command\-line options. |
| See \f[B]Options for the jstatd Command\f[R]. |
| .RS |
| .RE |
| .SH DESCRIPTION |
| .PP |
| The \f[CB]jstatd\f[R] command is an RMI server application that monitors |
| for the creation and termination of instrumented Java HotSpot VMs and |
| provides an interface to enable remote monitoring tools, \f[CB]jstat\f[R] |
| and \f[CB]jps\f[R], to attach to JVMs that are running on the local host |
| and collect information about the JVM process. |
| .PP |
| The \f[CB]jstatd\f[R] server requires an RMI registry on the local host. |
| The \f[CB]jstatd\f[R] server attempts to attach to the RMI registry on the |
| default port, or on the port you specify with the \f[CB]\-p\f[R] |
| \f[CB]port\f[R] option. |
| If an RMI registry is not found, then one is created within the |
| \f[CB]jstatd\f[R] application that\[aq]s bound to the port that\[aq]s |
| indicated by the \f[CB]\-p\f[R] \f[CB]port\f[R] option or to the default RMI |
| registry port when the \f[CB]\-p\f[R] \f[CB]port\f[R] option is omitted. |
| You can stop the creation of an internal RMI registry by specifying the |
| \f[CB]\-nr\f[R] option. |
| .SH OPTIONS FOR THE JSTATD COMMAND |
| .TP |
| .B \f[CB]\-nr\f[R] |
| This option does not attempt to create an internal RMI registry within |
| the \f[CB]jstatd\f[R] process when an existing RMI registry isn\[aq]t |
| found. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-p\f[R] \f[I]port\f[R] |
| This option sets the port number where the RMI registry is expected to |
| be found, or when not found, created if the \f[CB]\-nr\f[R] option |
| isn\[aq]t specified. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-r\f[R] \f[I]rmiport\f[R] |
| This option sets the port number to which the RMI connector is bound. |
| If not specified a random available port is used. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-n\f[R] \f[I]rminame\f[R] |
| This option sets the name to which the remote RMI object is bound in the |
| RMI registry. |
| The default name is \f[CB]JStatRemoteHost\f[R]. |
| If multiple \f[CB]jstatd\f[R] servers are started on the same host, then |
| the name of the exported RMI object for each server can be made unique |
| by specifying this option. |
| However, doing so requires that the unique server name be included in |
| the monitoring client\[aq]s \f[CB]hostid\f[R] and \f[CB]vmid\f[R] strings. |
| .RS |
| .RE |
| .TP |
| .B \f[CB]\-J\f[R]\f[I]option\f[R] |
| This option passes a Java \f[CB]option\f[R] to the JVM, where the option |
| is one of those described on the reference page for the Java application |
| launcher. |
| For example, \f[CB]\-J\-Xms48m\f[R] sets the startup memory to 48 MB. |
| See \f[B]java\f[R]. |
| .RS |
| .RE |
| .SH SECURITY |
| .PP |
| The \f[CB]jstatd\f[R] server can monitor only JVMs for which it has the |
| appropriate native access permissions. |
| Therefore, the \f[CB]jstatd\f[R] process must be running with the same |
| user credentials as the target JVMs. |
| Some user credentials, such as the root user in Linux and OS X operating |
| systems, have permission to access the instrumentation exported by any |
| JVM on the system. |
| A \f[CB]jstatd\f[R] process running with such credentials can monitor any |
| JVM on the system, but introduces additional security concerns. |
| .PP |
| The \f[CB]jstatd\f[R] server doesn\[aq]t provide any authentication of |
| remote clients. |
| Therefore, running a \f[CB]jstatd\f[R] server process exposes the |
| instrumentation export by all JVMs for which the \f[CB]jstatd\f[R] process |
| has access permissions to any user on the network. |
| This exposure might be undesirable in your environment, and therefore, |
| local security policies should be considered before you start the |
| \f[CB]jstatd\f[R] process, particularly in production environments or on |
| networks that aren\[aq]t secure. |
| .PP |
| The \f[CB]jstatd\f[R] server installs an instance of |
| \f[CB]RMISecurityPolicy\f[R] when no other security manager is installed, |
| and therefore, requires a security policy file to be specified. |
| The policy file must conform to Default Policy Implementation and Policy |
| File Syntax. |
| .PP |
| If your security concerns can\[aq]t be addressed with a customized |
| policy file, then the safest action is to not run the \f[CB]jstatd\f[R] |
| server and use the \f[CB]jstat\f[R] and \f[CB]jps\f[R] tools locally. |
| However, when using \f[CB]jps\f[R] to get a list of instrumented JVMs, the |
| list will not include any JVMs running in docker containers. |
| .SH REMOTE INTERFACE |
| .PP |
| The interface exported by the \f[CB]jstatd\f[R] process is proprietary and |
| guaranteed to change. |
| Users and developers are discouraged from writing to this interface. |
| .SH EXAMPLES |
| .PP |
| The following are examples of the \f[CB]jstatd\f[R] command. |
| The \f[CB]jstatd\f[R] scripts automatically start the server in the |
| background. |
| .SH INTERNAL RMI REGISTRY |
| .PP |
| This example shows how to start a \f[CB]jstatd\f[R] session with an |
| internal RMI registry. |
| This example assumes that no other server is bound to the default RMI |
| registry port (port \f[CB]1099\f[R]). |
| .RS |
| .PP |
| \f[CB]jstatd\ \-J\-Djava.security.policy=all.policy\f[R] |
| .RE |
| .SH EXTERNAL RMI REGISTRY |
| .PP |
| This example starts a \f[CB]jstatd\f[R] session with an external RMI |
| registry. |
| .IP |
| .nf |
| \f[CB] |
| rmiregistry& |
| jstatd\ \-J\-Djava.security.policy=all.policy |
| \f[R] |
| .fi |
| .PP |
| This example starts a \f[CB]jstatd\f[R] session with an external RMI |
| registry server on port \f[CB]2020\f[R]. |
| .IP |
| .nf |
| \f[CB] |
| jrmiregistry\ 2020& |
| jstatd\ \-J\-Djava.security.policy=all.policy\ \-p\ 2020 |
| \f[R] |
| .fi |
| .PP |
| This example starts a \f[CB]jstatd\f[R] session with an external RMI |
| registry server on port \f[CB]2020\f[R] and JMX connector bound to port |
| \f[CB]2021\f[R]. |
| .IP |
| .nf |
| \f[CB] |
| jrmiregistry\ 2020& |
| jstatd\ \-J\-Djava.security.policy=all.policy\ \-p\ 2020\ \-r\ 2021 |
| \f[R] |
| .fi |
| .PP |
| This example starts a \f[CB]jstatd\f[R] session with an external RMI |
| registry on port 2020 that\[aq]s bound to |
| \f[CB]AlternateJstatdServerName\f[R]. |
| .IP |
| .nf |
| \f[CB] |
| rmiregistry\ 2020& |
| jstatd\ \-J\-Djava.security.policy=all.policy\ \-p\ 2020\ \-n\ AlternateJstatdServerName |
| \f[R] |
| .fi |
| .SH STOP THE CREATION OF AN IN\-PROCESS RMI REGISTRY |
| .PP |
| This example starts a \f[CB]jstatd\f[R] session that doesn\[aq]t create an |
| RMI registry when one isn\[aq]t found. |
| This example assumes an RMI registry is already running. |
| If an RMI registry isn\[aq]t running, then an error message is |
| displayed. |
| .RS |
| .PP |
| \f[CB]jstatd\ \-J\-Djava.security.policy=all.policy\ \-nr\f[R] |
| .RE |
| .SH ENABLE RMI LOGGING |
| .PP |
| This example starts a \f[CB]jstatd\f[R] session with RMI logging |
| capabilities enabled. |
| This technique is useful as a troubleshooting aid or for monitoring |
| server activities. |
| .RS |
| .PP |
| \f[CB]jstatd\ \-J\-Djava.security.policy=all.policy\ \-J\-Djava.rmi.server.logCalls=true\f[R] |
| .RE |