Upgrading Alfresco

This is a short note on how I upgraded Alfresco. The basic idea was to just replace WAR files while keeping configuration files with local modifications intact. To be able to do that, I'll unpack WAR archive, integrate changes I made to running instance of Alfresco, create new WAR archives and place them in tomcat webapps folder so that he unpacks and deploys them.

Preparation

So, I downloaded Alfresco 4.2.c. More specifically, I downloaded file alfresco-community-4.2.c.zip. The version I had was 4.0.d.

To find out what configuration files are changed in the running instance I unpacked alfresco.war archive (that file is in the downloaded archive) into a separate directory using unzip command. I suggest that you create directory alfresco, enter that directory and then run unzip command. There, I run the following script:

#!/bin/bash
OLDPATH=/var/lib/tomcat6/webapps/alfresco/
for i in `find . -path ./WEB-INF/classes/alfresco/messages -prune -o -name \*properties -print`
do
        # If file doesn't exist we don't need to check it, go to next one
        [ -f $OLDPATH/$i ] || continue
        # If the old and new files are the same, then skip it also
        cmp -s $OLDPATH/$i $i && continue
        # diff -uN $OLDPATH/$i $i | less
        echo $i
done

The script showed me what files have changed:

./WEB-INF/classes/test/alfresco/test-hibernate-cfg.properties./WEB-INF/classes/alfresco/model/dataTypeAnalyzers_en.properties./WEB-INF/classes/alfresco/workflow/invitation-nominated-workflow-messages_ja.properties./WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/slingshot/wiki/move.post_it.properties./WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/slingshot/wiki/move.post_de.properties./WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/slingshot/wiki/move.post_nl.properties./WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/slingshot/wiki/move.post_es.properties./WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/slingshot/wiki/move.post_fr.properties./WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/slingshot/wiki/move.post_ja.properties./WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/slingshot/wiki/move.post.properties./WEB-INF/classes/alfresco/domain/hibernate-cfg.properties./WEB-INF/classes/alfresco/repository.properties./WEB-INF/classes/alfresco/subsystems/email/OutboundSMTP/outboundSMTP.properties./WEB-INF/classes/alfresco/subsystems/thirdparty/default/swf-transform.properties./WEB-INF/classes/alfresco/subsystems/thirdparty/default/imagemagick-transform.properties./WEB-INF/classes/alfresco/subsystems/fileServers/default/file-servers.properties./WEB-INF/classes/alfresco/subsystems/Synchronization/default/default-synchronization.properties./WEB-INF/classes/alfresco/subsystems/Search/solr/solr-search.properties./WEB-INF/classes/alfresco/subsystems/Search/solr/solr-backup.properties./WEB-INF/classes/alfresco/subsystems/Authentication/ldap-ad/ldap-ad-authentication.properties./WEB-INF/classes/alfresco/subsystems/Authentication/ldap/ldap-authentication.properties./WEB-INF/classes/alfresco/subsystems/Authentication/kerberos/kerberos-authentication.properties./WEB-INF/classes/alfresco/subsystems/Authentication/alfrescoNtlm/alfresco-authentication.properties./WEB-INF/classes/alfresco/subsystems/Authentication/passthru/passthru-authentication-context.properties./WEB-INF/classes/alfresco/subsystems/OOoDirect/default/openoffice-transform.properties./WEB-INF/classes/alfresco/version.properties./WEB-INF/classes/log4j.properties

Of those, localization files are not important (the ones ending in _[a-z][a-z].properties). If you uncomment a line containing less then the script will compare each file and show you difference in less. Based on that, I factored out the following configuration files that were changed:

./WEB-INF/classes/alfresco/repository.properties
./WEB-INF/classes/alfresco/subsystems/Authentication/ldap/ldap-authentication.properties
./WEB-INF/classes/alfresco/subsystems/Authentication/kerberos/kerberos-authentication.properties
./WEB-INF/classes/log4j.properties

I also found that I didn't change mail configuration data in the file:

./WEB-INF/classes/alfresco/subsystems/email/OutboundSMTP/outboundSMTP.properties

The next step was to find what changes are due to local configuration, and which ones are due to the changes in upstream. Namely, I'll take old configuration files but the changes in the new version have to be propagated. It turned out that repository.properties doesn't have any changes, while the other three have. So, I started to change files in the new version of Alfresco, that I unpacked. Finally, when all the changes are done, create new archive:

