Enabling Centralized Administration of Payara Server Instances

Distributed Component Object Model (DCOM) remote protocol support has been deprecated and as such may not function as intended.

Initially, DCOM was the recommended solution for remote node management in Windows OS systems. However, over the years, DCOM has proven to be extremely unreliable in most scenarios. This in conjunction with Microsoft’s lack of support for the technology on newer versions of Windows systems has deemed it fairly unusable.

Due to the issues with DCOM and Windows officially starting to support its own native SSH server by including an OpenSSH implementation, SSH nodes should be used instead of DCOM nodes.

However, at the moment of the publication of this documentation, using the natively provided SSH utilities by Windows OS environments doesn’t work. The main reason for this is significant issues with file transfers not working correctly across nodes.

We have discovered that when SSH is provided using a Cygwin-based OpenSSH and Bash shell from Cygwin is used to manage Payara Server, remote nodes can be created and operated without issues.

Until the problems with natively provided OpenSSH implementation are addressed, we recommend you configure SSH nodes using the Cygwin-based OpenSSH toolset in production environments.

Payara Server uses the Distributed Component Object Model (DCOM) remote protocol or secure shell (SSH) to ensure that instances that span multiple hosts can be administered centrally.

To perform administrative operations on Payara Server instances that are remote from the domain administration server (DAS), the DAS must be able to communicate with those instances.

If an instance is running, the DAS connects to the running instance directly. For example, when you deploy an application to an instance, the DAS connects to the instance and deploys the application to the instance.

However, the DAS cannot connect to an instance to perform operations on an instance that is not running, such as creating or starting the instance.

For these operations, the DAS uses DCOM or SSH to contact a remote host and administer instances there. DCOM or SSH provides confidentiality and security for data that is exchanged between the DAS and remote hosts.

About Centralized Administration of Payara Server Instances

The use of DCOM or SSH to enable centralized administration of remote instances is optional and is required only for specific operations. Instances local to the DAS can be administered without DCOM or SSH. If DCOM or SSH is not a possibility in your environment, you can administer remote instances locally instead.

Determining Whether to Enable Centralized Administration

Before setting up a Payara Server cluster or deployment group, use the following considerations to determine whether to enable centralized administration of remote instances:

  • If you are planning to set up a large cluster or deployment group of many instances, consider enabling centralized administration of their corresponding instances.

    Centralized administration of instances simplifies the administration of the Deployment Groups by enabling you to perform all administrative operations on the Deployment Groups and its instances from the DAS.

  • If you are planning a small Deployment Groups of few instances, consider whether enabling centralized administration requires more effort than logging in to individual hosts to administer remote instances locally.

How you administer instances and the nodes on which they reside varies depending on whether and how centralized administration is enabled. The following table provides cross-references to instructions for administering nodes and instances depending on the protocol that is used for enabling centralized administration, if any.

Protocol Node Administration Instructions Instance Administration Instructions

DCOM

Creating, Listing, Testing, and Deleting DCOM Nodes

Administering Payara Server Instances Centrally

SSH

Creating, Listing, Testing, and Deleting SSH Nodes

Administering Payara Server Instances Centrally

None

Creating, Listing, and Deleting CONFIG Nodes

Administering Payara Server Instances Locally

Considerations for Using DCOM for Centralized Administration

As stated in the opening paragraph of this document, DCOM support has fallen out of favor in Windows Operating systems, so the instructions detailed in this section may not apply to newer Windows releases.

DCOM enables communications between Windows hosts. In a typical Payara Server deployment, the DAS acts as a DCOM client, and hosts where instances reside act as DCOM servers. To create or start an instance on a remote host, the DAS instructs the DCOM server on the host to start the asadmin utility of Payara Server. The asadmin utility then performs the required operation on the host to create or start the instance.

The DCOM service must be running on hosts where instances reside, but is not required to be running on the DAS host. The DAS uses its own DCOM client for communicating with hosts where instances reside. On Windows hosts, the DCOM server is typically running by default as a Windows Service.

DCOM is available in older Windows operating system distributions. Because DCOM is typically installed and preconfigured, minimal additional setup is required to use DCOM with Payara Server.

Before setting up DCOM, decide which Windows user Payara Server will use when connecting to remote hosts. For the following reasons, administration is simplest if the Windows user is the user that starts the DAS:

  • Remote instances are started as the Windows user.

  • By default, the DAS assumes that the Windows user is the user that is running the DAS.

Considerations for Using SSH for Centralized Administration

In a typical Payara Server deployment, the DAS acts as the SSH client, and hosts where instances reside act as SSH servers. The SSH Server Daemon sshd must be running on hosts where instances reside, but is not required to be running on the DAS host.

The DAS uses its own SSH client for communicating with hosts where instances reside. However, to generate keys and test SSH setup, a native SSH client must be installed on the DAS host.

The requirements for SSH configuration and user management are different for each operating system on which Payara Server is supported. Therefore, the use of SSH for centralized administration involves using SSH tools to configure SSH on the operating system that you are using.

On UNIX and Linux systems, SSH is typically installed and preconfigured, and requires minimal additional setup. On Windows systems, additional setup is required to install and configure an SSH provider.

Obtaining SSH Software

On UNIX and Linux systems, SSH software is typically installed as part of the base operating system.

However, on Windows systems, you must install one of the following SSH providers:

Determining the SSH User

Before setting up SSH, decide which SSH user Payara Server will use when connecting to remote hosts. For the following reasons, administration is simplest if the SSH user is the user that starts the DAS:

  • For public key authentication, the user that starts the DAS must be able to read the SSH user’s private key file.

  • Remote instances are started as the SSH user.

  • By default, the DAS assumes that the SSH user is the user that is running the DAS.

