
Leading the Way: Payara Platform Community 7 Beta Now Fully Jakarta EE 11 Certified
We’re excited to announce that Payara Platform Community 7 Beta application server is now fully certified as Jakarta EE 11 […]
The asadmin Command Line Interface (CLI) is a mean of controlling Payara Server from the command line (or terminal, if you prefer). It allows you to start, stop or edit the server in a number of ways. While to some the administration console is the go-to for any administration that needs to be done, the CLI can be a potentially quicker and easier way of performing any administration tasks, particularly when dealing with headless servers, i.e. a server without a GUI.
The Payara Server CLI is used with the asadmin utility (as in “Application Server Administration”, it isn’t just gibberish). This can be found in the bin directory of your Payara Server install. All Payara Server administration commands are sub-commands of this utility and, as such, each command must be prepended with this function (e.g. asadmin do-a-little-dance).
A handy tip to avoid prepending asadmin to each command is to call the asadmin function on its own (e.g. asadmin). This will run asadmin in an interactive mode, saving you a few keystrokes if you intend to execute several commands in sequence.
You can specify additional options for most commands in the CLI, some of which are mandatory for certain commands to execute. The list of options that a command takes, as well as a description of the command and examples, can be found by passing the –help parameter to the command (e.g. asadmin start-domain –help). Each of these options must be prepended with “–“, though some options have a shortened version for which a single dash is sufficient. For example:
asadmin start-domain --debug true
is equivalent to:
asadmin start-domain –d
asadmin itself has various options you may find useful, which you can see by passing –help or -h to asadmin itself:
asadmin --help
Options such as –host and –port allow you to run commands against a Domain Administration Server (DAS) that isn’t local to your current machine or isn’t running on the default port of 4848. There is also an –autoname / -a option supported by various commands, which can be handy and/or fun for generating names quickly !
If you’ve already installed Payara Server, you will likely be aware that you can use the CLI to start and stop domains, clusters and instances. In effect, it’s likely that the first thing you did after installing Payara Server was using the CLI to start the default domain:
asadmin start-domain
The start-domain command starts domain1 by default. To start an alternative domain, you must specify the domain as an additional parameter, like this:
asadmin start-domain myDomain
As previously noted, you can use –help to list the available parameters that each command can take. Doing so for the start-domain command reveals the following parameters: dry-run, domaindir, upgrade, debug, verbose, and watchdog. Of particular note are the debug and verbose options, which are very useful for debugging.
Stopping a domain is as easy as starting it, the command is just stop-domain.
asadmin stop-domain
As with when starting domains, domain1 is stopped by default. To stop an alternative domain you must specify the domain to stop:
asadmin stop-domain myDomain
Notable options for this command are force and kill. These options are useful to specify the shutdown behaviour of the domain. The force option determines whether the domain stops immediately (true) or waits for all threads to exit before stopping the domain (false). The kill option determines how the domain process is terminated. This defaults to false, meaning that the Java platform will terminate the process. Specifying this option as true will cause the operating system to kill the domain process.
asadmin stop-domain --kill true domain1
There are two asadmin commands for starting Payara Server instances: start-instance and start-local-instance. The biggest difference between the two is that the start-local-instance command is designed solely for use with instances residing on the machine from which the command is being run from, while start-instance can be used to start both local and remote instances.
asadmin start-instance instance1
asadmin start-local-instance instance2
Debugging is available for these commands with the –debug option, which starts the instance with debugging enabled. An additional debugging option is available to the start-local-instance command: –verbose. This allows you to have both start-up and log messages printed to the console when starting the instance, helping you to quickly see what is happening.
Another notable and useful option is –sync, which takes one of three parameters: none, normal and full. If using this option, it is mandatory you specify one of the parameters, as the sync option specifies how the instance synchronises itself with the DAS (Domain Administration Server):
asadmin start-local-instance --sync full --verbose true --debug true instance1
Just like with stopping domains, the commands to stop an instance are well named: stop-instance and stop-local-instance. The difference between the two commands are the same as the difference between the start commands. The first can be used for local and remote instances, whereas the second can only be used for local instances.
asadmin stop-instance instance1
asadmin stop-local-instance instance2
As with the stop-domain command, you can specify the force and kill options, which act in the same way as they do for the stop-domain command.
Deployment Groups were introduced in Payara Platform 5 to replace the legacy clustering system. For resources on how to use the admin console in Payara Server 5, download our guide here:
Just like before, there’s no differentiation between a remote and local start/stop command for deployment groups, so you only need to know of the following commands:
asadmin start-deployment-group group1
asadmin stop-deployment-group group1
These commands are devoid of any unique options and they do exactly what they say. The start command will attempt to start every instance registered to the specified deployment group, while the stop command will attempt to stop them.
Now let’s dig deeper. If you just want to create a new domain with default values, run this:
asadmin create-domain
It will ask for you to specify a name for the domain, an administrator username and password. It will then list the ports that it will use the default ports and generate a self-signed certificate.
If you want to customise the domain, there are many options available. Below are some notable ones:
There is a command to create each kind of Payara Server node: create-node-${type}. If creating a config node with default settings, you only need to provide a name for the node. If creating an SSH node, then you will need to provide both a name for the node and the host name of the machine that the node will be located on.
asadmin create-node-config configNode
asadmin create-node-ssh --nodehost localhost sshNode
When creating a config node, if the default values are not suitable, you can have their node host, install directory and node directory specified with the nodehost, installdir and nodedir options, respectively.
asadmin create-node-config --nodehost localhost --installdir /home/user/payara --nodedir /home/user/nodes configNode
These options refer to the machine that will host the node, the installation directory of Payara Server on that machine and the directory under which the nodes are stored (this particular option can probably be omitted for most configurations). The default install directory is taken as the install location of the DAS. The default settings assume that Payara Server is installed in the same location on all hosts.
Due to the relative complexity of an SSH node in comparison to that of a config node, it has more options that can be used to create and configure them. The full list of options can be seen by passing the help option (asadmin create-node-ssh –help), but I’ll cover a few here.
For SSH nodes:
Creating a deployment group is very simple: run the create-deployment-group command and give it a name. That’s it!
asadmin create-deployment-group guppy1
The complexity of deployment groups comes when managing them, which I’ll cover later on in a section specifically about adding/removing instances from deployment groups.
When creating instances, there are two commands for doing this: create-instance and create-local-instance. As you can likely tell from the name, the create-local-instance command can only be run on the host on which the instance will resides. It cannot be used to create instances on remote machines. This command is used to create all types of instances: shared, standalone and clustered.
asadmin create-instance instance1
asadmin create-local-instance instance2
By default, an instance will create its own config, copied from the default-config. You can change to use a pre-created one with the –config option:
asadmin create-instance --config instance-config-1 instance3
You can specify the listen ports that the instance will use with the –systemproperties option.
To specify the node that an instance will belong to, use the –node option, like this:
asadmin create-instance --node node1
You can use the CLI to manage the admin and master passwords of Payara Server. The two passwords are managed with the following commands:
asadmin change-admin-password
asadmin change-master-password
The change-admin-password command is specific to a domain, so it has the following two options to allow you to specify the domain to use: domain_name and domaindir. If multiple admin users exist, you can specify which user to change the password of like this:
asadmin --user admin change-admin-password
The change-master-password command has three options. nodedir, specifies the directory containing the node for which the password will be changed, domaindir specifies the domain directory used and savemasterpassword dictates whether or not the master password will be saved to disk (which is pretty bad practice if you weren’t aware).
Deploying an application can be quite a complicated affair depending on your environment set up. For example, using the CLI can be significantly quicker than the admin console if you know what you’re doing!
To deploy an application to the default instance (the server where the admin console is installed), simply enter the following:
asadmin deploy $path_to_war
Once you have your Payara Server environment set up, you’re not likely to be deploying to the default server instance, so the target option will likely be of use to you, as it specifies where your deployment will be deployed to. With this option, you can specify that the component be deployed to an instance or a deployment group.
asadmin deploy --target group1 testWar
asadmin deploy --target instance1 testWar
The CLI also has an additional deployment option, which is not available from the admin console – deploy-remote-archive. This command can be used to deploy an application not just from a URL, but also from a Maven repository using Group, Artifact, Version (GAV) coordinates.
There is no special flag to differentiate between a URL and Maven GAV coordinates – the command should figure it out on its own, making the following look identical:
asadmin deploy-remote-archive https://my.maven.repo/repository/example/fish/payara/example /clusterjsp/3.2.1/clusterjsp-3.2.1.war
asadmin deploy-remote-archive --additionalRepositories https://my.maven.repo/repository/example fish.payara.example,example-app,3.2.1
In the code above, there is an option I haven’t discussed yet: –additionalRepositories. This is used to provide a comma separated list of maven repositories to search for the specified application in. By default the command will only look in Maven Central.
Adding and Removing Instances from Deployment Groups
The main feature that differentiates deployment groups from the legacy clustering system is that the instances in a deployment group are more flexible – an instance is no longer tied to a cluster for its life, and can belong to more than one deployment group.
To accommodate this new flexibility, there are two new asadmin commands for adding and removing instances from a deployment group:
asadmin add-instance-to-deployment-group --instance instance1 --deploymentgroup group1
asadmin remove-instance-from-deployment-group --instance instance1 --deploymentgroup group1
These commands do what their name says, having only a couple of configuration options denoting the instance to remove and the deployment group to remove it from. Both of the configuration options are mandatory, so you’ll be prompted to enter whichever one you forget to specify.
Another place where you want to pay attention is Hazelcast. This has been present in Payara Server and Micro for quite a while as our replacement for Shoal. Hazelcast is embedded into Payara Platform to provide the domain data grid, and the configuration commands are named after that relationship:
asadmin get-hazelcast-configuration --target server-config
asadmin set-hazelcast-configuration --target config1
The set command has a multitude of options, so I’ll only go over the most commonly used ones here:
An important configuration option for Payara and Hazelcast is to instruct them how to cluster the instances within a domain with each other, configured with the –clustermode option. Note that this is another option that is domain wide – you can’t have one config to use cluster mode and another to use a different one.
The domain discovery mode is the default option used by Payara Server, and by being the default, it typically does not require any extra configuration out of the box. In fact, all you need to do is set the discovery mode to domain, and that’s it! There’s no extra configuration required with regards to telling each instance where to find the DAS – it’s figured out from the address the DAS used to bind Hazelcast to.
asadmin set-hazelcast-configuration --clustermode domain
This cluster mode is aimed more at being used with Payara Micro in cloud environments, so I’m not going to go into detail about it in this blog.
In short, though, it’s for use in environments where there may not be a DAS and multicast can be problematic (or just impossible!). Functionally it’s a bit like a reverse of the domain discovery mode. With the domain discovery mode, you tell each instance where to find the DAS, with TCP/IP mode, you tell the DAS where to find the other instances.
This is how Hazelcast did it’s clustering back in Payara Platform 4, and it remains the default for Payara Micro.
There haven’t been any changes to this mode (outside of having to specify to use it with Payara Server) – you just have to tell it the multicast group and port number with the respective options:
asadmin set-hazelcast-configuration --clustermode multicast --multicastgroup 224.2.2.3 --multicastport 54327
This marks the end of the introduction to the Payara Server CLI. By following this guide, you have taken your first steps to navigating the technical aspects behind this interface. While there is much more to it, you should be able to see the advantages of the CLI and how it offers a robust alternative to the admin console, offering streamlined functionalities for server management. Happy coding!
Share:
We’re excited to announce that Payara Platform Community 7 Beta application server is now fully certified as Jakarta EE 11 […]
Managing Payara Server Just Got Smarter Imagine managing your Jakarta EE applications not just with Maven goals, but by […]
Welcome aboard the August 2025 issue of The Payara Monthly Catch! With summer in full swing, things may have felt […]