cd ..
mv alfresco.war alfresco.war.OLD
cd alfresco
zip -9rv ../alfresco .
cd ..
mv alfresco.zip alfresco.war

The first two commands rename old archive, next two create a new archive, and the final command changes name to have extension WAR. I assumed here that you unpacked original WAR archive into directory called alfresco.

All this has to be done with share.war archive too. In my case, the script showed that only log4j.properties has been changed so I incorporated changes and created a modified share.war archive.

Update

Finally, I stopped tomcat, and alfresco using:

service tomcat6 stop

created a copy of existing alfresco and share directories in tomcat's webapp directory. I also renamed old alfresco.war and share.war, and moved the ones I prepared in their place. Take care about permissions, tomcat has to be owner of everything! Then, I started tomcat with:

service tomcat6 start

and also started to pray that it works. Well, almost, I watched logs (/var/log/tomcat6/catalina.out) because I doubt that praying would help. ;)

Everything was OK, i.e. errors that I received (openoffice, pdf2swf) were expected because I didn't inistalled them. But, two errors were not expected:

java.io.FileNotFoundException: alfresco.log (Permission denied)

well, that one was cause by share.war not being able to reopen log file already being used by alfresco.war. So, I changed in appropriate log4j.properties that it uses its own separate log file. Except that it turned that I forgot to change log4j.properties. Anyway, I gave separate log to share.war just to be on a safe side and to finish this finally. The second error was:

java.net.BindException: Permission denied

That one was caused by FTP server not being able to bind to a low numbered port. This is OK, because I'm not running tomcat as a root. So, I'm safe to ignore it.

Integrating LibreOffice 4 and Alfresco using CMIS

Alfresco is an excellent CMS solution, that unfortunately doesn't have good integration with LibreOffice. That is, it didn't have until LibreOffice 4 (LO4) was released. You could use WebDav to mount Alfresco shares, but there are some quirks related to versioning. First, after each save version is automatically increased by Alfresco, and second, there is no clear way to do check in and provide log of changes. Also, LibreOffice's autosave mechanism can make some problems. But, as I said, LO4 added CMIS protocol. CMIS is actually more than a simply protocol, but in essence it is a standard way of accessing content management systems so any CMS that supports CMIS will allow LibreOffice to be well integrated. CMIS is in Alfresco supported without any additional customizations, so if you followed my post about installing Alfresco, you are ready to try LibreOffice and CMIS.

Now, I was trying all this on Fedora 18 as a client workstation, so if you also have Fedora 18 you'll have to install manually LO4. So, if you didn't already install it, I wrote a post about that so take a look at it and install LO4.

So, to use CMIS first you'll have to enable LibreOffice's native Load/Save dialog boxes. This is done via Options... dialog (found in Toos menu option). Then, select option General in the left pane and you'll see in the main pane check box labeled Use LibreOffice dialogs under Open/Save dialogs section. Mark that check box and close the dialog. Finally, there is no need to restart LibreOffice:

Now, you need to add share from Alfresco where you have your documents stored. To do that, go to the Open dialog (in File menu), and now you'll see a button with three dots in the upper right corner. Click on it and new dialog appears:

Under the Type drop down box select CMIS, and then, under Server Details heading choose option Alfresco 4 as a Server Type. The dialog will have the following form:

Then Binding URL that has the following form:

http://<host>/alfresco/cmisws/RepositoryService?wsdl

has to be changed by filling in the host and port. When you fill URL, click on circular arrow beneath URL on the right hand side of Repository option. This will query repository for available URLs. You have also to type in name for this repository, and that's basically it, click OK to close this dialog. You'll be asked several times for username and password, so, provide it every time. This has to be username/password combination of a user that will access documents, not an administrator's password. Also, during this process, if you clicked check box that LO should remember password, a dialog will appear that will ask you for a master password that will protect your saved password(s).

Now, each time you go to Open dialog to open a new file, you'll have on the left pane this repository under the whatever name you've typed in Name text box.

There were several gotchas during this process. First, don't expect some useful/meaningful error messages. Basically, when you press that circular arrow, and something isn't right, you won't receive any message at all. So, here are some things that might catch you.

First of, while setting up the LO4 I suggest that you start it from the command line. The reason is that you'll see error messages on the console. Like the following ones I got:

http://your.server.name:8443/alfresco/cmisws/RepositoryService?wsdl:1: parser error : Start tag expected, '<' not found