Requirements for the SSH User’s Environment

The SSH user’s environment on a host is set by the environment set-up files that are run when the user uses SSH to run a command on the host. You must ensure that these files set up the SSH user’s environment correctly.

The files that are run when the user uses SSH to run a command are different from the files that are run when the user logs in to a host. For example, in the bash shell, .profile and .bashrc are run when the user logs in, but only .bashrc is run when the user runs a command.

Therefore, in the bash shell, you must ensure that .bashrc contains the required environment settings for the SSH user.

File Access Permissions on UAC-Enabled Windows Systems

The User Account Control (UAC) (http://technet.microsoft.com/en-us/library/cc709691%28WS.10%29.aspx) feature is available only on older versions of the Windows operating system( like Windows 7, Windows Vista, and Windows Server 2008).

You might be using a UAC-enabled Windows system and choose to store files for Payara Server instances in a directory other than the SSH user’s home directory. In this situation, the SSH user must have native (that is, non-virtual) read and write access to the file system where the instances are to be stored. The OS-level administrator has such access by default.

You can also configure the system to grant such access to other users. For more information, see the documentation for the Windows operating system.

Setting Up DCOM and Testing the DCOM Set Up

Setting up DCOM on a host involves the following tasks:

  • Verifying Windows operating system settings for the host

  • Enabling the Windows user to run scripts on the host

  • Setting up password authentication for the Windows user on the host

Set up DCOM on all hosts where instances in your Deployment Groups or clusters will reside.

After setting up DCOM on a host, test the connection over DCOM to the host.

Windows Operating System Settings

To enable access to a host over DCOM, ensure that the following items in the Windows operating system are set as follows on the host:

  • The following services are in the started state and are set to start automatically:

    • Server

    • Remote Registry

  • Network Access: Sharing security model for local accounts is set to Classic.

  • The following ports are open:

    • DCOM port 135 or 139

    • Windows Shares port 445

To Enable the Windows User to Run Scripts on a Remote Host

To run scripts on a remote host, full control over the following Windows registry keys must be allowed for the Windows user or the group that contains the Windows user:

  • One of the following keys, depending on the processor architecture of the host:

    • 32-bit architecture: HKEY_LOCAl_MACHINE\SOFTWARE\Classes\Wow6432Node\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6}

    • 64-bit architecture: HKEY_LOCAl_MACHINE\SOFTWARE\Classes\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6}

  • HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{72C24DD5-D70A-438B-8A42-98424B88AFB8}

In some versions of Windows, only the NT SERVICE\TrustedInstaller user has full control over these Windows registry keys. If your version of Windows is configured in this way, you must modify these keys to allow full control over them for the Windows user or the group that contains the Windows user.

Remember that only an administrator user can edit the Windows registry.

Perform this procedure for each Windows registry key that you are modifying on each host where instances in your Deployment Groups will reside.

  1. If necessary, start the Registry Editor.

    $ regedit.exe

  2. In the Registry Editor window, navigate to the registry key that you are modifying.

  3. Select the key, click mouse button 3, and from the pop-up menu that opens, select Permissions.

  4. Determine whether full control is allowed for the Windows user or the group that contains the Windows user.

    • If full control is allowed, no further action is required.

    • If full control is not allowed, allow full control as follows:

      1. In the Permissions window, click Advanced.

      2. In the Advanced Security Settings window, select the Owner tab.

      3. From the Change owner to list, select the Windows user or the group that contains the Windows user.

      4. Ensure that the Replace owner on subcontainer and objects option is selected.

      5. Click Apply, then OK.

        The Advanced Security Settings window closes. The Permissions window shows that full control is allowed for the Windows user or the group that contains the Windows user.

      6. In the Permissions window, click OK.

        The Permissions window closes.

  5. After modifying all the Windows registry keys over which full control is required, quit the Registry Editor.

Next Steps

Set up password authentication for the Windows user as explained in To Set Up Password Authentication for the Windows User.

To Set Up Password Authentication for the Windows User

When a Payara Server subcommand uses DCOM to log in to a remote host, Payara Server requires the Windows user’s password to authenticate the Windows user.

To provide this password securely to Payara Server, create a Payara Server password alias to represent the password and store this alias in a password file that is passed to the asadmin utility.

Before You Begin

Ensure that the following prerequisites are met:

  • The Windows user is a valid user on the host to which you are testing the connection over DCOM.

  • Items in the Windows operating system are set on the host as described in Windows Operating System Settings.

  • The Windows user is able to run scripts on the host. For more information, see To Enable the Windows User to Run Scripts on a Remote Host.

    1. Ensure that the DAS is running. Remote subcommands require a running server.

    2. Create an alias for the Windows user’s password.

      Only the options that are required to complete this task are provided in this step. For information about all the options for creating a password alias, see the create-password-alias help page. 
      asadmin> create-password-alias alias-name
      alias-name

      Your choice of name for the alias that you are creating. The create-password-alias subcommand prompts you to type the password for which you are creating an alias.

    3. In response to the prompt, type the Windows user’s password.

      The create-password-alias subcommand prompts you to type the password again.

    4. In response to the prompt, type the Windows user’s password again.

    5. Create a plain text file that contains the following entry for the password alias:

      AS_ADMIN_WINDOWSPASSWORD=${ALIAS=alias-name}
      alias-name

      The alias name that you specified in Step 2.

      When you create a DCOM node, pass this file as the --passwordfile option of the asadmin utility. For more information, see To Create a DCOM Node.

The following example creates an alias that is named winuser-password for the Windows user’s password.

