Overview of Payara Server Administration
Payara Server provides a runtime for developing and deploying Jakarta EE Platform and Eclipse MicroProfile applications.
As an administrator of Payara Server, your main responsibilities are to establish a secure Payara Server environment and to oversee the services, resources, and users that participate in that environment.
Your key tasks include configuring resources and services, managing Payara Server at runtime, and fixing problems that are associated with the server’s operation.
Default Settings and Locations
After installation, you might need to perform some immediate configuration tasks to make your installation function as intended.
If configuration defaults have been accepted, some features are enabled and some not. For an overview of initial configuration tasks for Payara Server services and resources, see Initial Configuration Tasks.
In addition, you might want to reset default passwords, change names or locations of files, and so on.
The following tables list the default administration values.
The default administrator login is admin , with no password, which means that no login is required.
|
Default Administration Values
Item | Default |
---|---|
Domain Name |
|
Master Password |
|
Administration User |
|
Administration Server Port |
|
HTTP Port |
|
HTTPS Port |
|
Pure JMX Clients Port |
|
Message Queue Port |
|
IIOP Port |
|
IIOP/SSL Port |
|
IIOP/SSL Port With Mutual Authentication |
|
Item | Default |
---|---|
Command-line Utility ( |
|
Configuration Files |
|
Log Files |
|
Configuration Tasks
Some configuration tasks must be performed directly after installation for your Payara Server environment to work as intended. For example, if you are using a database with Payara Server, you need to set up database connectivity right away.
Some configuration situations are ongoing and will require you to make changes many times during the life of your installation. You can use either the Administration Console or the asadmin
utility to modify the configuration. Changes are automatically applied to the appropriate configuration file.
Initial Configuration Tasks
This section maps the common configuration tasks to the command-line procedures in this guide. In some situations, the resource or service is automatically enabled and your configuration tasks involve adjusting or changing the default settings to suit your specific needs.
The following resources and services frequently require configuration immediately after installation:
- System Properties
- Domains
-
The initial
domain1
is created during installation. Additional configuration tasks might include such tasks as configuring additional domains or setting up automatic restart. See Administering Domains. - JVM
-
The initial tasks for configuring the JVM include creating JVM options and profilers.
- Logging
-
By default, logging is enabled, so basic logging works without additional configuration. However, you might want to change log levels, property values, or the location of log files. See Administering the Logging Service.
- Monitoring
-
By default, the monitoring service is enabled. However, monitoring for the individual modules is not enabled, so your first monitoring task is to enable monitoring for the modules that you want to monitor. See Administering the Monitoring Service.
- Life Cycle Modules
- Security
-
-
System Security. Initial configuration tasks might include setting up passwords, audit modules, and certificates. See "Administering System Security" in the Payara Server Security Guide.
-
User Security. Initial configuration tasks might include creating authentication realms and file users. See "Administering User Security" in the Payara Server Security Guide.
-
Message Security. Initial configuration tasks might include configuring a Java Cryptography Extension (JCE) provider, enabling default and non-default security providers, and configuring message protection policies. See "Administering Message Security" in the Payara Server Security Guide.
-
- Database Connectivity
-
The initial tasks involved in configuring Payara Server to connect to an external database include creating a Java Database Connectivity (JDBC) connection pool, creating a JDBC resource, and integrating a JDBC driver. See Administering Database Connectivity.
- EIS Connectivity
-
The initial tasks involved in configuring Payara Server to connect to an enterprise information system (EIS) include creating a connector connection pool, creating a connector resource, editing a resource adapter configuration, creating a connector security map, creating a connector work security map, and creating an administered object (if needed). See Administering EIS Connectivity.
- Internet Connectivity
-
The initial tasks involved in making deployed web applications accessible by internet clients include creating HTTP network listeners and virtual servers, and configuring the HTTP listeners for SSL (if needed). See Administering Internet Connectivity.
- Object Request Broker (ORB)
-
An initial configuration task might involve creating an IIOP listener. See Administering the Object Request Broker (ORB).
- JavaMail Service
-
An initial configuration task might involve creating a JavaMail resource. See Administering the JavaMail Service.
- Java Message Service (JMS)
-
Initial configuration tasks might include creating a physical destination, creating connection factories or destination resources, creating a JMS host (if the default JMS host is not adequate), adjusting connection pool settings (if needed), and configuring resource adapters for JMS. See Administering the Java Message Service (JMS).
- JNDI Service
-
An initial configuration task might involve creating a JNDI resource. See Administering the Java Naming and Directory Interface (JNDI) Service.
Information and instructions for accomplishing the tasks by using the Administration Console are contained in the Administration Console online help.
How Dotted Names Work for Configuration
After the initial configuration is working, you will continue to manage ongoing configuration for the life of your Payara Server installation.
You might need to adjust resources to improve productivity, or issues might arise that require settings to be modified or defaults to be reset. In some situations, an asadmin
subcommand is provided for updating, such as the update-connector-work-security-map
subcommand. However, most updating is done by using the list
, get
, and set
subcommands with dotted names. For detailed information about dotted names, see the dotted-names
(5ASC) help page.
Dotted names also apply to monitoring, but the method is slightly different. For information on using dotted names for monitoring, see How the Monitoring Tree Structure Works. |
The general process for working with configuration changes on the command line is as follows:
-
List the modules for the component of interest.
The following single mode example uses the|
(pipe) character and thegrep
command to narrow the search:asadmin list "*" | grep http | grep listener
shellInformation similar to the following is returned:
configs.config.server-config.network-config.network-listeners.network-listener.http-listener-1 configs.config.server-config.network-config.network-listeners.network-listener.http-listener-2 configs.config.server-config.network-config.protocols.protocol.admin-listener.http configs.config.server-config.network-config.protocols.protocol.admin-listener.http.file-cache configs.config.server-config.network-config.protocols.protocol.http-listener-1 configs.config.server-config.network-config.protocols.protocol.http-listener-1.http configs.config.server-config.network-config.protocols.protocol.http-listener-1.http.file-cache configs.config.server-config.network-config.protocols.protocol.http-listener-2 configs.config.server-config.network-config.protocols.protocol.http-listener-2.http configs.config.server-config.network-config.protocols.protocol.http-listener-2.http.file-cache configs.config.server-config.network-config.protocols.protocol.http-listener-2.ssl
text -
Get the attributes that apply to the module you are interested in.
The following multimode example gets the attributes and values for
http-listener-1
:asadmin> get server-config.network-config.network-listeners.network-listener.http-listener-1.*
shellInformation similar to the following is returned:
server.http-service.http-listener.http-listener-1.acceptor-threads = 1 server.http-service.http-listener.http-listener-1.address = 0.0.0.0 server.http-service.http-listener.http-listener-1.blocking-enabled = false server.http-service.http-listener.http-listener-1.default-virtual-server = server server.http-service.http-listener.http-listener-1.enabled = true server.http-service.http-listener.http-listener-1.external-port = server.http-service.http-listener.http-listener-1.family = inet server.http-service.http-listener.http-listener-1.id = http-listener-1 server.http-service.http-listener.http-listener-1.port = 8080 server.http-service.http-listener.http-listener-1.redirect-port = server.http-service.http-listener.http-listener-1.security-enabled = false server.http-service.http-listener.http-listener-1.server-name = server.http-service.http-listener.http-listener-1.xpowered-by = true
text -
Modify an attribute by using the
set
subcommand.This example sets the
security-enabled
attribute ofhttp-listener-1
to true:asadmin> set server.http-service.http-listener.http-listener-1.security-enabled = true
shell
Configuration Files
The bulk of the configuration information about Payara Server resources, applications, and instances is stored in the domain.xml
configuration file. This file is the central repository for a given administrative domain and contains an XML representation of the Payara Server domain model. The default location for the domain.xml
file is domain-dir/config
.
Payara Server maintains a backup of the domain.xml file that is named domain.xml.bak . The purpose of this file is solely to enable Payara Server to start a domain if the domain.xml file cannot be read. Do not modify or delete the domain.xml.bak file and do not use this file for any other purpose.
|
The logging.properties
file is used to configure logging levels for individual modules. The default logging.properties
file is located in the same directory as the domain.xml
file. For further information on the logging.properties
file, see Logging Properties.
The asenv.conf
file is located in the as-install/config
directory. Its purpose is to store the Payara Server environment variables, such as the installation location of the database, Message Queue, and so on.
Changes are automatically applied to the appropriate configuration file. Do not edit the configuration files directly. Manual editing is prone to error and can have unexpected results. |
Impact of Configuration Changes
Some configuration changes require that you restart the DAS or Payara Server instances for the changes to take effect. Other changes are applied dynamically without requiring that the DAS or instances be restarted. The procedures in this guide indicate when a restart is required. Payara Server enables you to determine whether the DAS or an instance must be restarted to apply configuration changes.
Some changes to resources or connection pools affect the applications that use the resources or connection pools. These changes do not require restart. However, any applications that use the resources or connection pools must be disabled and re-enabled or redeployed for the change to take effect.
To Determine Whether the DAS or an Instance Requires Restart
-
Ensure that the DAS is running.
To obtain information about the DAS or an instance, a running server is required. -
Do one of the following:
-
To determine if the DAS requires restart, list the domains in your Payara Server installation.
Use thelist-domains
subcommand for this purpose.asadmin> list-domains [--domaindir domain-root-dir]
shellThe domain-root-dir is the directory that contains the directories in which individual domains' configuration is stored. The default is
as-install/domains
, whereas-install
is the base installation directory of the Payara Server software.If the DAS requires restart, a statement that restart is required is displayed.
-
To determine if an instance requires restart, list information about the instance.
Use the
list-instances
subcommand for this purpose:asadmin> list-instances instance-name
shellThe instance-name is the name of the instance for which you are listing information.
If the instance requires restart, one of the following pieces of information is displayed: a statement that restart is required, or a list of configuration changes that are not yet applied to the instance.
-
Example 1-1 Determine whether the DAS or an instance requires restart
This example determines that the DAS for the domain domain1
requires restart to apply configuration changes.
asadmin> list-domains
domain1 running, restart required to apply configuration changes
Command list-domains executed successfully.
Example 1-2 Determine whether the DAS or an instance requires restart
This example determines that the instance pmd-i1
requires restart to apply configuration changes.
asadmin> list-instances pmd-i1
pmd-i1 running; requires restart
Command list-instances executed successfully.
You can also view the full syntax and options of the subcommands by typing the following commands at the command line.
-
asadmin help list-domains
-
asadmin help list-instances
Configuration Changes That Require Restart
The following configuration changes require restart for the changes to take effect:
-
Changing JVM options
-
Changing port numbers
-
Changing log handler elements
-
Configuring certificates
-
Managing HTTP, JMS, IIOP, JNDI services
-
Enabling or disabling secure administration as explained in "Running Secure Admin" in the Payara Server Security Guide
Dynamic Configuration Changes
With dynamic configuration, changes take effect while the DAS or instance is running. The following configuration changes do not require restart:
-
Adding or deleting add-on components
-
Adding or removing JDBC, JMS, and connector resources and pools (Exception: Some connection pool properties affect applications.)
-
Changing a system property that is not referenced by a JVM option or a port
-
Adding file realm users
-
Changing logging levels
-
Enabling and disabling monitoring
-
Changing monitoring levels for modules
-
Enabling and disabling resources and applications
-
Deploying, un-deploying, and redeploying applications
Changes That Affect Applications
Some changes to resources or connection pools affect the applications that use the resources or connection pools. These changes do not require restart. However, any applications that use the resources or connection pools must be disabled and re-enabled or redeployed for the change to take effect.
If you do not know which applications use the changed resources or connection pools, you can apply these changes by restarting the clusters or Payara Server instances to which applications are deployed. However, to minimize the disruption to the services that your applications provide, avoid restarting clusters or instances to apply these changes if possible. |
The following changes affect applications:
-
Creating or deleting resources (Exception: Changes to some JDBC, JMS, or connector resources do not affect applications.)
-
Modifying the following JDBC connection pool properties:
-
datasource-classname
-
associate-with-thread
-
lazy-connection-association
-
lazy-connection-enlistment
-
JDBC driver vendor-specific properties
-
-
Modifying the following connector connection pool properties:
-
resource-adapter-name
-
connection-definition-name
-
transaction-support
-
associate-with-thread
-
lazy-connection-association
-
lazy-connection-enlistment
-
Vendor-specific properties
-
Administration Tools
For the most part, you can perform the same tasks by using either the graphical Administration Console or the asadmin
command-line utility, however, there are exceptions.
Administration Console
The Administration Console is a browser-based utility that features an easy-to-navigate graphical interface that includes extensive online help for the administrative tasks.
To use the Administration Console, the domain administration server (DAS) must be running. Each domain has its own DAS, which has a unique port number. When Payara Server was installed, you chose a port number for the DAS, or used the default port of 4848. You also specified a username and password if you did not accept the default login (admin
with no password).
When specifying the URL for the Administration Console, use the port number for the domain to be administered. The format for starting the Administration Console in a web browser is http://hostname:port
. For example:
https://admin.payara.fish:4848
If the Administration Console is running on the host where Payara Server was installed, specify localhost
for the host name. For example:
http://localhost:4848
If the Administration Console is run on a host different from the host where Payara Server was installed, a secure connection (https
instead of http
) is used. Some browsers do not display pages on secure connections by default and must be configured to permit secure protocols (SSL and TLS).
You can display the help material for a page in the Administration Console by clicking the Help button on the page. The initial help page describes the functions and fields of the page itself.
If you try to use the Administration Console from a system through a proxy server on another system back to the original system, while using the system’s full host name (instead of localhost
or 127.0.0.1
) you are denied access because the request is treated as a remote request, which requires that the secure administration feature (secure admin) to be enabled.
To avoid this situation, do one of the following:
-
Do not use a proxy server.
-
Use
localhost
or127.0.0.1
as the host name. -
Enable secure admin so that what Payara Server interprets as a remote request is accepted as such.
To enable secure admin, see "Managing Administrative Security" in the Payara Server Security Guide.
asadmin
Utility
The asadmin
utility is a command-line tool that runs subcommands for identifying the operation or task that you want to perform. You can run asadmin
subcommands either from a command prompt or from a script.Running asadmin
subcommands from a script is helpful for automating repetitive tasks. Basic information about how the asadmin
utility works can be found in the asadmin
(1M) help page. For instructions on using the asadmin
utility, see Using the asadmin
Utility.
To issue an asadmin
subcommand in the standard command shell (single mode), go to the as-install/bin
directory and type the asadmin
command followed by a subcommand. For example:
asadmin list-jdbc-resources
You can invoke multiple command mode (multimode) by typing asadmin
at the command prompt, after which the asadmin>
prompt is presented. The asadmin
utility continues to accept subcommands until you exit multimode and return to the standard command shell. For example:
asadmin> list-jdbc-resources
You can display a help page for any asadmin
subcommand by typing help
before the subcommand name. For example:
asadmin> help restart-domain
or
asadmin help restart-domain
A collection of the asadmin
help pages is available in HTML and PDF format in the Payara Server Reference Manual.
REST Interfaces
Payara Server provides representational state transfer (REST) interfaces to enable you to access monitoring and configuration data for Payara Server, including data that is provided by newly installed add-on components. For more information, see Using REST Interfaces to Administer Payara Server.
OSGi Module Management Subsystem
The OSGi module management subsystem that is provided with Payara Server is the Apache Felix OSGi framework .
To administer this framework, use either the Apache Felix Gogo remote shell. This shell is provided with Payara Server. The shell uses the Felix Gogo shell-service to interact with the OSGi module management subsystem.
This tool allows you to perform administrative tasks on OSGi bundles such as:
-
Browsing installed OSGi bundles
-
Viewing the headers of installed OSGi bundles
-
Installing OSGi bundles
-
Controlling the life cycle of installed bundles
To Enable the Apache Felix Gogo Remote Shell
By default, the Apache Felix Gogo remote shell in Payara Server is disabled. Before using the shell to administer OSGi bundles in Payara Server, you must enable the shell.
Enabling the Apache Felix Gogo remote shell in Payara Server involves changing the value of the property glassfish.osgi.start.level.final
. This property controls whether the OSGi start level service enables the shell when the DAS or a Payara Server instance is started.
-
Ensure that the DAS is running.
-
Change the value of the
glassfish.osgi.start.level.final
property from2
to3
.If the domain includes clustered or standalone instances on remote hosts, perform this step on each remote host. You can change this value either by creating a Java system property or by editing a file.
To change this value by creating a Java system property, create the system property
glassfish.osgi.start.level.final
with a value of3
:asadmin> create-jvm-options --target target -Dglassfish.osgi.start.level.final=3
shellTo change this value by editing a file, edit the plain-text file
as-install/config/osgi.properties
to change the value of theglassfish.osgi.start.level.final
property from2
to3
. -
Restart the DAS.
For instructions, see To Restart a Domain.
To Run Apache Felix Gogo Remote Shell Commands
The Apache Felix Gogo remote shell is integrated with the Payara Server asadmin
command line utility. You can use the asadmin
subcommands osgi
and osgi-shell
to access the remote shell and run OSGi shell commands.
To Run Remote Shell Commands Using the osgi
Subcommand
The osgi
subcommand delegates the command line to the Apache Felix Gogo remote shell for the execution of OSGi shell commands. Commands are executed by the remote shell and results are returned by the asadmin
utility. The osgi
subcommand is supported in remote mode only.
-
Ensure that the server is running. Remote commands require a running server.
-
Access the remote shell by using the
osgi
subcommand. For the full syntax and options for this subcommand, seeosgi
.
To Run Remote Shell Commands Using the osgi-shell
Subcommand
The osgi-shell
subcommand provides interactive access to the Apache Felix Gogo remote shell for the execution of OSGi shell commands. OSGi shell commands are executed on the server and results are printed on the client. You can run multiple commands from a file or run commands interactively. The osgi-shell
subcommand is supported in local mode only. Unlike other local subcommands, however, the DAS and the server instance whose shell is being accessed must be running.
-
Ensure that the server is running.
-
Access the remote shell by using the
osgi-shell
subcommand. For the full syntax and options for this subcommand, seeosgi-shell
.
Example 1-3 To run remote shell commands using the osgi-shell subcommand
This example lists Apache Felix Gogo remote shell commands. Some lines of output are omitted from this example for readability.
asadmin> osgi help
felix:bundlelevel
felix:cd
felix:frameworklevel
gogo:cat
gogo:each
gogo:echo
asadmin> osgi-shell
Use "exit" to exit and "help" for online help.
gogo$ help
felix:bundlelevel
felix:cd
felix:frameworklevel
gogo:cat
gogo:each
gogo:echo
Example 1-4 To run remote shell commands using the osgi-shell subcommand 2
This example runs the Felix Remote Shell Command lb
without any arguments to list all installed OSGi bundles. Some lines of output are omitted from this example for readability.
asadmin> osgi lb
START LEVEL 2
ID|State |Level|Name
0|Active | 0|System Bundle
1|Active | 1|Metro Web Services API OSGi Bundle
2|Active | 1|jakarta.annotation API
Command osgi executed successfully.
asadmin> osgi-shell
Use "exit" to exit and "help" for online help.
gogo$ lb
START LEVEL 2
ID|State |Level|Name
0|Active | 0|System Bundle
1|Active | 1|Metro Web Services API OSGi Bundle
2|Active | 1|jakarta.annotation API
gogo$
Example 1-5 To run remote shell commands using the osgi-shell subcommand 3
This example runs the Felix Remote Shell Command inspect
with the service
option and the capability
option to determine the services that OSGi bundle 251
provides. Some lines of output are omitted from this example for readability.
asadmin> osgi inspect service capability 251
Payara EJB Container for OSGi Enabled EJB Applications (251) provides services:
---------------------------------------------------------------------------
objectClass = org.glassfish.osgijavaeebase.Extender
service.id = 68
-----
objectClass = org.glassfish.osgijavaeebase.OSGiDeployer
service.id = 69
service.ranking = -2147483648
Command osgi executed successfully.
...
asadmin> osgi -shell
Use "exit" to exit and "help" for online help.
gogo$ inspect service capability 251
Payara EJB Container for OSGi Enabled EJB Applications (251) provides services:
---------------------------------------------------------------------------
objectClass = org.glassfish.osgijavaeebase.Extender
service.id = 68
...
gogo$
Java Monitoring and Management Console (JConsole)
Java SE provides tools to connect to an MBean server and view the MBeans that are registered with the server. JConsole is one such popular JMX Connector Client and is available as part of the standard Java SE distribution.
For instructions on integrating JConsole in the Payara Server environment, see Configuring JConsole to View Payara Server Monitoring Data.
Instructions for Administering Payara Server
Information and instructions on performing most of the administration tasks from the command line are provided in this document and in the asadmin
utility help pages. For instructions on accessing asadmin
online help, see To Display Help Information for the asadmin
Utility or a Subcommand.
Phone Home
All Payara Platform distributions report back a limited amount of information about their specific configuration at launch time. No sensitive data about your machine or specific usage of Payara Server is sent to 0s or any member of the Payara Services team.
Gathered phone home data is sent via a GET
request to http://www.payara.fish/phonehome
The following is the list of information attributes gathered by the Phone Home service:
Attribute | Example |
---|---|
Payara Server Version |
6.4.0 #badassfish |
Java Virtual Machine Version |
1.8.0_121 |
Domain Uptime |
36500 |
Number of nodes in the domain |
1 |
Number of instances in the domain |
2 |
Randomly generated UUID |
eaa6fe2c-2388-4aa7-fdcc-288c7b318ddfeaa6ef23-2388-4aa7-8dcc-288c7b318ddf |
This is the only data which the phone home service gathers from your system.
The UUID is specific to the DAS and is randomly generated on startup, so it is not machine specific. |
What is the data used for?
The phone home data is presently used to gather usage statistics about the corresponding distribution, such as how long users typically run instances, and what versions they use.
Previously this could only be done at an extremely simple level from downloads over time, giving us no idea how Payara Server is used beyond specific interactions with contributors and customers which may not accurately represent the state of our user base.
The phone home service was designed as a non-intrusive survey tool which would only gather data specific to Payara and has no contact with any running applications, or indeed anything on your machine other than the mentioned attributes.
Disabling and Enabling Phone Home
The phone home service is enabled by default when starting a Payara Server. The phone home service can be easily disabled in the following ways.
Disable the Phone Home service
List the current status of the Phone Home service.
asadmin> list-phone-home
See list-phone-home