Install Configure Alfresco Lab 3 Stable

Alfresco Labs 3 Stable

Installing and Configuring Alfresco Labs 3 Stable


Installing and Configuring Alfresco Labs 3 Stable - i

Contents

Preface.................................................................................................................. 2Audience......................................................................................................2Conventions................................................................................................ 2

Typographic conventions........................................................................ 2Command conventions........................................................................... 2System paths.......................................................................................... 3

Frequently occurring tasks....................................................................... 3Opening a command prompt.................................................................. 3Running batch files................................................................................. 4Adding folder paths to the Windows path variable................................. 5

Resources....................................................................................................5

Before installing...................................................................................................7Installation files.......................................................................................... 7

Alfresco....................................................................................................7SharePoint Protocol Support.................................................................. 8Alfresco WCM......................................................................................... 8Alfresco Web Service client.................................................................... 8Alfresco SDK AND APIs......................................................................... 8Extensions............................................................................................... 9Microsoft Office Add-ins..........................................................................9

Software requirements...............................................................................9Installing a JDK........................................................................................ 10

Verifying the JAVA_HOME environment variable location....................10Installing MySQL...................................................................................... 10

Installing MySQL................................................................................... 10Using the MySQL Configuration wizard................................................11Verifying the MySQL installation...........................................................11

Installing Alfresco..............................................................................................12Installing Alfresco on Windows..............................................................12

Installing Alfresco on Windows (full installation)................................... 12Installing Alfresco on Windows (excluding JDK)...................................13Installing Alfresco Tomcat bundle on Windows.................................... 14

Installing Alfresco on Redhat Linux.......................................................15Installing Alfresco on Redhat Linux (excluding JDK)............................ 15Installing the Alfresco Tomcat bundle on Linux.................................... 16

Installing Alfresco on Mac (full installation)..........................................16Installing the Alfresco WAR on any platform........................................17

Download the extension samples......................................................... 17Modifying the directory paths for Tomcat 6.......................................... 18Deploying Share into a separate Tomcat instance............................... 18

Installing Alfresco components..............................................................19Installing Alfresco WCM........................................................................19


ii - Installing and Configuring Alfresco Labs 3 Stable

Installing OpenOffice.............................................................................20Installing ImageMagick..........................................................................21Installing Microsoft Office Add-ins.........................................................21Installing Flash Player...........................................................................22Installing SWF Tools............................................................................. 22Installing an Alfresco Module Package.................................................24Installing Microsoft Office SharePoint Protocol Support....................... 25

Running Alfresco......................................................................................27Starting the Alfresco server.................................................................. 28Starting Alfresco Explorer..................................................................... 28Starting Alfresco Share......................................................................... 28Stopping the Alfresco server.................................................................28Starting the Alfresco virtualization server............................................. 29Stopping the Alfresco virtualization server............................................29Starting and stopping the FSR server.................................................. 29

Configuring Alfresco......................................................................................... 30Configuration overview............................................................................30

Modifying extension files.......................................................................30Modifying default configuration files......................................................30About default configuration file types....................................................31Customizing the web client................................................................... 33Customizing individual configuration items........................................... 34Creating a customized configuration file...............................................36Pointing to configuration files................................................................36Pointing to customized configuration files.............................................37

Configuring databases.............................................................................39Overriding database connection properties.......................................... 39Configuring a MySQL database............................................................39Configuring a PostgreSQL database.................................................... 41

Configuring core services....................................................................... 42Tuning the JVM.....................................................................................42Command line configuration................................................................. 44Customizing dir.root.............................................................................. 45Configuring new installations................................................................ 45Configuring the repository cache.......................................................... 46

Configuring extended services...............................................................47Adding a MIME type............................................................................. 47Configuring metadata extraction........................................................... 48Versioning..............................................................................................48Setting up replication............................................................................ 49Configuring the connection pool........................................................... 50Customizing content transformations....................................................50Configuring a JMX interface................................................................. 51

Configuring the file system.....................................................................52File system configuration...................................................................... 52Configuring WebDAV............................................................................ 55


Installing and Configuring Alfresco Labs 3 Stable - iii

Configuring CIFS...................................................................................56Configuring FTP.................................................................................... 58Configuring the NFS............................................................................. 58Configuring file server ACLs................................................................. 59

Configuring the virtualization server......................................................61Using ip.alfrescodemo.net.....................................................................61Configuring wildcard DNS on a nameserver.........................................62

Enabling WCM links validation............................................................... 62Configuring the FSR................................................................................ 62

FSR Metadata....................................................................................... 64Configuring the email server and email service................................... 64

Configuring the email server.................................................................64Configuring the RMI email service........................................................65Configuring the email service............................................................... 65Handling messages by target node type.............................................. 66

Configuring security and authentication............................................... 66Configuring SSL communication between the Alfresco repository andShare..................................................................................................... 66Configuring CIFS server authentication................................................ 67Configuring the Alfresco CIFS and web servers for Kerberos/ActiveDirectory integration.............................................................................. 69Configuring NTLM authentication..........................................................73Chaining authentication.........................................................................79Configuring JAAS authentication.......................................................... 84

Troubleshooting................................................................................................. 85Debugging an Alfresco installation........................................................ 85

Configuring the JVM............................................................................. 85Configuring Eclipse............................................................................... 86

Setting log levels......................................................................................86Testing and debugging links.................................................................. 86Error messages........................................................................................ 87


iv - Installing and Configuring Alfresco Labs 3 Stable


Installing and Configuring Alfresco Labs 3 Stable - 1

Copyright

Copyright 2009 by Alfresco and others.

Information in this document is subject to change without notice. No part of this document may bereproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose,without the express written permission of Alfresco. The trademarks, service marks, logos, or otherintellectual property rights of Alfresco and others used in this documentation ("Trademarks") are theproperty of Alfresco and their respective owners. The furnishing of this document does not give youlicense to these patents, trademarks, copyrights, or other intellectual property except as expresslyprovided in any written agreement from Alfresco.

The United States export control laws and regulations, including the Export Administration Regulations ofthe U.S. Department of Commerce, and other applicable laws and regulations apply to this documentationwhich prohibit the export or re-export of content, products, services, and technology to certain countriesand persons. You agree to comply with all export laws, regulations, and restrictions of the UnitedStates and any foreign agency or authority and assume sole responsibility for any such unauthorizedexportation.

You may not use this documentation if you are a competitor of Alfresco, except with Alfresco'sprior written consent. In addition, you may not use the documentation for purposes of evaluating itsfunctionality or for any other competitive purposes.

If you need technical support for this product, contact Customer Support by email [email protected]. If you have comments or suggestions about this documentation, contact us [email protected].

This copyright applies to the current version of the licensed program.

mailto:[email protected]

mailto:[email protected]


2 - Installing and Configuring Alfresco Labs 3 Stable

Preface

The purpose of this guide is to provide information on installing and configuring Alfresco Labs 3 Stable.

This guide contains the following chapters:

• Chapter 1 - Before installing describes the installation files, software requirements, andprerequisites

• Chapter 2 - Installing Alfresco describes how to install Alfresco and components

• Chapter 2 - Configuring Alfresco describes how to configure Alfresco core and extended services

• Chapter 3 - Troubleshooting describes how to analyze and troubleshoot various scenarios

AudienceThis guide provides information to assist in the installation and configuration of Alfresco.

No specialist knowledge is assumed to install and configure Alfresco; however, the information providedin this guide assumes that you are familiar with the environment on which you are installing. Someconfiguration tasks also require knowledge of your environment and configuration processes.

ConventionsThis guide uses the following terms and conventions.

Typographic conventionsThe following typographic conventions identify certain types of information.

Formatting convention Type of information

bold Used when referring to any item in the User Interface (UI). This includesitems that users select, such as menu options, command buttons, anditems in a list.

monospace Used to indicate anything that is not covered by Bold. This includes fileand path names, text the user types, standard output, code, and so on.

italics Used to emphasize importance and for variable expressions, such asparameters. For example:

kill -9 <process_id>

CAPITALS Used to refer to specific keys on the keyboard. For example:

SHIFT, CTRL, or ALT

KEY+KEY Used to refer to key combinations when a user must press and holddown the first key, and then press another key. For example:

CTRL+P or ALT+F4

Command conventionsThis guide uses a standard convention to indicate a series of commands in succession.

For example, a standard convention to open a new document is:



File > New > Document

This means:

1. On the menu bar, click File.

2. In the menu, click New.

3. In the sub-menu, click Document.

System pathsThe following standard conventions describe common system paths:

• Explicit Windows paths use back slashes

c:\Adirectory

• Explicit Linux paths use forward slashes

/srv/adirectory

• Back slashes also indicates the same path can apply in both Windows or Linux environments

<extension>\adirectory\

Windows commonly used directories

The following standard conventions are used to describe the <extension> directory:

• (Tomcat) C:\Alfresco\tomcat\shared\classes\alfresco\extension

• (JBoss) C:\jboss\server\default\conf\alfresco\extension

• (WebLogic) C:\bea\user_projects\domains\alf_domain\lib\alfresco\extensionNote: The path can be anywhere on the Weblogic classpath.

Linux commonly used directories

The following standard conventions are used to describe the <extension> directory:

• (Tomcat) tomcat/shared/classes/alfresco/

• (JBoss) /jboss/server/default/conf/alfresco/extension

• (Weblogic) <bea>/user_projects/domains/alf_domain/lib/alfresco/extensionNote: The path can be anywhere on the Weblogic classpath.

Frequently occurring tasksThis section describes tasks that are frequently used or referred to in this guide.

Opening a command promptYou may need to run and edit scripts in a command prompt when installing on a Windows-based system.

1. On the Windows task bar, click Start > Run.

2. In the Run dialog box, type cmd.



3. Click OK.The Run dialog box closes and a command prompt opens.

Running batch filesWhen installing Alfresco on a Windows-based system, you may have to run a batch file. A batch file is aWindows file with a BAT extension.

1. In Windows Explorer, double-click a file name with a BAT extension.

The command prompt is closed on normal completion, or if the program is terminated by acommand error. If the command prompt closes before you have time to see the error that causedthe program to terminate, you can run the batch program by opening a command prompt yourself.

2. In a command prompt, type cd c:\alfresco, and press ENTER.

3. To check that you are in the correct directory, type dir alf_*, and look for alf_start.bat.

4. Type alf_start.



If there are no errors, proceed to the next instruction.

Adding folder paths to the Windows path variableYou may need to add folder paths to the Windows Path variable when installing on a Windows-basedsystem.

1. On the Windows desktop, right-click My Computer.

2. In the pop-up menu, click Properties.

3. In the System Properties window, click the Advanced tab, and then click Environment Variables.

4. In the System Variables window, highlight Path, and click Edit.

5. In the Edit System Variables window, insert the cursor at the end of the Variable value field.

6. If the last character is not a semi-colon (;), add one.

7. After the final semi-colon, type the full path to the file you want to find.

For example: path C:\jdk

8. Click OK in each open window.The new path will be used the next time a command prompt is opened, or a service is started.

ResourcesThe resources in the following table provide additional information related to using Alfresco.

Resource Description

Getting Started with SharePoint Protocol for Enterprise3.01

How to use the Alfresco

Installing and Configuring Labs 3 Stable Installing Alfresco and related components, andconfiguring core and extended services

Getting Started with Share for Labs 3 Stable Introduction to using Alfresco Share for collaborativecontent management

Share End User Help for Labs 3 Stable How to use the Alfresco Share user interface

Explorer ECM End User Help for Labs 3 Stable How to use the Alfresco Explorer user interface



Knowledge Base Additional information on specific Enterprise featuresand applications in white papers, Frequently AskedQuestions (FAQ), and articles

http://wiki. alfresco.com Alfresco Labs wiki, community-contributed informationon all aspects of the Alfresco Labs environment

http://www.alfresco.com Alfresco web site for all information about Alfresco,including links to various resources, such as webinarsand forums

http://www.alfresco.com/services/support/faq Contacting support information on the most requestedinformation from support and how to contact support



Before installing

This chapter describes how to prepare your system for installing Alfresco.

Installation filesThere are a number of different installation files available to you, each of which you can choosedepending on what is already installed on your system. By choosing an installation file that contains onlythe necessary components, this lets you reduce your download time. For example, if you already have aJDK installed, you can download an installation file that does not contain JDK.

Alfresco runs within an instance of the Tomcat application server. The installers and the Tomcat bundlesare preconfigured with Tomcat. If you wish to install Alfresco within another application server, use theAlfresco WAR file.

The following tables help you to determine what files to download and install. The installation files areavailable to download from the Alfresco wiki at http://wiki.alfresco.com.

Alfresco

Description File name

Full Alfresco installation wizard for Windows includingShare and Explorer web clients, DM and WCM,Web Studio, Records Management, and SharePointfunctionality. Use this file if no Alfresco component isinstalled on your system. This installer ensures thatyou have all the recommended software installed andensures that configurations are set.

Alfresco-Labs-3Stable-Full-Setup.exe

Full Alfresco installation wizard for Windows excludingJDK. Use this file if you already have JDK installed butneed to install

Alfresco-Labs-3Stable-OOo-Setup.exe

Full Alfresco installation wizard for Linux includingShare and Explorer web clients, DM and WCM,Web Studio, Records Management, and SharePointfunctionality. Use this file if no Alfresco component isinstalled on your system.

Alfresco-Labs-3Stable-Linux-x86-Install

Full Alfresco installation wizard for Mac including Shareand Explorer web clients, DM and WCM, Web Studio,Records Management, and SharePoint functionality.Use this file if no Alfresco component is installed on yoursystem.

Alfresco-Labs-3Stable-MacOS-X-Install

Preconfigured Tomcat bundle for any platform includingLinux, Solaris, Apple Mac OS (.tar.gz). Use this bundle ifyou already have the required software installed.

alfresco-labs-tomcat-3Stable.tar.gz

Preconfigured Tomcat bundle for Windows (.zip). Usethis bundle if you already have the required softwareinstalled.

alfresco-labs-tomcat-3Stable.zip

Alfresco WAR files for deployment in existing applicationservers (.tar.gz)

alfresco-labs-war-3Stable.tar.gz

Alfresco WAR files for deployment in existing applicationservers (zipped)

alfresco-labs-war-3Stable.zip



SharePoint Protocol Support


Microsoft SharePoint Protocol support connectorfunctionality

vti-module.amp

Alfresco WCM


WCM functionality for adding to an Alfresco Labs 3install (.tar.gz)

alfresco-labs-wcm-3Stable-tar.gz

WCM functionality for adding to an Alfresco Labs 3install (zipped)

alfresco-labs-wcm-3Stable.zip

Windows installer for Deployment/FSR alfresco-DeployLabs-3Stable-Setup.exe

Linux installer for Deployment/FSR alfresco-DeployLabs-3Stable-Linux-x86-Install

XML utility alfresco-truncateMalformedXml.amp

Alfresco Web Service client


WSDL-based API providing standard remote access tothe Alfresco repository

alfresco-web-service-client-3Stable-tar.gz

WSDL-based API providing standard remote access tothe Alfresco repository

alfresco-web-service-client-3Stable.zip

Alfresco SDK AND APIs


Alfresco Software Development Kit, including the sourcefiles

alfresco-labs-sdk-3Stable.tar.gz

Alfresco Software Development Kit, including the sourcefiles, zipped

alfresco-labs-sdk-3Stable.zip

Sample extension file such as custom-repository.properties

alfresco-labs-sample-extensions-3Stable.tar.gz

Sample extensions files such as custom-repository.properties, zipped

alfresco-labs-sample-extensions-3Stable.zip

Add-in for PHP integration phpIntegration.amp



Extensions


Module Management Tool, already included in mainserver bundles

alfresco-mmt-3Stable.jar

iGoogle gadgets aggadget.zip

Blog publishing, deprecate alfresco-blog-integration.amp

JCR Benchmarking toolkit alfresco-bm-3Stable.jar

FaceBook integration alfresco-fb-doclib.amp

Records Management sample functionality alfresco-recordsmanagement.amp

MediaWiki integration org.alfresco.module.mediawikiintegration.amp

Microsoft Office Add-ins


Add-in for Microsoft Excel 2003 alfresco-labs-excel2003-addin-3Stable.zip

Add-in for Microsoft Office 2003 alfresco-labs-office2003-addins-3Stable.zip

Add-in for Microsoft PowerPoint 2003 alfresco-labs-powerpoint2003-addin-3Stable.zip

Add-in for Microsoft Word 2003 alfresco-labs-word2003-addin-3Stable.zip

Software requirementsThe following table lists the required software that must be on your system before you install Alfresco.

Component Recommendation

Java SE Development Kit (JDK) JDK 5 or 6 is required. See Installing JDK.

Database Alfresco comes preconfigured with the Derby database for testing andevaluation. If you intend to use Alfresco with a supported database, installand configure the database before you install Alfresco.

Flash Player Version 10.x The Alfresco Share client requires Flash Player Version 10.x to uploadmultiple files and view Flash previews. If you do not install Flash, you seethe upload screen for single files.

SWF Tools The Alfresco Share client uses the pdf2swf utility for previewing PDF files. Ifyou do not install SWF Tools, you will not see the PDF previews, but you willcan still see image previews.

OpenOffice.org Alfresco uses OpenOffice for transforming documents from one formatto another, for example, a text file to a PDF file. If you do not installOpenOffice, you will not have access to the transformation functionality.



Installing a JDKA Java SE Development Kit (JDK) must be installed on your system before you install Alfresco. SomeAlfresco installation wizards will detect whether you have a JDK on your machine and, if not, install aversion for you. This task explains how to install JDK manually.

1. Browse to Sun Microsystem's Java download website: http://java.sun.com

2. Select and download the Java Development Kit (JDK) 6 for your platform.

3. If prompted, specify a location in which to download.

4. Navigate to where you downloaded the JDK.

5. Install the JDK on your system.

JDK is installed on your system. Next, set the JAVA_HOME environment variable.

Verifying the JAVA_HOME environment variable locationThe JAVA_HOME environment variable location must be set to where the JDK is installed.

To verify the JAVA_HOME variable location:

1. Open a command prompt.

2. Enter the following:

• (Windows) echo %JAVA_HOME

• (Linux) echo $JAVA_HOME

To add or update a path in Windows, see Adding folder paths to the Windows Path variable.

Installing MySQLThis section describes how to set up a MySQL open source relational database management system(RDBMS) for use with Alfresco.

Note: Alfresco comes preconfigured with a database for testing and evaluation. For a productionenvironment, you must use a supported database, such as MySQL.

Installing MySQLThis task describes how to install a MySQL database for use with Alfresco.

1. Browse to the MySQL download site: http://dev.mysql.com/downloads

2. Locate and select the appropriate package for your platform.Note: Alfresco requires MySQL 5.0.67 or higher.

3. If prompted, specify a location on your system in which to download and install MySQL.

4. Browse to where you downloaded MySQL, and double-click the installer file.The MySQL Server Setup wizard guides you through the MySQL installation, followed by theConfiguration wizard.

5. At the Welcome window, click Next.

6. Select the Typical setup type, and click Next.

7. Click Install, and click Next.

8. Skip the MySQL registration.

http://java.sun.com

http://dev.mysql.com/downloads



9. In the Wizard Completed window, click Finish.The MySQL Server Setup wizard closes, and the MySQL Server Instance Configuration wizardopens.

Using the MySQL Configuration wizardThe MySQL Configuration wizard starts immediately after the MySQL Server Setup wizard closes.

1. In the Welcome window, click Next.

2. Select Detailed Configuration, and click Next.

3. Select Server Machine, and click Next.For production use, choose Dedicated MySQL Server Machine. The option selected determinesthe memory allocation.

4. For database use, select Transactional Database Only, and click Next.This creates an InnoDB database.

5. Accept the default drive and path for the InnoDB tablespace settings, and click Next.

6. To set the approximate number of concurrent connections to the server, select Decision Support(DSS) OLAP, and click Next.

7. Accept the default networking options (Enable TCP/IP Networking, Port Number 3306), and thedefault server SQL mode (Enable Strict Mode), and click Next.

8. Select Best Support for Multilingualism, and click Next.This sets the default character set to be UTF-8.

9. (Windows) Select Install as Windows Service and Include Bin Directory in Windows PATH, andclick Next.

10. Set the following security options:

a. Select Modify Security Settings.

b. Type the root password admin, then retype the password.

11. Click Next.

12. Click Execute.A message informs you the configuration is complete and MySQL is installed.

13. Click Finish.

MySQL is set up. Next, you can verify that MySQL is correctly installed.

Verifying the MySQL installationOnce you have installed MySQL, this task describes how to verify that it was installed correctly.


2. At the prompt, enter mysql -u root -p.