that one was caused because I tried to use http protocol on https port (8443)! :D

Secondly, try first with http, and when you set that up, then you should try to switch to https. The problem is that LibreOffice has to have installed CA that issued certificate for Alfresco. If it doesn't have, then it will silently disconnect, and, as I said, it won't tell you what happened.

Third, if the hostname is incorrect, you also won't receive any error message. So, I suggest that you c/p the URL and try to retrieve wsdl using wget or curl:

wget --no-check-certificate 'https://your.server.name:8443/alfresco/cmisws/RepositoryService?wsdl'

For the end of this setup part, I'll mention that CMIS was introduced in LibreOffice 3.6 but it is marked as an experimental feature and those have to be explicitly enabled via Options dialog. Also, the dialog is different in LibreOffice 4 than in LibreOffice 3.6. Take a look at this blog post, but after several unsuccessful tries I decided to do it with LO4 because that was what I needed.

Experiences

Functionality seems to be OK but access to Alfresco repository is slow. This has a big impact on autosave, i.e. when you type everything suddenly freezes. Also, now and then, LO4 freezes very shortly but noticeably, when editing file from Alfresco.

Installing certificate for Alfresco...

This post is continuation of the post about installing Alfresco using native Tomcat6 installation (on CentOS6). If you followed steps given in that post, you have running Alfresco installation but Tomcat uses self-signed certificate.

To install your own certificate first obtain it (you can use your own, self managed, CA or you can buy commercial one), then install it on your Tomcat instance. You'll find a lot of information about this in SSL Howto on Tomcat's Web pages, but that page assumes that everything you do, you are doing using keytool.

Here is a quick Howto with an assumption that you have files newcert.pem (containing certificate), newkey.pem (containing private key) and cacert.pem (your CA certificate). By default, tomcat's keystore is in its home (/usr/share/tomcat6) and it is named .keystore. Keystore file is password protected and default password for it is changeit. Note that the period isn't part of password! I suggest that you copy this file to root's home under the name keystore (note no leading dot!) or whatever else you wish so that you can restore old copy in case something goes wrong with the following steps.

The installation is two step process. First, you create keystore containing you certificate, private key and CA's certificate. In second step, you import that information to Tomcat's keystore.

First step is to pack certificate for Alfresco, its private key and CA's certificate into PKCS12 store using openssl tool as follows:

$ openssl pkcs12 -export \
        -in newcert.pem -inkey newkey.pem \
        -out mycert.p12 -name tomcat \
        -CAfile cacert.pem -caname root -chain
Enter Export Password:
Verifying - Enter Export Password:

This command assumes that all necessary files (newcert.pem, newkey.pem and cacert.pem) are in you current directory. Output of the command is also stored into current directory. Note that you are asked for password that will protect all the data. Enter something or later you'll see the following warning:

*****************  WARNING WARNING WARNING  *****************
* The integrity of the information stored in the srckeystore*
* has NOT been verified!  In order to verify its integrity, *
* you must provide the srckeystore password.                *
*****************  WARNING WARNING WARNING  *****************

And then you'll receive the following error:

keytool error: java.security.UnrecoverableKeyException: Get Key failed: / by zero

Second step is to import this pkcs12 file to tomcat's keystore using keytool as follows:

$ keytool -importkeystore -srckeystore mycert.p12 \
        -srcstoretype pkcs12 -destkeystore /usr/share/tomcat6/.keystore
Enter destination keystore password:
Enter source keystore password:
Existing entry alias tomcat exists, overwrite? [no]:  yes
Entry for alias tomcat successfully imported.
Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

Again, input file is in the current directory and you are importing directly into tomcat's keystore. Note that the existing certificate with the alias tomcat will be removed and you are asked to confirm that! The default alias Tomcat searches when it start is called tomcat.

Third step is to change private key's password that has to be the same as for the keystore. Do that using the following command:

keytool -keypasswd -alias tomcat -new <keypassword> -keystore /usr/share/tomcat6/.keystore

You'll be asked for the keystore's password and the password for the key will be set to keypassword.

And that's it. Restart tomcat and check if it is using new certificate.

Integrating FreeIPA and Alfresco...

After describing how to install CentOS, DNS and reverse DNS, FreeIPA and Alfresco, in this post I'm going to describe how to integrate Alfresco with FreeIPA. I want to achieve the following goals with the integration:

• Users and groups are kept within FreeIPA and authentication is done by FreeIPA.
• Alfresco Web interface honors Kerberos tickets. Upon opening Web interface users are immediately presented with their pages withoug necessity for authentication (if, of course, they have valid Kerberos tickets).
• Authentication when mounting DAV share is also done via Kerberos tickets.

In short, I want to achieve SSO (Single Sign-On) as much as possible. Users sign in when they start to use their workstations once, that's the only time they have to enter password.

Installing Alfresco Community Edition on minimal CentOS...

In this post I'm going to describe how to install Alfresco Community Edition 4.0d starting with a minimal CentOS 6 installation. This will be a two part post after which I'm going to describe how to integrate Alfresco with FreeIPA for authentication and authorization purposes. The goal of the installation is to use as much as possible software available in CentOS. The reason for doing so is that update process is easier, i.e. you only have to do yum update instead of manually downloading and installing updated software.

Environment and Configuration Parameters

I assume that you have CentOS installation ready. If not, then install it, and if you need some info on how to do it, look at this post. Furthermore, I assume that Alfresco should reside within Intranet, i.e. local network. The reason is that there is no need for Alfresco to be accessible from the Internet and thus it doesn't have to be in DMZ. I'll assign IP address 172.16.1.3 to this host. The FQDN of the host will be alfresco.example-domain.local. Now, if you have working DNS you should put this name into DNS, but it's not necessary, i.e. you can put it into /etc/hosts file of any host that will access Alfresco (including Alfresco itself) and that will do for now.

Alfresco needs a relational database. I'm going to use MySQL database. Furhtermore, I'll assume that this database is on the same host as Alfresco. This will allow me to restrict access to database. Unfortunately, standard JDBC driver for MySQL doesn't support access to database via Unix socket, so database has to be accessible via network stack. I'm going to restrict it to loopback interface.

Note that I started with the following state of disk usage:

# df -h
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda1             7,0G  944M  5,7G  15% /

Prerequisite software installation

As for the prerequsite software you have to install the following packages (all of them shipped with CentOS):

• java-1.6.0-openjdk - unless you explicitly specify which java you want to be installed, gcc's version will be used and that one won't work with Alfresco.
• tomcat6 - servlet container that will run Alfresco. It is mandatory to install this package. This, along with dependencies, will be 129M to download and will take about 382M disk space.
• mysql-server - this is a package that holds server part of MySQL database.
• mysql-connector-java - JDBC connector that will allow Alfresco to access MySQL database.
• unzip - so that you can unpack Alfresco archive (which is distributed as a zip file)

So, install it using yum. This will download 168M which will expand into 503M. Afterwards, this is the state of disk usage:

# df -h
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda1             7,0G  1,6G  5,1G  24% /

Configure MySQL database

We also have to prepare MySQL database, i.e. you have to do the following steps:

1. Configure database to use UTF-8 by default.
2. Configure it to listen only on loopback interface.
3. Start database and set root password.
4. Create alfresco database.
5. Create alfresco user and assign it a password.
6. Configure system to start MySQL database during the boot process.

