<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!ENTITY metainfo SYSTEM "metainfo.sgm">
<!ENTITY ERROR-CODES "ERROR CODES">
<!ENTITY Date "22 Dec 2004">
<!ENTITY SectDesc "User Commands">
<!ENTITY Software "J2EE SDK 1.4">
<!ENTITY arch "generic">
<!ENTITY copyright "Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved">
<!ENTITY exam-tt "EXAMPLES">
<!ENTITY options-common SYSTEM "options-common.sgm">
<!ENTITY synopsis-common SYSTEM "synopsis-common.sgm">
<!ENTITY sjsas "Sun Java System Application Server">
<!ENTITY attr-tt "ATTRIBUTES">
<!ENTITY opts-tt "OPTIONS">
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
<!ENTITY Dash "&ndash;">
]>
<?Pub UDT _bookmark _target>
<?Pub EntList brvbar bull cross dash diam diams frac12 frac13 frac14 hellip
 laquo lArr loz mdash nabla ndash para pound rArr raquo sect yen ne>
<?Pub Inc>
<refentry id="asupgrade-1m">
<refmeta><refentrytitle>asupgrade</refentrytitle><manvolnum>1</manvolnum>&metainfo;
</refmeta>
<refnamediv><indexterm><primary sortas="template">template &mdash; template
for documenting manpages for the Sun Java System Application Server</primary>
</indexterm><indexterm><primary sortas="template for documenting manpages for the Sun Java System Application Server">
template for documenting manpages for the Sun Java System Application Server &mdash;
template</primary></indexterm><refname>asupgrade </refname><refpurpose>migrates
the configuration of a previously installed Sun Java System Application Server
</refpurpose></refnamediv>
<refsynopsisdiv><title>&synp-tt;</title>
<cmdsynopsis><command>asupgrade</command><arg>&Dash;&Dash;console </arg><arg>&Dash;&Dash;version 
</arg><arg>&Dash;&Dash;help </arg><arg>&Dash;&Dash;source <replaceable>applicationserver_7.x/8.x_installation
</replaceable></arg><arg>&Dash;&Dash;target <replaceable>applicationserver_9_installation
</replaceable></arg><arg>&Dash;&Dash;passwordfile <replaceable>path_to_password_file
</replaceable>&Dash;&Dash;nsspwdfile <replaceable> NSS_password_filepath</replaceable></arg>
<arg>&Dash;&Dash;targetnsspwdfile <replaceable> target_NSS_password_filepath
</replaceable></arg><arg>&Dash;&Dash;jkspwdfile <replaceable> JKS_password_filepath
</replaceable></arg><arg>&Dash;&Dash;capwdfile <replaceable> CA_password_filepath
</replaceable></arg><arg>&Dash;&Dash;clinstancefile <replaceable> file1</replaceable><arg><replaceable>
, file2, file3, ... filen</replaceable></arg></arg>
</cmdsynopsis></refsynopsisdiv>
<refsect1><title>&desc-tt;</title>
<para>Use the <command>asupgrade</command> utility to migrate the server configuration
and its persisted state, J2EE services, and deployed J2EE applications. The
configuration of an installed Sun <trademark>Java</trademark><?Pub Caret1>
System Application Server 7.x/8.x installation is migrated to the Sun Java
System Application Server 9 installation. If the domain contains information
about a deployed application and the installed application components do not
agree with the configuration information, the configuration is migrated as
is without any attempt to reconfigure the incorrect configurations.</para>
<para><command>asupgrade</command> migrates the configuration and deployed
applications of a previous version of the Application Server; however, the
runtime binaries of the server are not updated. Database migrations or conversions
are also beyond the scope of the <command>asupgrade</command> command.</para>
<para>Only those instances that do not use Sun Java System Web Server-specific
features will be upgraded seamlessly. Configuration files related to HTTP
path, CGI bin, SHTML, and NSAPI plugins will not be upgraded.</para>
<para>The upgrade process can also be initiated automatically at installation
time using the Upgrade checkbox in the Application Server installer. After
completion of the upgrade, use the uninstaller to remove the previous version
of the application server.</para>
<para>Application archives (EAR files) and component archives (JAR, WAR, and
RAR files) that are deployed in the Application Server 7.x/8.x environment
do not require any modification to run on Application Server 9. Applications
and components that are deployed in the source server are deployed on the
target server during the upgrade. Applications that do not deploy successfully
on the target server must be migrated using the Migration Tool or <command>
asmigrate</command> command, then redeployed manually.</para>
<para>Specify the source and target directories for the upgrade. </para>
<para>If the upgrade includes certificates, provide the passwords for the
source PKCS12 file and the target JKS keyfile for each domain that contains
certificates to be migrated. Since Application Server 7 uses a different certificate
store format (NSS) than Application Server 9 PE (JSSE), the migration keys
and certificates are converted to the new format. Only one certificate database
password per domain is supported. If multiple certificate database passwords
are used in a single domain, all of the passwords must be made the same before
starting the upgrade. The passwords can be reset after the upgrade has been
completed. </para>
<para>If the upgrade includes clusters, specify one or more cluster files.
Upon successful upgrade, an upgrade report is generated listing successfully
migrated items along with a list of the items that could not be migrated.
</para>
<para>If you issue the <command>asupgrade</command> command with no options,
the Upgrade Tool GUI will be displayed. If the <command>asupgrade</command>
command is used in command-line mode and all of the required information is
not supplied, an interviewer will request information for any required options
that were omitted.</para>
</refsect1>
<refsect1><title>&opts-tt;</title>
<variablelist termlength="medium">
<varlistentry><term><option role="nodash">&Dash;c</option> <option role="nodash">&Dash;&Dash;console
</option></term><listitem><para>Launches the upgrade command line utility.
</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;V</option> <option role="nodash">&Dash;&Dash;version
</option></term><listitem><para>The version of the Upgrade Tool.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;h</option> <option role="nodash">&Dash;&Dash;help
</option></term><listitem><para>Displays the arguments for launching the UpgradeTool.
</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;s</option> <option role="nodash">&Dash;&Dash;source
</option></term><listitem><para>The installation or domains root directory
for Sun Java System Application Server 7.x/8.x installation that will be upgraded.
</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;t</option> <option role="nodash">&Dash;&Dash;target
</option></term><listitem><para>The domains root directory for Sun Java System
Application Server 9.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;a</option> <option role="nodash">&Dash;&Dash;adminuser
</option></term><listitem><para>The username of the administrator.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;f</option> <option role="nodash">&Dash;&Dash;passwordfile
</option></term><listitem><para>The path to the file that contains the adminpassword
and masterpassword. Content of this file should be in the following format: <?Pub _newline><?Pub _newline><property>
AS_ADMIN_ADMINPASSWORD</property>=<emphasis>adminpassword</emphasis><?Pub _newline> <property>
AS_ADMIN_MASTERPASSWORD</property>=<emphasis>masterpassword</emphasis></para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;n</option> <option role="nodash">&Dash;&Dash;nsspwdfile
</option></term><listitem><para>The path to the NSS password file.</para>
<para>The format for the NSS password file is:<?Pub _newline><literal>domain_name1
password</literal><?Pub _newline><literal>domain_name2 password</literal></para>
<para>If the source server is Application Server 7.x, the format of the NSS
password file is:<?Pub _newline><literal>domain_name1 instance_name1 password
</literal><?Pub _newline><literal>domain_name2 instance_name2 password</literal></para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;e</option> <option role="nodash">&Dash;&Dash;targetnsspwdfile
</option></term><listitem><para>The path to the target NSS password file.
</para>
<para>The format for the target NSS password file is:<?Pub _newline><literal>
domain_name1 password</literal><?Pub _newline><literal>domain_name2 password
</literal></para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;j</option> <option role="nodash">&Dash;&Dash;jkspwdfile
</option></term><listitem><para>The path to the JKS password file.</para>
<para>The format for the JKS password file is:<?Pub _newline><literal>domain_name1
password</literal><?Pub _newline><literal>domain_name2 password</literal></para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;p</option> <option role="nodash">&Dash;&Dash;capwdfile
</option></term><listitem><para>The path to the CA certificate password file.
</para>
<para>The format for the CA certificate password file is:<?Pub _newline><literal>
domain_name1 password</literal><?Pub _newline><literal>domain_name2 password
</literal></para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;i</option> <option role="nodash">&Dash;&Dash;clinstancefile
</option></term><listitem><para>The path to the cluster file. The default
filename is <filename>$AS_INSTALL/conf/clinstance.conf</filename> .</para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1><title>&exam-tt;</title>
<example>
<title>Upgrading an Application Server 7 Installation to Application Server
9 with Prompts for Certificate Migration</title>
<para>This example shows how to upgrade a Sun Java System Application Server
7 installation to Sun Java System Application Server 9. You will be prompted
to migrate certificates. If you reply no, then no certificates will be migrated.
</para>
<screen>example% <userinput>asupgrade --adminuser admin <?Pub _newline>--passwordfile password.txt 
--source /home/sunas7 --target /home/sjsas9</userinput></screen>
</example>
<example>
<title>Upgrading an Application Server 7.1 EE Installation with Clusters and
NSS Certificates to Application Server 9 EE</title>
<para>This example shows how to upgrade a Sun Java System Application Server
7.1 EE installation with a cluster to Sun Java System Application Server 9
EE. NSS certificates will be migrated, as will the <filename>clinstance.conf
</filename> cluster file.</para>
<screen>example% <userinput>asupgrade --adminuser admin 
--passwordfile password.txt 
--source /home/sjsas7.1 --target /home/sjsas9 
--nsspwdfile /home/sjsas7.1/nsspassword.txt 
--targetnsspwdfile /home/sjsas9/nsspassword.txt
--clinstancefile /home/sjsas7.1/config/clinstance.conf</userinput></screen>
<para>After the upgrade, node agents for all remote instances must be created
and started on their respective host systems.</para>
</example>
<example>
<title>Upgrading an Application Server 7.0 PE Installation with NSS Certificates
to Application Server 9 PE</title>
<para>This example shows how to upgrade a Sun Java System Application Server
7.0 PE installation to Sun Java System Application Server 9 PE. The NSS certificates
from the 7.0 PE source server will be converted to JKS and CA certificates
in the 9 PE target server.</para>
<screen>example% <userinput>asupgrade --adminuser admin 
--passwordfile password.txt 
--source /home/sjsas7.0 --target /home/sjsas9 
--nsspwdfile /home/sjsas7.0/nsspassword.txt 
--jkspwdfile /home/sjsas7.0/jkspassword.txt 
--capwdfile /home/sjsas7.0/capassword.txt </userinput></screen>
</example>
<example>
<title>Upgrading an Application Server 8.0 PE Installation with JKS and CA
Certificates to Application Server 9 PE</title>
<para>This example shows how to upgrade a Sun Java System Application Server
8.0 PE installation to Sun Java System Application Server 9 PE. JKS and CA
certificates will be migrated.</para>
<screen>example% <userinput>asupgrade --adminuser admin 
--passwordfile password.txt 
--source /home/sjsas8.0 --target /home/sjsas9 
--jkspwdfile /home/sjsas8.0/jkspassword.txt 
--capwdfile /home/sjsas9/capassword.txt</userinput></screen>
</example>
</refsect1>
<refsect1><title>&exit-tt;</title>
<variablelist termlength="medium">
<varlistentry><term>0</term><listitem><para>command executed successfully
</para>
</listitem></varlistentry>
<varlistentry><term>1</term><listitem><para>error in executing the command
</para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1><title>&also-tt;</title>
<para><link linkend="asmigrate-1m"><citerefentry><refentrytitle>asmigrate
</refentrytitle><manvolnum>1M</manvolnum></citerefentry></link> </para>
</refsect1>
</refentry>
<?Pub *0000013157>