3. Type the password that you set during the installation, and press ENTER.Information about the installed MySQL version displays. If no errors are reported, MySQL is installedand running.

4. At the mysql> prompt, type exit to exit MySQL.

You have verified the MySQL installation was successful.



Installing Alfresco

This chapter provides information for installing Alfresco and Alfresco components.

Depending on your system, you can install Alfresco using a number of different methods. For example,you can install Alfresco with one of the installer wizards, which contains all the required software andcomponents you need. Alternatively, you can install Alfresco using a bundle that includes a preconfiguredTomcat server, the Alfresco WAR (alfresco.war), batch files, database setup scripts, and a sampleextensions folder. Finally, you can manually install Alfresco as a standard Web Archive (WAR) file todeploy on your existing application server.

For more information on the different files available to you, see Installation files.

A typical installation scenario includes the following procedures:

1. Install a Java SE Development Kit (JDK). See Installing a JDK.

2. Install a supported database. See Installing a database.

3. Install Alfresco. See Installing Alfresco.

4. Configure an Alfresco database. See Configuring databases.

5. Install Alfresco components. See Installing Alfresco components.

6. Run Alfresco. See Running Alfresco.

Installing Alfresco on WindowsThis section describes how to install Alfresco using the following methods:

1. Alfresco Windows complete installation

2. Alfresco Windows installation excluding JDK

3. Installing Alfresco Tomcat bundle on Windows

Installing Alfresco on Windows (full installation)The installation wizard for Microsoft Windows installs all the software and components that you require forrunning Alfresco.

1. Browse to the Alfresco downloads area, and download the following installation file:Alfresco-Labs-3Stable-Full-Setup.exe

2. Double-click the downloaded file.

3. At the Language Selection prompt, select English, and click OK.

4. When prompted to confirm installation, click Yes. The Installation wizard launches.


6. In the Setup Type window, select one of the following options:

Typical To select all the components within the Alfrescofull installation.

Custom To select individual components: Defaultcomponent (includes DM), Samples (containingAMPs including SharePoint Protocol), WCM, Java(JDK), OpenOffice.



7. Click Next.

8. In the Choose Destination Location window, click Next to accept the default location for Alfresco orchoose another location.

9. In the Start Copying Files window, review the settings and click Next.The installation starts. A prompt notifies you when OpenOffice is being installed. No action isrequired.

10. In the Database Selection window, select the database to use from one of the following options:

Derby Derby is the default database and can be usedfor evaluation and testing. Select this option ifyou are using a database other than MySQL,then following the instructions in Configuringdatabases.

MySQL Select MySQL if you already have a MySQLdatabase installed and running. By selecting thisoption, Alfresco the installer tries to communicatewith the database for the configuration settingsand for creating the database.

11. Click Next.

12. (MySQL) In the Database Configuration window, enter the Root Password of your chosen databaseand modify the database port and server settings, if required.The installer will create a database called alfresco. You will be prompted to confirm that thedatabase has been created.

13. Click OK.

14. Click Next.

15. In the InstallJammer Wizard Complete window, click Finish.

The installation is complete. To run Alfresco, see Running Alfresco.

Installing Alfresco on Windows (excluding JDK)This section describes how to use the Alfresco OpenOffice installation wizard. This installation fileincludes all the required components for Alfresco, including OpenOffice, but it excludes the JavaDeveloper Toolkit (JDK).

1. Download the following Alfresco installation file:Alfresco-Labs-3Stable-OOo-Setup.exe

2. Double-click the downloaded file.


4. When prompted to confirm installation, click Yes.The Installation wizard launches.

5. In the Welcome window, click Next.The Browse for Folders window displays, prompting you to locate your JDK installation.

6. Browse to your JDK installation and click OK.


Typical To select all the components within the AlfrescoOpenOffice installation.

Custom To choose individual components: Defaultcomponent (includes DM), Samples (containing



AMPs including SharePoint Protocol), WCM, andOpenOffice.

8. In the Choose Destination Location window, click Next to accept the default location to installAlfresco or choose another location.

9. In the Start Copying Files window, review the settings and click Next.The installation starts. A prompt notifies you when OpenOffice is being installed. No action isrequired.


Derby Derby is the default database and can be used for evaluation andtesting. Select this option if you are using a database other thanMySQL, then following the instructions in Configuring databases.

MySQL Select MySQL if you already have a MySQL database installed andrunning. By selecting this option, Alfresco the installer tries tocommunicate with the database for the configuration settings andfor creating the database.

11. Click Next.

12. (MySQL) In the Database Configuration window, enter the Root Password of your chosen databaseand modify the database port and server settings, if required.The installer will create a database called alfresco. You will be prompted to confirm that thedatabase has been created.

13. Click OK.

14. Click Next.


16. In the Readme window, click Close.


Installing Alfresco Tomcat bundle on WindowsThis section describes how to install Alfresco using the Tomcat bundle on a Windows platform.

Before you start, ensure that you have a JDK installed. Refer to Installing a JDK. Alfresco also requiresFlash Player, SWF Tools, and OpenOffice.org. For more information on installing these components, referto Installing Alfresco components.

1. Download the following Alfresco Tomcat bundle:alfresco-labs-tomcat-3Stable.zip

2. Specify C:\Alfresco as the location for the download.

3. Extract the downloaded file into the location you specified.

4. Ensure that the JAVA_HOME environment variable points to the location of your JDK install.

5. Open the <extension>\custom-repository.properties file.

6. Locate the property dir.root.

7. Change the property to show the absolute path of the alf_data directory. For example:dir.root=C:/Alfresco/alf_data

8. Save the custom-repository.properties file.

The Tomcat bundle uses Derby as the default database. If you wish to use another database, refer toConfiguring databases

../tasks/jdk-install.dita



Installing Alfresco on Redhat LinuxThis section describes how to install Alfresco on Redhat Linux using the following methods:

1. Alfresco complete installation

2. Alfresco Tomcat bundle

Installing Alfresco on Redhat Linux (excluding JDK)This section describes how to use the Alfresco installation wizard on Redhat Linux. This installation fileexcludes JDK.Note: These instructions are for working on a Graphical User Interface (GUI) in an X11 environment.

Before you install Alfresco, ensure that you have JDK 6 installed on your system.

1. Download and run the following installation file:Alfresco-Labs-3Stable-Linux-x86-InstallNote: Ensure that you have the correct permissions set for executing the file.


3. When prompted to confirm installation, click Yes.The Installation wizard launches.

4. In the Welcome window, click Next.The Browse for Folder window displays, prompting you to locate your JDK installation.

5. Browse to your JDK installation and click OK.



Custom To select individual components: Defaultcomponent (includes DM), Samples (containingAMPs including SharePoint Protocol), WCM, Java(JDK), OpenOffice.

7. Click Next.

8. In the Choose Destination Location window, click Next to accept the default location for Alfresco.

9. In the Start Copying Files window, review the settings and click Next.The installation starts.


Derby Derby is the default database and can be usedfor evaluation and testing. Select this option ifyou are using a database other than MySQL,then following the instructions in Configuringdatabases.

MySQL Select MySQL if you already have a MySQLdatabase installed and running. By selecting thisoption, Alfresco the installer tries to communicatewith the database for the configuration settingsand for creating the database.

11. Click Next.

12. (MySQL) In the Database Configuration window, enter the Root Password of your chosen databaseand modify the database port and server settings, if required.



The installer will create a database called alfresco. You will be prompted to confirm that thedatabase has been created.

13. Click OK.

14. In the OpenOffice Location window, browse to your OpenOffice location and click OK. If you do notwant to use OpenOffice for your document conversions, select the Alfresco installation folder as thelocation.Note: In the current version, the installer looks for <path>/soffice.exe. As a temporaryworkaround, cp soffice.bin soffice.exe will help the installer finish correctly.

15. Click Next.


17. In the Readme window, click Close.


Installing the Alfresco Tomcat bundle on LinuxThis section describes how to install the Alfresco Tomcat bundle on Linux.

Before you start, ensure that you have a JDK installed. Refer to Installing a JDK. Alfresco also requiresFlash Player, SWF Tools, and OpenOffice.org. For more information on installing these components, referto Installing Alfresco components.

1. Download the following Alfresco Tomcat bundle:alfresco-labs-tomcat-3Stable.tar.gz

2. Specify /opt/alfresco/ as the location for the download.Note: If you change this location from/opt/alfresco/, edit alfresco.sh to point theAPPSERVER variable to the Tomcat bundle location /opt/alfresco/tomcat.

3. Extract the downloaded file into the location you previously specified.

4. Ensure that the JAVA_HOME environment variable points to the location of your JDK install.

5. Open the <extension>/custom-repository.properties file.

6. Locate the property dir.root.

7. Change the property to show the absolute path of the alf_data directory. For example:dir.root=/opt/alfresco/alf_data

8. Save the custom-repository.properties file.

9. (Optional) If you deployed previous versions of Alfresco, you can remove any temporary filescreated by your application server.

The Tomcat bundle uses Derby as the default database. If you wish to use another database, refer toConfiguring databases

Installing Alfresco on Mac (full installation)The installation wizard for Mac installs all the software and components that you require for runningAlfresco. The Mac installer uses Derby as the default database.

1. Download the following installation file:Alfresco-Labs-3Stable-MacOSXInstall.tar.gz

2. Double-click the downloaded file to unpack it.

3. Run the following executable file:Alfresco-Labs-3Stable-MacOS-X-Install

../tasks/jdk-install.dita




5. When prompted to confirm installation, click Yes. The Installation wizard launches.




Custom To choose individual components: Defaultcomponent (includes DM), Samples (containingAMPs including SharePoint Protocol), WCM, Java(JDK), OpenOffice.

8. Click Next.

9. In the Choose Destination Location window, click Next to accept the default location for Alfresco.

10. In the Start Copying Files window, review the settings and click Next. The installation starts.



Installing the Alfresco WAR on any platformThis section describes how to install the Alfresco Web Archive (WAR) file on any platform. A WAR file isa JAR file used to distribute a collection of files (JavaServer Pages, servlets, Java classes, XML files, taglibraries and static Web pages) that together constitute a web application.

Use this method of installing Alfresco if you already have installed a JDK, a supported database, anapplication server, and the additional Alfresco components. The WAR zip includes the binaries forImageMagick and pdf2swf.

1. Select and download one of the following files:

• alfresco-labs-war-3Stable.zip

• alfresco-labs-war-3Stable-dev.tar.gz

2. Specify a location for the download.

3. Extract the downloaded file.

4. Copy the alfresco.war file and share.war file to the appropriate location for your applicationserver, for example: <TOMCAT_HOME>/webapps.

Note: If you deployed previous versions of Alfresco, you must remove any temporary files created byyour application server.

Download the extension samplesEach Alfresco distribution includes a download containing sample extensions, such as the repositoryproperties. You can use these sample extensions if you wish to configure Alfresco.

1. Select and download one of the following files:

• alfresco-labs-sample-extensions-3Stable.zip

• alfresco-labs-sample-extensions-3Stable.tar.gz

2. Specify a location for the download.



The extension samples are available for you to configure.

Once you have downloaded the sample properties files, copy them into the shared classes location, forexample <TOMCAT_HOME>/shared/classes/.

Modifying the directory paths for Tomcat 6If you install Tomcat 6 separately, some of the directories that were present in Tomcat 5.x are notpresent. For example, Tomcat 6 does not contain the shared/classes and shared/lib directories.Alfresco uses these directories to locate the configuration override files found in shared/classes/alfresco/extension.

This section describes how to configure Tomcat 6 to use the correct directory structure and files forAlfresco.

1. Locate <TOMCAT_HOME>.

2. Create the shared/classes directory and copy the extensions files and full structure from theWAR to create the following directories:

../shared/classes/alfresco/extension/<files> (alfresco.war extension override files)../shared/classes/alfresco/messages/<files> (locale specific message files)../shared/classes/alfresco/web-extension/<files> (share.war extension override files)

3. Open the <TOMCAT-HOME>/conf/catalina.properties file.

4. Change the value shared.loader= to the following:shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar

Deploying Share into a separate Tomcat instanceThis task provides information for running share in a separate Tomcat instance. These instructions are forWindows deployments, but Linux-based deployments can use the same methods.

1. Install a new Tomcat instance.

2. Modify the \conf\server.xml file for the new Tomcat instance as follows:

a. Change the port number in the line (for example, to 8006):

<Server port="8005" shutdown="SHUTDOWN">

b. Change the port number in the section (for example, to 8180):

 <Connector port="8080" ....

3. Move the share.war file from the original Tomcat \webapps directory to the new Tomcat\webapps directory.

4. (Optional) Configure the original Alfresco Tomcat deployment.

5. Start the original Tomcat. You can use Alfresco supplied batch files.

6. Move a copy of the commons-el.jar file to the Share Tomcat lib directory.

7. If you are running the Share Tomcat on a separate machine, you must modify the override file in theShare Tomcat extension directory, as follows:

a. Open the webscript-framework-config-custom.xml file.

b. Change any instance of the server and port to the correct name or IP address of the Alfrescoserver.



http://yourserver:8080

8. Start the new Share Tomcat. You can use copies of the Alfresco supplied batch files, or your ownmethods.

Installing Alfresco componentsThis section describes how to install components that integrate with Alfresco. These can be installedanytime before or after installing Alfresco.

• Installing Alfresco WCM

• Installing OpenOffice

• Installing ImageMagick

• Installing Microsoft Office® Add-ins

• Installing Flash Player

• Installing SWFTools

• Installing an AMP

• Installing SharePoint Protocol Support

• Installing MediaWiki integration

Installing Alfresco WCMThis section describes how to set up Alfresco Web Content Management (WCM).

Installing the WCM component to an existing instance of Alfresco

This task describes how to download Alfresco WCM to an existing instance of Alfresco.

1. Select one of the following files:

• alfresco-labs-wcm-3Stable.zip

• alfresco-labs-wcm-3Stable.zip

2. Download the file into the Alfresco home directory. For example:

• (Windows) C:\Alfresco

• (Linux) /opt/alfresco

3. Browse to the Alfresco home directory, and unzip the downloaded file.If your unzip program asks about existing directories, allow this because no existing files will beoverwritten.

4. In the root of the Alfresco home directory, copy the file wcm-bootstrap-context.xml to theAlfresco<extension> directory.

5. Restart the Alfresco server.This ensures that the Alfresco server starts to use the installed WCM components. To restart theAlfresco server, see Starting the Alfresco server.

Alfresco WCM is installed and configured.

Verifying the WCM installation

Verify the WCM installation after you have installed, configured, and started the Alfresco server.

1. In the Alfresco home directory, open alfresco.log.



2. In alfresco.log, search for the following text:The Web Forms folder was successfully created: and The Web Projects folderwas successfully created:

3. Check that the following additional spaces are in your Alfresco repository:

• Web Projects in Company Home

• Web Forms in Data Dictionary

Alfresco WCM has been installed, configured, started, and verified. To use the Website Preview feature,start the Alfresco virtualization server (see Starting the Alfresco virtualization server).

Installing the FSR server

The File System Receiver (FSR) allows a web project to be deployed to a remote file server, typicallya web or application server. The FSR is a deployment server that receives updates from an Alfrescorepository running Web Content Management and publishes the updates to a flat file system.

The published files are then typically published by a web server such as Apache for static content, or anapplication server such as Tomcat or JBoss for dynamic content.

1. Download the alfresco-labs-deployment-3Stable.zip file.

2. Unzip the file into a location on your system, such as C:\alfresco\deployment on Windows or/opt/alfresco/deployment on Linux.

Before you run the server, you must configure it. See Configuring the FSR. To start and stop the FSR,see Starting and stopping the FSR server.

Installing OpenOfficeWithin Alfresco, you can transform a document from one format to another, for example, a text file to aPDF file. To have access to these transformation facilities in Alfresco, you must install OpenOffice. This isoptional, and can be done any time after Alfresco is installed.Note: If you installed Alfresco using an installation wizard, OpenOffice may already be installed.

1. Browse to the OpenOffice.org download site: http://download.openoffice.org

2. Download the latest (stable) version of OpenOffice for your platform.

3. When prompted, specify a download destination.

4. Browse to the location of your downloaded file, and install the application.A wizard guides you through the installation.

5. Accept the license agreement, and click Next.

6. Enter Customer information as appropriate, and click Next.

7. Select the set up type and Custom, and click Next.

8. Change the installation directory to:

• (Windows) c:\Alfresco\OpenOffice

• (Linux) /opt/alfresco/OpenOffice

9. Optionally, select the files for which you want OpenOffice to be the default application, and clickNext.

10. Start one of the OpenOffice programs for the initial registration, and then close the program.

11. (Linux) For a Linux installation, set a path as follows:

a. Rename /opt/alfresco/zstart_oo.sh to /opt/alfresco/start_oo.sh.

http://download.openoffice.org



b. Set the correct location for OpenOffice.

12. If the Alfresco server is running, stop and restart the server.

13. Modify the following properties in the <extension>/custom-repository.properties file:

a. Set ooo.exe= to point to the OpenOffice binary soffice.exe.

b. Set ooo.user= to point to the path for the user profile.

Installing ImageMagickTo enable image manipulation in Alfresco, you must install and configure ImageMagick. Alfresco usesImageMagick to manipulate images for previewing.Note: ImageMagick is already available if you installed using the Alfresco installers, and on many otherAlfresco distributions.

1. Verify if ImageMagick is already installed on your system.You can run the convert command, which is part of ImageMagick and usually located in /usr/bin.

2. If ImageMagick is not on your system, browse to the ImageMagick download site and install theappropriate package for your platform.

3. Create the appropriate folders for ImageMagick. The binary must be located in the ./ImageMagick/bin directory.

4. Ensure the ImageMagick binaries are in the system path.

a. (Linux) If ImageMagick is installed in /Imagemagick/bin, then add the following lines to thealfresco.sh startup script to make it available in the path:

export PATH=$PATH:/ImageMagick/bin export MAGICK_HOME="/ImageMagick/bin" export DYLD_LIBRARY_PATH="/ImageMagick/lib"

5. Create a link to work with Alfresco:

• (Windows) Add the path C:\alfresco\ImageMagick\bin to the Windows PATH variableto let Windows locate the convert.exe file.

• (Linux) Create a symbolic link to the convert executable.

Installing Microsoft Office Add-insThis task describes how to install Alfresco Add-ins for Microsoft® Office applications, such as Word,Excel, and PowerPoint.

Before you start, make sure that:

• The .NET Programmability Support option is installed for each of the Office applications that you areinstalling the Add-ins (such as Word, Excel, and PowerPoint). To find these options, run the OfficeSetup program and expand the list of available options for each application. You may require youroriginal Office 2007 install media to add these required components.

• The installing user has Windows administrator privileges.

• Any Microsoft Office applications on your system are NOT running, including Outlook if you useWord as an email editor.

1. Run the Microsoft setup file:alfresco-labs-office2003-addins-3Stable.zipThis example refers to the Office installer that installs all three Add-ins. You can also use individualinstallers to add Alfresco to one of the three Office applications.



These individual installers are:

• alfresco-labs-word2003-addin-3Stable.zip

• alfresco-labs-excel2003-addin-3Stable.zip

• alfresco-labs-powerpoint2003-addin-3Stable.zip

2. Run setup.exe.If required, the setup program will download the required components from the Microsoft website.These components are .NET 2.0 framework, and Visual Studio 2005 Tools for Office Second Editionruntime.

3. Run the Office application, for example, Word.A Welcome window with configuration options display.

4. In the Web Client URL area, enter the location to the Alfresco web client.For example: http://server:8080/alfresco/

5. In the WebDAV URL area, append webdav/ to the web client URL.For example: http://server:8080/alfresco/webdav/

6. In the CIFS Server area, enter the path to the CIFS server. The Add-in will try to auto-complete thisvalue, but you should verify for the correct address.For example: \\server_a\alfresco\ or \\servera\alfresco\

7. In the Authentication area, enter your Alfresco user name and password.If you are using the CIFS interface, authentication is usually automatic. However, sometimes theAdd-in presents your Alfresco user name and password for authentication. All values are stored inthe Windows registry and your password is encrypted against casual hacking attempts.

8. Click Save Settings.

Installing Flash PlayerAlfresco Share uses the Flash Player for viewing Flash previews and also when you use the multi-fileupload facility.

This is optional and may be installed after you have installed Alfresco.

1. Browse to Adobe's Flash Player download website: http://www.adobe.com/products/flashplayer

2. Download the latest (stable) version of Flash Player for your platform.

3. Browse to the location of your downloaded file and install the application.A wizard guides you through the installation.

4. When the installation is complete, click Close.