$ asadmin create-password-alias winuser-password
Enter the alias password>
Enter the alias password again>
Command create-password-alias executed successfully.

The entry in the password file for the winuser-password alias is as follows:

AS_ADMIN_WINDOWSPASSWORD=${ALIAS=winuser-password}

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-password-alias at the command line.

Next Steps

Test the DCOM setup as explained in To Test the Connection Over DCOM to a Remote Host.

To Test the Connection Over DCOM to a Remote Host

Testing the connection over DCOM to a remote host verifies that the required Windows services are running, the required ports are open, and the Windows user has a valid user account on the host.

Before attempting to perform any task that requires for the DAS to contact the DCOM server on a remote host, test the connection over DCOM to the host. If this test fails, any attempt to perform a task that requires the DAS to contact the DCOM server on the host will also fail.

Examples of such tasks are creating a DCOM node to represent the host or creating an instance that resides on the host. For more information, see To Create a DCOM Node and To Create an Instance Centrally.

If you cannot connect to the host over DCOM, troubleshoot the DCOM setup before proceeding.

Before You Begin

Ensure that the following prerequisites are met:

  • The Windows user is a valid user on the host to which you are testing the connection over DCOM.

  • Items in the Windows operating system are set on the host as described in Windows Operating System Settings.

  • The Windows user is able to run scripts on the host. For more information, see To Enable the Windows User to Run Scripts on a Remote Host.

  • Password authentication is set up for the Windows user as explained in To Set Up Password Authentication for the Windows User.

    1. Ensure that the DAS is running. Remote subcommands require a running server.

    2. Run the validate-dcom subcommand.

      Specify the file that contains the alias for the Windows user’s password through the --passwordfile option of the asadmin utility.

      For more information about this file, see To Set Up Password Authentication for the Windows User.

      Only the options that are required to complete this task are provided in this step. For information about all the options for configuring the node, see the validate-dcom(1) help page. 
      C:\>asadmin --passwordfile filename validate-dcom host-name
      filename

      The name of the file that contains the alias for the Windows user’s password.

      host-name

      The name of the host to which you are testing the connection over DCOM.

Example 2-2 Testing the Connection Over DCOM to a Remote Host

This example tests the connection over DCOM to the host wpmdl2.

$ asadmin --passwordfile aspwalias.txt validate-dcom wpmdl2
Command validate-dcom executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help validate-dcom at the command line.

Setting Up Cygwin SSH on Windows

Set up Cygwin SSH on the DAS host and on all hosts where instances in your Deployment Groups or clusters will reside.

Download and Install Cygwin

