docs/ha-administration-guide/src/main/asciidoc/ssh-setup.adoc

type=page
status=published
title=Enabling Centralized Administration of {productName} Instances
next=nodes.html
prev=overview.html
~~~~~~

= Enabling Centralized Administration of {productName} Instances

[[GSHAG00003]][[gkshg]]


[[enabling-centralized-administration-of-glassfish-server-instances]]
== 2 Enabling Centralized Administration of {productName} Instances

{productName} uses the Distributed Component Object Model (DCOM)
remote protocol or secure shell (SSH) to ensure that clusters that span
multiple hosts can be administered centrally. To perform administrative
operations on {productName} 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.


[NOTE]
====
The use of DCOM or SSH to enable centralized administration of remote
instances is optional. If the use of DCOM or SSH is not feasible in your
environment, you can administer remote instances locally.
====


The following topics are addressed here:

* link:#gkshz[About Centralized Administration of {productName} Instances]
* link:#CEGIFJJF[Setting Up DCOM and Testing the DCOM Set Up]
* link:#gksiy[Setting Up Cygwin SSH on Windows]
* link:#gkskf[Setting Up the MKS Toolkit on Windows]
* link:#gksja[Setting Up SSH on UNIX and Linux Systems]
* link:#gkslw[Testing the SSH Setup on a Host]
* link:#gkshh[Setting Up SSH User Authentication]
* link:#gkshn[Installing and Removing {productName} Software on Multiple Hosts]

[[gkshz]][[GSHAG00172]][[about-centralized-administration-of-glassfish-server-instances]]

=== About Centralized Administration of {productName} 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 practicable in your environment, you can administer
remote instances locally.

[[GSHAG446]][[sthref4]]


[[determining-whether-to-enable-centralized-administration]]
==== Determining Whether to Enable Centralized Administration

Before setting up a {productName} cluster, use the following
considerations to determine whether to enable centralized administration
of remote instances:

* If you are planning a large cluster of many instances, consider
enabling centralized administration of instances in the cluster.
Centralized administration of instances simplifies the administration of
the cluster by enabling you to perform all administrative operations on
the cluster and its instances from the DAS.
* If you are planning a small cluster 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 resides 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.

[width="100%",cols="<15%,<42%,<43%",options="header",]
|===
|Protocol |Node Administration Instructions |Instance Administration Instructions

|DCOM
|link:nodes.html#CHDBIHFJ[Creating, Listing, Testing, and Deleting `DCOM` Nodes]
|link:instances.html#gkqal[Administering {productName} Instances Centrally]

|SSH
|link:nodes.html#gkrkn[Creating, Listing, Testing, and Deleting `SSH` Nodes]
|link:instances.html#gkqal[Administering {productName} Instances Centrally]

|None
|link:nodes.html#gkrnp[Creating, Listing, and Deleting `CONFIG` Nodes]
|link:instances.html#gkqdw[Administering {productName} Instances Locally]
|===


[[GSHAG447]][[sthref5]]


[[considerations-for-using-dcom-for-centralized-administration]]
==== Considerations for Using DCOM for Centralized Administration

DCOM enables communications between Windows hosts. In a typical
{productName} 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 {productName}. 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 only with the Windows operating system. Because DCOM
is typically installed and preconfigured, minimal additional setup is
required to use DCOM with {productName}.

Before setting up DCOM, decide which Windows user {productName} 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.

[[GSHAG320]][[sthref6]]


[[considerations-for-using-ssh-for-centralized-administration]]
==== Considerations for Using SSH for Centralized Administration

In a typical {productName} 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 {productName} 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.

[[gksmt]][[GSHAG00262]][[obtaining-ssh-software]]

===== 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:

* http://www.cygwin.com/[Cygwin] (`http://www.cygwin.com/`) release 1.7.6
* http://www.mkssoftware.com[MKS Toolkit for Developers]
 (`http://www.mkssoftware.com`) release 9.2

[[gkshj]][[GSHAG00263]][[determining-the-ssh-user]]

===== Determining the SSH User

Before setting up SSH, decide which SSH user {productName} 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.

[[glghe]][[GSHAG00222]][[requirements-for-the-ssh-users-environment]]

===== Requirements for the SSH User's Environment