Installing SWF ToolsAlfresco Share uses the pdf2swf utility of the SWF Tools for previewing PDF files. The pdf2swf utilitygenerates one frame per page of fully formatted text inside a Flash movie. To install the pdf2swf utility,you must install the complete SWF Tools.

This is optional and may be installed after you have installed Alfresco.

Installing SWFTools on Windows

1. Browse to the SWF Tools download website: http://www.swftools.org

2. Download the latest (stable) version of the SWF Tools for your platform. The windows version isdesignated with the suffix .exe.

http://www.adobe.com/products/flashplayer/

http://www.swftools.org



Note: Download a version post 0.8.1 from 2007-02-28 because it does not support somefunctionalities Alfresco needs to render the preview.

3. Browse to the location of your downloaded file and and install the application.A wizard guides you through the installation.

4. Accept the license agreement and click Next.

5. Select the installation directory.

6. Select whether you want to install the SWF Tools for all users or only for the current user.

7. Click Next to begin the install process.By default, the options to Create start menu and Create desktop shortcut are selected.

8. Click Finish.

The SWF Tools are installed. For the most up-to-date instructions on installing the SWF Tools, refer to theSWF Tools website.

Installing SWF Tools on Linux

Alfresco Share uses the features provided in the development snapshots of the tools. For Linux, there isno binary version, so you need to compile a development snapshot.

(Linux) Before you compile, ensure that the following packages are installed on your machine:

• zlib-devel

• ibjpeg-devel

• giflib-devel

• freetype-devel

• gcc

• gcc-c++

You can download and install all of these packages using the following command:

yum install zlib-devel libjpeg-devel giflib-devel freetype-devel gcc gcc-c++

1. Browse to the SWF Tools download website:

2. Download the latest version of the SWF Tools for your platform. The Unix version is designated withthe suffix .tar.gz.Note: Download a version post 0.8.1 from 2007-02-28 because it does not supportsome functionalities Alfresco needs to render the preview. Note, the following version hasbeen tested and verified by Alfresco as being fully functional: http://www.swftools.org/swftools-2008-10-08-0802.tar.gz (note, you may have to copy this URL and paste it into a downloadmanager).

3. Unpack the tar.gz file.The INSTALL file contains detailed instructions on how to compile and install the SWF Tools.

4. . Change to the directory containing the source code.

5. Type the following command to configure the package for your system:./configureIf you see a message on Red Hat Linux that states your operating system is unknown, then use thefollowing setting: ./configure–build=x86_64-pc-linux-gnu

If you have an issue on Solaris with the lame libs, you can disable the making of portions of SWFTools that use lame by using the following setting: ./configure -disable-lame

6. Type the following command to compile the package.make



Optionally, you can run make check to run any self-tests that come with the package.

7. Type the following command to install the programs and any data files and documentation.make installBy default, the files are installed to the /usr/local/bin directory.

The SWF Tools are installed. For the most up-to-date instructions on installing the SWF Tools, refer to theSWF Tools website.

Installing an Alfresco Module PackageAn Alfresco Module Package (AMP) is a bundle of code, content model, content, and the directorystructure that is used to distribute additional functionality for Alfresco. This section describes how to installan AMP in an Alfresco WAR using the Module Management Tool (MMT). The MMT is used to install andmanage AMP files, and it is included in the Alfresco installers.

The MMT is also available as a separately downloadable JAR file from the Alfresco release downloadarea (alfresco-mmt-3Stable.jar).

1. Browse to the /bin directory:

• (WIndows) C:\Alfresco\bin

• (Linux) /opt/alfresco/bin

2. Run the following command:java -jar alfresco-mmt.jar install <AMPFileLocation> <WARFileLocation>[options]Installs the files found in the AMP file into the Alfresco WAR, and updates if an older version isalready installed. If the module represented by the AMP is already installed and the installing AMPis of a higher release version, then the files for the older version are removed from the WAR andreplaced with the newer files.

Where:

<AMPFileLocation> is the location of the AMP file that you want toinstall.

<WARFileLocation> is the location of the WAR file for your Alfrescoinstallation.

-verbose Install command [options]. Enables detailedoutput containing what is being updated andto where it is being copied.

-directory Install command [options]. Indicates that the ampfile location specified is a directory. All amp filesfound in the directory and its sub directories areinstalled.

-force Install command [options]. Forces installationof AMP regardless of currently installed moduleversion .

-preview Install command [options]. Previews installationof AMP without modifying WAR file. It reports themodifications that will occur on the WAR withoutmaking any physical changes, for example, thechanges that will update existing files. It is goodpractice to use this option before installing theAMP.

-nobackup Indicates that the WAR will not be backed upbefore the AMP is installed.



The following commands show examples of how to install the example-amp.amp, and assumesthat the AMP file is in the same directory as the WAR file:

java -jar alfresco-mmt.jar install example-amp.amp alfresco.war -preview

Review the modification to check the changes that will update any existing files.

The following example will install the AMP file:

java -jar alfresco-mmt.jar install example-amp.amp alfresco.war -verbose

The modified Alfresco WAR can then be redeployed back into your application server.

On restarting the application server, the console will show that the custom class was initializedduring startup.

3. Verify that the AMP is installed using the MMT list command. For example:java -jar alfresco-mmt.jar list <WARFileLocation>This command provides a detailed listing of all the modules currently installed in the WAR filespecified.

When the repository is next started, the installed module configuration will be detected, and the repositorywill be bootstrapped to include the new module functionality and data.

Its is not recommended that you overwrite an existing file in an AMP, however it is sometimes necessary.The MMT makes a backup copy of the updated file and stores it in the WAR. When an update of themodule occurs and the old files are removed, this backup will be restored prior to the installation of thenew files. Problems may occur if multiple installed modules modify the same existing file. In these cases amanual restore may be necessary if recovery to an existing state is required.

Note that some application servers (notably Tomcat) do not always fully clean up their temporary workingfiles, and this can interfere with successful installation of an AMP file. To remedy this situation, it isrecommended that you delete (or move) the Tomcat work and temp directories while Tomcat (Alfresco)is shut down, and prior to restarting it.

Installing Microsoft Office SharePoint Protocol SupportThe Microsoft Office SharePoint Protocol Support offers Microsoft users greater choice by providing afully-compatible SharePoint repository that allows the Microsoft Office Suite applications (for example,Word, PowerPoint, Excel) to interact with Alfresco as if it was SharePoint. This enables your users toleverage the Alfresco repository directly from Microsoft Office.

You can also use Microsoft Office SharePoint Protocol Support to enable online editing for Officedocuments within Alfresco Share. It enables your users to modify Office files without checking them inand out. Alfresco locks the file while it is being modified and releases the lock when the file is saved andclosed.

The following diagram shows the architecture of the SharePoint Protocol Support in relation to an Alfrescoinstallation.



The SharePoint Protocol Support architecture embeds a Jetty web server within the Alfresco repository.The Microsoft Office clients communicate directly with the Jetty server using WebDAV-like calls withproprietary extensions and on different port number from Alfresco Share. This port number can beconfigured in the SharePoint Protocol Support properties files.

Installing the SharePoint Protocol Support AMP

The SharePoint Protocol support functionality is installed from an Alfresco AMP. If you use the Windowsor Linux installers to install Alfresco, the SharePoint Protocol Support is installed by default. Theseinstructions describe how to install the SharePoint Protocol Support into the Alfresco WAR. When youinstall this file, it responds to the SharePoint requests from Office, and therefore allows Alfresco to appearas the SharePoint server.

1. Shut down your Alfresco server.

2. Download the vti-module.amp file.

3. Move the file to the amps directory.

4. Install the vti-module.amp file into the alfresco.war file using the Module Management Tool(MMT).The vti-module.amp file holds the functionality for the SharePoint connector.Note: For Tomcat, alternatively, run the apply_amps.bat command, which is in the root Alfrescodirectory, to install the vti-module.amp. This batch file applies all the amps that are located in theamps directory.

5. Start your Alfresco server to expand the directory structure.

6. Verify that you have applied the SharePoint AMP to Alfresco by checking that you have the followingdirectory:/webapps/alfresco/WEB-INF/classes/alfresco/module/org.alfresco.module.vti/context

Configuring SharePoint Protocol Support

The SharePoint Protocol Support functionality uses the setting in the default configuration file calledvti.properties in <TOMCAT_HOME>/webapps/alfresco/WEB-INF/classes/alfresco/module/org.alfresco.module.vti/context. Custom properties and overrides can be set in thecustom-vti.properties and custom-vit-context.xml files. These two files are available whenyou apply the AMP file, or you can create the files yourself.

Ensure that you have applied the SharePoint Protocol Support AMP, following the instructions in InstallingSharePoint Protocol Support.

1. Stop the Alfresco server.

2. Browse to the following directory:<TOMCAT_HOME>/webapps/alfresco/WEB-INF/classes/alfresco/module/org.alfresco.module.vti/context

3. Copy the following two files to the <extension> directory:

• custom-vti.properties.sample

• custom-vti-context.xml.sample

4. Open the custom-vti.properties.sample file. The file contains the following properties:

vti.server.port=7070vti.share.shareHostWithPort=http://your-share-host:8080vti.alfresco.deployment.context=/alfresco

5. Edit the properties as required.

vti-server.port Use this property to configure on which portthe SharePoint server listens. The default portnumber is 7070.



vti.share.shareHostWithPort Use this property to specify the Share instance.Replace your-share-host with the location ofyour Share instance. This property includes theprefix http:// which allows for HTTPS support.

vti.alfresco.deployment.context Use this property to specify the URL that youenter in the Microsoft Office Shared Workspace.The default is set to /alfresco. For example,http://your-share-host:7070/alfresco.

The vti.properties file in <TOMCAT_HOME>/webapps/alfresco/WEB-INF/classes/alfresco/module/org.alfresco.module.vti/context contains the full list of properties.Do not change the properties in this file; use only the sample file that you copied into the<extension> directory.

6. Save the custom-vti.properties file without the .sample extension.

7. The custom-vti-context.xml.sample file contains the following:

<?xml version='1.0' encoding='UTF-8'?><!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>

<beans>

<bean id="vtiProperties" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"> <property name="ignoreUnresolvablePlaceholders"> <value>true</value> </property> <property name="locations"> <list>

<value>classpath:alfresco/module/org.alfresco.module.vti/context/vti.properties</value>  <value>classpath:alfresco/extension/custom-vti.properties</value> </list> </property> </bean>

</beans>

You do not need to make any changes to the custom-vti-context.xml file.

8. Save the custom-vti-context.xml file without the .sample extension.

9. Restart your Alfresco server.

The Microsoft SharePoint Protocol Support functionality is installed and configured.

Configuring SharePoint Protocol for Online Editing

There is a known issue with Office 2003 and 2007 Office documents opening as read-only in InternetExplorer for all versions before Vista SP1.

Please refer to the knowledge base article 870853 on the Microsoft website to enable the Online Editingfunctionality.

Running AlfrescoThis section describes how to start and stop the following:

• Alfresco server



• Alfresco Explorer

• Alfresco Share

• Virtualization server

• FSR server

Note: Before running Alfresco, you may need to modify the configuration settings. Refer to theConfiguring Alfresco chapter for more information on how to set up Alfresco for your system.

Starting the Alfresco serverOnce you have installed Alfresco, you can test the installation by starting the server.

• (Windows)

• Browse to C:\alfresco, and double-click alf_start.bat, or

• If you installed Alfresco using the installer, from the Start menu, select All Programs>Alfresco Labs > Start Alfresco Server.

A command prompt opens with a message indicating the server has started.

INFO: Server startup in nnnn ms

• (Linux) Browse to /opt/alfresco/ and run alfresco.sh start.

Starting Alfresco ExplorerOnce you have installed Alfresco, you can start Alfresco Explorer using a browser.

1. Browse to the location of your Alfresco installation. If you installed Alfresco on your local machine,browse to http://localhost:8080/alfresco.In Windows, alternatively, you can click the Start menu, and select All Programs >Alfresco Labs >Alfresco Explorer.Alfresco Explorer opens.

2. Log in using admin as the default user name and password.

Starting Alfresco ShareOnce you have installed Alfresco, you can start Alfresco Share using a browser.

1. Browse to the location of your Alfresco installation. If you installed Alfresco on your local machine,browse to http://localhost:8080/share.In Windows, alternatively, you can click the Start menu, and select All Programs > Alfresco Labs> Alfresco Share.Alfresco Share opens.

2. Log in using admin as the default user name and password.

Stopping the Alfresco server• (Windows)

• Browse to C:\alfresco, and double-click alf.stop.bat, or

• Click the Start menu, and select All Programs > Alfresco Labs > Stop Alfresco Server.

The command prompt that opened during startup closes. Alfresco has now stopped.

• (Linux) Browse to /opt/alfresco/, and run alfresco.sh stop.



Starting the Alfresco virtualization serverIf you have installed Alfresco WCM, you can use the Website preview feature by starting the Alfrescovirtualization server.

• (Windows)

• Browse to C:\alfresco, and double-click virtual.start.bat, or

• Click the Start menu, and select Programs > Alfresco WCM Labs > Start Virtual Server.

• (Linux) Browse to /opt/alfresco/ and run virtual.alf_sh start.

Stopping the Alfresco virtualization server• (Windows)

• Browse to C:\alfresco, and double-click virtual.stop.bat, or

• Click the Start menu, and select Programs >Alfresco WCM Labs > Stop Virtual Server.

• (Linux) Browse to /opt/alfresco/, and run sh virtual_alf.sh stop.

Starting and stopping the FSR serverThis task describes how to start and stop the File System Receiver (FSR) server.

The FSR is implemented as a set of Java libraries and is inherently multi-platform. To simplify thecommand line, Bourne shell scripts are provided for UNIX and Windows batch files are provided forWindows.

• To start the FSR, open a command prompt, and run the deploy_start script.

• To stop the FSR, open a command prompt, and run the deploy_stop script.



Configuring Alfresco

This chapter provides information for configuring databases and the Alfresco core and extended services.

It is divided into the following sections:

• Configuration overview

• Configuring databases

• Configuring core services

• Configuring extended services

Configuration overviewAlfresco configuration items are completely exposed, letting you override the default setup by customizingindividual configuration items. You can overwrite the majority of configuration items by insertingalternative items in one or more extension files.

When Alfresco starts, it reads all the default configuration files, and then reads the extension filescontaining the customized configuration items. Depending on the type of item, the customization eitherextends or overrides the default configuration item.

Several default configuration files are included in the <extension> and <web-extension> directories.In many cases, you need only uncomment some lines to enable the customization. These extension filesaddress most of the configuration items you may want to modify.

Modifying extension filesMost Alfresco customization involves overriding files. This means that instead of opening a default fileand directly modifying a configuration item, you open a file in the <extension> directory or the <web-extension> directory and insert your customized version of the configuration item. The <extension>directory contains the configuration files you need to extend Alfresco. The <web-extension> directorycontains the configuration files you need to extend Alfresco Share.

1. Browse to the <extension> directory. For example, for Tomcat 6:

• (Windows) C:\Alfresco\tomcat\shared\classes\alfresco\extension

• (Linux) tomcat/shared/classes/alfresco/extension

Each file has a copy with a .sample extension. For example, the custom-repository.properties file has a duplicate file called custom-repository.properties.sample.

2. Open the configuration file with the .sample extension.

3. Add your configurations to the file.

4. Save the file without the .sample extension.You can either save the file in the <extension> directory, or in another directory. If you savethe file in the in another directory, you must point to your customized file using the repository-properties bean in the <extension>/customrepository- context.xml file. See Pointingto customized files.

Modifying default configuration filesThe default files that are read by Alfresco are contained in the WEB-INF directory. If you choose to modifythe default file directly, to minimize the risk, use the following approach.



Before you start, back up all your configuration files for security.

1. Make a copy of the default file you want to modify, and rename it.

2. Make your customization. Make only one logical change at one time (one logical change may meanseveral physical changes).

3. Check any XML is well-formed. You can use any XML editor or you can open the file in a browser,such as Firefox.

4. Before making further changes, test each logical change by stopping and restarting Alfresco.

5. If you need to roll back the changes for troubleshooting, roll them back in the reverse sequence towhich you applied them. Stop and restart Alfresco after each rollback.

About default configuration file typesThe two main types of default configuration files you most likely would want to customize are:

• Repository configuration files

• Web client configuration files

Repository configuration files

The default Alfresco configuration files are in the application WAR file. When the server starts, the filesexpand to <configRoot>. The path is different depending on your server. For example:

• Tomcat: <TOMCAT_HOME>/webapps/alfresco/WEB-INF/classes

• JBoss: <JBOSS_HOME>/server/default/tmp/deploy/tmp*alfresco-exp.war/WEB-INF/classes

The default configuration files are maintained by Alfresco, and contained in <configRoot> and<configRoot>/alfresco.

The following four files represent the core of the application configuration:

1. <configRoot>/alfresco/application-context.xml

This file is the starting point of the Spring configurations. The file imports the -context.xml filesfrom the following directories:

• <extension>

• <configRoot>/alfresco

2. <configRoot>/alfresco/core-services-context.xml

Core Alfresco beans are defined here, including the importing of properties using the repository-properties bean.

3. <configRoot>/alfresco/repository.properties

This file is imported by the repository-properties bean. The file defines some of the coresystem properties, including:

• dir.root

This folder is where the binary content and Lucene indexes are stored. The alf_data folderis where they are stored by default, but you should change this to your own location. It isrelative by default, but must point to a permanent, backed-up location for permanent datastorage.

• dir.indexes

This folder contains all Lucene indexes and deltas against those indexes.

• db.*



These are the default database connection properties.

• db.schema.update

This property controls whether the system bootstrap should create or upgrade the databaseschema automatically.

• hibernate.hbm2ddl.auto

This determines whether Hibernate updates the database schema or just validates it.

• update: checks and updates the database schema as appropriate

• validate: checks the database schema and fails if it is not compliant

4. <configRoot>/alfresco/domain/hibernate-cfg.properties

This file defines Hibernate default system properties. The file is imported by thehibernateConfigProperties bean, which is in hibernate-context.xml. The importantHibernate property is:

• hibernate.dialect

This alters the SQL dialect that Hibernate uses when issuing queries and updates to thedatabase. Normally, this is the only Hibernate property that will need changing, depending onthe database you are running against.

Web client configuration files

Web client configuration files contain configurations that either augment or replace the standardconfiguration. Default web client configuration files are located in:

<configRoot>/alfresco/web-client-config-*

Replacing a configuration

To replace the configuration, add a replace= “true” attribute to the configuration element. Forexample: <config evaluator="xx" condition= “yy” replace= “true” >

Attention: Any configuration within a section marked this way completely replaces any configurationfound in the Alfresco-maintained files.

For example, to replace the list of languages shown in the login page, add the following:

<config evaluator="string-compare" condition="Languages" replace="true"> <languages> <language locale="fr_FR">French</language> <language locale="de_DE">German</language> </languages> </config>

Modifying one property

The attribute replace completely replaces the configuration. To modify one property, you can add thechanged piece.

For example, to add another language, you need a single <language> item. The other <language>items remain enabled. For example, if you want Spanish in addition to English and German:

<config evaluator="string-compare" condition="Languages"> <languages> <language locale="es_ES">Spanish</language> .. </languages> </config>

For example configurations, see Configuring the web client.



Customizing the web clientThis section describes how to customize web client configuration items. There are several different waysthat you can customize the web client.

1. Modify the web client configuration file in the <extension> directory.

a. Open the file: <extension>/web-client-config-custom.xml.sample.

b. Uncomment any <config> items that you want to enable.

c. Save the file without the .sample extension.You can either save the file in its current location (the <extension> directory), or in anotherdirectory.

If you save the file in the <extension> directory, no further action is needed because thefile is already pointed to by the webClientConfigSource bean in the file <configRoot>/alfresco/web-client-application-context.xml.

If you save the file elsewhere, you must point to your customized file.

2. Modify the web client configuration file in the META-INF directory of a JAR file.

a. Open the file: META-INF/web-client-config-custom.xml.


c. Save the file.

d. Move the custom JAR file into the WEB-INF/lib directory.

Use this method to package the web client customizations together with any Java classes you haveas part of an extension.

3. Modify the web client configuration file in the repository.

a. Open the file: /Company Home/Data Dictionary/Web Client Extensions/web-client-config-custom.xml.


c. Save the file.Use this method to edit a file directly in the repository and then to reload it using the web client.This means that you do not have to restart the server and applies versions to the configurationchanges.

4. Modify the web client configurations within an AMP file.

a. Open the file: module-context.xml.

b. Add the following bean definition:

<bean id="myModule_configBootstrap" class="org.alfresco.web.config.WebClientConfigBootstrap" init-method="init"> <property name="configs"> <list> <value>classpath:alfresco/module/myModuleId/my-web-client-custom.xml</value> </list> </property> </bean>

c. Save the file.



Customizing individual configuration itemsThe Alfresco configuration is implemented using three types of files:

1. Properties files

2. <config> files

3. <bean> files

Customizing default .properties files

Properties files end with the extension .properties. Each property has one line in a property file. A.properties file has no header, so you do not need to take any action to preserve the header.

1. Open the file you want to customize.For example, the following snippet is from the file <configRoot>/alfresco/repository.properties.

db.driver=org.gjt.mm.mysql.Driverdb.name=alfrescodb.url=jdbc:mysql:///${db.name}db.username=alfrescodb.password=alfresco

2. Copy the default file and rename it using a meaningful name, for example: custom-filename-context.properties.

3. Comment out all the properties you do not want to modify by adding the “#” character.For example, to override the db.driver property, you only require one line:

db.driver=oracle.jdbc.OracleDriver

4. Customize the remaining properties.

5. Save the file.

Customizing a <config> file

The <config> files end with the extension .xml, and define values. The values of these files are definedin <config> tags.

A typical <config> file is <extension>/web-client-config-custom.xml. A <config> filecontains <alfresco-config> tags outside the <config> tags. You must preserve these tags in yourcustomized file.

1. Open the <config> file you want to customize.

For example, the following snippet is from the file <configRoot>/alfresco/web-client-config.xml:

<config evaluator="string-compare" condition="Languages"> <languages> <language locale="en_US">English</language> <language locale="fr_FR">French</language> </languages></config>

2. Delete each pair of <config> </config> tags that you do not want to modify.

3. To delete part of an item:

a. Copy the original <config> statement.

b. Delete the children you do not want.

c. Use the replace= “true” attribute.

For example, to delete French from the example in Step 1:



<config evaluator="string-compare" condition="Languages" replace="true"> <languages> <language locale="en_US">English</language> </languages></config>

4. To add another item, such as another language, you only need a single <language> item. Theother <language> items will remain enabled. For example, if you wanted Spanish in addition toEnglish and French:

<config evaluator="string-compare" condition="Languages"> <languages> <language locale="es_ES">Spanish</language> ..</languages> </config>

5. Customize the contents of the remaining <config> tags.

6. Save your customized file.

Customizing <bean> files

Configuration items are defined in <bean> tags, which end with the extension .xml. You can modify<bean> tags to define properties or point to customized files.

You are likely to be interested in two uses of beans:

• To define properties

• To point to one or more of your customized files

A typical <bean> file is <extension>/custom-repository-context.xml, and contains: A <bean>file contains <?xml> and <!DOCTYPE> headers, and <beans> tags outside the <bean> tags. You mustpreserve these items in your customized file.

> Important:

When you override a <bean>, the entire effects of the original bean are lost. The effect is the same asif you had overridden a <config> by using replace="true". Therefore, the overriding <bean> mustcontain any information from the default bean that you want to keep, as well as any additional information.

For example, if a core bean has four values, and you want to modify a single value, the resultant beanmust still have four values. However, if you want to add a value, then the resultant bean must have fivevalues - the original four values plus the added value.

1. Open the <bean> file you want to customize.

For example, the following <bean> is from the file <configRoot>/alfresco/action-services-context.xml:

<bean id="mail" class="org.alfresco.repo.action.executer.MailActionExecuter" parent="action-executer"> <property name="publicAction"> <value>true</value>  </property> <property name="mailService"> <ref bean="mailService"></ref> </property></bean>

2. Delete each pair of <bean> </bean> tags that you do not want to modify.

3. Modify the contents of the remaining <bean> tags.

For example, the following overrides the publicAction property from the previous example:

<bean id="mail" class="org.alfresco.repo.action.executer.MailActionExecuter" parent="action-executer">



<property name="publicAction"> <value>false</value>  </property> <property name="mailService"> <ref bean="mailService"></ref> </property></bean>

4. Save the file.

Creating a customized configuration fileYou can override the default configuration items by customizing your own configuration file.

Customizing a configuration item is based on the following assumptions:

• You do not want to modify the data dictionary

• There are no files in the <extension> directory

1. Locate the file containing the default configuration item you want to customize.

2. Copy this file to a different directory.

This location would normally be the <extension> directory. However, you might want to createyour files outside the Alfresco directory structure to avoid overwriting them during an upgrade.

3. Customize the file.

4. Save the file.

5. Point to the file so that Alfresco knows where to find it. See Pointing to customized configurationfiles.

Pointing to configuration filesAfter you have customized a configuration item, you must point to the file from another file.

Alfresco configuration files are read at startup. Some files are read in automatically. These files, in turn,point to other files that are then read in, and so on.

The default configuration files are:

• Web client files

• All other configuration files

There are two types of location for your customization files:

• The <extension> directory (default)

• A directory outside your Alfresco directory structure. You might choose this location if you need toreinstall or upgrade Alfresco.

Note:

The files containing your customized configuration items can be stored anywhere, but your files that pointto those customized files must remain in the <extension> directory. For safety, always back up thecontents of <extension> to a location outside the Alfresco directory structure.

Pointing to web client files

The webClientConfigSource bean in web-client-application-context.xml points to the webclient files.

The default bean also points to one extension file in <extension>.

For example:



Pointing to other default configuration files

This section shows the process for how some default configuration files are pointed to.

1. The application-context.xml file contains a series of <import> statements. Two of thesestatements import the files core-services-context.xml and hibernate-context.xml.

2. The core-services-context.xml file contains a bean that pulls in therepository.properties file.

3. The hibernate-context.xml file contains a bean that pulls in thehibernate#cfg.properties file.

Pointing to customized configuration filesAssuming there are no files in the <extension> directory, you must use a combination of text searchesand file searches in <configRoot> and its subdirectories. Some specific examples are given in thefollowing topics, but the general procedure follows:

1. Locate the default configuration item you want to customize.

2. Note the name of the default file in which the configuration item appears.

3. Do a global text search within <configRoot> for any file that contains the file name for which youare looking.



4. Identify the file containing the pointer that causes the file to be pulled into Alfresco at startup.

5. Use one of the following two methods to point to your customized file:

• An <import> statement points directly to your file, which must have a suffix of .xml.

• An <import> statement points to a file, which must have a suffix of .xml. In turn, this filecontains a <bean> that points to your customized file, which can have a suffix of .xml or.properties (depending on the suffix of the default file).

Pointing to customized files for the web client

To point to extension files:

• Override the webClientConfigSource bean, and insert it into a new file. The following exampleshows one Windows file and one Linux file being pointed to for web client configuration items.

Pointing to customized files (non-web client) in an external directory

For external files, the file paths in the repository-properties bean contain paths outside theAlfresco directory structure.

For example:

<value>classpath:alfresco/extension/custom-repository.properties</value>

Pointing to files in the <extension> directory

How you point to a customized file is determined by whether your file already exists, or if you are adding anew file to the <extension> directory.

Existing files

If you modify any file that already exists in the <extension> directory, then that file is already pointed to.You do not need to take any further action.

New files



If you add a new file that ends in -context.xml to the <extension> directory, it will be found by thewildcard search in the file:

<configRoot>/alfresco/application-context.xml

If the new file ends in .properties, you must add a bean definition in which to load it.

If the new file does not end in -context.xml or .properties, you must create a file containing thefollowing line:

<import resource="file:..." />

Pointing to files outside the Alfresco directory structure

You must point to every external file. There are two types of files to which you can point:

• .xml file: pointed to by a <bean> or by an <import> statement

• .properties file: pointed to by a <bean>

In both cases, files are pointed to from -context.xml files in the <extension> directory.

Configuring databasesThis section describes how to configure supported databases for use with Alfresco.

Overriding database connection propertiesThis section describes how to override database properties.

1. Open the following files:

a. <extension>/custom-repository.properties.sample

b. <extension>/custom-hibernate-dialect.properties.sample