For centralized Payara Server administration, a basic Cygwin installation that includes the SSH client and the SSH server daemon sshd is sufficient. The default installation options are sufficient to create such a basic installation.

  1. Log in as a user with Administrator privileges.

  2. Create the C:\cygwin directory.

  3. From the Cygwin home page (http://www.cygwin.com/), download and save the setup.exe file to your desktop.

  4. Run the setup.exe file.

  5. Select the default for the following options:

    • Install from Internet

    • Install Root Directory: C:\cygwin

    • Install for All Users

  6. Specify a folder for the local package directory that is not the Cygwin root folder, for example, C:\cygwin\packages.

  7. Specify the connection method.

    For example, if the host is connected to the Internet through a proxy server, specify the proxy server.

  8. Select the mirror site from which to download the software.

  9. Select the openssh package for installation.

  10. Under the Net category, search for openssh.

  11. Locate the openssh package and click Skip.

    The package is selected.

  12. Click Next.

    Any unsatisfied dependencies are listed.

  13. Leave the Select Required Packages option selected and click Next

    The packages are installed.

  14. Click Finish.

See Also

For detailed information about installing Cygwin, see "Internet Setup" in Cygwin User’s Guide (http://cygwin.com/cygwin-ug-net/setup-net.html#internet-setup).

To Set the Path for Windows and for the Cygwin Shell

To enable Payara Server tools to find commands for SSH, each user’s path for Windows and for the Cygwin shell must contain the following directories:

  • The Cygwin bin directory, for example C:\cygwin\bin

  • The bin directory of the JDK software

    1. Log in as a user with Administrator privileges.

      Logging in as a user with Administrator privileges ensures that the change applies to all users.

    2. In the System Information control panel, click Advanced → Environment Variables.

    3. Add the following directories to the PATH environment variable:

  • The Cygwin bin directory, for example C:\cygwin\bin

  • The bin directory of the JDK software installation

To Set the Home Directory for the Cygwin SSH User

The SSH Server Daemon sshd locates a user’s home directory from the configuration in the user database, not from environment variables such as HOME. To ensure that all Payara Server commands can run without errors, each SSH user must be configured to have a home directory.

Each user on a Windows host where SSH is set up potentially has two home directories:

Windows home directory

Payara Server commands, which are run in a Windows command window, use the Windows home directory.

SSH home directory

SSH commands, which are run in a shell such as bash or ksh, use the SSH home directory.

If these home directories are different, Payara Server and SSH each locate a user’s .ssh directory in different directories. To simplify the setup of SSH, configure each user’s home directory for SSH and Windows to be the same directory. A disadvantage of this approach is that the SSH home directory has spaces in its path name. Spaces in path names are cumbersome in the UNIX environment.

  1. Log in as a user with Administrator privileges.

  2. In the c:\cygwin\etc\passwd file, edit the home directory setting for the SSH user to specify the user’s home directory for Windows.

To Configure and Start the Cygwin SSH Server Daemon sshd

Before You Begin

Ensure that the following prerequisites are met:

  • A user account is created for each user that will log in to the host through SSH.

  • A password is set for each user account.

    The SSH server daemon sshd disallows authentication of any user for whose account a password is not set. . Double-click the Cygwin icon.

    + A Cygwin terminal is started.

    1. If necessary, set the password for your user account.

      1. Run the passwd command as follows:

        $ passwd user-name
        user-name

        The username for your account.

      2. Type a password.

        The password for your Windows account is also set.

    2. Configure SSH on the host.

      1. Run the ssh-host-config command.

        $ ssh-host-config
        If you are using Windows XP, specify the -y option of ssh-host-config to answer yes to all prompts. If you run ssh-host-config with the -y option, omit Step b.

      2. Ensure that the StrictModes and PubkeyAuthentication options are set to yes in the file /etc/ssh_config.

        The file /etc/ssh_config can also be accessed as /cygdrive/c/cygwin/etc/sshd_config.

    3. Start the SSH server daemon sshd.

      $ net start sshd

    4. Confirm that the SSH server daemon sshd is running.

      $ cygrunsrv --query sshd
 Service             : sshd
 Display name        : CYGWIN sshd
 Current State       : Running
 Controls Accepted   : Stop
 Command             : /usr/sbin/sshd -D

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

Setting Up the MKS Toolkit on Windows

Set up the MKS Toolkit on the DAS host and on all hosts where instances in your Deployment Groups will reside.

To Install the MKS Toolkit

For centralized Payara Server administration, the default installation of the MKS Toolkit is sufficient.

Follow the instructions in the MKS Toolkit product documentation to install OpenSSH from the MKS Toolkit with default installation options.

See Also

For detailed information about installing MKS Toolkit, see "Installing MKS Toolkit" in the MKS Toolkit v9.4 Release Notes (http://www.mkssoftware.com/docs/rn/relnotes_tk94.asp#install).

To Set the Path for Windows and for the MKS Toolkit Shell

To enable Payara Server tools to find commands for SSH, each user’s path for Windows and for the MKS Toolkit shell must contain the following directories:

  • The MKS Toolkit bin directory, for example C:\Program Files\MKS Toolkit\mksnt

  • The bin directory of the JDK software

The MKS Toolkit installer automatically adds the MKS Toolkit bin directory to the path. However, you must add the bin directory of the JDK software to the path yourself.

  1. Log in as a user with Administrator privileges.

    Logging in as a user with Administrator privileges ensures that the change applies to all users.

  2. In the System Information control panel, click Advanced>Environment Variables.

  3. Add the bin directory of the JDK software to the Path environment variable.

To Set the Home Directory for the MKS Toolkit SSH User

The SSH Server Daemon sshd locates a user’s home directory from the configuration in the user database, not from environment variables such as HOME. To ensure that all Payara Server commands can run without errors, each SSH user must be configured to have a home directory.

Each user on a Windows host where SSH is set up potentially has two home directories:

  • Windows home directory. Payara Server commands, which are run in a Windows command window, use the Windows home directory.

  • SSH home directory. SSH commands, which are run in a shell such as bash or ksh, use the SSH home directory.

If these home directories are different, Payara Server and SSH each locate a user’s .ssh directory in different directories. To simplify the setup of SSH, configure each user’s home directory for SSH and Windows to be the same directory.

A disadvantage of this approach is that the SSH home directory has spaces in its path name. Spaces in path names are cumbersome in a UNIX environment.

  1. Compare the pairs of settings for Windows and the MKS Toolkit that are listed in the following table.

    Windows Environment Variable MKS Toolkit Field

    HOMEPATH

    Home Directory

    HOMEDRIVE

    Home Directory Drive

    1. In a Windows command window, determine the values of the HOMEPATH and HOMEDRIVE environment variables.

    2. In an MKS Toolkit shell, determine the current settings of the Home Directory and Home Directory Drive fields for the user.

      $ userinfo user-name
      user-name

      The username for the user whose home directory you are setting, for example Administrator.

  2. If the settings do not match, update setting of each MKS Toolkit field to match its corresponding Windows environment variable.

    If the settings match, no further action is required.

    To update the settings, run the following command in an MKS Toolkit shell:

    $ userinfo -u -fHomeDirDrive:"drive" -fHomeDir:"path" user-name
    drive

    The drive identifier of the disk drive on which the user’s Windows home directory resides, for example, C:.

    path

    The path to the user’s Windows home directory, for example, \Documents and Settings\Administrator.

    user-name

    The username for the user whose home directory you are setting, for example Administrator.

    Do not set the HOME environment variable explicitly. If the Home Directory and Home Directory Drive are set correctly, the HOME environment variable specifies the correct path by default.

  3. In an MKS Toolkit shell, confirm that the settings were updated.

    $ userinfo user-name
    user-name

    The username for the user whose home directory you are setting, for example Administrator.

  4. Log out of the host and log in to the host again.

  5. Confirm that the home directories are the same as explained in Step 1.

The following example sets the home directory for the MKS Toolkit user Administrator to C:\Documents and Settings\Administrator.

$ userinfo -u -fHomeDirDrive:"C:" -fHomeDir:"\Documents and Settings\Administrator" Administrator

To Configure and Start the MKS Toolkit SSH Server Daemon sshd

Do not set the command shell to cmd.exe. The use of SSH for centralized Payara Server administration requires a shell in the style of a UNIX shell.

  1. From the Programs menu, choose MKS Toolkit → Configuration → Configuration Information.

  2. Enable password authentication and strict modes.

    1. Click the Secure Shell Service tab.

    2. Select the Password Authentication option.

    3. Click Advanced settings.

    4. Click the Login tab.

    5. Deselect the Strict Modes option.

  3. If you are using SSH key-file authentication, enable MKSAUTH password authentication.

    1. Click the Authentication tab.

    2. Under Enable/Disable Password using MKSAUTH, type the user’s password and click the Enable.

  4. Start the SSH server daemon sshd.

    1. Confirm that the SSH server daemon sshd is running.

      $ service query MKSSecureSH

Name:           MKS Secure Shell Service
Service Type:   WIN32_OWN_PROCESS
Current State:  RUNNING
Controls Accepted:      ACCEPT_STOP
Check Point:    0
Wait Hint:      0
Start Type:     AUTO_START
Error Control:  IGNORE
Path:           "C:\Program Files\MKS Toolkit\bin\secshd.exe"
Dependency:     NuTCRACKERService
Dependency:     tcpip
Service Start Name:     LocalSystem

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

Setting Up SSH on UNIX and Linux Systems

Setting up SSH on UNIX and Linux systems involves verifying that the SSH server daemon sshd is running and, if necessary, starting this daemon. Set up SSH on the DAS host and on all hosts where instances in your Deployment Groups will reside.

On UNIX and Linux systems, SSH software is typically installed as part of the base operating system. If SSH is not installed, download and install the appropriate OpenSSH (http://www.openssh.com/) SSH package for your operating system.

To Set Up SSH on Oracle Solaris Systems

  1. Ensure that the following options in the configuration file /etc/ssh/sshd_config are set to yes:

    • StrictModes

    • PubkeyAuthentication

  2. Determine if the SSH server daemon sshd is running.

    $ /usr/bin/svcs ssh

  3. If the SSH server daemon sshd is not running, start this daemon.

    If the daemon is running, no further action is required.

    $ /usr/sbin/svcadm enable ssh

The following example confirms that the SSH server daemon sshd is running on an Oracle Solaris system.

$ /usr/bin/svcs ssh
STATE          STIME    FMRI
online         Jul_06   svc:/network/ssh:default

See Also

svcs(1)

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

To Set Up SSH on macOS Systems

  1. Open System Preferences and click Sharing.

    The Sharing window opens.

  2. Ensure that Remote Login is selected in the Service list.

  3. Ensure that either of the following is allowed access:

    • All Users

    • The user that running the DAS or instance

  4. (macOS 10.6 systems only) Ensure that the SSH server daemon sshd allows password authentication.

    On macOS 10.5 systems, the SSH server daemon sshd allows password authentication by default. However, on macOS 10.6 systems, the SSH server daemon sshd disallows password authentication by default. .. Edit the configuration file /etc/sshd_config to set the PasswordAuthentication option to yes. .. Stop the SSH server daemon sshd.

    +

    $ sudo launchctl stop com.openssh.sshd

  5. Start the SSH server daemon sshd.

    $ sudo launchctl start com.openssh.sshd

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

To Set Up SSH on Linux systems

  1. Ensure that the following options in the configuration file /etc/ssh/sshd_config are set to yes:

    • StrictModes

    • PubkeyAuthentication

  2. Determine if the SSH server daemon sshd is running.

    $ /sbin/service sshd status

  3. If the SSH server daemon sshd is not running, start this daemon.

    If the daemon is running, no further action is required.

    $ /sbin/service sshd start

This example confirms that the SSH server daemon sshd is running on a Linux system.

$ /sbin/service sshd status
openssh-daemon (pid  2373) is running...

Next Steps

After you have completed the setup of SSH on a host, test the setup on the host as explained in Testing the SSH Setup on a Host.

Testing the SSH Setup on a Host

After setting up SSH on a host, test the setup to ensure that you can use SSH to contact the host from another host. Testing the SSH setup on a host verifies that the SSH server daemon sshd is running and that the SSH user has a valid user account on the host.

If you cannot use SSH to contact the host, troubleshoot the SSH setup before setting up SSH user authentication.

To Test the SSH Setup on a Host

  1. From another host, use SSH to log in into the host that you are testing as the SSH user.

    $ ssh -l user-name host-name
    user-name

    The username for the SSH user’s account on the host.

    host-name

    The host name of the host that you are logging in to.

  2. In response to the prompt, type your password.

    If this step succeeds, your setup of SSH is complete.

    The first time that you connect to a host, you might be warned that the authenticity cannot be established and be asked if you want to continue connection. If you trust the host, answer yes to connect to the host.

Troubleshooting

To obtain diagnostic information, use the -v option of the command-line SSH client and the -d option of the SSH server daemon sshd. How to start the SSH server daemon sshd manually depends on the operating system and SSH provider that you are using.

If the SSH server daemon sshd is set up on a host that has a firewall, ensure that a rule is defined to allow inbound traffic on the SSH port. The default SSH port is port 22.

If your connection is refused, the SSH server daemon sshd is not running, and you must start the daemon.

If your connection is accepted, but you cannot log in, ensure that the SSH user has a valid user account on the host.

Next Steps

After testing the SSH setup, set up SSH user authentication to enable SSH to authenticate users without prompting for a password. For more information, see Setting Up SSH User Authentication.

Setting Up SSH User Authentication

When a Payara Server subcommand uses SSH to log in to a remote host, Payara Server must be able to authenticate the SSH user. Setting up SSH user authentication ensures that this requirement is met.

Before setting up SSH user authentication, determine the authentication scheme to use. If SSH is already deployed at your site, the authentication scheme to use might already be chosen for you.

The following table lists the authentication schemes that Payara Server supports. The table also lists the advantages and disadvantages of each authentication scheme.

Authentication Scheme Advantages Disadvantages

Public key without encryption

Payara Server provides tools to simplify set up.

SSH must be configured to locate users' key files in the correct location. File access permissions for key files and the directory that contains the key files must be set correctly.

Public key with passphrase-protected encryption

This scheme is more secure than public key authentication without encryption.

SSH must be configured to locate users' key files in the correct location. File access permissions for key files and the directory that contains the key files must be set correctly. For each SSH user, Payara Server password aliases are required for the encryption passphrase.

Password

No SSH configuration is required to locate key files or to ensure that file access permissions are correct.

For each SSH user, Payara Server password aliases are required for the SSH password.

To Set Up Public Key Authentication Without Encryption

Use the setup-ssh subcommand in local mode to set up public key authentication without encryption. This subcommand enables you to set up public key authentication on multiple hosts in a single operation.

The setup-ssh subcommand generates a key pair and distributes the public key file to specified hosts. The private key file and the public key file are protected only by the file system’s file access permissions.

If you require additional security, set up public key authentication with passphrase-protected encryption as explained in To Set Up Encrypted Public Key Authentication.

Before You Begin

Ensure that the following prerequisites are met:

If other users can write to these files and directories, the secure service might not trust the authorized_key file and might disallow public key authentication.

  1. Generate an SSH key pair and distribute the public key file to the hosts where you are setting up public key authentication.

    Only the options that are required to complete this task are provided in this step. For information about all the options for setting up an SSH key, see the setup-ssh(1) help page. 
    asadmin> setup-ssh [--sshuser sshuser] host-list
    sshuser

    The SSH user for which you are generating the SSH key pair. If you are running the subcommand as the SSH user, you may omit this option.

    host-list

    A space-separated list of the names of the hosts where the SSH public key is to be distributed.

    After generating the SSH key pair, the subcommand uses SSH to log in to each host in host-list as the SSH user to distribute the public key. Each time a password is required to log in to a host, you are prompted for the SSH user’s password.

  2. In response to each prompt for a password, type the SSH user’s password.

The following example generates and sets up an SSH key for the user gfuser on the hosts sua01 and sua02. The command is run by the user gfuser.

asadmin> setup-ssh --generatekey=true sua01 sua02

Enter SSH password for gfuser@sua01>
Created directory /home/gfuser/.ssh
/usr/bin/ssh-keygen successfully generated the identification /home/gfuser/.ssh/id_rsa
Copied keyfile /home/gfuser/.ssh/id_rsa.pub to gfuser@sua01
Successfully connected to gfuser@sua01 using keyfile /home/gfuser/.ssh/id_rsa
Copied keyfile /home/gfuser/.ssh/id_rsa.pub to gfuser@sua02
Successfully connected to gfuser@sua02 using keyfile /home/gfuser/.ssh/id_rsa
Command setup-ssh executed successfully.

Next Steps

After setting up public key authentication, test the setup by using ssh to log in as the SSH user to each host where the public key was distributed. For each host, log in first with the unqualified host name and then with the fully qualified name. If SSH does not prompt for password, public key authentication is set up correctly on the host.

If you are prompted for a password, verify that the public key file was copied correctly to the SSH user’s authorized_keys file.

Troubleshooting

Setup might fail because file access permissions in the SSH user’s home directory are too permissive. In this situation, ensure that the file access permissions in the SSH user’s home directory meet the requirements for performing this procedure.

If you have set the file access permissions in the SSH user’s home directory correctly, setup might still fail if you are using the MKS Toolkit. In this situation, correct the problem in one of the following ways:

  • On each remote host, copy the public key file to the SSH user’s ~/.ssh directory and import the file. To import the file, select the Secure Service tab in the MKS configuration GUI and click Passwordless.

  • Disable strict modes.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help setup-ssh at the command line.

To Set Up Encrypted Public Key Authentication

Encrypted key file authentication uses an encrypted private key file that is protected with a passphrase. This passphrase must be provided to use the private key to unlock the public key.

If you require encrypted public key authentication, you must use the SSH utility ssh-keygen to generate an SSH key pair with an encrypted private key. You can then use the setup-ssh subcommand to distribute the public key file to specified hosts.

To use the encrypted key file, Payara Server requires the passphrase with which the key file was encrypted. To provide this passphrase securely to Payara Server, create a Payara Server password alias to represent the passphrase and store this alias in a password file that is passed to the asadmin utility.

Only the options that are required to complete this task are provided in each step. For information about all the options for the commands and subcommands in this task, see their help pages or man pages.

Before You Begin

Ensure that the following prerequisites are met:

  • SSH is set up on each host where you are setting up public key authentication. For more information, see the following sections:

  • Only the SSH user has write access to the following files and directories on each host where you are setting up public key authentication:

    • The SSH user’s home directory

    • The ~/.ssh directory

    • The authorized_key file

      If other users can write to these files and directories, the secure service might not trust the authorized_key file and might disallow public key authentication.

      1. Generate an SSH key pair with an encrypted private key file.

        Use the SSH utility ssh-keygen for this purpose.

        $ ssh-keygen -t type
        type

        The algorithm that is to be used for the key and which must be rsa, dsa, or rsa1.

        The ssh-keygen utility prompts you for a file in which to save the key.

      2. To simplify the distribution of the key file, accept the default file.

        The ssh-keygen utility prompts you for a passphrase.

      3. In response to the prompt, type your choice of passphrase for encrypting the private key file. The ssh-keygen utility prompts you to type the passphrase again.

      4. In response to the prompt, type the passphrase that you set in Step 3.

      5. Distribute the public key file to the hosts where you are setting up public key authentication.

        Use the setup-ssh asadmin subcommand for this purpose.

$ asadmin setup-ssh --generatekey=false host-list
host-list

A space-separated list of the names of the hosts where the SSH public key is to be distributed.

The subcommand uses SSH to log in to each host in host-list as the SSH user to distribute the public key. Each time a passphrase or a password is required to log in to a host, you are prompted for the passphrase or the SSH user’s password.

  1. In response to each prompt, type the requested information.

    • In response to each prompt for a passphrase, type the passphrase that you set in Step 3.

    • In response to each prompt for a password, type the SSH user’s password.

  2. Create a Payara Server password alias for the passphrase that you set in Step 3.

    1. Ensure that the DAS is running.

      Remote subcommands require a running server.

    2. Run the create-password-alias asadmin subcommand.

      $ asadmin create-password-alias alias-name
alias-name

Your choice of name for the alias that you are creating.

The create-password-alias subcommand prompts you to type the passphrase for which you are creating an alias. .. In response to the prompt, type the passphrase that you set in Step 3.

+ The create-password-alias subcommand prompts you to type the passphrase again.

  1. In response to the prompt, type the passphrase that you set in Step 3 again.

    1. Create a plain text file that contains the following entry for the passphrase alias:

      AS_ADMIN_SSHKEYPASSPHRASE=${ALIAS=alias-name}
When you create an SSH node, pass this file as the --passwordfile option of the asadmin utility. For more information, see To Create an SSH Node.

The following example generates an SSH key pair with an encrypted private key for the user gfadmin and distributes the public key to the hosts sj01 and ja02. The example also creates an alias that is named ssh-key-passphrase for the private key’s passphrase.

$ ssh-keygen -t rsa

Generating public/private rsa key pair.
Enter file in which to save the key (/home/gfadmin/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/gfadmin/.ssh/id_rsa.
Your public key has been saved in /home/gfadmin/.ssh/id_rsa.pub.
The key fingerprint is:
db:b5:f6:0d:fe:16:33:91:20:64:90:1a:84:66:f5:d0 gfadmin@dashost
$ asadmin setup-ssh --generatekey=false sj01 sj02
Key /home/gfadmin/.ssh/id_rsa is encrypted
Enter key passphrase>
Enter SSH password for gfadmin@sj01>
Copied keyfile /home/gfadmin/.ssh/id_rsa.pub to gfadmin@sj01
Successfully connected to gfadmin@sj01 using keyfile /home/gfadmin/.ssh/id_rsa
Successfully connected to gfadmin@sj02 using keyfile /home/gfadmin/.ssh/id_rsa
SSH public key authentication is already configured for gfadmin@sj02
Command setup-ssh executed successfully.
$ asadmin create-password-alias ssh-key-passphrase
Enter the alias password>
Enter the alias password again>
Command create-password-alias executed successfully.

The entry in the password file for the ssh-key-passphrase alias is as follows:

AS_ADMIN_SSHKEYPASSPHRASE=${ALIAS=ssh-key-passphrase}

Troubleshooting

Setup might fail because file access permissions in the SSH user’s home directory are too permissive. In this situation, ensure that the file access permissions in the SSH user’s home directory meet the requirements for performing this procedure.

If you have set the file access permissions in the SSH user’s home directory correctly, setup might still fail if you are using the MKS Toolkit. In this situation, correct the problem in one of the following ways:

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

  • asadmin help create-password-alias

  • asadmin help setup-ssh

To Set Up Password Authentication

To use SSH to log in to a remote host, Payara Server requires the SSH user’s password. To provide this password securely to Payara Server, create a Payara Server password alias to represent the password and store this alias in a password file that is passed to the asadmin utility.

Before You Begin

Ensure that SSH is set up on each host where you are setting up password authentication.

  1. Ensure that the DAS is running.

    Remote subcommands require a running server.

  2. Create an alias for the SSH user’s password.

    Only the options that are required to complete this task are provided in this step. For information about all the options for creating a password alias, see the create-password-alias(1) help page. 
    asadmin> create-password-alias alias-name
    alias-name

    Your choice of name for the alias that you are creating.

    The create-password-alias subcommand prompts you to type the password for which you are creating an alias.

  3. In response to the prompt, type the SSH user’s password.

    The create-password-alias subcommand prompts you to type the password again.

  4. In response to the prompt, type the SSH user’s password again.

  5. Create a plain text file that contains the following entry for the password alias:

    AS_ADMIN_SSHPASSWORD=${ALIAS=alias-name}
    alias-name

    The alias name that you specified in Step 2.

    When you create an SSH node, pass this file as the --passwordfile option of the asadmin utility. For more information, see To Create an SSH Node.

The following example creates an alias that is named ssh-password for the SSH user’s password.

$ asadmin create-password-alias ssh-password
Enter the alias password>
Enter the alias password again>
Command create-password-alias executed successfully.

The entry in the password file for the ssh-password alias is as follows:

AS_ADMIN_SSHPASSWORD=${ALIAS=ssh-password}

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-password-alias at the command line.

Installing and Removing Payara Server Software on Multiple Hosts

Payara Server software must be installed on all hosts where Payara Server will run. How to install Payara Server software on multiple hosts depends on the degree of control that you require over the installation on each host.

  • If you require complete control over the installation on each host, install the software from a Payara Server distribution on each host individually.

  • If the same setup on each host is acceptable, copy an existing Payara Server installation to the hosts. For more information, see To Copy a Payara Server Installation to Multiple Hosts.

Payara Server also enables you to remove Payara Server software from multiple hosts in a single operation. For more information, see To Remove Payara Server Software From Multiple Hosts.

To Copy a Payara Server Installation to Multiple Hosts

Use the install-node-dcom subcommand or the install-node-ssh subcommand in local mode to copy an installation of Payara Server software to multiple hosts.

Before You Begin

Ensure that DCOM or SSH is set up on the host where you are running the subcommand and on each host where you are copying the Payara Server software.

Run the appropriate subcommand for the protocol that is set up for communication between the hosts.

  • If DCOM is set up for communication between the hosts, run the install-node-dcom subcommand.

    Only the options that are required to complete this task are provided in this step. For information about all the options for copying an installation of Payara Server software, see the install-node-dcom(1) help page. 
    asadmin> install-node-dcom host-list
    host-list

    A space-separated list of the names of the hosts where you are copying the installation of Payara Server software.

  • If SSH is set up for communication between the hosts, run the install-node-ssh subcommand.

    Only the options that are required to complete this task are provided in this step. For information about all the options for copying an installation of Payara Server software, see the link install-node-ssh(1) help page. 
    asadmin> install-node-ssh host-list
    host-list

    A space-separated list of the names of the hosts where you are copying the installation of Payara Server software.

The following example copies the Payara Server software on the host where the subcommand is run to the default location on the DCOM-enabled hosts wpmdl1.example.com and wpmdl2.example.com.

Some lines of output are omitted from this example for readability.

asadmin> install-node-dcom wpmdl1.example.com wpmdl2.example.com

Created installation zip C:\payara8107276692860773166.zip
Copying 85760199 bytes..........................................................

WROTE FILE TO REMOTE SYSTEM: C:/payara/payara_install.zip and C:/payara/unpack.bat
Output from Windows Unpacker:

C:\Windows\system32>C:

C:\Windows\system32>cd "C:\payara"

C:\payara6>jar xvf payara_install.zip
 inflated: bin/asadmin
 inflated: bin/asadmin.bat
 inflated: glassfish/bin/appclient
 inflated: glassfish/bin/appclient.bat
 inflated: glassfish/bin/appclient.js
 inflated: glassfish/bin/asadmin
 inflated: glassfish/bin/asadmin.bat
...
 inflated: mq/lib/props/broker/default.properties
 inflated: mq/lib/props/broker/install.properties

Command install-node-dcom executed successfully.

The following example copies the Payara Server software on the host where the subcommand is run to the default location on the SSH-enabled hosts sj03.example.com and sj04.example.com.

asadmin> install-node-ssh sj03.example.com sj04.example.com

Created installation zip /home/gfuser/glassfish2339538623689073993.zip
Successfully connected to gfuser@sj03.example.com using keyfile /home/gfuser
/.ssh/id_rsa
Copying /home/gfuser/payara2339538623689073993.zip (81395008 bytes) to
sj03.example.com:/export/payara
Installing payara2339538623689073993.zip into sj03.example.com:/export/payara
Removing sj03.example.com:/export/payara/payara2339538623689073993.zip
Fixing file permissions of all files under sj03.example.com:/export/payara/bin
Successfully connected to gfuser@sj04.example.com using keyfile /home/gfuser
/.ssh/id_rsa
Copying /home/gfuser/payara2339538623689073993.zip (81395008 bytes) to
sj04.example.com:/export/payara
Installing payara2339538623689073993.zip into sj04.example.com:/export/payara
Removing sj04.example.com:/export/payara/payara2339538623689073993.zip
Fixing file permissions of all files under sj04.example.com:/export/payara/bin
Command install-node-ssh executed successfully

See Also

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

  • asadmin help install-node-dcom

  • asadmin help install-node-ssh

To Remove Payara Server Software From Multiple Hosts

Use the uninstall-node-dcom subcommand or the uninstall-node-ssh subcommand in local mode to remove Payara Server software from multiple hosts.

Before You Begin

Ensure that the following prerequisites are met:

  • DCOM or SSH is set up on the host where you are running the subcommand and on each host from which you are removing the Payara Server software.

  • No process is accessing the parent of the base installation directory for the Payara Server software or any subdirectory of this directory.

  • The parent of the base installation directory for the Payara Server software is the same on each host from which you are removing the Payara Server software.

  • For hosts that use DCOM for remote communication, the configuration of the following items is the same on each host:

    • Windows Domain

    • Windows User

  • For hosts that use SSH for remote communication, the configuration of the following items is the same on each host:

    • SSH port

    • SSH user

    • SSH key file

Run the appropriate subcommand for the protocol that is set up for communication between the hosts.

  • If DCOM is set up for communication between the hosts, run the uninstall-node-dcom subcommand.

    Only the options that are required to complete this task are provided in this step. For information about all the options for removing Payara Server software, see the uninstall-node-dcom(1) help page. 
asadmin> uninstall-node-dcom host-list
host-list

A space-separated list of the names of the hosts from which you are removing Payara Server software.

  • If SSH is set up for communication between the hosts, run the uninstall-node-ssh subcommand.

    Only the options that are required to complete this task are provided in this step. For information about all the options for removing Payara Server software, see the uninstall-node-ssh(1) help page. 
asadmin> uninstall-node-ssh host-list
host-list

A space-separated list of the names of the hosts from which you are removing Payara Server software.

The following example removes Payara Server software on the DCOM-enabled hosts wpmdl1.example.com and wpmdl2.example.com from the default location.

asadmin> uninstall-node-dcom wpmdl1 wpmdl2
Command uninstall-node-dcom executed successfully.

The following example removes Payara Server software on the SSH-enabled hosts sj03.example.com and sj04.example.com from the default location.

asadmin> uninstall-node-ssh sj03 sj04
Successfully connected to gfuser@sj03.example.com using keyfile /home/gfuser
/.ssh/id_rsa
Successfully connected to gfuser@sj04.example.com using keyfile /home/gfuser
/.ssh/id_rsa
Command uninstall-node-ssh executed successfully.

See Also

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

  • asadmin help uninstall-node-dcom

  • asadmin help uninstall-node-ssh