The environment of the SSH user on any remote host to which the user
will connect must meet the requirements that are stated in
"link:release-notes/release-notes.html#GSRLN00252[Paths and Environment Settings for the JDK Software]"
in {productName} Release Notes.

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 than 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.

[[glgfy]][[GSHAG00223]][[file-access-permissions-on-uac-enabled-windows-systems]]

===== File Access Permissions on UAC-Enabled Windows Systems


[NOTE]
====
The http://technet.microsoft.com/en-us/library/cc709691%28WS.10%29.aspx[User
Account Control (UAC)](`http://technet.microsoft.com/en-us/library/cc709691%28WS.10%29.aspx`)
feature is available only on some versions of the Windows operating
system, for example, Windows 7, Windows Vista, and Windows 2008.
====


You might be using a UAC-enabled Windows system and choose to store
files for {productName} instances in a directory other than the SSH
user's home directory. In this situation, the SSH user must have native
(that is, nonvirtual) 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.

[[CEGIFJJF]][[GSHAG448]][[setting-up-dcom-and-testing-the-dcom-set-up]]

=== 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 cluster will reside.

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

[[CEGDAFHD]][[GSHAG449]][[windows-operating-system-settings]]

==== 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

[[CEGCJGCF]][[GSHAG450]][[to-enable-the-windows-user-to-run-scripts-on-a-remote-host]]

==== 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 user `NT SERVICE\TrustedInstaller`
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.


[NOTE]
====
Only the operating-system-level 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 cluster will reside.

1. If necessary, start the Registry Editor.
+
[source]
----
regedit.exe
----
The Registry Editor window opens.

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.
+
The Permissions window for the key opens.

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:
[arabic]
.. In the Permissions window, click Advanced. +
The Advanced Security Settings window for the key opens.
.. In the Advanced Security Settings window, select the Owner tab.
.. From the Change owner to list, select the Windows user or the group
that contains the Windows user.
.. Ensure that the Replace owner on subcontainer and objects option is selected.
.. 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.

.. 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.

[[GSHAG451]]

Next Steps

Set up password authentication for the Windows user as explained in
link:#CEGCDCEF[To Set Up Password Authentication for the Windows User].

[[CEGCDCEF]][[GSHAG452]][[to-set-up-password-authentication-for-the-windows-user]]

==== To Set Up Password Authentication for the Windows User

When a {productName} subcommand uses DCOM to log in to a remote host,
{productName} requires the Windows user's password to authenticate
the Windows user. To provide this password securely to {productName},
create a {productName} password alias to represent the password and
store this alias in a password file that is passed to the
link:reference-manual/asadmin.html#GSRFM00263[`asadmin`] utility.

[[GSHAG453]]

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 link:#CEGDAFHD[Windows Operating System Settings].
* The Windows user is able to run scripts on the host. For more
information, see link:#CEGCJGCF[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. [[CEGGAHFH]]
Create an alias for the Windows user's password.
+
[NOTE]
====
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 link:reference-manual/create-password-alias.html#GSRFM00049[`create-password-alias`(1)] help page.
====
+
[source]
----
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:
+
[source]
----
AS_ADMIN_WINDOWSPASSWORD=${ALIAS=alias-name}
----
alias-name::
  The alias name that you specified in Step link:#CEGGAHFH[2].
+

[NOTE]
====
When you create a `DCOM` node, pass this file as the `--passwordfile`
option of the `asadmin` utility. For more information, see
link:nodes.html#CHDIGBJB[To Create a `DCOM` Node].
====


[[GSHAG454]][[sthref7]]
Example 2-1 Creating an Alias for the Windows User's Password

This example creates an alias that is named `winuser-password` for the
Windows user's password.

[source]
----
$ 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:

[source]
----
AS_ADMIN_WINDOWSPASSWORD=${ALIAS=winuser-password}
----

[[GSHAG455]]

See Also

* link:reference-manual/asadmin.html#GSRFM00263[`asadmin`(1M)]
* link:reference-manual/create-password-alias.html#GSRFM00049[`create-password-alias`(1)]

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

[[GSHAG456]]

Next Steps

Test the DCOM setup as explained in link:#CEGJFADH[To Test the
Connection Over DCOM to a Remote Host].