The first two steps are done by editing /etc/my.cnf file. Integrate the following lines with the already existing content (i.e. to existing sections add missing lines, if the section doesn't exist in my.cnf file add it along with all its lines):

[client]
default-character-set=utf8

[mysql]
default-character-set=utf8

[mysqld]
bind-address=127.0.0.1
character-set-server = utf8
collation-server = utf8_unicode_ci
init-connect='SET NAMES utf8'
character-set-server = utf8

Note that MySQL has to listen on loopback because JDBC doesn't allow connection via Unix socket, at least not without tweaks to Alfresco code itself.

Step 3 (i.e. set root password) is done by starting MySQL server and then setting password:

/etc/init.d/mysqld start
/usr/bin/mysqladmin -u root password 'new-password'

String 'new-password' replace with your password (and keep quotes, they prevent shell from interpreting any special character in password you might have!). You should be careful with this password as it is very critical peace of information!

Step 4 and 5 (create alfresco database and user) are done using mysql tool. So, first start this tool:

# mysql -u root -p
Enter password: <type here root password>
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 3
Server version: 5.1.61 Source distribution

Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

and now create database:

mysql> create database alfresco;
Query OK, 1 row affected (0.00 sec)

and grant alfresco user all permissions on the database:

mysql> grant all privileges on alfresco.* to alfresco@localhost identified by 'PASSWORD';
Query OK, 0 rows affected (0.00 sec)

The word PASSWORD should be replaced with a password. Again, this one is critical since all the data will be accessible if someone gets hold on that password. And, while you are at that, remove test database as it is not necessary and might even present security threat:

mysql> drop database test;
Query OK, 0 rows affected (0.00 sec)

That's it as far as mysql client is concerned. So, leave it using exit keyword.

Finally, we should configure system to start MySQL database on each boot. This is easily done with:

chkconfig mysqld on

OK, so much about database. One more thing before going to Alfresco installation. You have to configure tomcat so that it loads MySQL connector when starting, otherwise Alfresco won't be able to connect to database! To to that, open file /etc/tomcat6/catalina.properties and search for line "shared.loader=". Add to that line string /usr/share/java/mysql-connector-java.jar, i.e. it shoud look now like this:

shared.loader=/usr/share/java/mysql-connector-java.jar

Save the file and exit and that's it. Now on to Alfresco itself.

Alfresco Installation

First, go to Alfresco download site and download Community edition, i.e. download file alfresco-community-4.0.d.zip. Then, unpack it (using unzip tool) into a temporary directory:

mkdir tmp

cd tmp

unzip ../alfresco-community-4.0.d.zip

<unzip progress output>

You'll have now few new directories. From directory web-server/webapps move files alfresco.war and share.war into tomcat webapps directory, i.e. into /var/lib/tomcat6/webapps. From now on, I'm going to reference that directory as $WEBAPPS, to shorten a bit typing. Now, start wait a minute and then stop tomcat server. This is so that it unpacks alfresco and share war archives:

/etc/init.d/tomcat6 start
/etc/init.d/tomcat6 stop

In case you receive ERROR message trying to stop tomcat, wait a bit more and then try again. Namely, until tomcat finishes initialization you can not stop it.

Note also that tomcat writes its logs into /var/log/tomcat6. You should monitor that directory when starting tomcat. More specifically, watch catalina.out file. Furthermore, the tip, I remove all log files before starting tomcat again so that it doesn't clutter new log messages with the old ones. Of course, I'm doing that only during installation phase. Later, it is very good idea to keep the logs around!

Go now into directory  $WEBAPPS/alfresco/WEB-INF/classes. There, you'll see file alfresco-global.properties.sample. Copy this file into alfresco-global.properties and change permissions to a more restrictive values:

cp alfresco-global.properties.sample alfresco-global.properties
chmod 600 alfresco-global.properties

and open it in editor. In there do the following:

1. Immediately at the beginning uncomment lines  dir.root and dir.keystore. Set dir.root to a directory where Alfresco will store data. I used /var/lib/alf_data (which of course, should be created manually!) but any value with enough storage will do. Also, change the owner of that directory to tomcat and restrict access permissions so that only user tomcat can enter into that directory (use permissions 700). dir.keystore should be set to $WEBAPPS/alfresco/WEB-INF/classes/alfresco/keystore.
2. Uncomment lines db.username and db.password and set correct value for password (username is alfresco so that shouldn't be necessary to change). This password in plain text is the reason you had to change permissions of the file.
3. Find MySQL section, and in particular lines there db.driver and db.url and uncomment them. Change the value of db.driver to com.mysql.jdbc.Driver.

Now, open file log4j.properties that is in the same directory as the previous file, i.e. $WEBAPPS/alfresco/WEB-INF/classes. Find there the following line:

log4j.appender.File.File=alfresco.log

And change it to:

log4j.appender.File.File=/var/log/tomcat6/alfresco.log

This line specifies where Alfresco will do its logging. The obvious place is the same directory where tomcat places its logs. Do the same change in file $WEBAPPS/share/WEB-INF/classes/log4j.properties.

Now, start tomcat again and try to open the following URL in a Web browser: http://alfresco.example-domain.com:8080/alfresco. After a bit of wait you should be presented with a guest Alfresco home page. You can then logout and login as admin (U: admin/P: admin). Note that if you can not connect, the reason is firewall on Alfresco server. Temporarily turn off the firewall with:

/etc/init.d/iptables stop

and then try again.

Don't forget to configure system so that tomcat is started after each reboot. Anyway, this is the first part of the installation. There are some more tweaks you should do that I'm going to describe in the following post. For the end of this post let me show the disk usage:

# df -h
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda1             7,0G  2,1G  4,6G  31% /