Administering Passwords

There are multiple ways to administer passwords. You can rely on administrators to keep passwords secret and change the passwords regularly. You can set up files for storing passwords so that asadmin subcommands can access these files rather than having users type the commands. You can encrypt passwords by setting up aliases so that sensitive passwords are not visible in the domain.xml file.

The following topics are addressed here:

• To Change the Master Password

• Additional Considerations for the start-instance and start-cluster Subcommands

• Using start-instance and start-cluster With a Password File

• To Change an Administration Password

• To Set a Password From a File

• Administering Password Aliases

To Change the Master Password

The master password gives access to the keystore used with the domain. This password is not tied to a UNIX user. You should treat this overall shared password as sensitive data. GlassFish Server never uses it for authentication and never transmits it over the network.

You can choose to type the password manually when required, or to obscure the password in a password file. If there is no password file, you are prompted for the master password. If there is a password file, but you want to change access to require prompting, remove the file. The default master password is changeit.

When changing the master password, it has to be changed on all nodes as well as on the DAS. The master password on nodes is only stored once in the node, for all instances that are on that node.

Use the change-master-password subcommand in local mode to modify the master password.

When the master password is saved, it is saved in the master-password file.

Before You Begin

This subcommand will not work unless the domain is stopped.

1. Stop the domain whose password you are changing.

   See To Stop a Domain in Oracle GlassFish Server 3.1 Administration Guide.

2. Change the master password for the domain by using the change-master-password(1) subcommand.

   You are prompted for the old and new passwords. All dependent items are re-encrypted.

3. Start the domain.

   See To Start a Domain in Oracle GlassFish Server 3.1 Administration Guide.

Example 1-2 Changing the Master Password

The change-master-password subcommand is interactive in that you are prompted for the old master password as well as the new master password. This example changes the master password for domain44ps:

asadmin> change-master-password domain44ps

If you have already logged into the domain using the login login(1) subcommand, you are prompted for the new master password:

Please enter the new master password>
Please enter the new master password again>

If you are not logged into the domain, you are prompted for both the old and the new master passwords:

Please enter the master password>
Please enter the new master password>
Please enter the new master password again>

Information similar to the following is displayed:

Master password changed for domain44ps

See Also

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

Additional Considerations for the start-instance and start-cluster Subcommands

If you change the master password for DAS, the start-domain and start-local-instance subcommands allow you to provide it during domain or instance startup in one of three ways:

• Via the master-password file

• By entering it interactively

• Via the asadmin passwordfile

The start-instance and start-cluster subcommands are more problematic. If you create a domain with a master password other than the default, an associated remote instance or cluster must have access to the master password in order to start. However, for security reasons GlassFish Server never transmits the master password or the master password file over the network.

Consider the following scenario:

1. Change the master password on the DAS and save it with -–savemasterpassword.

2. Create an instance on another host using the subcommand create-instance. GlassFish Server copies the keystore and truststore from the DAS to the instance, but it does not copy the master password file.

3. Try to start the instance using the start-instance subcommand. An error results.

The start-instance command is looking for the file master-password in the node directory on the instance machine, and it is not there by default. Therefore, the subcommand fails.

You can use the change-master-password subcommand to make sure the correct password is used in this password file, as described in Using start-instance and start-cluster With a Password File.

Using start-instance and start-cluster With a Password File

Assume that you have changed the master password on the DAS and you want to make the same change for all instances.

The start-instance and start-cluster subcommands automatically use the master password file if it exists in the instance filesystem. You can use the change-master-password subcommand to make sure the password file exists and that the correct password is used.

1. From the DAS, create a domain and set the master password.

   asadmin> create-domain --savemasterpassword true domain-name

2. Start the domain.

   asadmin> start-domain domain-name

3. Create a node that is enabled for communication over secure shell (SSH).

   asadmin> create-node-ssh --nodehost host-name --installdir /some-dir node-name

4. Create an instance on the node.

   asadmin> create-instance --node node-name instance-name

5. Before you start the instance, on the instance machine run change-master-password with the ---savemasterpassword option to create a file called master-password in the agents directory to access the keystores. (The start-instance subcommand is looking for a file called master-password in the agents directory to access the stores.)

   asadmin> change-master-password --savemasterpassword true --nodedir /some-dir node-name

   You are prompted to enter the current and new master password:

   Enter the current master password>

   Enter the new master password>

   Enter the new master password again>

   Command change-master-password executed successfully.

   Remember that when you created the domain you specified a new master password. This master password was then used to encrypt the keystore and truststore for the DAS, and these stores were copied to the instance as a result of the create-instance subcommand.

   Therefore, enter the master password you set when you created the domain as both the current master password and again as the new master password. You enter it as the new master password because you do not want to change the master password for the instance and make it out of sync with the DAS.

6. Run start-instance from the DAS.

   asadmin> start-instance instance-name

   The master password file is associated with the node and not with an instance. After the master password file exists in the node directory on the instance machine, additional instances can be created, started and stopped from the DAS.

To Change an Administration Password

Use the change-admin-password subcommand in remote mode to change an administration password. The default administration password is admin. You are prompted for the old and new admin passwords, with confirmation. The passwords are not echoed to the display.

Encrypting the admin password is strongly encouraged.

Before You Begin

If you want to change the admin password before creating an alias for the password (encrypting), you can use the set subcommand with syntax similar to the following:

asadmin set --user admin server.jms-service.jms-host.default_JMS_host.admin-password=
new_pwd

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Change the admin password by using the change-admin-password(1) subcommand.
3. Enter the old and new admin passwords when prompted.
4. Restart GlassFish Server.

   See To Restart a Domain in Oracle GlassFish Server 3.1 Administration Guide.

Example 1-3 Changing the Admin Password

This example changes the admin password for user anonymous from adminadmin to newadmin:

asadmin> change-admin-password --username anonymous

You are prompted to enter the old and the new admin passwords:

Enter admin password>adminadmin
Enter new admin password>newadmin
Enter new admin password again>newadmin

Information similar to the following is displayed:

Command change-admin-password executed successfully.

See Also

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

To Set a Password From a File

Instead of typing the password at the command line, you can access the password for a command from a file such as passwords.txt. The --passwordfile option of the asadmin utility takes the name of the file that contains the passwords. The entry for a password in the file must have the AS_ADMIN_ prefix followed by the password name in uppercase letters.

The following other types of passwords can be specified:

AS_ADMIN_MASTERPASSWORD
AS_ADMIN_USERPASSWORD
AS_ADMIN_ALIASPASSWORD

1. Edit the password file.

   For example, to specify the password for the domain administration server (DAS), add an entry similar to the following to the password file, where adminadmin is the administrator password:

   AS_ADMIN_PASSWORD=adminadmin 

2. Save the password file.

   You can now specify the password file in an asadmin subcommand. In this example, passwords.txt is the file that contains the password:

   asadmin>delete-jdbc-resource --user admin --password passwords.txt jdbc/DerbyPool

Troubleshooting

If AS_ADMIN_PASSWORD has been exported to the global environment, specifying the --passwordfile option will produce a warning about using the --passwordfile option. To prevent this warning situation from happening, unset AS_ADMIN_PASSWORD.

Administering Password Aliases

A password alias is used to indirectly access a password so that the password itself does not appear in cleartext in the domain's domain.xml configuration file.

Storing passwords in cleartext format in system configuration files is common in many open source projects. In addition to GlassFish Server, Apache Tomcat, Maven, and Subversion, among others, store and pass passwords in cleartext format. However, storing and passing passwords in cleartext can be a security risk, and may violate some corporate security policies. In such cases, you can use password aliases.

The following topics are addressed here:

• To Create a Password Alias

• To List Password Aliases

• To Delete a Password Alias

• To Update a Password Alias

To Create a Password Alias

Use the create-password-alias subcommand in remote mode to create an alias for a password in the domain's keystore. The password corresponding to the alias name is stored in an encrypted form in the domain configuration file. The create-password-alias subcommand takes both a secure interactive form, in which users are prompted for all information, and a more script-friendly form, in which the password is propagated on the command line.

You can also use the set(1) subcommand to remove and replace the password in the configuration file. For example:

asadmin set --user admin server.jms-service.jms-host.default_JMS_host.
admin-password='${ALIAS=jms-password}'

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Go to the directory where the configuration file resides.

   By default, the configuration file is located in domain-dir/config.

3. Create the password alias by using the create-password-alias(1) subcommand.
4. Type the password for the alias when prompted.
5. Add the alias to a password file.

   For example, assume the use of a password file such as passwords.txt. Assume further that you want to add an alias for the AS_ADMIN_USERPASSWORD entry that is read by the create-file-user(1) subcommand. You would add the following line to the password file: AS_ADMIN_USERPASSWORD=${ALIAS=user-password-alias}, where user-password-alias is the new password alias.

6. To continue the example of the previous step, you would then run the create-file-user(1) subcommand.

   You could use this method to create several users (user1, user2, and so forth), all with the same password.

   asadmin> --passwordfile passwords.txt create-file-user user1

Example 1-4 Creating a Password Alias

This example creates the new jms-password alias for the admin user:

asadmin> create-password-alias --user admin jms-password

You are prompted to type the password for the alias:

Please enter the alias password>secret-password
Please enter the alias password again>secret-password
Command create-password-alias executed successfully.

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.

To List Password Aliases

Use the list-password-aliases subcommand in remote mode to list existing the password aliases.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List password aliases by using the list-password-aliases(1) subcommand.

Example 1-5 Listing Password Aliases

This example lists the existing password aliases:

asadmin> list-password aliases
jmspassword-alias
Command list-password-aliases executed successfully

See Also

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

To Delete a Password Alias

Use the delete-password-alias subcommand in remote mode to delete an existing password alias.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List all aliases by using the list-password-aliases(1) subcommand.
3. Delete a password alias by using the list-password-aliases(1) subcommand.

Example 1-6 Deleting a Password Alias

This example deletes the password alias jmspassword-alias:

asadmin> delete-password-alias jmspassword-alias
Command list-password-aliases executed successfully

See Also

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

To Update a Password Alias

Use the update-password-alias subcommand in remote mode to change the password for an existing password alias. The update-password-alias subcommand takes both a secure interactive form, in which the user is prompted for all information, and a more script-friendly form, in which the password is propagated on the command line.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Update an alias by using the update-password-alias(1) subcommand.
3. Type the password when prompted.

Example 1-7 Updating a Password Alias

This example updates the password for the jmspassword-alias alias:

asadmin> update-password-alias jsmpassword-alias

You are prompted to type the new password for the alias:

Please enter the alias password>new-secret-password
Please enter the alias password again>new-secret-password
Command update-password-alias executed successfully

See Also

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