[[CEGJFADH]][[GSHAG457]][[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 the requires the DAS 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 the
requires the DAS 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
link:nodes.html#CHDIGBJB[To Create a `DCOM` Node] and
link:instances.html#gkqch[To Create an Instance Centrally].

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

[[GSHAG458]]

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 link:#CEGDAFHD[Windows Operating System Settings].
* The Windows user is able to run scripts on the host. For more
information, see link:#CEGCJGCF[To Enable the Windows User to Run
Scripts on a Remote Host].
* Password authentication is set up for the windows user as explained in
link:#CEGCDCEF[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 link:#CEGCDCEF[To Set Up Password
Authentication for the Windows User].

[NOTE]
====
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 link:reference-manual/validate-dcom.html#GSRFM796[`validate-dcom`(1)] help page.
====

[source]
----
C:\>asadmin --passwordfile filename validate-dcom host-name
----
filname::
  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.

[[GSHAG459]][[sthref8]]
Example 2-2 Testing the Connection Over DCOM to a Remote Host

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

[source]
----
C:\> asadmin --passwordfile aspwalias.txt validate-dcom wpmdl2
Command validate-dcom executed successfully.
----

[[GSHAG460]]

See Also

* link:reference-manual/asadmin.html#GSRFM00263[`asadmin`(1M)]
* link:reference-manual/validate-dcom.html#GSRFM796[`validate-dcom`(1)]
* link:#CEGDAFHD[Windows Operating System Settings]
* link:#CEGCJGCF[To Enable the Windows User to Run Scripts on a Remote Host]
* link:nodes.html#CHDIGBJB[To Create a `DCOM` Node]
* link:instances.html#gkqch[To Create an Instance Centrally]

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

[[gksiy]][[GSHAG00173]][[setting-up-cygwin-ssh-on-windows]]

=== Setting Up Cygwin SSH on Windows

Set up Cygwin SSH on the DAS host and on all hosts where instances in
your cluster will reside.

The following topics are addressed here:

* link:#gksjn[To Download and Install Cygwin]
* link:#gksin[To Set the Path for Windows and for the Cygwin Shell]
* link:#gksov[To Set the Home Directory for the Cygwin SSH User]
* link:#gkskx[To Configure and Start the Cygwin SSH Server Daemon
`sshd`]

[[gksjn]][[GSHAG00071]][[to-download-and-install-cygwin]]

==== To Download and Install Cygwin

For centralized {productName} 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 folder `C:\cygwin`.

3. From the http://www.cygwin.com/[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.
[arabic]
.. Under the Net category, search for `openssh`.
.. Locate the `openssh` package and click Skip. +
The package is selected.
.. Click Next. +
Any unsatisfied dependencies are listed.

10. Leave the Select Required Packages option selected and click Next +
The packages are installed.

11. Click Finish.

[[GSHAG321]]

See Also

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

[[gksin]][[GSHAG00072]][[to-set-the-path-for-windows-and-for-the-cygwin-shell]]

==== To Set the Path for Windows and for the Cygwin Shell

To enable {productName} 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

[[gksov]][[GSHAG00073]][[to-set-the-home-directory-for-the-cygwin-ssh-user]]

==== 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 {productName} 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. {productName} 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, {productName} and SSH each
locate a user's `.ssh` directory in different directories. To simplify
the set up 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.

[[gkskx]][[GSHAG00074]][[to-configure-and-start-the-cygwin-ssh-server-daemon-sshd]]

==== To Configure and Start the Cygwin SSH Server Daemon `sshd`

[[GSHAG322]]

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.

1. Double-click the Cygwin icon. A Cygwin terminal is started.

2. If necessary, set the password for your user account.
[arabic]
.. Run the `passwd` command as follows:
+
[source]
----
$ passwd user-name
----
user-name::
  The user name for your account.
.. Type a password. The password for your Windows account is also set.

