1.4

GlassFish 3.1 supports controlling instance lifecycle on remote systems via SSH. This is through the creation of SSH nodes. This document describes how to configure an SSH node for the various authentication options support by SSH. We consider three basic options:

1. Key authentication with no key file passphrase
2. Key authentication with key file passphrase
3. Password authentication

You can configure an SSH node to use key or password authentication, or both. If you specify both then GlassFish will first try to use the password authentication, and if that fails it will use the key authentication (XXX need to verify this).

Important! The command examples below are for running in a Unix shell.

1. Key Authentication with no Key File Passphrase

This is the most convenient form of authentication to configure GlassFish to use, although it is not the most secure. When you generate an SSH key file using ssh-keygen you have the option of protecting the file with a passphrase or not. In this option you do not specify a passphrase which means the key file is only protected by the filesystem permissions. While not as secure, this option is more convenient because you do not need to worry about configuring GlassFish to know about your key file passphrase. As long as the DAS has permission to read your key file things work.

You can use the setup-ssh command to set up SSH to use this form of authentication. This blog has lots of details about setting up SSH for use with GlassFish 3: Using GlassFish v3.1 SSH Provisioning Commands.

Once SSH is set up you create the SSH node like this:

asadmin create-node-ssh --nodehost instance.host.name.com --installdir /export/gf/glassfish myhost_node

When GlassFish needs to access this node it will search for the SSH key file to use in default locations (~/.ssh/id_dsa, ~/.ssh/id_rsa), and it will use that key to authenticate to the remote host. If you want it to use a different key file then you may use the --sshkeyfile option to specify the key file's location.

2. Key authentication with a Key File Passphrase

This is the same as option 1 except that when you run ssh-keygen to generate your key you do specify a passphrase to encrypt (lock) the private ssh key. In order for GlassFish to access the private key it must know the passphrase you used to encrypt the key. To pass this passphrase to GlassFish you do it via an asadmin password file. You can either do this insecurely by providing your password in the clear, or securely using password aliases.

2.1 Key authentication with a clear-text Key File Passphrase: not recommended

Just put your passphrase, in the clear, in an asadmin password file and pass it to asadmin like this:

$ echo AS_ADMIN_SSHKEYPASSPHRASE=your_passphrase > /tmp/p
$ asadmin --passwordfile /tmp/p create-node-ssh --nodehost instance.host.name.com --installdir /export/gf/glassfish myhost_node
$ rm /tmp/p

Warning! In this case your ssh keyphrase will be stored in clear-text in the GlassFish domain.xml file. This option is not secure!!

2.2 Key authentication with secure Key File Passphrase: recommended

To securely configure GlassFish to know your key file passphrase you need to use the password alias feature of GlassFish.

Before creating the SSH node you must first create a password alias that refers to your key file passphrase. You do this by running create-password-alias like this:

$ asadmin create-password-alias ssh-key-passphrase
Enter the alias password>
Enter the alias password again>

When prompted enter the passphrase you used when you generated your SSH key. This command takes your passphrase and saves it safely in the GlassFish key store and tags it with the name "ssh-key-passphrase". You can now refer to this name when you create the SSH node.

GlassFish 3.1 only supports passing password information via an asadmin password file, so to pass the password alias to create-node-ssh you must do so through a password file. It looks like this:

$ echo AS_ADMIN_SSHKEYPASSPHRASE=\$\{ALIAS=ssh-key-passphrase\} > /tmp/p
$ asadmin --passwordfile /tmp/p create-node-ssh --nodehost instance.host.name.com --installdir /export/gf/glassfish myhost_node
$ rm /tmp/p

Important! The '$' and brackets are escaped with a backslash on Unix to protect them from the shell. If you don't do this the format of the admin password file will not be correct. Please see the end of this document for an example of what the password file should look like.

When GlassFish needs to access the node via SSH it looks up the password tagged with "ssh-key-passphrase" from its keystore and uses that password to unlock the keyfile.

3. Password authentication

In this case you do not use SSH key authentication at all, instead SSH requires your password to authenticate. You can either do this insecurely by providing your password in the clear, or securely using password aliases.

3.1 Password authentication using clear-text password: not recommended

For this option you just put your ssh password in the clear an an asadmin password file and pass the file to asadmin when you create the SSH node:

$ echo AS_ADMIN_SSHPASSWORD=your_ssh_password > /tmp/p
$ asadmin --passwordfile /tmp/p create-node-ssh --nodehost instance.host.name.com --installdir /export/gf/glassfish myhost_node
$ rm /tmp/p

Warning! In this case your ssh password will be stored in clear-text in the GlassFish domain.xml file. This option is not secure!!

3.2 Password authentication using password aliases: recommended

Before creating the SSH node you must first create a password alias that refers to your ssh password. You do this by running create-password-alias like this:

$ asadmin create-password-alias ssh-password
Enter the alias password>
Enter the alias password again>

Enter your SSH password when prompted. Then create the SSH node passing the SSH password information via an asadmin password file:

$ echo AS_ADMIN_SSHPASSWORD=\$\{ALIAS=ssh-password\} > /tmp/p
$ asadmin --passwordfile /tmp/p create-node-ssh --nodehost instance.host.name.com --installdir /export/gf/glassfish myhost_node
$ rm /tmp/p

Important! The '$' and brackets are escaped with a backslash on Unix to protect them from the shell. If you don't do this the format of the admin password file will not be correct. Please see the end of this document for an example of what the password file should look like.

4. Example asadmin password file with an entry that uses a password alias.

If create-node-ssh fails with an authentication error, and you are using password aliases then check the format of the pasword file you are passing to create-node-ssh. It should look something like this:

AS_ADMIN_SSHPASSWORD=${ALIAS=ssh-password}

or

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

Note the '$' and curly braces.