Administering Domains

A Payara Server instance is a single Virtual Machine for the Java platform (Java Virtual Machine or JVM machine) on a single node in which Payara Server is running. A node defines the host where the Payara Server instance resides. The JVM machine must be compatible with the Jakarta EE.

Payara Server instances form the basis of an application deployment.

Whenever a domain is created, Payara Server creates a default instance that is named server. If a single instance meets your requirements, you can use this instance for deploying applications without the need to administer Payara Server instances explicitly. You administer the default instance when you administer its domain.

If you require multiple instances, you must administer the instances explicitly. For more information, see "Administering Payara Server Instances" in the Payara Server High Availability section.

For an instance, you can also create virtual servers. Virtual servers do not span instances. For many purposes, you can use virtual servers instead of multiple instances in operational deployments. Virtual servers enable you to offer, within a single instance, separate domain names, IP addresses, and some administration capabilities to organizations or individuals. To these users, a virtual server behaves like a dedicated web server, but without the hardware and basic web server maintenance.

For more information about virtual servers, see Administering Virtual Servers.

A domain is an administrative boundary that contains a group of Payara Server instances that are administered together. Each instance can belong to only one domain. A domain provides a preconfigured runtime for user applications. Each domain has its own configuration data, log files, and application deployment areas that are independent of other domains. If the configuration is changed for one domain, the configurations of other domains are not affected.

Domains enable different organizations and administrators to share securely a single Payara Server installation. Each organization or administrator can administer the instances in a single domain without affecting the instances in other domains.

At installation time, Payara Server creates a default domain that is named domain1. After installation, you can create additional domains as necessary.

When a domain is created, you are prompted for the administration username and password. If you accept the default, the user admin is created without password. To reset the administration password, see To Change an Administration Password in Payara Server Security Guide.

The domain administration server (DAS) is a specially designated Payara Server instance that hosts administrative applications. The DAS is similar to any other Payara Server instance, except that the DAS has additional administration capabilities. The DAS authenticates the administrator, accepts requests from administration tools, and communicates with other instances in the domain to carry out the requests from administration tools.

Each domain has its own DAS with a unique administration port number. The default administration port is 4848, but a different port can be specified when a domain is created.

The DAS has the master copy of the configuration data for all instances in a domain. If an instance is destroyed, for example, because a host failed, the instance can be re-created from the data in the DAS.

The DAS is the default Payara Server instance in a domain and is named server. If a single instance meets your requirements, you can use the DAS for deploying applications and for administering the domain.

The graphical Administration Console communicates with a specific DAS to administer the domain that is associated with the DAS. Each Administration Console session enables you to configure and manage only one domain. If you create multiple domains, you must start a separate Administration Console session to manage each domain.

After installing Payara Server and creating the default domain (domain1), you can create additional domains by using the local create-domain subcommand. This subcommand creates the configuration of a domain. Any user who has access to the asadmin utility on a given system can create a domain and store the domain configuration in a folder of choice. By default, the domain configuration is created in the default directory for domains. You can override this location to store the configuration elsewhere.

You are required to specify an administrative user when you create a domain, or you can accept the default login identity which is username admin with no password.

A custom template enables you to customize the configuration of any domain that you create from the template.

See Also

You can also view the full syntax and options of the subcommands by typing the following commands at the command line.

Use the list-domains subcommand to display a list of domains and their statuses. If the domain directory is not specified, the contents of the domain-root-dir, the default for which is as-install`/domains`, is listed. If there is more than one domain, the domain name must be specified.

To list domains that were created in other directories, specify the --domaindir option.

List domains by using the list-domains subcommand.

All remote subcommands require that credentials be specified in terms of an administration user name and its password. By default, the domain is created with an identity that allows an asadmin user to perform administrative operations when no identity is explicitly or implicitly specified.

The default identity is in the form of a user whose name is admin and has no password. If you specify no user name on the command line or on prompt, and specify no password in the --passwordfile option or on prompt, and you have never logged in to a domain using either the login subcommand or the create-domain subcommand with the --savelogin option, then the asadmin utility will attempt to perform a given administrative operation without specifying any identity.

A server (domain) allows administrative operations to be run using this default identity if the following conditions are true:

By default, all of these conditions are true, unless you have created the domain with a specific user name and password. Thus, by default, the only administrative user is admin with no password.

Use the login subcommand in local mode to authenticate yourself (log in to) a specific domain. After such login, you do not need to specify the administration user or password for subsequent operations on the domain. The login subcommand can only be used to specify the administration password. For other passwords that remote subcommands require, use the --passwordfile option, or specify the password at the command prompt. You are always prompted for the administration user name and password.

There is no logout subcommand. If you want to log in to another domain, invoke asadmin login with new values for --host and --port.

Use the delete-domain subcommand to delete an existing domain from a server. Only the root user or the operating system user who is authorized to administer the domain can run this subcommand.

Before You Begin

A domain must be stopped before it can be deleted.

When you start a domain or server, the domain administration server (DAS) is started. After startup, the DAS runs constantly, listening for and accepting requests.

If the domain directory is not specified, the domain in the default domain root directory is started. If there are two or more domains, the domain_name operand must be specified. Each domain must be started separately.

This subcommand is supported in local mode only.