3. Configure SSH on the host.
[arabic]
.. Run the `ssh-host-config` command.
+
[source]
----
$ ssh-host-config
----
+
[TIP]
====
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 link:#gkuat[b].
====
+
.. [[gkuat]]
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`.

4. Start the SSH server daemon `sshd`.
+
[source]
----
$ net start sshd
----
5. Confirm that the SSH server daemon `sshd` is running.
+
[source]
----
$ cygrunsrv --query sshd
 Service             : sshd
 Display name        : CYGWIN sshd
 Current State       : Running
 Controls Accepted   : Stop
 Command             : /usr/sbin/sshd -D
----

[[GSHAG323]]

Next Steps

After you have completed the setup of SSH on a host, test the setup on
the host as explained in link:#gkslw[Testing the SSH Setup on a Host].

[[gkskf]][[GSHAG00174]][[setting-up-the-mks-toolkit-on-windows]]

=== Setting Up the MKS Toolkit on Windows

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

The following topics are addressed here:

* link:#gksmq[To Install the MKS Toolkit]
* link:#gksmu[To Set the Path for Windows and for the MKS Toolkit Shell]
* link:#gksox[To Set the Home Directory for the MKS Toolkit SSH User]
* link:#gksnx[To Configure and Start the MKS Toolkit SSH Server Daemon
`sshd`]

[[gksmq]][[GSHAG00075]][[to-install-the-mks-toolkit]]

==== To Install the MKS Toolkit

For centralized {productName} 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.

[[GSHAG324]]

See Also

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

[[gksmu]][[GSHAG00076]][[to-set-the-path-for-windows-and-for-the-mks-toolkit-shell]]

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

To enable {productName} 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.

[[gksox]][[GSHAG00077]][[to-set-the-home-directory-for-the-mks-toolkit-ssh-user]]

==== 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 {productName} 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. {productName} 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, {productName} and SSH each
locate a user's `.ssh` directory in different directories. To simplify
the set up 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. [[gkslo]]
Compare the pairs of settings for Windows and the MKS Toolkit that are
listed in the following table.
+
[width="100%",cols="<50%,<50%",options="header",]
|===
|Windows Environment Variable |MKS Toolkit Field
|`HOMEPATH` |Home Directory
|`HOMEDRIVE` |Home Directory Drive
|===
[arabic]
.. In a Windows command window, determine the values of the `HOMEPATH`
and `HOMEDRIVE` environment variables.
.. In an MKS Toolkit shell, determine the current settings of the Home
Directory and Home Directory Drive fields for the user.
+
[source]
----
$ userinfo user-name
----
user-name::
  The user name 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:
+
[source]
----
$ 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 user name for the user whose home directory you are setting, for
  example `Administrator`.
+
[NOTE]
====
Do not set the `HOME` environment variable explicitly. If 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.
+
[source]
----
$ userinfo user-name
----
user-name::
  The user name 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 link:#gkslo[1].

[[GSHAG00014]][[gksnj]]
Example 2-3 Setting the Home Directory for the MKS Toolkit User

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

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

[[gksnx]][[GSHAG00078]][[to-configure-and-start-the-mks-toolkit-ssh-server-daemon-sshd]]

==== To Configure and Start the MKS Toolkit SSH Server Daemon `sshd`


[NOTE]
====
Do not set the command shell to `cmd.exe`. The use of SSH for
centralized {productName} 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.
[arabic]
.. Click the Secure Shell Service tab.
.. Select the Password Authentication option.
.. Click Advanced settings.
.. Click the Login tab.
.. Deselect the Strict Modes option.

3. If you are using SSH key-file authentication, enable `MKSAUTH` password authentication.
[arabic]
.. Click the Authentication tab.
.. Under Enable/Disable Password using MKSAUTH, type the user's password and click the Enable.

4. Start the SSH server daemon `sshd`.

5. Confirm that the SSH server daemon `sshd` is running.
+
[source]
----
$ 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
----

[[GSHAG325]]

Next Steps

After you have completed the setup of SSH on a host, test the setup on
the host as explained in link:#gkslw[Testing the SSH Setup on a Host].

[[gksja]][[GSHAG00175]][[setting-up-ssh-on-unix-and-linux-systems]]

=== 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
cluster 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 http://www.openssh.com/[OpenSSH]
(`http://www.openssh.com/`) SSH package for your operating system.

How to set up SSH on UNIX and Linux systems depends on the flavor of the
operating system that you are running, as explained in the following
sections:

* link:#gksjx[To Set Up SSH on Oracle Solaris Systems]
* link:#gkspz[To Set Up SSH on MacOS Systems]
* link:#gksrd[To Set Up SSH on Linux systems]