Lines in these files are commented (begins with the “#” sign).

2. Remove the “#” sign from the beginning of each line for the database you want to activate.

3. Type a "#" at the beginning of each line for the database you want to deactivate.

4. Save the files without the .sample extension.

You can either save the file in its current location (the <extension> directory), or in anotherdirectory.

If you save the file elsewhere, you must point to your customized file using the repository-properties bean in the <extension>/custom-repository-context.xml file.

See Pointing to customized files.

Configuring a MySQL databaseSetting up the MySQL database to work with Alfresco involves the following tasks:

1. Installing a MySQL database connector

2. Creating the Alfresco database

3. Configuring the MySQL database

Installing a MySQL database connector

The MySQL database connector is required when installing Alfresco with MySQL. The databaseconnector allows MySQL database to talk to the Alfresco server.



If you install Alfresco using one of the installation wizards, the MySQL database connector is already inthe correct directory.

1. Browse to the MySQL download site: http://dev.mysql.com/

2. Download MySQL Connector/J x.x, and extract the following file from the downloaded .zip or.tar.gz file:mysql-connector-java-5.x.x-bin.jar

3. Copy the JAR file into the <container>/lib for Tomcat 6.

The MySQL connector is installed. The next step is to create the Alfresco MySQL database.

Creating the Alfresco database

This section describes how to set up a MySQL database to work with Alfresco.Note: If you installed Alfresco using the installer, and chose the MySQL database, the Alfresco databaseis already created for you. To check that the database is created correctly, go to step 7.


2. Type the following:

• (Windows) cd <alfresco install dir>\extras\databases\mysql

• (Linux) cd <alfresco install dir>/alfresco/extras/databases/mysql

3. Press ENTER.

4. Type the following:

• (Windows) db_setup.bat

• (Linux) mysql –u root –p <db_setup.sql

5. Press ENTER.

6. At the Enter Password prompt, type admin or the password you used to install MySQL, and pressENTER to prepare the database.

7. To verify the database, type mysql -u root -p.

8. At the mysql prompt, type show databases;

A list of databases in MySQL should display, including one named alfresco. If you receive anerror message, add the mysql command to the Windows Path variable, and recreate the MySQLdatabase.

9. Browse to the MySQL data directory, and verify a folder Alfresco exists.The MySQL database is created in the Alfresco folder.

You have now created the Alfresco database. To replace the default database configuration for theMySQL (or other) database, you must modify the values in two files. See Configuring the MySQLdatabase.

Configuring the MySQL database connection

To replace the default database configuration, you must modify values in both custom-repository.properties and custom-hibernate-dialect.properties. These are locatedwithin the <extension> directory.

1. Browse to the <extension> directory.

2. Locate and open the following two files:

a. custom-hibernate-dialect.properties

b. custom-repository.properties

3. For both files:

http://dev.mysql.com



a. Use “#” to comment out any lines that refer to Derby.

b. Remove the “#” from the beginning of each line for references to MySQL.

Note: If you installed Alfresco using the installer, and chose the MySQL database, the databaseconnection properties are already uncommented.

4. In the custom-repository.properties, locate the following line:

dir.root=./alf_data

5. Edit the line, with an absolute path, to point to the directory in which you want to store Alfresco data.For example: dir.root=c:\alfresco\alf_data

6. Set the localhost and port number to the location of your MySQL JDBC driver.

7. Save the file.Note: You can either save the file in its current location in the <extension> directory, orin another directory. If you save the file in the <extension> directory, no further action isneeded because the file is already pointed to by the repository-properties bean in the<extension>/custom-repository-context.xml file.

If you save the file elsewhere, you must point to your customized file. See Pointing to files.

You have now configured the MySQL database to work with Alfresco.

Configuring a PostgreSQL databaseThis section describes how to configure a PostgreSQL database for use with Alfresco.

1. Copy the appropriate PostgreSQL driver JAR to:

• (Tomcat) \tomcat\lib

• (JBoss) /jboss/server/default/lib

2. Create a database named alfresco.

3. Create a user named alfresco.

4. Set the new user's password to alfresco.

5. Ensure the alfresco user has the required privileges to create and modify tables.

6. Verify and modify (if required) the Alfresco data location in the custom-repository.properties file.

7. Override the following repository properties in custom-repository.properties:

db.driver=org.postgresql.Driver db.name=alfresco db.url=jdbc:postgresql://localhost/<database name> db.username=alfresco db.password=alfresco

8. Override the following Hibernate properties in custom-hibernate-dialect.properties:

hibernate.dialect=org.hibernate.dialect.PostgreSQLDialecthibernate.query.substitutions=true TRUE, false FALSE

9. To allow password-authenticated connections through TCP/IP, ensure the PostgreSQLconfiguration file contains:

host all all 127.0.0.1/32 password

For PostgreSQL version 8.1.3, the file name is pg_hba.conf. For every other version, the filename is postgresql.conf.

10. Change the ownership of the directory tree specified in custom-data-location.properties.



The tree must be owned by the user running the Alfresco server.

11. Start up the Tomcat or JBoss server.

Configuring core servicesThis section describes how to configure Alfresco core services.

Tuning the JVMThe Alfresco repository and web client hardware requirements are variable and depend on the numberof concurrent users that access the system. Tune the memory and garbage collection parameters for theJVM to be appropriate for your situation. This section suggests metrics and estimates, but your systemmay vary.Note: Concurrent users are users who are constantly accessing the system through the Alfresco webclient with only a small pause between requests (3-10 seconds maximum) with continuous access 24/7.Casual users are users occasionally accessing the system through the Alfresco web client or webDAV/CIFS interfaces with a large gap between requests (for example, occasional document access during theworking day).

Disk space usage

The size of your Alfresco repository defines how much disk space you will need; it is a very simplecalculation. Content in Alfresco is, by default, stored directly on the disk. Therefore, to hold 1000documents of 1 MB will require 1000 MB of disk space. You should also make sure there is sufficientspace overhead for temporary files.

Use a server class machine with SCSI Raid disk array. The performance of reading/writing content isalmost solely dependent on the speed of your network and the speed of your disk array. The overheadof the Alfresco server itself for reading content is very low as content is streamed directly from the disksto the output stream. The overhead of writing content is also low but depending on the indexing options(for example, atomic or background indexing), there may be some additional overhead as the content isindexed or metadata extracted from the file information.

JVM memory and CPU hardware for multiple users

The repository L2 Cache with initial VM overhead and basic Alfresco system memory is set up with adefault installation to require approximately 512 MB (maximum).

This means you can run the Alfresco repository and web client with many users accessing the systemwith a basic single CPU server and only 512 MB of memory assigned to the Alfresco JVM. However, youmust add additional memory as your user base grows, and add CPUs depending on the complexity of thetasks you expect your users to perform, and how many concurrent users are accessing the client.

Note: For these metrics, N concurrent users is considered equivalent to 10xN casual users that theserver could support.

Number of users Recommended memory /CPU settings per server

For 50 concurrent or up to 500 casual users 1 GB JVM RAM 2x server CPU (or 1 x Dual-core

For 100 concurrent users or up to 1000 casual users 1 GB JVM RAM 4x server CPU (or 2 x Dual-core)

For 200 concurrent users or up to 2000 casual users 2 GB JVM RAM 8x server CPU (or 4 x Dual-core)

Thread stack size



The default thread stack size on Windows32bit/Linux32bit is 256K - which is quite large (for example, for500 users, 128MB will be used just for native thread stacks). This can be safely reduced on a Windowsmachine, Tomcat-based deployment using Java cmd arguments to a more sensible number, for example,-Xss64k is a good starting point.

Note: It is not recommended that you change this value on Linux.Permanent Generation (PermGen) Size

The default PermGen size in Sun JVMs is 64M, which is very close to the total size of permanent objects(Spring beans, caches, etc.) that Alfresco creates. For this reason it's quite easy to overflow the PermGenvia configuration changes or with the addition of custom extensions, and so it's recommended to increasethe PermGen to avoid OutOfMemory errors eg. -XX:MaxPermSize=128M is a good starting point. Notethat as of Alfresco v3.0, we've increased the size of the PermGen in the alfresco startup scripts, soprovided you're using those scripts no changes should be necessary.

Maximum JVM Heap Size 32/64bitAn important calculation to keep in mind is:(Managed Heap + native heap + (thread stack size * number of threads)) cannot exceed 2GB on 32bitx86 Windows or Linux systems

This is a limitation of the Sun Java VM. It means that even if you install 4GB of RAM into your server, asingle instance of the JVM cannot grow beyond 2GB on a 32bit server machine.

Note: Note that a 64 bit OS/JVM has much bigger values. It is recommended that a 64bit OS with largememory hardware (>2GB assigned to the JVM) is used for deployments of >250 concurrent or >2500casual users.

You can also setup your machine to cluster if you prefer to solve multi-user access performance issueswith additional machines rather than a single powerful server.

JVM settings

Alfresco generates a high proportion of temporary objects, both in client threads as well as in thebackground processes. In order to reduce the number of temporary objects into the OldGen portion of theheap, you need to set the NewSize option.

The following settings reduced the garbage collections and revealed (with GC printing and JMX tracing)that the OldGen was not growing noticeably over and above the permanent space allocated for caches.Cache sizes are still estimated top out around 520M. The StackSize should also be generously set to 1M.So, for a typical 32 bit installation:

JAVA_OPTS= -server -Xcomp -Xbatch -Xss1024K -Xms1G -Xmx2G -XX:+UseConcMarkSweepGC -XX:+CMSIncrementalMode -XX:NewSize=512m -XX:MaxPermSize=128M -XX:CMSInitiatingOccupancyFraction=80

Given that the OldGen is composed primarily of cache data of up to about 520M, at least 1GB should bereserved for OldGen. Once -Xmx increases, the OldGen can be increased to 2G. 512M should be left asa buffer to account for miscellaneous (PermGen, and so on). So the following variations might be applied:

-Xmx2G -Xms1G -XX:NewSIze=512M (OldGen at least 1G) -Xmx3G -Xms1G -XX:NewSize=512M (OldGen at least 2G) -Xmx4G -Xms2G -XX:NewSize=1G (OldGen at least 2.5G) -Xmx6G -Xms3G -XX:NewSize=2G (OldGen at least 3.5G) -Xmx8G -Xms4G -XX:NewSize=3G (OldGen at least 4.5G)



Command line configurationThe beans that load the repository and Hibernate properties will give preferential treatment to any JVM-set properties.

<configRoot>/alfresco/core-services-context.xml

<bean id="repository-properties" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"> <property name="ignoreUnresolvablePlaceholders"> <value>true</value> </property> <property name="locations"> <list> <value>classpath:alfresco/repository.properties</value> <value>classpath:alfresco/version.properties</value> <value>classpath:alfresco/domain/transaction.properties</value> <value>classpath:alfresco/jndi.properties</value> </list> </property> <property name="systemPropertiesModeName"> <value>SYSTEM_PROPERTIES_MODE_OVERRIDE</value> </property> </bean>

<configRoot>/alfresco/hibernate-context.xml

<bean id="hibernateConfigProperties" class="org.alfresco.config.SystemPropertiesFactoryBean"> <property name="systemProperties"> <list> <value>hibernate.dialect</value> <value>hibernate.query.substitutions</value> <value>hibernate.jdbc.use_get_generated_keys</value> <value>hibernate.default_schema</value> </list> </property> <property name="locations"> <list> <value>classpath:alfresco/domain/hibernate-cfg.properties</value> </list> </property> </bean>

Setting properties on the JVM

• (Windows) At a command prompt, enter the following:Set JAVA_OPTS=-Ddir.root=e:/alfresco/data

• (Linux) At a command prompt, enter the following:export JAVA_OPTS==Ddir.root=/srv/alfresco/data

Mixing bean overrides and system property settings

You can use a combination of mixing bean overrides and setting system properties for certaincustomizations. For example, if you wish to distribute a system that has a core set of propertiesoverridden but need to customize the last few for each installation, follow the steps.

1. Activate the samples (remove the .sample extensions):

a. <extension>/alfresco/extension/custom-repository-context.xml.sample

b. <extension>/alfresco/extension/custom-repository.properties.sample



c. <extension>/alfresco/extension/custom-hibernate-dialect.properties.sample

2. Set all common defaults for your system.

3. On each installation, add the final configuration values. For example:

-Ddb.username=alfresco-Ddb.password=alfresco -Dhibernate.dialect=org.alfresco.repo.domain.hibernate.dialect.AlfrescoOracle9Dialect-Dhibernate.default_schema=ALFRESCO_DEV-Dindex.tracking.cronExpression='0/5 * * * * ?' -Dindex.recovery.mode=AUTO -Dalfresco.cluster.name=ALFRESCO_DEV

Customizing dir.rootThe dir.root property is specified in<configRoot>/alfresco/repository.properties, andpoints to the directory alf_data containing the content and the Lucene indexes.

1. Open the file <extension>/custom-repository.properties.sample.

2. Locate the following line: dir.root=...Note: This line can differ depending on your installation.

3. Edit the line to point to the current location of the alf_data directory. For example, change the lineto: dir.root=c:\alfresco\alf_data

4. Save the file without the .sample extension.

You can either save the file in its current location in the <extension> directory, or in anotherdirectory.

If you save the file in the <extension> directory, no further action is needed because the fileis already pointed to by the repository-properties bean in <extension>/custom-repository-context.xml.

If you save the file elsewhere, you must point to your customized file. See Pointing to customizedconfiguration files.

Configuring new installationsThe information in this section refers to new installations as well as upgrades.

Before running the server for the first time, check the database connection details and Alfresco datafolder locations and set them according to the environment in which the server is running.

By default, the server creates a data folder for storing content binaries and indexes at a location relativeto the caller's location when the server starts. This is appropriate for quick previews and tests, but shouldbe changed when running a server that will be storing long-lived data.

1. Locate the distribution's extension configuration files and samples.

2. Remove the following .sample extension:<extensionRoot>/alfresco/extension/custom-repository-context.xml.sample

3. Remove the following .sample extension:<extensionRoot>/alfresco/extension/custom-repository.properties.sample

a. Choose a root location for the storage of content binaries and index files.

b. Adjust the properties to change the database connection details.

c. Note the choice of JDBC driver used with each connection type.



4. Remove the following .sample extension:<extensionRoot>/alfresco/extension/custom-hibernate-dialect.properties.sample

5. Choose a Hibernate schema most appropriate to your database (Hibernate Dialects).

6. Refer to the appropriate procedures and Readme files, and ensure that all instructions have beenfollowed.

7. Start the server.

The configuration overrides will ensure that the server immediately directs data to the appropriatelocations.

Configuring the repository cacheThe Alfresco repository uses Ehcache in-memory caches. These caches are transaction safe andclusterable. Caches greatly improve repository performance but they use Java heap memory.

Cache settings depend on the amount of memory available to your Alfresco server. The defaultehcache-default.xml file is enough for most systems and is currently set for 512MB of cache heapmemory. This is the recommended default for a Java heap size of 1GB.

For information on Ehcache, refer to: http://ehcache.sourceforge.net/

Individual cache settings

All cache settings are in: <configRoot>/alfresco/ehcache-default.xml.

Note: Do not directly modify this file.

Each cache is configured in an XML block similar to the following:

 <cache name="org.alfresco.repo.domain.hibernate.NodeImpl.childAssocs" maxElementsInMemory="25000" eternal="true" timeToIdleSeconds="0" timeToLiveSeconds="0" overflowToDisk="false" />

The comment shows the approximate amount of Java heap memory required for the specific example.Some object references are shared by the caches, so the amount of memory used is not as high as theapproximate value may suggest. It is best to err on the side of caution. Cache tracing can show whichcaches fill quickly for your specific server usage pattern.

nameThe name attribute is the name of the cache and generally indicates the type of objects being cached.

maxElementsInMemoryThe maxElementsInMemory controls the maximum size of the cache. This value can be changedto tune the size of the cache for your system. Ehcache caches are implemented using a linked-mapsystem, which means that memory is only required for objects that are actually in memory. If you setthe maxElementsInMemory to a high value, it will not automatically allocate that number of slots.Instead, they are added to the linked list as required. When maxElementsInMemory is reached, thecache discards the oldest objects before adding new objects.

timeToIdleSeconds - timeToLiveSecondstimeToIdleSeconds and timeToLiveSeconds control the automatic timeout of cached objects.

overflowToDiskoverflowToDisk controls whether the cache should overflow to disk rather than discarding oldobjects.

A typical trace is as follows:

The criteria are:

• (MissCount - CurrentCount) must be as low as possible.

http://ehcache.sourceforge.net/



• (HitCount/MissCount) must be as high as possible.

Estimated maximum size affects the permanent memory taken up by the cache. If the caches growtoo large, they may crowd out transient session memory and slow down the system. It is useful to havethis running, on occasion, to identify the caches with a low HitCount/MissCount ratio.

Tracing the caches

This task describes how to trace the repository caches.

1. To output detailed Ehcache usage information, set the following logging category to DEBUG:

org.alfresco.repo.cache.EhCacheTracerJob

2. Browse to the file <configRoot>/alfresco/scheduled-jobs-context.xml.

3. Override the following bean to change the trigger schedule:

ehCacheTracerJob

4. Override the following property to activate the trigger:

schedulerFactory

When triggered, the job will collect detailed cache usage statistics and output them to the log/console, depending on how logging has been configured for the server.

Configuring extended servicesThis section describes how to configure extended services in the Alfresco server.

Adding a MIME typeTo add a MIME type, you create two new files in the <extension> directory:

1. A file containing the added or modified MIME type

2. A file containing a <bean> that points to your new MIME type file

In both cases, the new files are created by copying default files and modifying them.

1. Browse to the directory: <configRoot>/alfresco/mimetype/

2. Open the following files:

a. mimetype-map.xml

b. mimetype-map-openoffice.xml

3. Study the contents of both files to learn about various MIME types.

4. Copy the pair of <mimetype> </mimetype> tags that is most similar to what you want to add.

5. Paste these tags in the <extension>\mimetypes-extension.xml.sample file immediatelyafter the <example> </example> tags.

6. Modify the inserted MIME type to match your requirements.


8. Ensure you have created and added the new file to the the <extension> directory so that you canpoint to your new file.

9. To point to your new file:

a. Browse to the file: mimetype-map-extension.xml.sampleThis file contains the following line, which points to your modified file:<value>classpath:alfresco/extension/mimetypes-extension.xml</value>



b. Save the file without the .sample extension.

Configuring metadata extractionMetadata extractors offer server-side extraction of values from added or updated content. Definitionsof the default set of extractors are in <WEB-INF>/classes/alfresco/content-services-context.xml.

1. Declare a new extractor in <extension-config>/alfresco/extension/custom-repository-context.xml.The following example shows a new extractor written in class com.company.MyExtracter:

<bean id="com.company.MyExtracter" class="com.company.MyExtracter"parent="baseMetadataExtracter" />

VersioningVersioning allows you to track content history. By default, content that is created in the repository is notversionable. When creating content, users must specify versionable on a case-by-case basis.

When content is versionable, the version history is started. The first version of the content is the contentthat exists at the time of versioning. If you want all content to be versionable at the instant of creation,you can modify the definition of that content type in the data dictionary. The definition must include themandatory aspect versionable.

By default, all versionable content has auto-version on. As a result, when content is updated, the versionnumber is updated. The auto-version capability can be turned off on a content-by-content basis in the UI.If you want auto-versioning to be off for all content, you can modify the definition of that content type inthe data dictionary.

Making all content versionable

1. Open the data dictionary <configRoot>/alfresco/model/contentModel.xml.CAUTION: Be very careful when modifying any Alfresco core file.

2. Search for the <type>: <type name="cm:content">

3. Immediately after the closing </properties> tag, insert the following lines:

<type name="cm:content"> <properties> ... </properties> <mandatory-aspects> <aspect>cm:versionable</aspect> </mandatory-aspects></type>

4. Save the file.

5. Restart the repository.

Disabling the auto-versioning feature

1. Open the data dictionary file: <configRoot>/alfresco/model/contentModel.xml

2. Search for the following <aspect>: <aspect name="cm:versionable">

3. Change the boolean default to false, as follows:

<property name="cm:autoVersion"> <title>Auto Version</title> <type>d:boolean</type>



<default>false</default></property>

4. Save the file.

5. Restart the repository.

Setting up replicationReplication allows you to continuously copy a database to a different server.

To enable replication you set one server (the slave) to take all its updates from the other server (themaster). During replication, no data is actually copied. It is the SQL statements that manipulate the datathat is copied.

All statements that change the master database are stored in the master's binary logs. The slave readsthese logs and repeats the statements on its own database. The databases will not necessarily be exactlysynchronized. Even with identical hardware, if the database is actually in use, the slave will always bebehind the master. The amount by which the slave is behind the master depends on factors such asnetwork bandwidth and geographic location. The other server can be on the same computer or on adifferent computer. The effect of replication is to allow you to have a nearly current standby server.

Using more than one server allows you to share the read load. You can use two slaves. If one of thethree servers fails, you can use one server for service while another server can copy to the failed server.The slaves need not be running continuously. When they are restarted, they catch up. With one or moreslaves you can stop the slave server to use a traditional backup method on its data files.

Each slave uses as much space as the master (unless you choose not to replicate some tables) and mustdo as much write work as the master does to keep up with the write rate. Do not be without at least oneslave or comparable solution if high reliability matters to you.

Note: Replication is not another form of back up. You must do normal backups as well as replication. If auser mistypes a DELETE statement on the master, the deletion is faithfully reproduced on the slave.

Setting up MySQL replication

1. Open a MySQL command prompt on the master server.

2. Grant the slave permission to replicate:

GRANT REPLICATION SLAVE ON *.* TO <slave_user> IDENTIFIED BY '<slave_password>'

3. If the master is not using the binary update log, add the following lines to my.cnf (Linux) ormy.ini (Windows) configuration file on the master, and restart the server:

[mysqld]log-binserver-id=1

Note: By convention, server-id for the master is usually server-id 1, and any slaves from 2 onwards,although you can change this. If the master is already using the binary update log, either note theoffset at the moment of the backup (the next step), or use the RESET MASTER statement to clearall binary logs and immediately begin the backup. You may want to make a copy of the binary logsbefore doing this if you need to use the binary logs to restore from backup.

4. Make a backup of the database.This will be used to start the slave server. You can skip this step if you use the LOAD DATA FROMMASTER statement, but first review the following comments about locking the master.

5. Add the following to the configuration file on the slave:

master-host=master-hostnamemaster-user=slave-usermaster-password=slave-password



server-id=2

The slave user and slave password are those to which you set when you granted REPLICATIONSLAVE permission on the master. The server-id must be a unique number, different to the master orany other slaves in the system. There are also two other options: master-port, used if the master isrunning on a non-standard port (3306 is default), and master-connect-retry, a time in seconds for theslave to attempt to reconnect if the master goes down. The default is 60 seconds.

Restore the data from the master, either as you would normally restore a backup or with thestatement LOAD DATA FROM MASTER. The latter will lock the master for the duration of theoperation, which could be quite lengthy, so you may not be able to spare the downtime.

Configuring the connection poolThis task describes how to to override the connection pool.

1. Open the file:<extensionRoot>/alfresco/extension/custom-connection-pool-context.xml.sampleYou can also set the basic pool information in custom-repository.properties. For example:

db.pool.initial=10 db.pool.max=100

2. Remove the .sample extension from this file.

3. Modify the properties where appropriate, paying particular attention to the validationQueryproperty.

For explanations of each property shown in the file, refer to: http://jakarta.apache.org/commons/dbcp/configuration.html

Customizing content transformationsThis task describes how to customize content transformations.

1. Copy the following file:

<configRoot>/alfresco/content-services-context.xml

2. Paste this file into the <extension> directory or in your preferred directory.

3. Open the file. Transformers start below the comment:



4. Locate the bean containing a transformer that is most similar to the transformer that you want toadd. (It is unlikely that you would want to modify an existing transformer.)

5. Delete every pair of <bean> </bean> tags except the pair containing the similar transformer.

6. Rename and modify the bean.

7. Save the file with a meaningful name.

If you save the file in the <extension> directory, the filename must end with #context.xml. Youdo not need to point to this file because of the wildcard pointer

<import resource="classpath*:alfresco/extension/*-context.xml" />

which is in the file

<configRoot>/alfresco/application-context.xml

Alternatively, if you save the file in a different directory, then continue with the procedure for pointingto your customized file.

http://jakarta.apache.org/commons/dbcp/configuration.html

http://jakarta.apache.org/commons/dbcp/configuration.html



Configuring a JMX interfaceThis section describes how to configure the Java Management Extension (JMX) for the Alfrescorepository server. The JMX interface allows you to access Alfresco through a standard JMX console thatsupports JMX Remoting (JSR-160).

This lets you change log levels and enable or disable file servers without having to stop and restart theAlfresco server.

Example consoles include:

• JConsole (supplied with Java SE 5.0 and higher)

• MC4J

• JManage

Some of these consoles also provide basic graphs and/or alerts for monitoring JMX-managed attributes.

Configuring access through a JMX console / JSR-160

You can connect to Alfresco through a JMX console that supports JSR-160.

1. Open a JMX console that supports JMX Remoting (JSR-160).

2. Enter the JMX URL and change <hostname> to the name of your host or IP address:service:jmx:rmi:///jndi/rmi://<hostname>:50500/alfresco/jmxrmi

3. Enter the JMX User name: controlRole

4. JMX Password: change_asap> Important: You must change the default JMX password as soon as possible. Refer to thefollowing files:

• <configRoot>/alfresco/alfresco-jmxrmi.access

• <configRoot>/alfresco/alfresco-jmxrmi.password

Configuring JMX properties

When you make changes through the JMX interface, such as changing a log level, these changes arelost after the server restarts. To set permanent changes, you can apply the change to the appropriateconfiguration file.

• To configure the file server:

Attribute Value

ftpEnabled true = enable FTP server, false = disable FTPserver

cifsEnabled true = enable CIFS server, false = disable CIFSserver

nfsEnabled true = enable NFS server, false = disable NFSserver

Note: This is not cluster-aware. If more than one file server is running (for example, load-balancedFTP), you must apply the change to each machine. This is not cluster-aware. Some consoles(for example, JManage) may provide basic facilities for accessing each machine in an applicationcluster.

• To configure the repository server:

Attribute Value



readOnly Set repository transaction mode. true =READONLY, false = WRITABLE

singleUserOnly Set single user name, for example, “admin” orblank to disable single user mode and allow alluser names.

maxUsers Limit for non-expired user logins. -1 if no limit set,0 to prevent further logins

linkValidationDisabled Disable or enable link validation service.

These managed attributes/operations are cluster-aware.

• To change the log level, edit log4j.properties on the classpath.

• To change max users, edit the server.maxusers property in the custom repositoryproperties file.

• To change single-user mode, edit server.singleuseronly.name property in the customrepository properties file.

• To change read-only mode, edit the server.transaction.allow-writes property in thecustom transaction properties file.

• To disable/enable file servers (FTP/CIFS/NFS), edit the custom file servers config xmlfile.

Configuring the file systemThis section describes how to configure various aspects of the file system. These include:

• Repository file systems

• AVM/WCM file systems

• Web-based Distributed Authoring and Versioning (WebDAV)

• Common Internet File System (CIFS)

• File Transfer Protocol (FTP)

• Network File System (NFS)

• Access Control Lists (ACLs)

File system configurationThe file systems available to the file servers are configured in the WEB-INF\classes\alfresco\extension\file-servers-custom.xml file using the Filesystems configuration section.There are two types of file system included in Alfresco:

• repository file system

• AVM/WCM file system

The repository shared file systems are configured using the <filesystem> tag, and the AVM/WCMshared file systems are configured using the <avmfilesystem> tag.

Repository file systems

This section describes how to configure repository file systems.

Use the <filesystem name="..."> tag to create a repository file system with the specified name.



The file system requires a store name and root path. The default configuration creates an Alfresco filesystem using the following:

<filesystems> <filesystem name="Alfresco"> <store>workspace://SpacesStore</store> <rootPath>/app:company_home</rootPath> [<relativePath>/My Space</relativePath>] </filesystem></filesystems>

The <relativePath> tag is optional and specifies the root of the file system at a particular folder.The relative path can be specified using forward or back slashes, and may contain multiple levels. Therepository file system supports the adding of pseudo files into the file system to provide URL link files thatlink to the web location of a CIFS folder, and/or special applications that run on the client side known asdesktop actions.

Use the <disableNodeMonitor/> tag to disable the monitoring of node service events for this filesystem. Node service monitoring is used to generate CIFS change notifications and update the filestate cache when nodes are added, deleted, or updated outside of the file server. This includes ruleprocessing, where files may be moved or new files generated.

Configuring WCM/AVM file systems

This section describes how to configure AVM file systems.

Use the <avmfilesystem name="..."> tag to create an AVM file system with a specified name.

To configure the AVM file system, enter tags in the <extension>/file-servers-custom.xml file.You can also map the file system to an individual store within AVM, or you can use a pseudo folder at thetop of the hierarchy to create a view to all available stores.

The default filtering is equivalent to:

<avmfilesystem name="AVM"> <virtualView stores="site,staging,author" /></avmfilesystem>

Creating an AVM file system mapped to a store:

1. Open the <extension>/file-servers-custom.xml file.

2. Enter the following tags:

<filesystems> <avmfilesystem name="STORE"> <storePath>main:/</storePath> [<version>-1</version>] [<createStore/>] </avmfilesystem></filesystems>

Note:

The <storePath> value contains the store name, and, optionally, a relative path. The <version>value contains the version of the store to be shared; this defaults to -1, which allows writing to thestore. If the <version> value is not -1, the file system is read-only.

You can use the <createStore/> tag to create a new store when the server is started. The newstore will only be created if it does not already exist.

3. Save the file.

Sharing all available stores as separate shares:





<filesystems> <avmAllStores/></filesystems>

Note: The <avmAllStores/> tag creates a shared file system for each available store, using thesame name as the store. The shared file systems are writeable as they share the head version ofthe stores.

3. Save the file.

Sharing all AVM stores with access to all versions of stores:

By default, the virtualization view filters out workflow preview and author preview sandboxes/stores, andonly shows the web project store and author store for the user who is logged in. If the user is a contentmanager on one or more web projects, then all author sandboxes are shown. For the admin user, allsandboxes are shown.

The <virtualView/> configuration tag has an optional attribute called stores, which is used tospecify the types of stores/sandboxes you can see in the virtualization view as a comma-delimited list.The default view will show staging and author sandboxes/stores, with the access control filtering appliedto the view on a per user basis.

The following are available store/sandbox types:

normalShow normal stores, which are not part of a web project.

siteShow site stores relating to the Share application.

stagingShow web project staging sandboxes; the web project sandbox will be read-only to normal users.

authorShow author sandboxes; the sandbox will be writable.

previewShow staging preview and author preview sandboxes.



<filesystems> <avmfilesystem name="AVM"> <virtualView [stores="normal,site,staging,author,preview"]/> </avmfilesystem></filesystems>

3. To create multiple AVM/WCM views, add multiple file system definitions to the file-servers.xmlusing a unique name for each file system definition.The virtualization view shows all stores and versions using the following layout:

[store name] \HEAD \DATA \[folder] .. \METADATA \VERSION \vn \DATA \[folder] .. \METADATA



.. \v-1 \DATA \[folder] .. \METADATA[store name]..

4. Save the file.

Configuring WebDAVWeb-based Distributed Authoring and Versioning (WebDAV) lets you manage content on a remote webserver. This lets you use your own tools to edit content on the Alfresco server.

1. Browse to the WEB-INF folder, and open the web.xml file.WebDAV is enabled by default in the standard web.xml file through the following entries:

<servlet> <servlet-name>WebDAV</servlet-name> <servlet-class>org.alfresco.repo.webdav.WebDAVServlet</servlet-class> <init-param> <param-name>store</param-name> <param-value>workspace://SpacesStore</param-value> </init-param> <init-param> <param-name>rootPath</param-name> <param-value>/app:company_home</param-value> </init-param> <load-on-startup>5</load-on-startup> </servlet>

<filter> <filter-name>WebDAV Authentication Filter</filter-name> <filter-class>org.alfresco.repo.webdav.auth.AuthenticationFilter</filter-class>  </filter>

<servlet> <servlet-name>WebDAV</servlet-name> <servlet-class>org.alfresco.repo.webdav.WebDAVServlet</servlet-class> <init-param> <param-name>store</param-name> <param-value>workspace://SpacesStore</param-value> </init-param> <init-param> <param-name>rootPath</param-name> <param-value>/app:company_home</param-value> </init-param> <load-on-startup>5</load-on-startup> </servlet>

<filter-mapping> <filter-name>WebDAV Authentication Filter</filter-name> <url-pattern>/webdav/*</url-pattern> </filter-mapping>



<servlet-mapping> <servlet-name>WebDAV</servlet-name> <url-pattern>/webdav/*</url-pattern> </servlet-mapping>

2. Modify the WebDAV configuration section as required, and save the file.

3. To access the Alfresco server, use the URL: http://localhost:8080/alfresco/webdav.

4. To open a space in WebDAV:

a. In the Alfresco repository, browse to the space you want to access.

b. Click the Detailed View link of the space.

c. In the Links section, click View in WebDAV.

Configuring CIFSThe Common Internet File System (CIFS) server lets you map an Alfresco space as a folder in your localfile system. Once a space is mapped as a network folder, you can browse the space as if it were yourlocal folder.

The name to use for the mapping is based on the name of the server on which Alfresco is running, witha letter A on the end. For example, if the computer name is MYPC01, then the CIFS server name will beMYPC01A.

Note: The CIFS server is configured by default when you install Alfresco.

Before you start:

• Ensure that the Alfresco server has been started at least once before you configure the domain forCIFS.

• To access the repository directly from Firefox, install the Alfresco Firefox extension from: http://sourceforge.net/projects/alfrescoNote: Internet Explorer does not require the extension to open CIFS folders directly.

1. To check if the CIFS server is running, open a command prompt, and type nbtstat -n.The CIFS server name displays if the CIFS server is running. If you cannot connect to the CIFSserver, you might need to configure the domain for CIFS to use, depending on your network.

2. Browse to the <extension> folder.

3. Open file-servers-custom.xml.

4. Browse to the WEB-INF/classes/alfresco folder.

5. In the CIFS server configuration section of the file-servers.xml file, copy the completesection between <config>and </config>.

6. Paste the copied section into file-servers-custom.xml.For example:

<config evaluator="string-compare" condition="CIFS Server"><serverEnable enabled="true"/><host name="${localname}A"/>......</config>

7. In file-servers-custom.xml, set the domain by adding the domain to the end of the followingline: <host name="${localname}A"/>



<host name="${localname}A" domain="MYDOMAIN"/>

8. Configure other values as desired. The following table provides some examples.

Value Description

<serverEnable enabled="true|false"/> Enables or disables the CIFS server.

<host name="..." [domain="..."]/> Specifies a host name for the CIFS server anddomain this server belongs to (16 charactermaximum). Use the name attribute for the specialtoken of {localname} to use the local servers hostname and generate a unique name by prepending/appending to it. The domain attribute is optional,and specifies the domain or workgroup to whichthe server belongs. This defaults to the domain/workgroup of the server if not specified.

<comment>...</comment> Displays comment to appear as the window title.

<broadcast>n.n.n.n</broadcast> Specifies the broadcast mask for the network (onlyrequired if the Java socket based protocols are beingused).

<bindto>n.n.n.n</bindto> Specifies the network adapter to bind the Java socketbased interfaces to (if not specified the server willbind to all available adapters/addresses).

<tcpipSMB [platforms="..."]/> Enables native SMB on port 445 that is used byWin2000 and above clients.

<netBIOSSMB [bindto="..."][platforms="..."]/>

Enables the Java socket-based NetBIOS over TCP/IP implementation. The bindto attribute is optional,and specifies the network adapter to bind to. If itis not specified, NetBIOS will bind to all availableadapters/addresses. Overrides the global bindtosetting. To enable the Java socket-based NetBIOSimplementation under Windows requires thatNetBIOS is disabled on one or all network adapters.Use the Network Connections control panel in theadvanced TCP/IP properties for each adapter.

<hostAnnounce [interval="..."]/> Enables the announcement of the CIFS server tothe local domain/workgroup so that it shows up inNetwork Places/Network Neighborhood. The optionalinterval attribute specifies the announcementinterval in minutes. This value is only applicable whensocket based NetBIOS over TCP/IP is enabled.

<WINS> Specifies a primary and secondary WINS server toregister the server name with when using the Javasocket-based NetBIOS interface. For example:

<WINS> <primary>90.1.0.1</primary> <secondary>90.1.0.2</secondary></WINS>

<Win32NetBIOS [name="..."][api="winsock|netbios"]/>

Enables the JNI-based NetBIOS interface code underWindows; by default, api="winsock". On all otherplatforms this value is ignored. The optional nameattribute can be used to specify a different name forthe server than the name specified via the <host>tag. The optional api attribute specifies whether theJNI code uses the Win32 Netbios() API call or usesWinsock calls.



<Win32Announce [interval="..."]/> Enables annoucement of the CIFS server to the localdomain/workgroup so that it shows up in NetworkPlaces/Network Neighborhood. The optional intervalattribute specifies the annoucement interval inminutes. This value is only applicable when the JNIbased NetBIOS interface is enabled.

<sessionTimeout>n</sessionTimeout> Specifies the CIFS session timeout value in seconds.The default session timeout is 15 minutes. If no I/Ooccurs on the session within this time, then the servercloses the session. Windows clients send keep-aliverequests, usually within 15 minutes.

<disableNIO/> Disables the new NIO-based CIFS server code andreverts to using the older socket and JNI based code.

<sessionDebug flags="...,..."/> Enables debug output levels for CIFS serverdebugging (you must also set the desired level oflogging in the log4j.properties file).

9. Save file-servers-custom.xml.

10. Restart the Alfresco server for any changes to take effect.

Configuring FTPFile Transfer Protocol (FTP) lets you transfer files from your local file system to the Alfresco server.

1. Browse to the <extension> directory.

2. Open the file-servers-custom.xml file.

3. Browse to the the WEB-INF/classes/alfresco folder.

4. In file-servers.xml, copy the <config evaluator="string-compare"condition="FTP Server">.

5. Paste the copied section to:file-servers-custom.xml

6. Configure other values as required, for example:

Value Description

<serverEnable enabled="true|false"/> Enables or disables the FTP server

<debug flags="...,..."/> Enables debug output levels for FTP serverdebugging

<port>...</port> Specifies the port the FTP server listens for incomingconnections on (default port 21). On Linux or Solaris,you can also use port 1024 if you are not using theroot account.

<bindto>...</bindto> Specifies the address to which the FTP server binds

<rootDirectory>...</rootDirectory> Specifies the path of the root directory as an FTPformat path, such as using forward slashes

7. Save the file-servers-custom.xml file.

Configuring the NFSThis section describes how to configure the Network File System (NFS) server.

The NFS server is configured when Alfresco reads the file-servers.xml file in the \classes\alfresco folder. To set your own customizations, use the NFS server configuration section in the<extension>/file-servers-custom.xml file.



A TCP connection should be used to connect to the Alfresco NFS server. To help optimize theperformance, use a read/write size of 32K.

1. Browse the <extension> folder.

2. Open file-servers-custom.xml.

3. In the NFS server configuration section, configure the NFS server as required. For example, add theconfiguration values as follows:

<config evaluator="string-compare" condition="NFS Server"> <serverEnable enabled="true"/> </config>

The following table provides configuration value examples.

Value Description

<serverEnable enabled="true|false"/>

Enables or disables the NFS server.

<enablePortMapper> Enables the built-in portmapper service. This would usuallybe enabled on Windows where no default portmapper serviceexists. Under Linux/Unix operating systems, the built-inportmapper service can be used, which also saves having to runthe Alfresco server using the root account.

<ThreadPool>n</ThreadPool> Sets the size of the RPC processing thread pool. The minimumnumber of threads is 4, the default setting is 8.

<PacketPool>n</PacketPool> Sets the size of the packet pool used to receive RPC requestsand send RPC replies. The minimum number of packets is 10,the default setting is 50.

<PortMapperPort>n</PortMapperPort>

Sets the port number on which to run the portmapper service.The default port is 111.

<MountServerPort>n</MountServerPort>

Sets the port number on which to run the mountserver service.The default is to allocate an available non-privileged port.

<NFSServerPort>n</NFSServerPort>

Sets the port number on which to run main NFS server service.The default is to allocate the default NFS port: 2049. This willlikely clash with a running native NFS server.

<rpcAuthenticator> Configures the user id/group id to Alfresco user name mappingsthat are used by the current RPC authentication implementation.

<debug flags="...,..."/> Enables debug output levels for NFS serverdebugging. The log4j.properties file must alsohave NFS protocol debug output enabled using:log4j.logger.org.alfresco.nfs.server=debug

4. Save file-servers-custom.xml.


Configuring file server ACLsThe file systems that are configured in the file-servers.xml file can have access controls appliedto restrict access to read, read/write, or no access. The access control blocks can be specified perfile system, globally applied to all file systems, or file systems that do not have their own set of accesscontrols.

When the access control block has any rules defined, the default access may also be specified as None.If an SMB/CIFS client is granted None access to a file system, that file system will not appear in thebrowse list of available shares for that client. The access control block may contain a number of rules thatallow or disallow a particular client access to the file system. The rules are processed so that the clientreceives the highest access level.



1. Browse to the WEB-INF/classes/alfresco folder.

2. Open file-servers.xml.

3. Set rules as required. The following table provides configuration options.

Rule Description

<accessControl default="Read|Write"/> Set the default access control block for a file system.

<user name="..." access="Read|Write|None"/>

If the user matches name, then grant them accessaccess to the file system.

<protocol type="SMB|CIFS|FTP"access="Read|Write|None"/>

Grant access depending on the protocol being usedto access the file system.

<address subnet="n.n.n.n"mask="n.n.n.n" access="Read|Write|None"/>

Grant access depending on the client TCP/IPaddress.

<address ip="n.n.n.n" access="Read|Write|None"/>

Grant access to the specified TCP/IP address.

<domain name="..." access="Read|Write|None"/>

Grant access to SMB/CIFS clients from the specifieddomain.

4. To specify a global access control block in the File system Security section of the file-servers.xml file, use the following configuration:

<globalAccessControl default="None"> <user name="admin" access="Write"/> <address ip="90.1.0.90" access="Write"/></globalAccessControl>

The global access controls are applied to all file systems that do not have their own specific accesscontrols.

5. To make a file system read-only, use the following configuration:

<filesystem name="Alfresco"> <store>workspace://SpacesStore</store> <rootPath>/app:company_home</rootPath> <accessControl default="Read"/> </filesystem>

6. To allow read access to clients in the 90.1.x.x subnet with the admin user being allowed writeaccess, use the following configuration:

<filesystem name="Alfresco"> <store>workspace://SpacesStore</store> <rootPath>/app:company_home</rootPath> <accessControl default="None"> <address subnet="90.1.0.0" mask="90.1.255.255" access="Read"/> <user name="admin" access="Write"/> </accessControl> </filesystem>

7. To allow read access for SMB/CIFS with the admin user allowed write access but not FTP access,use the following configuration:

<filesystem name="Alfresco"> <store>workspace://SpacesStore</store> <rootPath>/app:company_home</rootPath> <accessControl default="None"> <protocol type="CIFS" access="Write"/> <user name="admin" access="Write"/> </accessControl> </filesystem>



8. Save file-servers.xml.


Configuring the virtualization serverThe virtualization server interprets data in the AVM repository as a set of virtual websites, allowing usersto preview these websites before submitting them. These websites may include virtualized servlets andJSPs, but completely static websites can be virtualized too ( for example, .html, .gif, .png).

Each virtual view corresponds to a virtual website within its own virtual host. You can see the virtual viewin the URL itself. The following URL shows the general format of an Alfresco virtual hyperlink:

http://virtual-hostname.www--sandbox.virtualization-domain:port/request-path

To configure virtual websites, the virtualization-domain and all its subdomains must resolve inDNS to the IP address of the virtualization server (also known as a “wildcard DNS” mapping). There aretwo ways to achieve this:

• Using the appropriate subdomain of ip.alfrescodemo.net (see Using ip.alfrescodemo.net)

• Configuring a nameserver, and setting up a wildcard domain pointing at your Virtualization server'sIP address (see Configuring wildcard DNS on a nameserver)

Using ip.alfrescodemo.netThis task lets you set up virtualization for a single machine or a LAN by using the appropriate subdomainof ip.alfrescodemo.net.

1. Set the directory in which you installed the virtualization server as $VIRTUAL_TOMCAT_HOME.In this example, 192.168.1.5 is the IP address of the machine hosting the virtualization server.

2. Open the file $VIRTUAL_TOMCAT_HOME/conf/alfresco-virtserver.properties.

3. Locate the property alfresco.virtserver.domain=127-0-0-1.ip.alfrescodemo.net.

4. Edit the property to contain the hyphen-encoded IP address you want.For example: alfresco.virtserver.domain=192-168-1-5.ip.alfrescodemo.net.> Important: When specifying alfresco.virtserver.domain that usesip.alfrescodemo.net, the IP address for a DNS wildcard domain must be hyphen-encoded.Otherwise, ip.alfrescodemo.net will assume an error, and return 127.0.0.1 for all DNS namelookups within your malformed virtualization domain.For example:

Valid: alfresco.virtserver.domain=192-168-1-5.ip.alfrescodemo.net

Malformed: alfresco.virtserver.domain=192.168.1.5.ip.alfrescodemo.net

The Alfresco webapp can now generate URLs that address the virtualization server's network-accessible address, such as 192.168.1.5 and not 127.0.0.1, allowing users on a LAN to usein-context preview.

5. Restart the Tomcat instance that runs the Alfresco webapp.

6. Near WCM assets, click the icon resembling an eyeball.A list of URLs displays, for example: http://<hostname>.www--sandbox.192-168-1-5.ip.alfrescodemo.net

These links will resolve to your virtualization server on 192.168.1.5.

7. To view this in isolation, run one of the following commands:

• ping alice.mysite.www--sandbox.192-168-1-5.ip.alfrescodemo.net

• ping mysite.www--sandbox.19



Configuring wildcard DNS on a nameserverThis task describes how to configure a nameserver, and set up a wildcard domain pointing at yourvirtualization server machine's IP address to:

• Virtualize content on a machine or LAN with no access to the Internet (for example: a demo laptop)

• Attain faster speeds on the first DNS lookup of a name than when served locally (IP addressanswers have a one day TTL)

• Keep everything centralized if you already have BIND, djbdns, Microsoft DNS, or other DNS solutionin place

• Be independent from Alfresco's alfrescodemo.net uptime

1. Set the directory where you installed the virtualization server, for example:$VIRTUAL_TOMCAT_HOME.In this example, the LAN's domain name is localdomain.lan, a wildcard DNS recordresolves to an IP address such as 192.168.1.5, and the wildcard DNS names are withinip.localdomain.lan.

2. Open the file $VIRTUAL_TOMCAT_HOME/conf/alfresco-virtserver.properties.

3. Modify the value of the alfresco.virtserver.domain property to resemble the following:alfresco.virtserver.domain=ip.localdomain.lanNote: You cannot use the “hosts” file to create a wildcard DNS domain on Windows or Unix. Tocreate a DNS wildcard that is usable when you are not connected to the Internet, you must install,configure, and maintain a real nameserver.

Enabling WCM links validationThe check links action is used to validate links in the web project and generate a report detailing brokenhyperlinks so they can be corrected. By default, links validation is disabled. This section describes how toenable links validation.

1. Open the <extension>/custom-repository.properties file.

2. Add the following property:linkvalidation.pollInterval=5000

3. Save your file.

4. Restart the Alfresco server and the virtualization server.

Links validation is enabled and visible in the graphical interface.

Configuring the FSRThe FSR is a server that receives updates from an Alfresco repository running Web Content Managementand publishes the updates to a flat file system..

The destination file server receiver has to be running with its RMI registry port and service port (44100and 44101 by default) accessible.

Before you start, you must have installed the FSR. See Installing the FSR.

1. Browse to the directory where you installed the FSR, for example:

• (Windows) C:\alfresco\deployment

• (Linux) /opt/alfresco/deployment

2. Open the deployment.properties file and modify the following values as required:



a. dep.datadir - Location for the FSR to store its temporary data

b. dep.logdir - Location for the FSR to store its log data

c. dep.metadatadir - Location for the FSR to save metadata

d. dep.rmi.port - Port number of the RMI registry (default 44100)

e. dep.rmi.service.port - Port number for the deployment service (default 44101)

3. Save the deployment.properties file.

4. Open the application-context.xml file and modify the following lines in the configurationbean:

a. Modify the root value to indicate where the FSR should place the deployed files, for example,./target.<entry key="root"><value>target</value></entry>

b. Modify the user value to restrict access to the FSR, for example, admin.<entry key="user"><value>admin</value></entry>

c. Modify the password value to restrict access to the FSR, for example, admin.<entry key="password"><value>admin</value></entry>

5. Add the errorOnOverwrite property.

If there is a mismatch between the metadata and the target file system, there may be errors duringdeployment. For example if a file is deleted by hand to the target file system. This parameter is usedto configure what the FSR should do if it attempts to delete a file that does not exist or create a filethat is already there.

6. Save the application-context.xml file.

7. Locate the <WEB-INF>/classes/alfresco/deployment-service-context.xml file.

8. Copy the file to the <extensions> directory.

9. Open the file and modify the value of the numberOfSendingThreads property in thedeploymentService bean.This property is used to assist with situations where files are deployed over a network with highlatency. The deployment client is multi-threaded and sends several files at once. The default valueis 5 sends in parallel. To change the number of sends in parallel, modify the value.

10. Save the <extensions>/deployment-service-context.xml file.

11. Locate the <WEB-INF>/classes/alfresco/action-services-context.xml file.This file contains the Action Service, which controls how many deployments happen in parallel.

12. Copy the file to the <extensions> directory.

13. Open the file and modify the value of the corePoolSize property in thedeploymentAsyncThreadPool bean.If you need to deploy to many servers, then you may need to increase the number of deploymentsin parallel. If you run out of processing power or memory, then you may need to reduce this setting.The default value is 2.

14. Save the <extensions>/action-services-context.xml file.

The FSR is now configured.

The log directory is used to store log files, which track the status of a deployment as it is in progress. Youmay delete these files to save disk space, but make sure you do not attempt to delete the log file of adeployment that is in progress.



The FSR uses a temporary directory to store content prior to a deployment being committed. During thecommit phase of a deployment, content is copied from this temporary directory to the destination filesystem. This file system should only contain data during a deployment.

• To start and stop the FSR, see Starting and Stopping a FSR.

• To upgrade the FSR, see Upgrading an FSR.

FSR MetadataThe FSR uses a simple repository of metadata to track which files, directories, and versions are on thetarget file system.

The FSR automatically maintains the metadata. FSR metadata reduces the amount of files that need tobe deployed.

The location of the metadata is configured through the ${dep.metadatadir} property.

The FSR can validate that the metadata and the target deployment are consistent. Validation occurs afterthe FSR starts up and after the FSR detects an inconsistency. For example, if you try to delete a file thatdoes not exist or overwrite a file that was outside the control of the FSR. The FSR either issues an errorupon detecting a problem or automatically fixes the problem. The autoFix parameter in the definition ofthe Target controls whether the FSR will attempt to fix the metadata itself or just issue a warning.

To force a full redeploy, you can safely delete the contents of the metadata directory.

Note: Do not delete the contents of the metadata directory when a deployment is already in progress.

Configuring the email server and email serviceThis section describes how to enable and configure the email server and service to run in the same JVMcontext as the repository itself, and remotely using Remote Method Invocation (RMI).

Configuring the email serverThis section describes how to change the behaviour of the email server and email service.

This is done using the properties file custom-email-server.properties in <ext-config>/alfresco/extension/.

1. Locate and unzip the file custom-email-server.sample.zip.The following files are extracted:

• custom-email-server-context.xml

• custom-email-server.properties

2. Open the following file:custom-email-server.properties

3. Modify the behaviour of the Alfresco email server and email service in this file as required.

The following table provides configuration examples.

Value Description

email.inbound.enabled=true Enables or disables the inbound email service. Theservice could be used by processes other than theemail server (for example, direct RMI access), so thisflag is independent of the email service.

email.inbound.unknownUser=anonymous Specifies the user name to authenticate as when thesender address is not recognized.



email.server.enabled=trueemail.server.port=25

email.server.domain=alfresco.com

Specifies email server properties.

email.server.allowed.senders= Provides a comma-separated list of email REGEXpatterns of allowed senders. If there are any valuesin the list, then all sender email addresses mustmatch. For example: .*\@alfresco\.com, .*\@alfresco\.org

email.server.blocked.senders= Provides a comma-separated list of email REGEXpatterns of blocked senders. If the sender emailaddress matches this, then the message will berejected. For example: .*\@hotmail\.com, .*\@googlemail\.com

Configuring the RMI email serviceYou can run the email server remotely on a separate JVM and server, and have it interact with theAlfresco server using Remote Method Invocation (RMI). RMI is configured via the remote-email-service-context.xml configuration file.

1. Browse to the folder WEB-INF\classes\alfresco.

2. Open the configuration file remote-email-service-context.xml.This file contains the emailService bean, specifying the related RMI configuration.

3. Modify the RMI configuration as required. For example:

Value Description

<serviceUrl></serviceUrl> Specifies the valid RMI Url.

<serviceInterface></serviceInterface> Specifies the interface used for RMI.

Configuring the email serviceThis section describes how to configure the email service email-service-context.xml file in theWEB-INF\classes\alfresco folder.

1. Browse to the WEB-INF\classes\alfresco folder.custom-email-server.properties

2. Open the file email-service-context.xml.This configuration file defines spring beans.

Properties of the bean with the id = “emailServerConfiguration” contain values for emailserver configuration.

3. Modify the values in this file as required.

The following table provides examples.

Value Description

<domain> </domain> Specifies the domain, for example,alfresco.mycompany.com.

<port> </port> Specifies the port the email server listens forincoming connections on. Defaults to port 25. Onsome platforms ports below 1024 require the serverto be run under a privileged account.

<blockedSenders></blockedSenders> Specifies the domains of the blocked list.



<allowedSenders></ allowedSenders> Specifies the domains of the allowed list.

Handling messages by target node typeThese are the default behaviours for incoming email to different types of referenced nodes. You canmodify or extend the default behaviours by adding in custom handlers.

Folder(Space)Content added with emailed aspect

Forum(Discussion)Content specialized to Post with emailed aspect; if email subject matches a topic, then add to topic,otherwise create new topic based on subject

Topic(Post)Content specialized to Post with emailed aspect; if referenced node is a Post, add to Post’s parentTopic

Document(Content)If discussion exists, same as for forums, otherwise add discussion with email as initial topic and post

Configuring security and authenticationThis section provides information to help you configure security and authentication in Alfresco. Thefollowing topics are included:

• Configuring SSL communication between two Alfresco servers

• Configuring CIFS server authentication

• Configuring the CIFS server for Kerberos/Active Directory

• Setting up NTLM authentication

• Setting up JAAS authentication

• Chaining authentication

Configuring SSL communication between the Alfresco repository andShareThis task provides information for encrypting communication between the Alfresco repository and theAlfresco Share Tomcat servers using SSL.

These instructions describe how to secure communications between two Tomcat instances on the samemachine without using a Certificate Authority for testing and debugging. For production environments,obtain a certificate from an authorized Certificate Authority.

1. Open a command prompt, and type the following in your jre\bin directory (for example: C:\Program Files\Java\jre1.6.0_07\bin)keytool -genkey -v -alias tomcat -keyalg RSA -validity 3650 -keystore /path/to/my/tomcat.keystore -dname "CN=localhost, OU=MYOU, O=MYORG,L=MYCITY, ST=MYSTATE, C=MY"

For example:

keytool -genkey -v -alias tomcat -keyalg RSA -validity 3650 -keystore "C:\Documents and Settings\Administrator\.keystore" -dname "CN=localhost,OU=SHARE, O=ALFRESCO, L=MAIDENHEAD, ST=BERKS, C=UK"

This creates the key and certificate for the Tomcat servers.



2. Enable the SSL connector in the Alfresco repository Tomcat's conf/server.xml, matching thedetails to the certificate information from the previous step.

  <Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystorefile="C:\Documents and Settings\Administrator\.keystore" keystorepass="changeit" truststorefile="C:\Documents and Settings\Administrator\.keystore" truststorepass="changeit" />

3. Modify the Alfresco Share startup command to point to the keystore by adding the following to theJAVA_OPTS, matching the details to the certificate information from step 1.

-Djavax.net.ssl.trustStore="C:\Documents and Settings\Administrator\.keystore" -Djavax.net.ssl.trustStorePassword=changeit

4. Modify the Alfresco Share config file webscript-framework-config-custom.xml thatspecifies the URL to connect to the Alfresco repository.

5. Modify any URLs to use the address specified in the configuration from step 2.For example:

<endpoint-url>https://localhost:8443/alfresco/s</endpoint-url>

6. (Optional) Enable SSL in Alfresco Share for secure connections from your browser to AlfrescoShare in the Alfresco Share Tomcat file conf/server.xml.

  <Connector port="8444" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" />

7. To enable debugging on the SSL connection, add the following to the alfresco.bat JAVA_OPTS:-Djavax.net.debug=all

8. To present Alfresco Share with the normal HTTPS address 8443, switch the configuration soAlfresco Share uses 8443, and Alfresco repository uses 8444 (or any port of your choice).

9. Ensure that you configure the connection URLS in step 4 to use the SSL port of the Alfrescorepository.

If you want to extend the communication between an Alfresco repository and Share running on separatemachines, see the Java documentation about exporting and importing keys.

Configuring CIFS server authenticationThe Alfresco CIFS server supports three authenticators:

1. Default Alfresco authenticator

2. Passthrough authenticator

3. Enterprise authenticator

Configuring the default authenticator

The CIFS server default authenticator uses NTLMv1 password hashing and offers the following additionaloptions:



• <allowGuest/>: allows access when the client uses the guest user name to connect

• <mapUnknownUserToGuest/>: maps client user names that are not in the user database to theguest user

The default configuration does not allow guest access. However, you can override the default to enableguest access, and specify that unknown users are automatically granted guest access.

1. Open the file <extension>/file-servers-custom.xml.sample.

2. Locate the <config> for <authenticator type="alfresco">.

The option to allow guest access is already enabled.

3. Optionally, uncomment the line <mapUnknownUserToGuest/>.This maps client user names that are not in the user database to the guest user.

4. Save the file without the .sample extension in its current location (the <extension> directory), orin another directory.

5. Ensure that the file is pointed to the appropriate bean.

If you saved the file in the <extension> directory, then it is already pointed to by thefileServersConfigSource bean. If you saved the file in another directory, you must modify thefileServersConfigSource bean to point to the location. This bean is in the file <extension>/network-protocol-context.xml.sample.

6. Save the file network-protocol-context.xml.sample without the .sample extension.

Configuring Alfresco for passthrough authentication

The CIFS passthrough authenticator uses existing Windows file servers to authenticate users accessingthe Alfresco CIFS server. NTLM passthrough authentication can be used instead of the Alfresco userdatabase. In this case, a Windows server, such as a domain controller, is used to authenticate the userand provides the list of available users.

1. Browse to the file:

<extension>\ntlm-authentication-context.xml.samples

2. Save the file without the .samples extension.

Configuring the Enterprise authenticator

The Enterprise authenticator provides support for the following types of log ons sent by a CIFS client:

• NTLMv1 hashed passwords

• NTLMv2 hashed passwords/blob

• NTLMSSP two stage session setup with NTLMv1/NTLMv2

• SPNEGO session setup with Kerberos or NTLMSSP

The default configuration enables NTLMv1/NTLMv2 and NTLMSSP support using the Alfresco userdatabase.

There is no <config> entry for the Enterprise authenticator; you must create a new file.

1. Open a new file and insert the following:

<alfresco-config area="file-servers"> <config evaluator="string-compare" condition="Filesystem Security"> <authenticator type="enterprise"> </authenticator>  </config>



</alfresco-config>

2. Optionally, uncomment the <disallowNTLMv1/> configuration item to disable support for theweaker NTLMv1 hashed password.

3. Optionally, uncomment the <disableNTLM> configuration item to force only Kerberos logins by theclient, and only accept Kerberos logins on the server side.

Configuring the Alfresco CIFS and web servers for Kerberos/ActiveDirectory integrationThis section describes how to configure the CIFS server for Kerberos/Active Directory.

Note: Alfresco Share is not supported with Kerberos.

Before you configure the CIFS server for Kerberos/Active Directory, you must have the following(available from http://www.microsoft.com/downloads):

• setspn utility

• ktpass utility

Note: Some versions of the ktpass command can generate invalid keytab files. Download the latestversion of the resource kit tools from the Microsoft site to avoid any problems.

The process is made up of the following procedures:

1. Setting up a user account in Active Directory for the Alfresco CIFS server

2. Setting up a user account in Active Directory for the Alfresco web server

3. Creating the Service Principal Names

4. Generating key tables

5. Setting up Kerberos

6. Setting up the Java login configuration file

7. Configuring the Alfresco CIFS server to use the Kerberos authenticator

8. Configuring the Alfresco web server to use the Kerberos authenticator web filter

9. Configuring the Alfresco WebDAV server to use the Kerberos authenticator web filter

Setting up a user account in Active Directory for the Alfresco CIFS server

1. Launch the Active Directory Users and Computers application.

2. Create a user account for the Alfresco CIFS server.

3. Choose Action > New > User.

4. Enter the full name as alfresco CIFS.

5. Enter the user login name as alfrescocifs.

6. Click Next.

7. Type a password.

8. Enable Password never expires.

9. Disable User must change password at next logon.

10. Click Finish.

11. Right click the new user account name, and select Properties.

12. Go to the Account tab and enable the following options:

a. Use DES encryption types for this account



b. Do not require Kerberos preauthentication options (in Account Options)

Setting up a user account in Active Directory for the Alfresco web server

1. Launch the Active Directory Users and Computers application.

2. Create a user account for the Alfresco CIFS server.

3. Choose Action > New > User.

4. Enter the full name as alfresco HTTP.

5. Enter the user login name as alfrescohttp.

6. Click Next.

7. Type a password.

8. Enable Password never expires.

9. Disable User must change password at next logon.

10. Click Finish.

11. Right click the new user account name, and select Properties.

12. Go to the Account tab and enable the following options:

a. Use DES encryption types for this account

b. Do not require Kerberos preauthentication options (in Account Options)

Creating the Service Principal Names

This task describes how to create the Service Principal Names for the Alfresco CIFS and web serverusing the setspn utility.

1. Using the setspn utility, create the Service Principal Name (SPN) for the Alfresco CIFS server asfollows:

setspn -a cifs/<cifs-server-name> alfrescocifs

setspn -a cifs/<cifs-server-name>.<domain> alfrescocifs

<cifs-server-name> is the NetBIOS name of the Alfresco CIFS server when running on anActive Directory client. It is also the host name for a client that is not an Active Directory client (thatis, not logged onto the domain).

2. Using the setspn utility, create the Service Principal Name (SPN) for the Alfresco web server asfollows:

setspn -a http/<web-server-name> alfrescohttp

setspn -a http/<web-server-name>.<domain> alfrescohttp

<web-server-name> is the host name that is running the Alfresco server.

You can list the SPNs for a server using:

setspn -l <account-name>

Note: Some versions of the ktpass command will add the SPN for the principal so you may onlyneed to add the NetBIOS/short name versions of the SPNs. Use the setspn -l <account-name> command to check if the ktpass command set the SPN.

Generating key tables

This task describes how to generate key tables for configuring the CIFS server for Kerberos/ActiveDirectory. The ''ktpass'' utility is a free download from the Microsoft site, and is also part of the Win2003Resource Kit. The ktpass command can only be run from the Active Directory server.

1. Using the ktpass utility, generate key tables for the CIFS server and web server as follows:



ktpass -princ cifs/<cifs-server-name>.<domain>@<realm> -pass <password> -mapuser <domain>\alfrescocifs -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -out c:\temp\alfrescocifs.keytab

ktpass -princ HTTP/<web-server-name>.<domain>@<realm> -pass <password> -mapuser <domain>\alfrescohttp -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -out c:\temp\alfrescohttp.keytab

2. Copy the key tables to the server where Alfresco will run.

Specify the principal using the server name and domain in lowercase with the realmin uppercase. The service types should match cifs and HTTP. For example: cifs/[email protected].

Note: Some versions of the ktpass command can generate invalid keytab files. Download the latestversion of the resource kit tools from the Microsoft site to avoid any problems.

Setting up Kerberos

This example illustrates how to set up the Kerberos ini file.

1. Set up the Kerberos ini file as follows:

[libdefaults] default_realm = ALFRESCO.ORG

[realms] ALFRESCO.ORG = { kdc = adsrv.alfresco.org admin_server = adsrv.alfresco.org }

[domain_realm] adsrv.alfresco.org = ALFRESCO.ORG .adsrv.alfresco.org = ALFRESCO.ORG

2. Specify the realm in upper case. The file default location is C:\WINNT\krb5.ini or /etc/krb5.conf

Setting up the Java login configuration file

1. Open the main Java security configuration file JRE\lib\security\java.security.

2. Add the following line to the Java security file:

login.config.url.1=file:${java.home}/lib/security/java.login.config

This will configure JAAS to look for the java.login.config file in the same directory as thejava.security file.

The location of the login configuration must be defined, either on the command line usingsystem properties or in the security configuration. The configuration defines which authenticationmechanisms must be in place and succeed for authentication to take place.

By default, the location of the login configuration can be set in the JRE java.security file,located in an area like C:\Program Files\Java\jdk1.5.0_04\jre\lib\security forWindows. If not, the location of the login configuration can be specified on the Java command lineusing -Djava.security.auth.login.config=c:\path\file.conf.

The file should be similar to the following:

AlfrescoCIFS { com.sun.security.auth.module.Krb5LoginModule required storeKey=true useKeyTab=true keyTab="C:/etc/alfrescocifs.keytab"



principal="cifs/<cifs-server-name>.<domain>"; }; AlfrescoHTTP { com.sun.security.auth.module.Krb5LoginModule required storeKey=true useKeyTab=true keyTab="C:/etc/alfrescohttp.keytab" principal="HTTP/<web-server-name>.<domain>"; };

Alfresco { com.sun.security.auth.module.Krb5LoginModule sufficient; }; com.sun.net.ssl.client{ com.sun.security.auth.module.Krb5LoginModule sufficient; }; other { com.sun.security.auth.module.Krb5LoginModule sufficient; };

This configures Alfresco to require Kerberos.

Configuring the Alfresco CIFS server to use the Kerberos authenticator

This task to configure the Alfresco CIFS server to use the Kerberos authenticator.

To configure the CIFS server to use the Kerberos authenticator:

1. Open the file <configRoot>\alfresco\file-servers.xml.

2. Configure this file to allow the Alfresco CIFS server to use the Kerberos authenticator:

<config evaluator="string-compare" condition="Filesystem Security"> <authenticator type="enterprise"> <KDC>adsrv.alfresco.org</KDC> <Realm>ALFRESCO.ORG</Realm> <Password>...</Password> </authenticator> </config>

<KDC>The IP address or DNS name of the Active Directory server.

<Realm>The Kerberos realm.

<Password>The account password used when creating the alfrescocifs account above.

<LoginEntry>Optional. Specifies the login configuration file entry name. Defaults to AlfrescoCIFS.

Configuring the web server to use the Kerberos authenticator web filter• Ensure the following entry is in the file <tomcat root>\webapps\alfresco\WEB-INF\web.xml:

<filter> <filter-name>Authentication Filter</filter-name> <filter-class>org.alfresco.web.app.servlet.KerberosAuthenticationFilter</filter-class> <init-param> <param-name>KDC</param-name> <param-value>adsrv.alfresco.org</param-value> </init-param> <init-param> <param-name>Realm</param-name> <param-value>ALFRESCO.ORG</param-value>



</init-param> <init-param> <param-name>Password</param-name> <param-value>...</param-value> </init-param> <init-param> <param-value>...</param-value> </init-param></filter>

Configuring the WebDAV server to use the Kerberos authenticator web filter

• Ensure the following entry is in the file <tomcat root>\webapps\alfresco\WEB-INF\web.xml:

<filter> <filter-name>WebDAV Authentication Filter</filter-name> <filter-class>org.alfresco.web.app.servlet.KerberosAuthenticationFilter</filter-class> <init-param> <param-name>KDC</param-name> <param-value>adsrv.alfresco.org</param-value> </init-param> <init-param> <param-name>Realm</param-name> <param-value>ALFRESCO.ORG</param-value> </init-param> <init-param> <param-name>Password</param-name> <param-value>...</param-value> </init-param> <init-param> <param-value>...</param-value> </init-param></filter>

Configuring NTLM authenticationNTLM (NT LAN Manager) is a Microsoft authentication protocol. In Alfresco, NTLM authenticationprovides single sign on to Alfresco Explorer and Alfresco Share, which means that the web browser canautomatically login. Also, the password that is sent over the network is more secure than when usingbasic authentication.Note: Alfresco supports NTLMv2, which is more secure that NTLMv1. If the client does not supportNTLMv2, it will automatically downgrade to NTLMv1.

NTLM passthrough authentication can also be used to replace the standard Alfresco user database. Ituses a Windows server/domain controller, or list of servers, to authenticate users accessing Alfresco. Thismeans that you do not have to create user accounts within Alfresco.

Cofiguring Alfresco Explorer and WebDAV single sign on using NTLM

When you configure NTLM authentication to access Alfresco Explorer and Alfresco WebDAV sites, theweb browser will automatically login.

Internet Explorer will use your Windows logon credentials when requested by the web server whenNTLM is configured. Firefox and Mozilla also support the use of NTLM but you need to add the URI tothe Alfresco site that you want to access to the network.automatic-ntlm-auth.trusted-urisoption (available through writing about:config in the URL field) to allow the browser to use your currentcredentials for login purposes.

The Opera web browser does not currently support NTLM authentication, the browser is detected and willbe sent to the usual Alfresco logon page.



To configure NTLM authentication for Alfresco Explorer, you must directly modify the web.xml file in the<TOMCAT_HOME>\webapps\alfresco\WEB-INF folder and change the servlet filter that is used.You cannot override the file contents.Note: If you upgrade, your configuration changes may be lost.

1. Open the web.xml file.CAUTION: When directly modifying a default file, ensure that you follow the approach outlined inModifying default files.

2. Locate the following filter:

<filter> <filter-name>Authentication Filter</filter-name> <filter-class>org.alfresco.web.app.servlet.AuthenticationFilter</filter-class> </filter>

3. Replace the <filter-class> with the NTLM servlet filter. For example:

<filter-class>org.alfresco.web.app.servlet.NTLMAuthenticationFilter</filter-class>

4. Locate the NTLM <filter-mapping> section.

5. Uncomment the filter mapping for NTLM. These mappings are:

<filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/navigate/*</url-pattern> </filter-mapping>

<filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/command/*</url-pattern> </filter-mapping>

<filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/download/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/template/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/n/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/c/*</url-pattern> </filter-mapping>

<filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/t/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/d/*</url-pattern> </filter-mapping>



<filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/wcservice/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/wcs/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/ajax/*</url-pattern> </filter-mapping>

6. Locate the following filter for configuring NTLM authentication for Alfresco WebDAV access:

<filter> <filter-name>WebDAV Authentication Filter</filter-name> <filter-class>org.alfresco.repo.webdav.auth.AuthenticationFilter</filter-class> </filter>

7. Replace the <filter-class> with the NTLM servlet filter. For example:

<filter-class>org.alfresco.repo.webdav.auth.NTLMAuthenticationFilter</filter-class>

8. Uncomment the section that contains the WebScript NTLM Authentication Filter:

<filter> <filter-name>WebScript NTLM Authentication Filter</filter-name> <filter-class>org.alfresco.web.app.servlet.WebScriptNTLMAuthenticationFilter</filter-class> </filter>

9. Ensure that the following are included in the filter mappings section:

<filter-mapping> <filter-name>WebScript NTLM Authentication Filter</filter-name> <url-pattern>/wcservice/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>WebScript NTLM Authentication Filter</filter-name> <url-pattern>/wcs/*</url-pattern> </filter-mapping>

10. Save the web.xml file.

Alfresco Share single sign on using NTLM

When you configure NTLM authentication to access Alfresco Share sites, the web browser willautomatically login.

Alfresco Share exists as an entirely separate web application to the main Alfresco repository/ExplorerWAR file. It can run in the same application server instance on the same machine to the main Alfrescoweb application or it can run on a separate application server instance on a different machine.

Alfresco Share uses HTTP(S) to communicate with the configured Alfresco repository.

To use NTLM with Share, you must first enable NTLM for Alfresco Explorer web application. Then edit theweb.xml file in the <TOMCAT_HOME>\webapps\alfresco\WEB-INF folder and change the servletfilter that is used for Share.



1. Open the web.xml file.CAUTION: When directly modifying a default file, ensure that you follow the approach outlined inModifying default files.

2. Enable the following servlet filter:

<filter> <filter-name>Authentication Filter</filter-name> <filter-class>org.alfresco.web.site.servlet.NTLMAuthenticationFilter</filter-class> <init-param> <param-name>endpoint</param-name> <param-value>alfresco</param-value> </init-param> </filter>

3. Add the following filter mappings:

<filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/page/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/p/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>Authentication Filter</filter-name> <url-pattern>/s/*</url-pattern> </filter-mapping>

4. Save the web.xml file.

5. Locate the following sample configuration override file:<TOMCAT_HOME>\shared\classes\alfresco\web-extension\webscript-framework-config-custom.xml.sample

6. Open the file and uncomment the following section:

     <value>admin</value> <value>administrator</value> </set> </property> </bean> </beans>

3. Save the custom-authority-services-context.xml file.

Chaining authenticationThis section describes how to chain Alfresco authentication and Active Directory, and multiple LDAPservers.

Chaining Alfresco authentication with Active Directory

The default configuration does not allow guest access. However, you can override the default to enableguest access, and specify that unknown users are automatically granted guest access.



1. Remove .sample from the following two files in the <extensions> directory:./extension/ldap-authentication-context.xml.sample./extension/ldap-synchronisation-context.xml.sample

2. In ./extension/ldap-authentication-context.xml, change:

a. <bean name="authenticationDao" . . . to <bean name="authenticationDaoLDAP"

b. <bean id="authenticationComponent" to <beanid="authenticationComponentLDAP"

The option to allow guest access is already enabled.

3. Make the appropriate changes to ./extension/ldap-authentication.properties and ./extension/ldap-synchronisation.properties. Your Active Directory admin is the bestsource for this information.

4. Remove .sample from ./extension/chaining-authentication-context.xml.sampleand replace all the xml with the following:

<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'> <beans> 

<bean id="authenticationService" class="org.alfresco.repo.security.authentication.ChainingAuthenticationServiceImpl"> <property name="authenticationServices"> <list> <ref bean="authenticationServiceLDAP"/ </list> </property> <property name="mutableAuthenticationService"> <ref bean="authenticationServiceImplAlfresco"/> </property> <property name="sysAdminCache"> <ref bean="sysAdminCache"/> </property> </bean>

<bean id="authenticationComponent" class="org.alfresco.repo.security.authentication.ChainingAuthenticationComponentImpl"> <property name="authenticationComponents"> <list> <ref bean="authenticationComponentLDAP"/> </list> </property> <property name="mutableAuthenticationComponent"> <ref bean="authenticationComponentImplAlfresco"/> </property> </bean>

 <bean id="authenticationServiceImplAlfresco" class="org.alfresco.repo.security.authentication.AuthenticationServiceImpl"> <property name="authenticationDao"> <ref bean="authenticationDaoAlfresco"/> </property> <property name="ticketComponent"> <ref bean="ticketComponent"/> </property> <property name="authenticationComponent"> <ref bean="authenticationComponentImplAlfresco"/> </property> <property name="sysAdminCache"> <ref bean="sysAdminCache"/> </property>



</bean>

<bean id="authenticationDaoAlfresco" class="org.alfresco.repo.security.authentication.RepositoryAuthenticationDao"> <property name="nodeService"> <ref bean="nodeService"/> </property> <property name="dictionaryService"> <ref bean="dictionaryService"/> </property> <property name="namespaceService"> <ref bean="namespaceService"/> </property> <property name="searchService"> <ref bean="admSearchService"/> </property> <property name="retryingTransactionHelper"> <ref bean="retryingTransactionHelper"/> </property> <property name="userNamesAreCaseSensitive"> <value>${user.name.caseSensitive}</value> </property> <property name="passwordEncoder"> <ref bean="passwordEncoder"/> </property> </bean>

<bean id="authenticationComponentImplAlfresco" class="org.alfresco.repo.security.authentication.AuthenticationComponentImpl"> <property name="authenticationDao"> <ref bean="authenticationDaoAlfresco"/> </property> <property name="authenticationManager"> <ref bean="authenticationManager"/> </property> <property name="allowGuestLogin"> <value>true</value> </property> <property name="nodeService"> <ref bean="nodeService" /> </property> <property name="personService"> <ref bean="personService" /> </property> <property name="transactionService"> <ref bean="transactionService" /> </property> </bean>

 <bean id="authenticationServiceLDAP" class="org.alfresco.repo.security.authentication.AuthenticationServiceImpl"> <property name="authenticationDao"> <ref bean="authenticationDaoLDAP"/> </property> <property name="ticketComponent"> <ref bean="ticketComponent"/> </property> <property name="authenticationComponent"> <ref bean="authenticationComponentLDAP"/> </property> </bean> </beans>

5. Start Alfresco and log in as the default Alfresco administrator (admin/admin).

6. Log out and log in as an Active Directory user.

Chaining multiple LDAP servers

This task describes how to chain multiple LDAP servers.

1. Open the following file:

./extension/ldap-authentication-context.xml.sample

2. Remove .sample from the file and rename it to:



./extension/ldap1-authentication-context.xml

3. Replace all the XML in ldap1-authentication-context.xml with the following:

<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>

<beans> <bean name="authenticationDaoLDAP1" class="org.alfresco.repo.security.authentication.DefaultMutableAuthenticationDao" >

<property name="allowDeleteUser"> <value>true</value> </property> </bean>

<bean id="authenticationComponentLDAP1" class="org.alfresco.repo.security.authentication.ldap.LDAPAuthenticationComponentImpl"> <property name="LDAPInitialDirContextFactory"> <ref bean="ldap1InitialDirContextFactory"/> </property> <property name="userNameFormat"> <value>${ldap1.authentication.userNameFormat}</value> </property> <property name="nodeService"> <ref bean="nodeService" /> </property> <property name="personService"> <ref bean="personService" /> </property> <property name="transactionService"> <ref bean="transactionService" /> </property> </bean>

<bean id="ldap1InitialDirContextFactory" class="org.alfresco.repo.security.authentication.ldap.LDAPInitialDirContextFactoryImpl"> <property name="initialDirContextEnvironment"> <map> <entry key="java.naming.factory.initial"> <value>${ldap1.authentication.java.naming.factory.initial}</value> </entry> <entry key="java.naming.provider.url"> <value>${ldap1.authentication.java.naming.provider.url}</value> </entry> <entry key="java.naming.security.authentication"> <value>${ldap1.authentication.java.naming.security.authentication}</value> </entry> <entry key="java.naming.security.principal"> <value>${ldap1.authentication.java.naming.security.principal}</value> </entry> <entry key="java.naming.security.credentials"> <value>${ldap1.authentication.java.naming.security.credentials}</value> </entry> </map> </property> </bean> </beans>

4. Make a copy of ldap1-authentication-context.xml and rename it ldap2-authentication-context.xml. In this file, replace all instances of ldap1 with ldap2. Forexample:



<bean id="authenticationComponentLDAP2” . . .

5. In ldap-authentication.properties, add the following:

ldap1.authentication.userNameFormat=CN=%s,CN=Users,DC=myHost,DC=com ldap1.authentication.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory ldap1.authentication.java.naming.provider.url=ldap://myHost.com:389 ldap1.authentication.java.naming.security.authentication=SIMPLE ldap1.authentication.java.naming.security.principal=CN=admin,CN=Users,DC=myHost,DC=com ldap1.authentication.java.naming.security.credentials=password

ldap2.authentication.userNameFormat=CN=%s,CN=Users,DC=myOtherHost,DC=com ldap2.authentication.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory ldap2.authentication.java.naming.provider.url=ldap://myOtherHost.com:389 ldap2.authentication.java.naming.security.authentication=SIMPLE ldap2.authentication.java.naming.security.principal=CN=admin,CN=Users,DC=myOtherHost,DC=com ldap2.authentication.java.naming.security.credentials=password

Note: Your ldap administrator is the best source to get this information.

6. Create a file named ./extension/ldap-common-context.xml, and add the following:


<beans> <bean name="ldapAuthenticationPlaceholderConfigurer" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">

<property name="ignoreUnresolvablePlaceholders"> <value>true</value> </property> <property name="locations"> <value>classpath:alfresco/extension/ldap-authentication.properties</value> </property> </bean> </beans>

7. Remove .sample from ./extension/chaining-authentication-context.xml.sample.

8. Replace all of the XML in chaining-authentication-context.xml with the following:


<beans> <bean id="authenticationService" class="org.alfresco.repo.security.authentication.ChainingAuthenticationServiceImpl">

<property name="authenticationServices"> <list> <ref bean="authenticationServiceLDAP2"/> </list> </property> <property name="mutableAuthenticationService"> <ref bean="authenticationServiceLDAP1"/> </property> <property name="sysAdminCache"> <ref bean="sysAdminCache"/> </property> </bean>

<bean id="authenticationComponent"



class="org.alfresco.repo.security.authentication.ChainingAuthenticationComponentImpl"> <property name="authenticationComponents"> <list> <ref bean="authenticationComponentLDAP2"/> </list> </property> <property name="mutableAuthenticationComponent"> <ref bean="authenticationComponentLDAP1"/> </property> </bean>

 <bean id="authenticationServiceLDAP1" class="org.alfresco.repo.security.authentication.AuthenticationServiceImpl"> <property name="authenticationDao"> <ref bean="authenticationDaoLDAP1"/> </property> <property name="ticketComponent"> <ref bean="ticketComponent"/> </property> <property name="authenticationComponent"> <ref bean="authenticationComponentLDAP1"/> </property> </bean>

 <bean id="authenticationServiceLDAP2" class="org.alfresco.repo.security.authentication.AuthenticationServiceImpl"> <property name="authenticationDao"> <ref bean="authenticationDaoLDAP2"/> </property> <property name="ticketComponent"> <ref bean="ticketComponent"/> </property> <property name="authenticationComponent"> <ref bean="authenticationComponentLDAP2"/> </property> </bean> </beans>

9. Start Alfresco and log in as a user from ldap1. Then, log out and log in as a user from ldap2. Thesame concept of copying the beans can be applied to the synchronization process as well.

Configuring JAAS authenticationAlfresco uses the JAAS (Java Authentication and Authorization Service) component most commonlyto support Kerberos authentication of user names and passwords. JAAS is an external authenticationmechanism: there is no authentication information held within the repository. For example, there is nopassword, and, therefore, no way to change a user's password, create, or delete a user. These actionsmust be supported by some other mechanism, for example, AD administration.

1. Replace the default implementation of the standard Alfresco authentication component bean withthe JAASAuthenticationComponent.

2. Replace the default DAO bean that provides access to authentication information stored withinAlfresco.

3. Name the configuration entry to use for the JAAS configuration, by default, this is Alfresco.Note: Configure the security and authentication components without changing any of the filescontained in the Alfresco distributions.



Troubleshooting

This chapter provides information to help you solve issues that may arise when installing and configuringAlfresco.

For additional help, refer to the following:

• Alfresco Installation forum (http://www.alfresco.org/forums)

• Alfresco Enterprise Knowledge Base

To troubleshoot errors, you can also use the System Administration console in the Alfresco web client toview various installation and setup information.

Debugging an Alfresco installationWhen developing add-ins, fixing bugs, or changing Alfresco from the source code, it is helpful to debugan instance of Alfresco running on a standard application server. This section outlines the steps neededto configure Alfresco and Eclipse to provide a real-time view of the server and to troubleshoot issues bystepping through the code line by line.

To debug a running Alfresco server, you must connect to the JVM in which Alfresco is running. Thefollowing steps configure the JVM to expose an interface for this connection, and then configure Eclipseto connect to and control that JVM.

Configuring the JVMThis task describes how to configure the JVM to expose an interface for connection to the Alfresco server.

Before you start, you must:

• Have a fully installed, configured, and running instance of Alfresco. These steps assume you areusing Tomcat on Windows, but the steps are similar for other application servers on other systems.

• Have an IDE installed. These steps describe how to configure Eclipse, which must be installed first(http://www.eclipse.org/downloads)

• Download and install the Alfresco source code from http://wiki.alfresco.com/wiki/Alfresco_SVN_Development_Environment.

• Ensure the source code is the same version as the installed Alfresco server.

1. Verify the Alfresco server is not running.

2. Edit the JVM options used to start the Alfresco Tomcat instance. If you are using the defaultalf_start.bat to start Alfresco, perform the following:

a. Edit alfresco.bat in a text editor.

b. Find the line: set JAVA_OPTS=%JAVA_OPTS% -server –X…

c. On the next line, add the following on one line:

set JAVA_OPTS=%JAVA_OPTS% -server -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8082

where address is a port for your system

3. Save the file and close the editor.



Configuring EclipseThis task describes how to configure Eclipse to connect to and control the JVM.

1. From the Run menu, choose the Open Debug dialog.

2. Right-click Remote Java Application and select New.

3. In the Name box, type Debug Local Tomcat Alfresco.

4. Next to Project, click Browse, and select Web Client. If this is not available as an option, ensureyour source code matches that of your server.

5. In Connection Properties, enter the Port number you added to the alf_start.bat file.

6. Check Allow Termination of remote VM if you want to be able to stop the Alfresco server from theEclipse console.

7. Click Apply to save the configuration.

You have configured Alfresco and Eclipse. Next, you can start the Alfresco server and start the Debugconfiguration in Eclipse. Eclipse will connect to the Alfresco JVM. From the Java perspective in Eclipse,you can expand the “core” or “web client” packages, open the class files you are interested in, andset breakpoints for the Alfresco server to stop at. From the Debug perspective, you can then interrogatespecific variables from the Alfresco server “live” , and step through the source code line by line.

Setting log levelsThe log4j.properties file lets you configure logging levels to provide debugging information whentroubleshooting. To set up logging policies, you must prepend log4.logger to the class name you wantto log to, and set the logging level.

1. Find a class definition in the Spring config files, or uncomment an existing configuration for thecomponent.

2. Add the class definition to the log4j.properties file.

3. Prepend log4j.logger onto the class definition in the log file. For example:log4j.logger.org.springframework.beans.factory.config.PropertyPlaceholderConfigure=debugThis example sets the logging level to debug. Other logging levels include all, info, warn,error, and fatal.

4. Restart the server.During startup, all the properties display.

Testing and debugging linksThe file <configroot>/log4j.properties lets you set the level of logging based on the amount ofinformation you need.

• To enable debugging for the background process that continually checks a web project's links,remove the comment from the following line: :

#log4j.logger.org.alfresco.linkvalidation.LinkValidationServiceImpl=debug

• To enable debugging for the action to run when performing a link validation check, add the followingline:

log4j.logger.org.alfresco.linkvalidation.LinkValidationAction=debug

• To enable debugging for the link validation report dialog, add the following line::

log4j.logger.org.alfresco.web.bean.wcm.LinkValidationDialog=debug



Error messagesThis section discusses possible issues you may encounter when installing Alfresco and suggests possibleremedies.

ImageMagick

Error message on the console:

ERROR [AbstractImageMagickContentTransformer]JMagickContentTransformer not available:ERROR [AbstractImageMagickContentTransformer]ImageMagickContentTransformer not available:Failed to execute command: imconvert ...

These issues will not cause the server to fail. Alfresco is reporting that external document transformationengines are not available for use by the server. You can remove the transformation references if they arenot required.

JAVA_HOME

Make sure the JAVA_HOME variable is set correctly for your Java installation.

FTP Socket

Error message on server startup:

ERROR [protocol] FTP Socket error

java.net.BindException: Address already in use: JVM_Bind at

java.net.PlainSocketImpl.socketBind(Native Method)

Check to see if you have any services running against port 8080 for the Alfresco server or port 21 for theAlfresco FTP integration.



Glossary

ACPACP (Alfresco Content Package) files hold exported information produced when using the Exportfeature.

alf_dataDirectory containing binary content and Lucene indexes.

Alfresco WARThe Alfresco Web application Archive (WAR) file is for deployment in existing application servers.

AMPAMP (Alfresco Module Package) is a collection of code, XML, images, CSS, that collectively extendthe functionality or data provided by the standard Alfresco repository. An AMP file can contain as littleas a set of custom templates or a new category. It can contain a custom model and associated userinterface customizations. It could contain a complete new set of functionality, for example recordsmanagement.

AVMAlfresco Advanced Versioning Manager (AVM) is an advanced store implementation designed tosupport the version control requirements of large websites and web applications.

breadcrumbA navigation link that allows you to jump to any part of the breadcrumb path.

<configRoot>The <configRoot> directory is where the default configuration files are stored. You should notoverride these files but you can store overrides in the <extension> directory. For example: forTomcat, <configRoot> is: <TOMCAT_HOME>/webapps/alfresco/WEB-INF/classes

CIFSMicrosoft Common Internet File System (CIFS) is a network file system for sharing files across theInternet.

contentFiles or documents made of two main elements: the content itself and information about the content(metadata). For example, documents, video, audio, images, XML, and HTML.

dashboardThe Alfresco dashboard is an interactive user interface that presents and organizes information to theuser.

dashletA dashlet is an application that appears in the Alfresco dashboard that presents information to theuser. Users can organize dashelets into different layouts and set keyboard short cuts for each dashlet.

dir.rootThe dir.root property is specified in:<configRoot>/alfresco/repository.properties.dir.root points to the directory alf_data, which contains the content and the Lucene indexes.

dir.indexesThis folder contains all Lucene indexes and deltas against those indexes.

Enterprise Content Management (ECM)Enterprise content management (ECM) is a set of technologies used to capture, store, preserveand deliver content and documents and content related to organizational processes. ECM toolsand strategies allow the management of an organization's unstructured information, wherever thatinformation exists.

Quoted from: http://en.wikipedia.org/wiki/Enterprise_content_management

http://en.wikipedia.org/wiki/Enterprise_content_management



Enterprise EditionThe Enterprise Edition is production ready open source - the stress-tested certified build that issupported by Alfresco Software. It is recommended for corporations, governments, and otherorganizations looking for a production-ready open source ECM solution, with the primary benefit ofbeing a stable, reliable, certified, supported application with warranty and indemnity, with the supportof Alfresco and its certified partners.

<extension>The <extension> directory is where you store files that extend and override the Alfresco defaultfiles. When Alfresco is installed, there are sample files in this directory. Many of these files havea .sample suffix, which must be removed to activate the file.

For example: for Tomcat, <extension> is:<TOMCAT_HOME>/shared/classes/alfresco/extension/

HibernateHibernate is an object-relational mapping (ORM) library for the Java language, providing a frameworkfor mapping an object-oriented domain model to a traditional relational database. Hibernate solvesObject-Relational impedance mismatch problems by replacing direct persistence-related databaseaccesses with high-level object handling functions.

ImageMagickImageMagick is a software suite to create, edit, and compose bitmap images. It can read, convert andwrite images in a large variety of formats. Images can be cropped, colors can be changed, variouseffects can be applied, images can be rotated and combined, and text, lines, polygons, ellipses andBézier curves can be added to images and stretched and rotated.

Quoted from: http://www.imagemagick.org/script/index.php

Java Content Repository (JCR) APIJava Content Repository API is a standard Java API (as defined by JSR-170) for accessing contentrepositories. Alfresco provides support for JCR level 1 and level 2 giving standardised read and writeaccess.

JVMJava Virtual Machine

JMagickJMagick is an open source Java interface of ImageMagick. It is implemented in the form of JavaNative Interface (JNI) into the ImageMagick API.

Quoted from: http://www.yeo.id.au/jmagick/

LuceneApache Lucene is a high-performance, full-featured text search engine library written entirely in Java.It is a technology suitable for nearly any application that requires full-text search, especially cross-platform.

Quoted from: http://lucene.apache.org/java/docs/index.html

repositoryThe repository is the combination of the content, the indexes, and the database.

sandboxAn environment for testing, experimenting, or using as a working area. In WCM, a sandbox is an areawhere users can make changes to web content. In the sandbox, a user can add, edit, and delete bothfolders and files.

siteA site is a collaborative area for a unit of work or a project.

SpringSpring is an open-source application framework for Java/JEE. The Alfresco repository uses the SpringFramework as the core foundation of its architecture.

http://www.imagemagick.org/script/index.php

http://www.yeo.id.au/jmagick/

http://lucene.apache.org/java/docs/index.html



storeA store is a logical partition within the repository, grouped for a particular automated use. Each storecontains a hierarchy of nodes with one root node. Two main stores in Alfresco are the DocumentManagement (DM) and the Advanced Versioning Manager (AVM) stores. AVM stores are used forWeb Content Management. Each store is identified by a content store reference. This referenceconsists of a store protocol (such as archive or workspace) and a store id (such as SpaceStore orUser).

WARThe Alfresco Web application ARchive (WAR) file is for deployment in existing application servers.

Web Content Management (WCM)Web Content Management is an Alfresco product for the rapid deployment of web content, allowingusers to create, develop, and maintain content for websites.

WebDAVWeb-based Distributed Authoring and Versioning. A protocol that allows users to edit and managefiles on remote web servers.

<web-extension>The <web-extension> directory is where you store files that extend and override the Alfresco defaultfiles for Alfresco Share. When Alfresco is installed, there are sample files in this directory. Many of thefiles have a .sample suffix, which must be removed to activate the file.

For example: for Tomcat, <web-extension> is:<TOMCAT_HOME>/shared/classes/alfresco/web-extension/

workflowA workflow is a work procedure and workflow steps that represent the activities users must follow inorder to achieve the desired outcome. Alfresco provides two different types of workflow: simple andadvanced. Simple workflow defines content rules for a space. Advanced workflow provides two out-of-the-box workflows (Review and Approve; Adhoc Task).