GlassFish Server Open Source Edition 3.1 - SSH Provisioning One Pager

1. Introduction

1.1. Project/Component Working Name:

GlassFish Server Open Source Edition 3.1 SSH Provisioning

1.2. Name(s) and e-mail address of Document Author(s)/Supplier:

Joe Di Pol: jfdipol@java.net
Carla Mott: carlavmott@java.net
Rajiv Mordani: mode@java.net

1.3. Date of This Document:

May 21, 2010

2. Project Summary

2.1. Project Description:

Support for invoking instance lifecycle commands on remote nodes over SSH.
Partial replacement for the GlassFish v2 node agent.

2.2. Risks and Assumptions:

1. Assumes customer has suitably configured SSH on all nodes involved in GlassFish cluster. This feature does nothing to aid SSH configuration.
2. Assumes customers running on Windows acquire SSH provider. No alternate implementation is provided for Windows. We will select one SSH provider to test with and support on Windows – this will likely be Cygwin SSHD.
3. Assumes customers must install GlassFish first on all nodes that will participate in a cluster.
4. Assumes that the user that the DAS runs as has SSH access to all nodes in the cluster. In other words the administrator must configure ssh access for the user that the DAS runs as, and this may not be the same as the user that installed GlassFish.
5. The intention is to support the bundled SSHD implementation on our supported Unix platforms. This assumes that bundled SSHD implementations on Unix based systems are relatively compatible.

3. Problem Summary

3.1. Problem Area:

SSH Provisioning attempts to accomplish two things:

1. Support the provisioning of a remote system (node) so that the user can use that system to host server instances for a cluster.
2. Support the remote execution of cluster and instance lifecycle asadmin commands on provisioned nodes.

In simple terms SSH Provisioning attempts to provide some of the capability that was provided by the node agent in GF v2. The provisioning of a system is somewhat analagous to creating a node agent on a system. Once a system is provisioned it can participate in a cluster.

In the long term we would like the operation of provisioning a system to include the capability of installing GlassFish on the system. But for 3.1 we will likely require users to install GlassFish on remote systems directly and the provisioning step will simply do some initialization on the system and register the system with the DAS.

SSHD is typically standard in current Unix distributions and is widely used for remote administration of systems. There are also popular implementations for Windows such as Cygwin SSHD. Java implementations of the SSH client exist. Hudson uses solution based on Trilead-ssh2. The intention is to leverage the work Hudson has done where possible.

3.2. Justification:

Without this feature clusters are inconvenient to configure and manage. Users
would need to create and start server instances directly on the server
instance systems – not remotely via the DAS. This feature is needed to support the start-cluster command.

4. Technical Description:

4.1. Details:

Design details are provided in the design specification.

The general approach is to use SSH as a mechanism to execute local admin commands on remote nodes. So instead of the user logging into the remote node and executing the local command, we let them execute the command via the DAS. Using the target of the command we can determine what node the target is running on and execute the command on the remote system using SSH.

This means that all the heavy lifting for these commands is performed by the local version of the command that is run (locally) on the remote system. Since SSH is an optional capability the user must always have the capability of running the remote command against the DAS, and if SSH is not operational subsequently run the local version of the command manually on the remote system.

4.2. Bug/RFE Number(s):

4.3. In Scope:

See RFE's above.

4.4. Out of Scope:

1. Providing an SSH alternative implementation on Windows
2. Support for watch dog restart of instances (provided by v2 node agent)
3. Support for remote viewing of failed server instance log files (provided by v2 node agent)
4. Execution of attrbitrary commands on a remote node via SSH (beyond what a user can do today using SSH independent of GlassFish).
5. Installation of GlassFish software on a remote node as part of node creation.

4.5. Interfaces:

4.5.1 Public Interfaces

List new, public interfaces this project exports.

• Interface: asadmin commands as defined in the design specification.
• Comment:

4.5.2 Private Interfaces

• Interface: domain.xml syntax for "nodes"
• Comment:

4.5.3 Deprecated/Removed Interfaces:

None with respect to 3.0

4.6. Doc Impact:

asadmin help for new and modified commands

asadmin reference manual

Any documentation that describes how to configure and manage a cluster

4.7. Admin/Config Impact:

This project has moderate impact to CLI administration and some impact
on the admin console. Details in the design specification.

4.8. HA Impact:

Minor. Makes clusters easier to setup and maintain, otherwise does not impact high availablilty.

4.9. I18N/L10N Impact:

Moderate impact. New error messages will be introduced by additions and enhancements to the CLI.

4.10. Packaging, Delivery & Upgrade:

4.10.1. Packaging

The final packaging is still being determined. The basic CLI functionality will be in the same package as the basic clustering (glassfish-cluster). We may choose to create a new package (glassfish-ssh) that contains the general SSH support.

4.10.2. Delivery

No impact on installation.

4.10.3. Upgrade and Migration:

We will make a best effort to migrate v2 node agents from domain.xml to the new "node" element. Details are in the design specification.

4.11. Security Impact:

The feature does not introduce any new services or ports. It does require that the user configure SSH on the systems that will be participating in a cluster. Authentication to SSH will be done using SSH public key authentication. Details are in the design specification.

4.12. Compatibility Impact

This feature does not introduce any incompatibilities relative to 3.0. It does introduce a feature that is similar to, but not completely compatible with the node-agent feature in v2. We make some attempt to ease migration to this feature from node agents, but this feature is not compatible with node-agents. See the upgrade and compatibility sections of the design specification.

4.13. Dependencies:

4.13.1 Internal Dependencies

1. Cluster Infrastructure. In particular:
   1. _create_local_filesystem / _delete_local_filesystem
   2. start-local-instance

4.13.2 External Dependencies

1. Trilead SSH2 client library (BSD License, OSR 11750)
2. SSH support of the native operating system. On Windows we will need to choose an SSH provider to test with which will likely be Cygwin SSHD.

4.14. Testing Impact:

It should be possible to re-use clustering tests from v2, but they will need to be modified to use the new "node" construct instead of node agents.

New unit tests may need to be written to validate behavior of new node commands.

5. Reference Documents

• SSH Provisioning Design Specification
• Clustering Infrastructure Specification
• 2.1 Quick Start Guide

6. Schedule:

6.1. Projected Availability:

Indicate which milestones from the current schedule the project
will be:

• Initially integrated (may not be feature complete): MS2
• Feature complete (ready for handoff to QA): MS3
• At production quality level: MS5