[[gksjx]][[GSHAG00079]][[to-set-up-ssh-on-oracle-solaris-systems]]

==== 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.
+
[source]
----
$ /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.
+
[source]
----
$ /usr/sbin/svcadm enable ssh
----

[[GSHAG00015]][[gkspo]]
Example 2-4 Determining if the `sshd` Daemon Is Running on an Oracle
Solaris System

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

[source]
----
$ /usr/bin/svcs ssh
STATE          STIME    FMRI
online         Jul_06   svc:/network/ssh:default
----

[[GSHAG326]]

See Also

http://www.oracle.com/pls/topic/lookup?ctx=E18752&id=REFMAN1svcs-1[`svcs`(1)]

[[GSHAG327]]

Next Steps

After you have completed the setup of SSH on a host, test the setup on
the host as explained in link:#gkslw[Testing the SSH Setup on a Host].

[[gkspz]][[GSHAG00080]][[to-set-up-ssh-on-macos-systems]]

==== 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.
[arabic]
.. Edit the configuration file `/etc/sshd_config` to set the `PasswordAuthentication` option to `yes`.
.. Stop the SSH server daemon `sshd`.
+
[source]
----
$ sudo launchctl stop com.openssh.sshd
----
.. Start the SSH server daemon `sshd`.
+
[source]
----
$ sudo launchctl start com.openssh.sshd
----

[[GSHAG328]]

Next Steps

After you have completed the setup of SSH on a host, test the setup on
the host as explained in link:#gkslw[Testing the SSH Setup on a Host].

[[gksrd]][[GSHAG00081]][[to-set-up-ssh-on-linux-systems]]

==== 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.
+
[source]
----
$ /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.
+
[source]
----
$ /sbin/service sshd start
----

[[GSHAG00016]][[gkssf]]
Example 2-5 Determining if the `sshd` Daemon Is Running on a Linux
System

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

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

[[GSHAG329]]

Next Steps

After you have completed the setup of SSH on a host, test the setup on
the host as explained in link:#gkslw[Testing the SSH Setup on a Host].

