ejbca_3_5_3(1).zip UPGRADE

www.pudn.com > ejbca_3_5_3(1).zip > UPGRADE

$Id: UPGRADE,v 1.41.2.1 2007/10/31 12:03:12 anatom Exp $

UPGRADE
=======

This document describes proceedures needed to upgrade from one
version of EJBCA to a new version.
Upgrades within a major version, from 3.4.1 to 3.4.2 for example, are
usually plug-in upgrades and can be made simply by deploying the new
software. See doc/RELEASE_NOTES for info about such upgrades.

If you use the patch file to upgrade use a command like:
- Have old version of ejbca unzipped to directory ejbca.
- Go to directory ejbca and apply patch with:
- patch --strip=0 -u < ../patch-341_342.txt
(change name of patch file depending on which version you are upgrading)

After this you must do:
- ant clean
- ant deploy

From EJBCA 3.5.x to EJBCA 3.5.x
-------------------------------
See release notes for details between certain versions.
Normally upgrades within a major release are plug-in upgrades.

Simply copy conf/*.properties from the earlier installation.
Merge changes (if there are any) from *.properties.sample into your *.properties.
Copy the directory 'p12' from the earlier installation and do 'ant deploy' with the new version.

Also note the possibility to use 'ejbca-custom' directory in EJBCA 3.5.x, see User's Guide.

From EJBCA 3.4.x to EJBCA 3.5.x
-------------------------------
See release notes for details between certain versions.

EJBCA 3.5 is a plug-in upgrade from EJBCA 3.4.x. A few steps are still needed for upgrade though.

Simply copy conf/*.properties from the earlier installation.
Merge changes (if there are any) from *.properties.sample into your *.properties.
Copy the directory 'p12' from the earlier installation and do 'ant deploy' with the new version.

The new root-less install on linux systems makes it much easier to have control of you Java truststore
(which CAs that are allowed for administrator certificates) both on linux and windows.
You must make these steps during upgrade on both linux and windows:
- copy $JAVA_HOME/jre/lib/security/cacerts $EJBCA_HOME/p12/truststore.jks
- ant clean; ant deploy

In EJBCA 3.5 when you run the command 'ant javatruststore' or 'ant -Dca.name=MyCAName javatruststore' it is now
the file $EJBCA_HOME/p12/truststore.jks that will be updated and copied to $JBOSS_HOME/server/default/conf/keystore.

You should also read about the new external merge directory 'ejbca-custom', where you can collect all your
own files. See 'Handling changes in a separate tree' in the User's guide.

There are some parameter name changes in ejbca.properties and web.properties.
These parameters are only used when freshly installing EJBCA though. If you plan to do this using
old configuration files, you should merge changes from ejbca.properties.sample and web.properties.sample.
No worry if you forget though, since you will be prompted for the values instead.

You should be ablo to upgrade from EJBCA 3.1.x directly to 3.5.x, by following the same instructions for database
upgrade as for EJBCA 3.4.

From EJBCA 3.4.x to EJBCA 3.4.x
-------------------------------
See release notes for details between certain versions.
Normally upgrades within a major release are plug-in upgrades.

Simply copy conf/*.properties from the earlier installation.
Merge changes (if there are any) from *.properties.sample into your *.properties.
Copy the directory 'p12' from the earlier installation and do 'ant deploy' with the new version.

From EJBCA 3.3.x to EJBCA 3.4.x
-------------------------------
Backup your database first! If the upgrade fails, you can always go back to the earlier version.

Upgrade from EJBCA 3.3.x to EJBCA 3.4.x requires one small database change.

If you are upgrading a cluster, you should run the upgrade process with only one node running,
and then simply update the software on the other nodes.

1. Copy ejbca.properties from the earlier installation into the conf directory of the new release.
Or better yet, split up your ejbca.properties file to match the new improved conf structure.

2. Merge changes from *.properties.sample into your *.properties files.

3. Copy the directory 'p12' from the earlier installation.

4. Shut down JBoss and do 'ant deploy' with the new version.

5. Start up JBoss. You will see some errors during startup due to that the database is not upgraded yet.

6. Issue the command 'ant upgrade' from EJBCA_HOME. This will make the neccesary database updates.
If you are upgrading from EJBCA 3.2 or 3.3, answer 'no' to the second question.
Note: On weblogic you have to upgrade the database manually, see below.

7. Go into the admin-GUI and verify you settings, specially verify the DN encoding in 'Edit Certificate Authorities'
as noted below.

8. Restart JBoss again to flush all caches.

If you don't want to do step 6 above (doing step 6 is the recommended way though) and instead want to do the upgrade
of the database manually, you can simply issue the following sql command:
MySQL:
alter table CAData add updateTime bigint NOT NULL DEFAULT 0;
PostgreSQL:
alter table CAData add updateTime INT8;
update cadata set updateTime = 0;
alter table cadata alter column updateTime set not null;
alter table cadata alter column updateTime set default 0;
Oracle:
alter table CAData add updateTime NUMBER(19) default 0;

Note: Since the default DN encoding changed to UTF8, there is an option in the CA configuration (Edit Certificate authorities)
called 'Use PrintableString encoding in DN'. Checking this checkbox causes the old behaviour to be used, using PrintableString as the default
encoding. The upgrade process tries to guess how this value should be set (upgrading an old CA we usually want to keep the old behaviour).
After the upgrade process, check your CA configuration to verify that the option is set to your liking.

Note: If you intend to use the XKMS service or the CMS service (log signing), then you should go into the Admin-GUI
after upgrading and press the button "Republish CA Certificates" for all CAs.
Otherwise you will not be able to revoke the certificates issued to these services, or view the certificates in the GUI.

You should be ablo to upgrade from EJBCA 3.1.x directly to 3.4.x, by following the same instructions
as above, but answering yes to the second question (this upgrade is not thoroughly tested though).

From EJBCA 3.3.x to EJBCA 3.3.x
-------------------------------
See release notes for details between certain versions.
Normally upgrades within a major release are plug-in upgrades.

Simply keep/copy ejbca.properties from the earlier installation.
Merge changes (if there are any) from ejbca.properties.sample into your ejbca.properties.
Copy the directory 'p12' from the earlier installation and 'ant deploy'
(or deploywithjbossservice) this new one.

From EJBCA 3.2.x to EJBCA 3.3.x
-------------------------------
Upgrade from EJBCA 3.2.x to EJBCA 3.3.x is a plug-in upgrade, because there are
no database changes, or the database changes are only new tables and not changed ones.

You should still follow this advice:
Backup your database first! If the upgrade fails, you can always go back to the earlier version.

Simply keep/copy ejbca.properties from the earlier installation.
Merge changes from ejbca.properties.sample into your ejbca.properties.
Copy the directory 'p12' from the earlier installation and 'ant deploy'
(or deploywithjbossservice) this new one.

You should be ablo to upgrade from EJBCA 3.1.x directly to 3.3.x, by following the same instructions
as when upgrading from 3.1.x to 3.2.x (untested though).

If you are using Eracom HSM, please notice that property names have changed for determining which key is used.
After upgrading EJBCA, you must go into CA configuration and update your HSM properties.
The property names are now the same for all different HSMs.

From EJBCA 3.2.x to EJBCA 3.2.x
-------------------------------
See release notes for details between certain versions.
Normally upgrades within a major release are plug-in upgrades.

Simply keep/copy ejbca.properties from the earlier installation.
Merge changes (if there are any) from ejbca.properties.sample into your ejbca.properties.
Copy the directory 'p12' from the earlier installation and 'ant deploy'
(or deploywithjbossservice) this new one.

From EJBCA 3.1.x to EJBCA 3.2
-----------------------------
Backup your database first! If the upgrade fails, you can always go back to the earlier version.
(If you are using weblogic, first copy weblogic.jar to EJBCA_HOME/lib)

The upgrade can consume a lot of memory if you have many users and certificates. You should make sure that your
memory parameters (-Xms and -Xmx) are sufficient. For 200.000 users it should be enough with '-Xms128m -Xmx512m',
but in general you should consider using -Xmx1024m to be future proof.
For JBoss these parameters are normally set in JBOSS_HOME/bin/run.conf.

1. Copy ejbca.properties from the earlier installation.
2. Merge changes from ejbca.properties.sample into your ejbca.properties,
specially datasource.jndi-name and datasource.jndi-name-prefix if you changed them from the default values.
3. Copy the directory 'p12' from the earlier installation.
4. Shut down JBoss and do 'ant deploy' (or deploywithjbossservice) with the new version.
5. Start up JBoss.
6. Issue the command 'ant upgrade' from EJBCA_HOME. This will make the neccesary database updates.

If you don't want to do step 6 above (doing step 6 is the recommended way though) and instead want a
quick-and-dirty upgrade of the database, do this instead of step 6:
- if you have NOT done any special Log Configurations and only used the default,
- and you DO NOT mind deleting the EJBCA log entries from the database, i.e. you are not interested in the log history,
- and you DO NOT mind deleting your complete Certificate request history.

If the above three conditions are met, issue the following three commands to your database:
-----
delete from LogConfigurationData;
delete from LogEntryData;
delete from CertReqHistoryData;
alter table UserData modify extendedInformationData LONGTEXT; (if NOT using MySQL, see src/upgrade/31_32 for commands for your specific database)
-----

From EJBCA 3.1.x to EJBCA 3.1.x
-------------------------------
See release notes for details between certain versions.
Normally upgrades within a major release are plug-in upgrades.

Otherwise simply keep/copy ejbca.properties from the earlier installation.
Merge changes from ejbca.properties.sample into your ejbca.properties,
specially datasource.jndi-name and datasource.jndi-name-prefix if you changed them from the default values.
Copy the directory 'p12' from the earlier installation and 'ant deploy'
(or deploywithjbossservice) this new one.

From EJBCA 3.0.x to EJBCA 3.1
-----------------------------
Backup your database first! If the upgrade fails, you can always go back to the earlier version.

The upgrade process typically consists of:
1. Stop JBoss.
2. Remove JBOSS_HOME/server/default/deploy/ejbca-ca.ear, the ear file changed name.
If you have configured a new datasource for EJBCA, remove this xml file as well.
3. Copy ejbca.properties.sample to ejbca.properties and configure.
You don't need to configure most options, since the installation is already done with EJBCA 3.0.x,
no new CAs will be created.
Pay special attention to the upgrade comments for 'CA configuration' and 'Web GUI configuration',
it says what options you must configure.
'Database configuration' is important if you changed from the default JBoss database.
4. run 'ant deploy'.
5. Copy JBOSS_HOME/bin/tomcat.jks to JBOSS_HOME/server/default/conf/keystore/keystore.jks (note - name change).
5. Start JBoss.

Optional database migration
---------------------------
If you are using MySQL and:
1. Issues hard tokens using the hard token functionality of EJBCA AND uses images larger than 64KB
in your card layouts.
or
2. Have CRLs that are larger than 64KB in size, or will become this large.

Then you should apply the following SQL commands on your MySQL database:

ALTER TABLE crldata MODIFY base64Crl longtext NULL DEFAULT NULL;
ALTER TABLE hardtokenprofiledata MODIFY data longtext NULL DEFAULT NULL;