Start a domain by using the start-domain subcommand.

Stopping a domain or server shuts down its domain administration server (DAS). When stopping a domain, the DAS stops accepting new connections and then waits for all outstanding connections to complete. This shutdown process takes a few seconds. While the domain is stopped, the Administration Console and most of the asadmin subcommands cannot be used. This subcommand is particularly useful in stopping a runaway server. For more controlled situations, you can use the restart-domain subcommand.

Use the restart-domain subcommand in remote mode to restart the Domain Administration Server (DAS) of the specified host. When restarting a domain, the DAS stops accepting new connections and then waits for all outstanding connections to complete. This shutdown process takes a few seconds. Until the domain has restarted, the Administration Console and most of the asadmin subcommands cannot be used.

This subcommand is particularly useful for environments where the server machine is secured and difficult to get to. With the right credentials, you can restart the server from a remote location as well as from the same machine.

If the server will not restart, use the stop-domain subcommand followed by the start-domain subcommand.

On Windows systems, the create-service subcommand creates a Windows service to represent the DAS or instance. The service is created in the disabled state. After this subcommand creates the service, you must use the Windows Services Manager or the Windows Services Wrapper to start, stop, uninstall, or install the service. To administer the service from the Windows command line, use the sc.exe tool.

This subcommand must be run as the OS-level administrator user.

If you are using the sc.exe tool to administer the service, use the tool as follows:

On Linux systems, the create-service subcommand creates a System-V-style initialization script /etc/init.d/GlassFish_`domain-or-instance-name and installs a link to this script in any `/etc/rc`N.d` directory that is present, where N is 0, 1, 2, 3, 4, 5, 6, and S. After this subcommand creates the script, you must use this script to start, stop, or restart the domain or instance.

The script automatically restarts the domain or instance only during a reboot. If the domain or instance is stopped, but the host remains running, the domain or instance is not restarted automatically. To restart the domain or instance, you must run the script manually.

You might no longer require the domain or instance to be automatically restarted during a reboot. In this situation, use the operating system to delete the initialization script and the link to the script that the create-service subcommand creates.

The create-service subcommand must be run as the OS-level root user.

Create the service by using the create-service subcommand.

On Oracle Solaris systems, the create-service subcommand creates an Oracle Solaris Service Management Facility (SMF) service that restarts a DAS or an instance. The service grants to the process the privileges of the user that runs the process. When you create an SMF service, the default user is the superuser. If you require a different user to run the process, specify the user in method_credential.

If your process is to bind to a privileged port of Oracle Solaris, the process requires the net_privaddr privilege. The privileged ports of the Oracle Solaris operating system have port numbers less than 1024.

To determine if a user has the net_privaddr privilege, log in as that user and type the command ppriv -l | grep net_privaddr.

After you create and enable the SMF service, if the domain or instance is stopped, SMF restarts it.

Before You Begin

To run the create-service subcommand, you must have solaris.smf.* authorization. For information about how to set the authorizations, see the useradd man page and the `usermod man page. You must also have write permission in the directory tree: /var/svc/manifest/application/SUNWappserver. Usually, the superuser has both of these permissions. Additionally, Oracle Solaris administration commands such as svccfg, svcs, and auths must be available in the PATH.

If a particular Payara Server domain or instance should not have default user privileges, modify the manifest of the service and reimport the service.

By default, the Java Virtual Machine (VM) receives signals from Windows that indicate that Windows is shutting down, or that a user is logging out of Windows, which causes the system to shut itself down cleanly. This behavior causes the Payara Server service to shut down. To prevent the service from shutting down when a user logs out, you must set the -Xrs Java VM option.

Use the backup-domain subcommand in local mode to make a backup of a specified domain.

When you use the backup-domain subcommand, Payara Server creates a ZIP file backup of all the files and subdirectories in the domain’s directory, domain-root-dir`/domain-dir, except for the `backups subdirectory.

The backup-domain subcommand provides several options to meet particular needs, including:

Use the restore-domain subcommand in local mode to use a backup file to restore the files and subdirectories in a specified domain’s directory.

The restore-domain subcommand can use backup files created by the backup-domain subcommand and by automatic backup configurations, both full backups and configuration-only backups. Automatic backup configurations are available only in Payara Server.

Use the list-backups subcommand in local mode to display information about backups of a specified domain stored in a specified backup directory.

The list-backups subcommand provides several options to meet particular needs, including --backupdir to specify a directory where backups are stored instead of the default domain-dir`/backups`.

List backups by using the list-backups subcommand.

The following steps are required to migrate the DAS from the first host (olddashost) to the third host (newdashost).

Use the uptime subcommand in remote mode to display the length of time that the domain administration server (DAS) has been running since it was last started.

Payara Server requires Java SE 11 as the underlying virtual machine for the Java platform (Java Virtual Machine or JVM machine).

Use the set subcommand in remote mode to change the administration port of a domain.

The HTTP port or the HTTPS port for administration of a domain is defined by the --adminport option of the create-domain subcommand when the domain is created. If this port must be reallocated for another purpose, change the port on which the DAS listens for administration requests.

The domain-name is the name of the domain to start. If only one domain subdirectory is contained in the domains directory, you may omit this option.