[[gkslw]][[GSHAG00176]][[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.

[[gkskk]][[GSHAG00082]][[to-test-the-ssh-setup-on-a-host]]

==== 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.
+
[source]
----
$ ssh -l user-name host-name
----
user-name::
  The user name 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.

[[GSHAG330]]

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. For instructions, see the
following sections:

* link:#gkskx[To Configure and Start the Cygwin SSH Server Daemon `sshd`]
* link:#gksnx[To Configure and Start the MKS Toolkit SSH Server Daemon `sshd`]
* link:#gksjx[To Set Up SSH on Oracle Solaris Systems]

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

[[GSHAG331]]

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 link:#gkshh[Setting Up SSH User Authentication].

[[gkshh]][[GSHAG00177]][[setting-up-ssh-user-authentication]]

=== Setting Up SSH User Authentication

When a {productName} subcommand uses SSH to log in to a remote host,
{productName} 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 {productName} supports. The table also lists the advantages and disadvantages
of each authentication scheme.

[width="100%",cols="<34%,<33%,<33%",options="header",]
|===
|Authentication Scheme |Advantages |Disadvantages
|Public key without encryption |{productName} 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, {productName}
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,
{productName} password aliases are required for the SSH password.
|===


The following topics are addressed here:

* link:#gksqe[To Set Up Public Key Authentication Without Encryption]
* link:#gktaq[To Set Up Encrypted Public Key Authentication]
* link:#gktbd[To Set Up Password Authentication]

[[gksqe]][[GSHAG00083]][[to-set-up-public-key-authentication-without-encryption]]

==== 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
link:#gktaq[To Set Up Encrypted Public Key Authentication].

[[GSHAG332]]

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:

** link:#gksiy[Setting Up Cygwin SSH on Windows]
** link:#gkskf[Setting Up the MKS Toolkit on Windows]
** link:#gksja[Setting Up SSH on UNIX and Linux Systems]

* 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 and distribute the public key file to the
hosts where you are setting up public key authentication.
+
[NOTE]
====
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 link:reference-manual/setup-ssh.html#GSRFM00229[`setup-ssh`(1)] help page.
====
+
[source]
----
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.
+
2. 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.
+
In response to each prompt for a password, type the SSH user's password.

[[GSHAG00017]][[gktat]]
Example 2-6 Setting Up Public Key Authentication Without Encryption

This 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`.

[source]
----
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.
----

[[GSHAG333]]

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.

[[GSHAG334]]

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.

[[GSHAG335]]

See Also

* link:#gksiy[Setting Up Cygwin SSH on Windows]
* link:#gkskf[Setting Up the MKS Toolkit on Windows]
* link:#gksja[Setting Up SSH on UNIX and Linux Systems]
* link:reference-manual/setup-ssh.html#GSRFM00229[`setup-ssh`(1)]

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

[[gktaq]][[GSHAG00084]][[to-set-up-encrypted-public-key-authentication]]

==== 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, {productName} requires the passphrase
with which the key file was encrypted. To provide this passphrase
securely to {productName}, create a {productName} password alias
to represent the passphrase and store this alias in a password file that
is passed to the link:reference-manual/asadmin.html#GSRFM00263[`asadmin`] utility.


[NOTE]
====
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.
====


[[GSHAG336]]

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:

** link:#gksiy[Setting Up Cygwin SSH on Windows]
** link:#gkskf[Setting Up the MKS Toolkit on Windows]
** link:#gksja[Setting Up SSH on UNIX and Linux Systems]

* 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
http://www.oracle.com/pls/topic/lookup?ctx=E18752&id=REFMAN1ssh-keygen-1[`ssh-keygen`]
for this purpose.
+
[source]
----
$ 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. [[gktbh]]
In response to the prompt, type your choice of passphrase for encrypting
the private key file.
4. The `ssh-keygen` utility prompts you to type the passphrase again.
+
In response to the prompt, type the passphrase that you set in Step link:#gktbh[3].

5. Distribute the public key file to the hosts where you are setting up
public key authentication.
+
Use the link:reference-manual/setup-ssh.html#GSRFM00229[`setup-ssh`]
`asadmin` subcommand for this purpose.
+
[source]
----
$ 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.

6. 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 link:#gktbh[3].
* In response to each prompt for a password, type the SSH user's password.
--
+
7. [[gktbm]]
Create a {productName} password alias for the passphrase that you set
in Step link:#gktbh[3].
[arabic]
.. Ensure that the DAS is running. +
Remote subcommands require a running server.
.. Run the link:reference-manual/create-password-alias.html#GSRFM00049[`create-password-alias`]
`asadmin` subcommand.
+
[source]
----
$ 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 link:#gktbh[3].
+
The `create-password-alias` subcommand prompts you to type the passphrase again.
.. In response to the prompt, type the passphrase that you set in
Step link:#gktbh[3] again.

8. Create a plain text file that contains the following entry for the passphrase alias:
+
[source]
----
AS_ADMIN_SSHKEYPASSPHRASE=${ALIAS=alias-name}
----
alias-name::
  The alias name that you specified in Step link:#gktbm[7].
+
[NOTE]
====
When you create an `SSH` node, pass this file as the `--passwordfile`
option of the `asadmin` utility. For more information, see
link:nodes.html#gkrnf[To Create an `SSH` Node].
====


[[GSHAG00018]][[gktav]]
Example 2-7 Setting Up Encrypted Public Key Authentication

This 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.

[source]
----
$ 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:

[source]
----
AS_ADMIN_SSHKEYPASSPHRASE=${ALIAS=ssh-key-passphrase}
----

[[GSHAG337]]

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.

[[GSHAG338]]

See Also

* link:#gksiy[Setting Up Cygwin SSH on Windows]
* link:#gkskf[Setting Up the MKS Toolkit on Windows]
* link:#gksja[Setting Up SSH on UNIX and Linux Systems]
* link:reference-manual/asadmin.html#GSRFM00263[`asadmin`(1M)]
* link:reference-manual/create-password-alias.html#GSRFM00049[`create-password-alias`(1)]
* link:reference-manual/setup-ssh.html#GSRFM00229[`setup-ssh`(1)]
* http://www.oracle.com/pls/topic/lookup?ctx=E18752&id=REFMAN1ssh-keygen-1[`ssh-keygen`(1)]

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`

[[gktbd]][[GSHAG00085]][[to-set-up-password-authentication]]

==== To Set Up Password Authentication

To use SSH to log in to a remote host, {productName} requires the SSH
user's password. To provide this password securely to {productName},
create a {productName} password alias to represent the password and
store this alias in a password file that is passed to the
link:reference-manual/asadmin.html#GSRFM00263[`asadmin`] utility.

[[GSHAG339]]

Before You Begin

Ensure that SSH is set up on each host where you are setting up password
authentication. For more information, see the following sections:

* link:#gksiy[Setting Up Cygwin SSH on Windows]
* link:#gkskf[Setting Up the MKS Toolkit on Windows]
* link:#gksja[Setting Up SSH on UNIX and Linux Systems]

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

2. [[gktbb]]
Create an alias for the SSH user's password.
+
[NOTE]
====
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 link:reference-manual/create-password-alias.html#GSRFM00049[`create-password-alias`(1)] help page.
====
+
[source]
----
asadmin> create-password-alias alias-name
----
alias-name::
  Your choice of name for the alias that you are creating.

3. The `create-password-alias` subcommand prompts you to type the password
for which you are creating an alias. +
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:
+
[source]
----
AS_ADMIN_SSHPASSWORD=${ALIAS=alias-name}
----
alias-name::
  The alias name that you specified in Step link:#gktbb[2].

[NOTE]
====
When you create an `SSH` node, pass this file as the `--passwordfile`
option of the `asadmin` utility. For more information, see
link:nodes.html#gkrnf[To Create an `SSH` Node].
====


[[GSHAG00019]][[gktba]]
Example 2-8 Creating an Alias for the SSH User's Password

This example creates an alias that is named `ssh-password` for the SSH user's password.

[source]
----
$ 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:

[source]
----
AS_ADMIN_SSHPASSWORD=${ALIAS=ssh-password}
----

[[GSHAG340]]

See Also

* link:#gksiy[Setting Up Cygwin SSH on Windows]
* link:#gkskf[Setting Up the MKS Toolkit on Windows]
* link:#gksja[Setting Up SSH on UNIX and Linux Systems]
* link:reference-manual/asadmin.html#GSRFM00263[`asadmin`(1M)]
* link:reference-manual/create-password-alias.html#GSRFM00049[`create-password-alias`(1)]

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

[[gkshn]][[GSHAG00178]][[installing-and-removing-glassfish-server-software-on-multiple-hosts]]

=== Installing and Removing {productName} Software on Multiple Hosts

{productName} software must be installed on all hosts where {productName} will run. How to install {productName} 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 {productName} distribution on each host
individually. For more information, see link:installation-guide.html#GSING[{productName} Installation Guide].
* If the same set up on each host is acceptable, copy an existing
{productName} installation to the hosts. For more information, see
link:#gksil[To Copy a {productName} Installation to Multiple Hosts].

{productName} also enables you to remove {productName} software
from multiple hosts in a single operation. For more information, see
link:#gktaw[To Remove {productName} Software From Multiple Hosts].

The following topics are addressed here:

* link:#gksil[To Copy a {productName} Installation to Multiple Hosts]
* link:#gktaw[To Remove {productName} Software From Multiple Hosts]

[[gksil]][[GSHAG00086]][[to-copy-a-glassfish-server-installation-to-multiple-hosts]]

==== To Copy a {productName} Installation to Multiple Hosts

Use the `install-node-dcom` subcommand or the `install-node-ssh`
subcommand in local mode to copy an installation of {productName}
software to multiple hosts.

[[GSHAG341]]

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 {productName}
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.
+
[NOTE]
====
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 {productName} software, see the
link:reference-manual/install-node-dcom.html#GSRFM626[`install-node-dcom`(1)] help page.
====
+
[source]
----
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 {productName} software.
* If SSH is set up for communication between the hosts, run the
`install-node-ssh` subcommand.
+
[NOTE]
====
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 {productName} software, see the
link:reference-manual/install-node-ssh.html#GSRFM628[`install-node-ssh`(1)] help page.
====
+
[source]
----
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 {productName} software.

[[GSHAG461]][[sthref9]]
Example 2-9 Copying a {productName} Installation to Multiple
DCOM-Enabled Hosts

This example copies the {productName} 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.

[source]
----
asadmin> install-node-dcom wpmdl1.example.com wpmdl2.example.com
Created installation zip C:\glassfish8107276692860773166.zip
Copying 85760199 bytes..........................................................
....................................
WROTE FILE TO REMOTE SYSTEM: C:/glassfish7/glassfish_install.zip and C:/glassfish7/unpack.bat
Output from Windows Unpacker:

C:\Windows\system32>C:

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

C:\glassfish7>jar xvf glassfish_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.
----

[[GSHAG342]][[sthref10]]
Example 2-10 Copying a {productName} Installation to Multiple
SSH-Enabled Hosts

This example copies the {productName} 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`.

[source]
----
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/glassfish2339538623689073993.zip (81395008 bytes) to
sj03.example.com:/export/glassfish7
Installing glassfish2339538623689073993.zip into sj03.example.com:/export/glassfish7
Removing sj03.example.com:/export/glassfish7/glassfish2339538623689073993.zip
Fixing file permissions of all files under sj03.example.com:/export/glassfish7/bin
Successfully connected to gfuser@sj04.example.com using keyfile /home/gfuser
/.ssh/id_rsa
Copying /home/gfuser/glassfish2339538623689073993.zip (81395008 bytes) to
sj04.example.com:/export/glassfish7
Installing glassfish2339538623689073993.zip into sj04.example.com:/export/glassfish7
Removing sj04.example.com:/export/glassfish7/glassfish2339538623689073993.zip
Fixing file permissions of all files under sj04.example.com:/export/glassfish7/bin
Command install-node-ssh executed successfully
----

[[GSHAG343]]

See Also

* link:reference-manual/install-node-dcom.html#GSRFM626[`install-node-dcom`(1)]
* link:reference-manual/install-node-ssh.html#GSRFM628[`install-node-ssh`(1)]

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`

[[gktaw]][[GSHAG00087]][[to-remove-glassfish-server-software-from-multiple-hosts]]

==== To Remove {productName} Software From Multiple Hosts

Use the `uninstall-node-dcom` subcommand or the `uninstall-node-ssh`
subcommand in local mode to remove {productName} software from
multiple hosts.

[[GSHAG344]]

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 {productName} software.

* No process is accessing the parent of the base installation directory
for the {productName} software or any subdirectory of this directory.

* The parent of the base installation directory for the {productName}
software is the same on each host from which you are removing the
{productName} 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.
+
[NOTE]
====
Only the options that are required to complete this task are provided in this step.
For information about all the options for removing {productName} software, see the
link:reference-manual/uninstall-node-dcom.html#GSRFM775[`uninstall-node-dcom`(1)] help page.
====
+
[source]
----
asadmin> uninstall-node-dcom host-list
----
host-list::
  A space-separated list of the names of the hosts from which you are
  removing {productName} software.
* If SSH is set up for communication between the hosts, run the
`uninstall-node-ssh` subcommand.
+
[NOTE]
====
Only the options that are required to complete this task are provided in this step.
For information about all the options for removing {productName} software, see the
link:reference-manual/uninstall-node-ssh.html#GSRFM778[`uninstall-node-ssh`(1)] help page.
====
+
[source]
----
asadmin> uninstall-node-ssh host-list
----
host-list::
  A space-separated list of the names of the hosts from which you are
  removing {productName} software.

[[GSHAG462]][[sthref11]]
Example 2-11 Removing {productName} Software From Multiple
DCO\M-Enabled Hosts

This example removes {productName} software on the DCOM-enabled hosts
`wpmdl1.example.com` and `wpmdl2.example.com` from the default location.

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

[[GSHAG345]][[sthref12]]
Example 2-12 Removing {productName} Software From Multiple
SSH-Enabled Hosts

This example removes {productName} software on the SSH-enabled hosts
`sj03.example.com` and `sj04.example.com` from the default location.

[source]
----
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.
----

[[GSHAG346]]

See Also

* link:reference-manual/uninstall-node-dcom.html#GSRFM775[`uninstall-node-dcom`(1)]
* link:reference-manual/uninstall-node-ssh.html#GSRFM778[`uninstall-node-ssh`(1)]

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`