Building and Running ManifoldCF

2015/7/18Building ManifoldCF Apache > ManifoldCF > Release Documentation > release > release­2.1 > en_US Search the site with Solr    Search Powered by LucidWorks Last Published: 05/05/2015 08:23:01   Building ManifoldCF Building ManifoldCF Building overview Building the framework and the connectors using Apache Ant Building and testing the legacy Alfresco connector Building and testing the Alfresco Webscript connector Building and running the Documentum connector Building and running the FileNet connector Building and running the JDBC connector, including Oracle, MSSQL, MySQL, SQLServer, and Sybase JDBC drivers Building and running the jCIFS/Windows Shares connector Building and running the LiveLink connector Building the Meridio connector Building and running the SharePoint connector Running the Apache Solr output connector Running the ElasticSearch output connector Building the framework and the connectors using Apache Maven Preparation How to build Building ManifoldCF's Apache2 plugin Running ManifoldCF Overview Binary organization Example deployments Quick­start single process model Single­process deployable war Simplified multi­process model using file­based synchronization Simplified multi­process model using ZooKeeper­based synchronization Command­driven multi­process model The connectors.xml configuration file Running connector­specific processes Database selection Configuring a PostgreSQL database Configuring a MySQL database Configuring an HSQLDB database The ManifoldCF configuration files properties.xml file properties Logging configuration file properties Running the ManifoldCF Apache2 plug in Configuring the ManifoldCF Apache2 plug in Running ManifoldCF with Apache Maven Integrating ManifoldCF into another application Integrating the Quick Start example Integrating a multi­process setup Integrating ManifoldCF with a search engine Building ManifoldCF ManifoldCF consists of a framework, a set of connectors, and an optional Apache2 plug­in module. These can be built as follows. Building overview There are two ways to build ManifoldCF. The primary means of building (and the most supported) is via Apache Ant. The ant build is used to create ManifoldCF releases and to run tests, load tests, and UI tests. Maven is also supported for develop building only. Maven ManifoldCF builds have many restrictions and challenges and are of secondary priority for the development team. http://manifoldcf.apache.org/release/release­2.1/en_US/how­to­build­and­deploy.html#Running+ManifoldCF 1/17  See below for details. which should be used consistently with all involved processes.1/en_US/how­to­build­and­deploy. The latter is the only possibility if you are building from trunk.2015/7/18 Building ManifoldCF The ManifoldCF framework is built without any dependencies on connector code. which usually serves to isolate the crawler­ui servlet. to download LGPL and other open source but non­Apache compatible libraries. with the just the POSTGRESQL jdbc driver Atlassian Jira connector OpenText LiveLink connector. built against a FileNet API stub WGET­compatible filesystem connector Generic XML repository connector Google Drive connector GridFS connector (mongoDB) HDFS connector JDBC connector. or unpack the desired source distribution. or a mapping connector. which are meant to support or configure the connector in some way. 4. not all capabilities of ManifoldCF will be available.org/release/release­2. 7. (This is historical.g. 2. Connectors are then built that have well­defined dependencies on the framework modules. a family of web applications. An individual connector package will typically supply an output connector. the agents process. and any commands from problematic aspects of the client environment A recommended set of java "define" variables.apache. but it is not guaranteed to work for older releases. It consists of a set of jars.html#Running+ManifoldCF 2/17 . 6. built against modified Meridio API WSDLs and XSDs Null authority Microsoft SharePoint/AD authority http://manifoldcf.  Check out the desired release from https://svn. built against SharePoint API WSDLs Webcrawler connector Wiki connector The following authority connectors will be built: Active Directory authority Alfresco Webscript authority CMIS authority EMC Documentum authority Atlassian Jira authority LDAP authority OpenText LiveLink authority Meridio authority. See below for details. 5.  cd to the top­level directory. or sometimes both a repository connector and an authority connector. and a number of java command classes.  Run "ant make­deps". The main ant build script automatically forms each individual connector's contribution to the overall system into the overall package.org/repos/asf/manifoldcf/tags.  Run "ant build". The framework itself and the following repository connectors will be built: Alfresco Webscript connector CMIS connector EMC Documentum connector. you currently need to do the following: 1. OR run "ant make­core­ deps" to build the code dependencies. Building the framework and the connectors using Apache Ant To build the ManifoldCF framework code. 3. Possibly some java commands. agents process. e. where possible).  Install proprietary build dependencies. and no connectors as of this writing have any of these any longer).  EITHER: overlay the lib directory from the corresponding lib distribution (preferred. If you do not run the ant "make­deps" target. Possibly a connector­specific process or two. and any commands. and you supply NO LGPL or proprietary libraries. or a transformation connector.  Install desired dependent proprietary libraries. built against a Documentum API stub DropBox connector Email connector FileNet connector. authority­service servlet. A properly built connector typically consists of: One or more jar files meant to be included in the library area meant for connector jars and their dependencies.apache. and the particular connectors you are interested in. built against a LiveLink API stub Meridio connector. each requiring a distinct classpath. the application server running the authority­service and crawler­ui. or a repository connector. built against modified Meridio API WSDLs and XSDs RSS connector Microsoft SharePoint connector.  and you may need to build the connector yourself. SQLServer. simply copy your Jace. For Oracle.org/release/release­2. If your FileNet is newer. The ant target "make­deps" will do this for you automatically. The stubs mimic the class structure of DFC 6. Building and testing the legacy Alfresco connector The legacy Alfresco connector requires the Alfresco Web Services Client provided by Alfresco in order to be built. This Alfresco Indexer plugin is included with ManifoldCF distributions. This will occur automatically if you execute the ant target "make­deps" from the ManifoldCF root directory. and you may need to build the connector yourself.5.jar at build time. Building and testing the Alfresco Webscript connector The Alfresco Webscript connector is built against an open­source Alfresco Indexer client. and for the plugin itself. The Jace. you should be able to start the Documentum connector's registry and server processes.jar will be copied into the right place in your dist directory automatically. In order to support these databases. but is usually built against a set of stub classes. Building and running the FileNet connector The FileNet connector requires IBM's FileNet P8 API jar in order to be run. copy it to the source directory connectors/filenet/lib­proprietary. If you need to supply DFC classes during build time.jar and the other dependent jars from that installation into the distribution directory processes/filenet­server/lib­proprietary. The stubs mimic the class structure of FileNet P8 API 4. it is possible that the class structure of the API might have changed. as per the instructions. including Oracle. and copy it into the same directory before you http://manifoldcf. it is possible that the class structure of the DFC classes might have changed. and build using "ant build". If correctly done. and Sybase JDBC drivers. Building and running the Documentum connector The Documentum connector requires EMC's DFC product in order to be run.jar in the lib­proprietary directory.apache. For a binary distribution. Installation of the plugin should follow the standard Alfresco installation steps. you will be able to start the FileNet connector's registry and server processes. copy the DFC and dependent jars to the source directory connectors/documentum/lib­proprietary. start by placing the mysql­connector­java. To run integration tests for the connector you have to copy the alfresco. and build using "ant build". If you have done everything right. but is built against a set of stub classes. The jars will be copied into the right place in your dist directory automatically. just copy the DFC jars to processes/documentum­server/lib­proprietary instead. Building and running the JDBC connector. as described here. which requires a corresponding Alfresco Indexer plugin to be installed on your Alfresco instance. and Sybase JDBC drivers The JDBC connector also knows how to work with Oracle. If you do not wish to build.war including H2 support created by the Maven module test­ materials/alfresco­4­war (using "mvn package" inside the folder) into the connectors/alfresco/test­materials­proprietary folder.0. built against SharePoint API WSDLs The following output connectors will be built: WGET­compatible filesystem output connector MetaCarta GTS output connector Apache Solr output connector OpenSearchServer output connector ElasticSearch output connector WGET­compatible filesystem output connector HDFS output connector Null output connector The following transformation connectors will be built: Field mapping transformation connector Document filter transformation connector Null transformation connector Tika extractor transformation connector The following mapping connectors will be built: Regular­expression mapping connector The dependencies and build limitations of each individual LGPL and proprietary connector is described in separate sections below.html#Running+ManifoldCF 3/17 . SQLServer.jar and the jtds. download the appropriate Oracle JDBC jar from the Oracle site.2015/7/18 Building ManifoldCF Microsoft SharePoint/Native authority. Place this jar into the directory connectors/alfresco/lib­proprietary before you build. MySQL. MSSQL. See this page for configuration details.1/en_US/how­to­build­and­deploy. If you need to supply your own Jace. as per the instructions. Then use the "ant test" or "mvn integration­test" for the standard build to execute integration tests. If your DFC is newer. html#Running+ManifoldCF 4/17 .x 2.org.exe utility is installed as part of Microsoft Visual Studio. and install it following the instructions in the file Installation Readme. Building and running the LiveLink connector This connector needs OpenText's LAPI package in order to be run.asmx http[s]://<server_name>/_vti_bin/Dspsts.6. SharePoint version 5.x plugin compatibility ManifoldCF versions Plugin version 0. in order to run the connector. you can obtain unmodified wsdls and xsds by interrogating the following Meridio web services: http[s]://<meridio_server>/DMWS/MeridioDMWS. and is typically found under "c:\Program Files\Microsoft SDKs\Windows\V6.1. mimic the class structure of LAPI 9. documents will not be properly secured.7. the service is even more critical.asmx http[s]://<server_name>/_vti_bin/webs.exe. For SharePoint version 4.asmx Building and running the SharePoint connector The SharePoint connector generates interface classes using checked­in wsdls originally obtained from an installed Microsoft SharePoint instance using disco.exe utility is installed as part of Microsoft Visual Studio.txt file in the plugins themselves. Running the ElasticSearch output connector http://manifoldcf.jar from http://jcifs.2015/7/18 Building ManifoldCF build ManifoldCF. and subsequently modified to work around limitations in Apache Axis. Building the Meridio connector The Meridio connector generates interface classes using checked­in wsdls and xsds originally obtained from an installed Meridio instance using disco.xml file.txt. in order for Apache Solr to be able to enforce document security. and build using "ant build". you may need to rebuild ManifoldCF against your lapi. If desired.jar into the connector­lib­proprietary directory. If you have downloaded a binary distribution. simply copy your lapi. because backwards compatibility was not maintained and without this service no crawling can occur. so there is a different distribution. you also must deploy a custom SharePoint web service on the SharePoint instance you intend to connect to. and copy it into the connectors/jcifs/lib­proprietary directory before building. The disco.asmx http[s]://<server_name>/_vti_bin/usergroup. place the jcifs. Later versions (such as 10. in order for the connector to work properly. If desired.x) have a different class structure. copy it to the source directory connectors/livelink/lib­proprietary. Thus. Therefore. The correct versions of the plugins are included in the plugins/solr directory of the main ManifoldCF distribution. Building and running the jCIFS/Windows Shares connector To build this connector. Much more information can be found in the README.jar into the binary distribution's connector­lib­proprietary directory. Running the Apache Solr output connector The Apache Solr output connector requires no special attention to build or run within ManifoldCF. and uncomment the LiveLink­related connector lines in connectors. It is usually built against a set of stubs.jar and llssl. it is essential to verify that the proper plugin version has been deployed for the version of ManifoldCF you are using.1/en_US/how­to­build­and­deploy. Pick the version appropriate for your SharePoint installation. You can also just type "ant make­deps" from the root ManifoldCF directory and this step will be done for you.samba.x >=1.x 1. however. The lapi.4. You can also download updated versions of the plugins from the ManifoldCF download page.5. The compatibility matrix is as follows: 0.asmx http[s]://<meridio_server>/RMWS/MeridioRMWS. The versions of this service can be found in the distribution directory plugins/sharepoint.asmx Important: For SharePoint instances version 3.org/release/release­2. the binary you install is built against SharePoint 2013 resources rather than SharePoint 2010 resources.x and for Solr 4.xml file.x and Solr 4. or as a search component. you must install and properly configure a plugin for Solr.x. and can be used either as a query parser plugin.jar at build time. you need to download jcifs.0 (2010). However. Additional index fields are also required to contain the necessary security information.0 (2007) or higher. you can obtain unmodified wsdls by interrogating the following SharePoint web services: http[s]://<server_name>/_vti_bin/Permissions.0. The stubs.x 1.asmx http[s]://<server_name>/_vti_bin/Lists. This is required because Microsoft overlooked support for web­service­based access to file and folder security information when SharePoint 2007 was released. and is typically found under "c:\Program Files\Microsoft SDKs\Windows\V6. If you need to supply your own lapi.x\bin". This plugin is available for both Solr 3.jar and llssl.0 (2013) also requires a plugin; although its functionality is the same as for SharePoint 4.x Apache ManifoldCF Solr 3.jar.1. found in the corresponding directory. If you do not wish to build. The disco. and uncomment the Windows Shares line in the connectors.x If the proper version of the plugin is not deployed on Solr.x\bin".x­1.apache.asmx http[s]://<server_name>/_vti_bin/versions.exe.jar will be copied into the right place in your dist directory automatically.       "shareName" : {         "type" : "string"       }.       "deny_token_document" : {         "type" : "string"       }.1. However. you must install.       "file" : {         "type" : "attachment".       "attributes" : {         "type" : "string"       }. The compatibility matrix is as follows: 0.org/release/release­2. Here are some simple steps for creating an ElasticSearch index.4. It is configured for highlighting ("term_vector" : "with_positions_offsets"). it is essential to verify that the proper plugin version has been deployed for the version of ManifoldCF you are using.       "deny_token_share" : {         "type" : "string"       }.             "type" : "string"           }         }       }     }   } }'            This command creates an index called manifoldcf with a mapping named attachment which has some generic fields for access tokens and a field file which makes use of the ElasticSearch attachment mapper plugin.             "term_vector" : "with_positions_offsets".x Apache ManifoldCF ElasticSearch plugin compatibility ManifoldCF versions 0. The correct versions of the plugin is included in the plugins/elasticsearch directory of the main ManifoldCF distribution.x 1.x Plugin version If the proper version of the plugin is not deployed and properly integrated. documents will not be properly secured.x 2.html#Running+ManifoldCF 5/17 .6.1/en_US/how­to­build­and­deploy. Thus.         "fields" : {           "file" : {             "store" : true.x >=1.apache.       "lastModified" : {         "type" : "string"       }.x­1. http://manifoldcf. You can also download updated versions of the plugin from the ManifoldCF download page.       "allow_token_share" : {          "type" : "string"        }.       "deny_token_parent" : {         "type" : "string"       }. To work with ManifoldCF. and code against a toolkit plugin for ElasticSearch. Additional index fields are also required to contain the necessary security information.         "path" : "full".5.x 1.2015/7/18 Building ManifoldCF The ElasticSearch output connector requires no special attention to build or run within ManifoldCF. your ElasticSearch instance must also include the appropriate indexes created as well. in order for ElasticSearch to be able to enforce document security. properly configure.       "allow_token_parent" : {          "type" : "string"        }.     "properties": {        "allow_token_document" : {          "type" : "string"        }.txt file in the plugin itself. Much more information can be found in the README. using the CURL utility: % curl ‐XPUT 'http://localhost:9200/manifoldcf' % curl ‐XPUT 'http://localhost:9200/manifoldcf/attachment/_mapping' ‐d ' {   "attachment" : {     "_source" : {       "excludes" : [ "file" ]     }.       "createdOn" : {         "type" : "string"       }.  If you build ManifoldCF yourself. The build will produce a file called mod­authz­annotate. and also include the agents process. you MUST run a complete "mvn clean install" as the first step. In the ManifoldCF root.xml proprietary jars for all the connectors. which is where ManifoldCF keeps all of its configuration and state information. In a binary distribution. which responds to requests for authorization tokens. Then. You cannot skip steps.xml; not included in binary release http://manifoldcf. and also run the Hsqldb­based tests. referred to by properties. These are enumerated below: A database. These contents are described below. which is the process that actually crawls documents and ingests them A crawler­ui servlet. type: mvn clean install            This should generate all the necessary artifacts to run with. you need to start with a Unix system that has the apache2 development tools installed on it. which responds to REST API requests These underlying components can be packaged in many ways. One may also deploy all three servlets in one combined web application.1/en_US/how­to­build­and­deploy. Preparation No special preparation is required. Binary organization Whether you build ManifoldCF yourself. thus avoiding conditional compilation. Building ManifoldCF's Apache2 plugin To build the mod­authz­annotate plugin. If you want to change the configuration in any way. For example. Apache Ant is considered to be ManifoldCF's primary build system. and executes under Maven using only the Quick Start example. dist file/directory connectors. plus the curl development package (from http://curl. or the build will fail. usually PostgreSQL A synchronization directory.xml connector­lib connector­lib­ proprietary Distribution directories and files Meaning an xml file describing the connectors that should be registered jars for all the connectors. type: mvn clean package            NOTE: Due to current limitations in the ManifoldCF Maven poms. the three servlets can be deployed in separate war fields as separate web applications. and type "make". the contents of the distribution are the contents of the dist directory. or download a binary distribution. referred to by properties. you will need to rebuild with Maven accordingly. How to build Building is straightforward.org/release/release­2.so. to only build ManifoldCF artifacts. so your mileage with Maven may vary.html#Running+ManifoldCF 6/17 .apache. given a user name An api­service servlet. which should be copied to the appropriate Apache2 directory so it can be used as a plugin. cd to mod­authz­annotate.haxx. Running ManifoldCF Overview ManifoldCF consists of several components.se or elsewhere). which how ManifoldCF coordinates activity among its various processes An agents process. The biggest limitation of the current Maven build is that it does not support any of the proprietary connectors or the multi­process model of execution. which presents the UI users interact with to configure and control the crawler An authority­service servlet. type: mvn clean install ‐DskipITs               When you have the default package installed locally in your Maven repository. other than to have access to the Apache Maven repository.            Building the framework and the connectors using Apache Maven ManifoldCF includes some support for building jars under Maven. the binary build result can be found in the subdirectory dist. The build includes only the Apache­licensed and LGPL­licensed connectors.2015/7/18 Building ManifoldCF The following part is useful for not saving the source json on the index which reduces the index size significantly. you will need to know what is what in the build result. Be aware that you shouldn't do this if you will need to re­index data on the ElasticSearch side or you need access to the whole document: "_source" : {   "excludes" : [ "file" ] }. To build and skip only the integration tests. A canned version of all configuration files are included as resources.  The command ant download­dependencies will do most of this for you. excluding example all proprietary libraries multiprocess­file­ scripts and jars for an example that uses the multiple process model using file­based synchronization.xml fields jars for all of the examples. incompatibly­licensed jars may not be redistributed. excluding all proprietary libraries example­proprietary a jetty­based example that runs in a single process (except for any connector­specific processes). For each of the processes subdirectories above. referenced by the proprietary example scripts scripts. referenced by the example scripts proprietary jars for all of the examples. we suggest you try the quick­start single process model first. The directory titled processes include separate processes which must be started in order for the associated connector to function. Nor can the JDBC Connector access MySQL. e. since that is the easiest. with the exception of the Oracle JDBC driver. See the README file in each directory for detailed instructions on how to deploy the components. and ­D switch values needed for the required connector­specific processes jars and scripts for running the ManifoldCF script interpreter a jetty­based example that runs in a single process (except for any connector­specific processes). the Solr connector includes plug­in classes for enforcing ManifoldCF security on Solr 3.sh]            http://manifoldcf. single­process models limit the flexibility of deploying ManifoldCF components.jar. excluding all proprietary libraries multiprocess­zk­ scripts and jars for an example that uses the multiple process model using ZooKeeper­based synchronization. or Oracle databases in that distribution.x. The directory example­proprietary contains an equivalent example that includes proprietary connectors and jars. The supplied scripts for a process generally take care of building an appropriate classpath and setting necessary ­D switches. for inclusion in properties. you must build ManifoldCF yourself. you will find everything you need to fire up ManifoldCF in a single­process model under Jetty. SyBase. All you need to do to run this version of ManifoldCF is to follow the Ant­based build instructions above. excluding all proprietary libraries web­proprietary app­server deployable web applications (wars). This single­process version uses Jetty to handle its web applications.txt describes the jars that you need to add to the connector­lib­proprietary directory in order to get the corresponding connector working.xml file accordingly to enable the connector for use. any scripts that pertain to that connector­supplied process will be placed in the root level of the subdirectory. it is important to remember that "more" is not necessarily "better". A README. This is the standard place to start if you build ManifoldCF yourself. These jars are not included in the binary distribution. several connectors are structured using multiple processes precisely for that reason. Inside the example directory. Multi­process models require that inter­process synchronization be properly configured. classpath jars.1/en_US/how­to­build­and­deploy. and Hsqldb as an embedded database. These are enumerated below: Quick­start single process model Single­process deployable war Simplified multi­process model Command­driven multi­process model Each way has advantages and disadvantages. and then: cd example start[. for evaluation and convenience.bat|. This is because under Apache licensing rules.org/release/release­2. The proprietary libraries required by the secondary process processes subdirectories should be in the directory processes/xxx/lib­ proprietary. You will also then need to uncomment the appropriate entries in the connectors. include support for MySQL. If you are just starting out with ManifoldCF. For example. MSSQL. including proprietary libraries; not included in binary release doc javadocs for framework and all included connectors plugins pre­built integration components to deploy on target systems. because optional individual connectors may or may not supply processes that must be run to support the connector. Example deployments There are many different ways to run ManifoldCF out­of­the­box. The process deployment strategy implied by the build structure has been carefully thought out to avoid jar conflicts. Everything is included so that all you need to do is change to that directory.txt file is placed in each lib­proprietary directory describing what needs to be provided there.2015/7/18 Building ManifoldCF obfuscation­utility lib lib­proprietary processes script­engine example a utility to obfuscate passwords.html#Running+ManifoldCF 7/17 . for Solr If you downloaded the binary distribution. This is described in more detail later. Each such <connector>­README. at this time. NOTE: The prebuilt binary distribution cannot. Quick‐start single process model You can run most of ManifoldCF in a single process. and start it using the command <java> ­jar start. (Note: none of the current connectors require special ­D switches at this time. Indeed. including example­proprietary proprietary libraries; not included in binary release multiprocess­zk­example scripts and jars for an example that uses the multiple process model using ZooKeeper­based synchronization. Start by downloading the drivers and placing them in the lib­proprietary directory.apache. The number of produced processes subdirectories may vary.txt files. In order to use these JDBC drivers. For example.) If you need to construct a classpath by hand. The plugins directory contains components you may need to deploy on the target system to make the associated connector function correctly. and you will need to supply them in order to make the process work. example­proprietary including proprietary libraries; not included in binary release web app­server deployable web applications (wars).x and 4. and is the recommended way for beginners to try out ManifoldCF. you may notice that the connector­lib­proprietary directory contains only a number of <connector>­README.g. including proprietary libraries; not included in binary release multiprocess­file­ scripts and jars for an example that uses the multiple process model using file­based synchronization.  The programmatic API is at http://<host>:8345/mcf­api­service. Furthermore. or use the Tomcat service administration client.xml to find it syncharea an example ManifoldCF synchronization directory. Then.sh|.bat]). so you cannot use any of the ManifoldCF commands (as described below) while the quick­start ManifoldCF is running. the Documentum and FileNet connectors require processes to be independently started in order to function. You can stop the quick­start ManifoldCF at any time using ^C.bat] script to clean up dirty locks (run only when all webapps and processes are stopped) Initializing the database and running If you run the file­based multiprocess model.2015/7/18 Building ManifoldCF In the quick­start model. (The multiprocess­file­example­proprietary directory is similar but includes proprietary material and is available only if you build ManifoldCF yourself. embedded Hsqldb only permits one process at a time to be connected to its databases. Inside the multiprocess­ file­example directory. The crawler UI can be found at http://<host>:8345/mcf­crawler­ui. Running multiprocess file‐based example using Tomcat In order to run the ManifoldCF multiprocess file­based example under Tomcat.sh|. you will need to take the following steps: 1.  Deploy and start the mcf­combined­service web application. This web application contains the exact same functionality as the quick­start example. all you need to do is run the initialize[.sh|.war. you will need to start the web applications (using start­webapps[.) Below is a list of what you will find in this directory.  Start Tomcat. The authority service can be found at http://<host>:8345/mcf­authority­service/UserACLs. 3. which must be writable in order for multiprocess ManifoldCF to work logs where the ManifoldCF logs get written to start­database[.xml file. Scripts for running these processes can be found in the directories named processes/xxx. You can execute the script as follows:   cd example   start‐combined[.xml an example ManifoldCF configuration file. The authority service functionality can be found at http://<host>:8345/mcf/UserACLs.bat] script to create the database instance. but bundled up as a single war instead.bat]).bat]) and the agents process (using start­agents[. all database initialization and connector registration takes place automatically whenever ManifoldCF is started (at the cost of some startup delay).sh|. create all database tables.bat] script. and the same properties.sh] Bear in mind that Hsqldb is not as full­featured a database as is PostgreSQL. in the right place for the multiprocess script to find it logging. using the same convention as described for tomcat.sh|. the programmatic API service has a path other than the root: http://<host>:8345/mcf/api/.org/release/release­2. An example script is provided to run this web application under Jetty.ini an example ManifoldCF logging configuration file. 2. you will need to take the following steps: http://manifoldcf. after you first start the database (using start­database[. The same caveats about required individual connector processes also apply as they do for the quick­start example. in the right place for the properties. or by using the script stop[.sh|.bat] script to start the (first) agents process start­agents­2[. This means that any performance testing you may do against the quick start example may not be applicable to a full installation. and optionally the second agents process (using start­agents­2[.bat] script to start a second agents process stop­agents[.bat]            The combined web service presents the crawler UI at the root path for the web application. and register connectors start­webapps[. there is a war file called mcf­combined­service. Running single‐process combined war example using Tomcat In order to run the ManifoldCF single­process combined war example under Tomcat.bat] script to stop all running agents processes cleanly lock­clean[. Simplified multi‐process model using file‐based synchronization ManifoldCF can also be deployed in a simplified multi­process model which uses files to synchronize processes. preferably using the Tomcat administration client. you will find everything you need to do this.sh|. along with ­ D switches. You will need to read about these connector­specific processes below in order to use the corresponding connectors. Specifically. above properties.sh|.apache. The script that starts the combined­service web application uses the same database instance (Hsqldb by default) as does the quick­start.sh|.sh|. plus recommended application server ­D switch names and values processes classpath jars that should be included in the class path for all non­connector­specific processes.sh|.bat|.1/en_US/how­to­build­and­deploy. which is http://<host>:8345/mcf/.sh|.manifoldcf. Another caveat that you will need to be aware of with the quick­start version of ManifoldCF is that it in no way removes the need for you to run any separate processes that individual connectors require. to set a Java "­Dorg. similar to the quick­start example.bat] script to start Jetty with the ManifoldCF web applications deployed start­agents[.html#Running+ManifoldCF 8/17 . However. you will need to initialize the database before you start the agents process or use the crawler UI.xml file.  Modify the Tomcat startup script.bat] script to start the HSQLDB database initialize[. To do this.bat]).apache. File­based multiprocess example files and directories multiprocess­file­ Meaning example file/directory web Web applications that should be deployed on tomcat or the equivalent.configfile" switch to point to the example's properties.sh|. Single‐process deployable war Under the distribution directory web/war. bat]) 5.apache.bat]) 3.bat]) 3.bat]) 4. and are thus considered to be ManifoldCF commands.sh|.sh|.bat]script to initialize ZooKeeper with properties from properties­global.  Deploy and start the mcf­crawler­ui.  Initialize the ManifoldCF shared configuration data (using setglobalproperties[. in the right place for the setglobalproperties script to find it logging.xml an example ManifoldCF shared configuration file. and optionally start­agents­2[. with appropriate arguments supplied. then you must follow the following steps: 1.sh|. to set a Java "­Dorg. mcf­authority­service.bat]. which must be writable in order for ZooKeeper to work logs where the ManifoldCF logs get written to runzookeeper[.  Deploy and start the mcf­crawler­ui.configfile" switch to point to the example's properties. you will find everything you need to do this.bat] script to start a second agents process stop­agents[.  Start the agents process (using start­agents[.sh|.  Start Tomcat. 7.xml file. using the same convention as described for tomcat.sh|.sh|.  Start the database (using start­database[. These classes are usually invoked from the command line. in the right place for the multiprocess script to find it properties­global. There are a number of java classes among the ManifoldCF classes that are intended to be called directly.apache.sh|.bat] script to start Jetty with the ManifoldCF web applications deployed start­agents[.  Start the database (using start­database[.bat] script) 2.html#Running+ManifoldCF 9/17 .2015/7/18 Building ManifoldCF 1.sh|.sh|.sh|. along with ­ D switches.bat] script to start (the first) agents process start­agents­2[. plus recommended application server ­D switch names and values processes classpath jars that should be included in the class path for all non­connector­specific processes.1/en_US/how­to­build­and­deploy.bat] script to run a ZooKeeper server instance setglobalproperties[. and mcf­api­service web applications.bat]) 2.  Start the web applications (using start­webapps[. mcf­authority­service. preferably using the Tomcat administration client. or use the Tomcat service administration client.  Initialize the database (using initialize[.bat]) Running multiprocess ZooKeeper example using Tomcat In order to run the ManifoldCF ZooKeeper example under Tomcat.bat]) 4. Inside the multiprocess­kz­example directory.manifoldcf.  Initialize the ManifoldCF shared configuration data (using setglobalproperties[.bat].sh|. to set a Java "­Dorg.sh|. and optionally start­agents­2[.sh|.sh|. in the right place for the properties.sh|.  Start Tomcat. 6.  Start the database (using start­database[.  Initialize the database (using initialize[.org/release/release­2.sh|. above properties.  Start ZooKeeper (using the runzookeeper[. Simplified multi‐process model using ZooKeeper‐based synchronization ManifoldCF can be deployed in a simplified multi­process model which uses Apache ZooKeeper to synchronize processes. 5. you will need to take the following steps: 1. Basic functionality supplied by these command classes is as follows: Create/Destroy the ManifoldCF database instance Start/Stop the agents process http://manifoldcf.sh|.  Start the agents process (using start­agents[. 8.sh|.xml an example ManifoldCF configuration file.bat] script to create the database instance.  Modify the Tomcat startup script.xml start­database[.sh|. and optionally start­agents­2[.sh|.bat]) 5. and mcf­api­service web applications. (The multiprocess­zk­example­proprietary directory is similar but includes proprietary material and is available only if you build ManifoldCF yourself.configfile" switch to point to the example's properties. to perform specific actions in the environment or in the database. preferably using the Tomcat administration client. ZooKeeper­based multiprocess example files and directories multiprocess­zk­ Meaning example file/directory web Web applications that should be deployed on tomcat or the equivalent.sh|. Command‐driven multi‐process model The most generic way of deploying ManifoldCF involves calling ManifoldCF operations using scripts. and register connectors start­webapps[.xml to find it zookeeper the example ZooKeeper storage directory.sh|.bat] script to start the HSQLDB database initialize[.  Initialize the database (using initialize[.sh|.bat]) 6.  Start the agents process (using start­agents[.xml file. or use the Tomcat service administration client.  Modify the Tomcat startup script.apache.  Start ZooKeeper (using the runzookeeper[. create all database tables.sh|.sh|.bat].bat] script) 2.ini an example ManifoldCF logging configuration file.bat]) 6.manifoldcf.bat]) 3.) Below is a list of what you will find in this directory.bat] script to stop all running agents processes cleanly Initializing the database and running If you run the ZooKeeper­based multiprocess example.bat]) 4.  you should be able to interact with the ManifoldCF UI.war.agents.1/en_US/how­to­build­and­deploy.manifoldcf.html#Running+ManifoldCF 10/17 .manifoldcf. The PostgreSQL JDBC driver included with ManifoldCF is known to work with version 9.DBCreate org.RegisterTransformation Function Create ManifoldCF database instance Drop ManifoldCF database instance Clean out synchronization directory Obfuscate a string.manifoldcf.SynchronizeTransformations None Function Create ManifoldCF agents tables Remove ManifoldCF agents tables Register an agent class Un­register an agent class Un­register all current agent classes Un­register all registered agent classes that can't be found Register an output connector class Un­register an output connector class Un­register all current output connector classes Un­register all registered output connector classes that can't be found Register a transformation connector class Un­register a transformation connector class Un­register all current transformation connector classes Un­register all registered transformation connector classes http://manifoldcf. so that version is the currently recommended one.agents.manifoldcf.UnRegisterOutput org.apache. Create the database instance (see commands below) Initialize the database instance (see commands below) Register the pull agent (org.agents.2015/7/18 Building ManifoldCF Register/Unregister an agent class (there's currently only one included) Register/Unregister an output connector Register/Unregister a transformation connector Register/Unregister a repository connector Register/Unregister an authority connector Register/Unregister a mapping connector Clean up synchronization directory garbage resulting from an ungraceful interruption of an ManifoldCF process Query for certain kinds of job­related information Individual connectors may contribute additional command classes and processes to this picture.manifoldcf.agents.) The basic steps required to set up and run ManifoldCF in command­driven file­based multi­process mode are as follows: Install PostgreSQL or MySQL.manifoldcf.bat|.manifoldcf.UnRegisterAllTransformationsNone org.Obfuscate Arguments dbuser [dbpassword] dbuser [dbpassword] None string Agents Command Class org. The classes implementing these commands are specified below. Core Command Class org. ManifoldCF provides a set of commands for performing these actions.Install org.agents.manifoldcf.manifoldcf.apache.manifoldcf.manifoldcf.RegisterOutput org.manifoldcf.core.agents. which can be accessed via the mcf­crawler­ui web application The detailed list of commands is presented below.apache. Set the starting environment variables for your app server to include any ­D commands found in web/define. and others as well.DBDrop org.core. register the "pull­agent" agent.SynchronizeOutputs org.manifoldcf.bat].CrawlerAgent.UnRegisterAll org.SynchronizeAll org.manifoldcf.sh] command from execute the appropriate commands from the next section below. the ant "download­dependencies" build target will fetch the appropriate MySQL JDBC driver. and MCF_HOME. Configure the database for your environment; the default configuration is acceptable for testing and experimentation.apache.agents. You will also need a "­Dorg. Use the processes/executecommand[.) Start your application server.core. to your application server (see below).system.apache.agents.apache. This script requires two environment variables to be set before execution: JAVA_HOME.Uninstall org.UnRegisterTransformation classname org. Commands After you have created the necessary configuration files.LockClean org. you will need to initialize the database. The multiprocess command execution scripts are delivered in the processes subdirectory.org/release/release­2.apache.apache.apache. for use as an obfuscated parameter value Arguments None None classname classname None None classname description classname None None classname description org. "­D<file name>=<file contents>". The script for executing commands is processes/executecommand[. see below) Register your connectors and authorities (see below) Install a Java application server.UnRegisterAllOutputs org.apache.agents.manifoldcf.crawler.xml file is found. If you want to use MySQL. being sure to first set the JAVA_HOME and MCF_HOME environment variables properly.agents. Start the ManifoldCF agents process. Start any supporting processes that result from your build. or the equivalent. which should point to ManifoldCF's home execution directory. (Some connectors such as Documentum and FileNet have auxiliary processes you need to run to make these connectors functional.manifoldcf. except for mcf­combined.sh|. such as Tomcat.apache.1.apache.apache.apache.UnRegister org.apache. where the properties.configfile=<properties file>" define option.manifoldcf.apache.manifoldcf.apache. and then register your individual connectors. At this point.agents. in the application server's JVM startup in order for ManifoldCF to be able to locate its configuration file. Deploy the war files from web/war.core.agents.apache.Register org.agents.apache.apache.agents.manifoldcf. The ­D commands should be of the form.apache.manifoldcf.  The same passcode along with the salt value are used to decrypt the file with the ImportConfiguration command class.manifoldcf.manifoldcf.UnRegisterAuthority classname org.2015/7/18 org.html#Running+ManifoldCF 11/17 . You should ignore the mcf­combined war in this directory for this deployment model. The file has this basic format: <?xml version="1. called connectors.authorities.manifoldcf.apache.configfile=<configuration file path>              Running the agents process The agents process is the process that actually performs the crawling for ManifoldCF.0" encoding="UTF‐8" ?> <connectors>  (clauses) </connectors> http://manifoldcf.manifoldcf. they must be deployed on the same physical server. It is highly recommended that you stop the process in this way.RegisterAuthority Arguments classname description org.authorities. and mcf‐api‐service web applications If you built ManifoldCF using ant. however.manifoldcf.crawler.manifoldcf.AgentStop".apache.SynchronizeConnectorsNone Function Register a repository connector class org.AgentStop Building ManifoldCF that can't be found Main agents process class Stops the running agents process None None Crawler Command Class org. There is no requirement that the mcf­crawler­ui.apache. but "kill ­9" or the equivalent is NOT recommended.SynchronizeMappers None Authority Command Class org.authorities.agents.manifoldcf.authorities.UnRegisterMapper classname org. which is used to register the available connectors in the database. In order to use this functionality.agents.crawler.crawler.manifoldcf.manifoldcf.apache.agents.apache.manifoldcf.apache.crawler.authorities.UnRegisterAllAuthoritiesNone org.) The connectors.agents.manifoldcf.apache. Deploying the mcf‐crawler‐ui.AgentRun".apache.apache.manifoldcf.ExportConfiguration Un­register a repository connector class Un­register all repository connector classes Un­register all registered repository connector classes that can't be found Export crawler configuration to a file org.UnRegister classname org.apache.SynchronizeAuthorities None Function Register an authorization domain Un­register an authorization domain Function Register a mapping connector class Un­register a mapping connector class Un­register all mapping connector classes Un­register all registered mapping connector classes that can't be found Function Register an authority connector class Un­register an authority connector class Un­register all authority connector classes Un­register all registered authority connector classes that can't be found Remember that you need to include all the jars under multiprocess­file­example/processes/lib in the classpath whenever you run one of these commands! But.manifoldcf. The scripts require some environment variables to be set.manifoldcf.authorities. there are scripts which do this for you.UnRegisterAllMappersNone org.manifoldcf.apache.UnRegisterDomain Arguments domainname description domainname User Mapping Command Class org.UnRegisterAll None org.authorities. you will need to deploy the other web applications on you application server.manifoldcf. Authorization Domain Command Class org. mcf‐authority‐service.crawler. Start this process by running the command "org.apache.RegisterDomain org.apache. and invoking the command "org.apache.sh. the exported file will be encrypted by using the AES algorithm.authorities. and mcf­api­service web applications be deployed on the same instance of the application server.AgentRun org. With the current architecture of ManifoldCF. then the ant build will have constructed four war files for you under web/war. See the documentation for the commands and properties above to find the correct arguments and settings.apache.authorities.apache. such as MCF_HOME and JAVA_HOME.manifoldcf. (If you have to.apache.apache.manifoldcf. You may also stop the process using a SIGTERM signal. and simplified multi­process sample deployments of ManifoldCF have their own configuration file. you must set the following define.apache.org/release/release­2.Register Arguments classname description org.LockClean".crawler. so that the ManifoldCF web applications can locate the configuration file: ‐Dorg.apache. mcf­authority­service.bat]. For each of the application servers involved with ManifoldCF.1/en_US/how­to­build­and­deploy.manifoldcf. you must enter a salt value to your configuration file.manifoldcf..xml configuration file The quick­start.xml. These can be found in multiprocess­file­ example/processes/executecommand[. luckily.manifoldcf.core.RegisterMapper Arguments classname description org. and expect the configuration file to be found at MCF_HOME/properties. If you intend to run ManifoldCF in multiprocess mode. combined.authorities.apache. This class will run until stopped by invoking the command "org.manifoldcf.ImportConfiguration filename [passcode] filename [passcode] Import crawler configuration from a file NOTE: By adding a passcode as a second argument to the ExportConfiguration command class. including the application server instances that are running the web applications. This can be useful to prevent repository passwords to be stored in clear text.apache. because that may result in dangling locks in the ManifoldCF synchronization directory.xml.apache. clean up these locks by shutting down all ManifoldCF processes. Connector Process Documentumprocesses/documentum­ server Documentumprocesses/documentum­ registry FileNet processes/filenet­server FileNet processes/filenet­registry Main class Script name (relative to dist) org. if they are running in a shell). The details and caveats of each choice is described below.apache. and are listed below: PostgreSQL (preferred) MySQL (preferred) MariaDB (not yet evaluated)) HSQLDB You can select the database of your choice by setting the approprate properties in the applicable properties.crawler. ManifoldCF is currently fairly specific to PostgreSQL at this time. PostgreSQL is pretty good at doing analysis quickly.DCTM. on the other hand.DCTMprocesses/documentum­ registry/run[. so if you use this option you will still need to copy them there yourself for the processes to run.crawler. consistent with the needs of the DFC or the FileNet API respectively.server.manifoldcf. If you build ManifoldCF yourself. Running connector‐specific processes Connector­specific processes require the classpath for their invocation to include all the jars that are in the corresponding processes/<process_name> directory. The server scripts also require other environment variables as well. For example. Database selection You have a variety of open­source databases to choose from when deploying ManifoldCF.sh|.Filenet processes/filenet­registry/run[. or the server process will report an error. The supported databases each have their own strengths and weaknesses.crawler. ManifoldCF uses the database for its document queue. but for both PostgreSQL and for (say) Oracle.crawler. It is important to understand that the scripts work by building a classpath out of all jars that get copied into the lib and lib­proprietary directory underneath each process during the ant build. The back­end database is thus a significant factor in ManifoldCF's performance. takes a very long time to perform analysis. in exchange. Start these processes using the commands listed below. while other databases return this efficiently. and will not generate a performant plan if the statistics are inaccurate by even a little.bat] The registry process in all cases must be started before the corresponding server process. The lib­proprietary jars cannot be distributed in the binary version of ManifoldCF.sh|. ManifoldCF benefits enormously from the underlying ACID properties of the database.sh|. Ideally. But.org/release/release­2.xml tags commented out. for PostgreSQL.DCTM.DCTM processes/documentum­ server/run[.filenet. the example­proprietary and multiprocess­file­ example­proprietary and multiprocess­zk­example­proprietary directories instead use connectors­proprietary.manifoldcf. but its plans are much less sensitive. the lib­proprietary directories should have all of the jars needed to allow the api code to function. The Documentum and FileNet connectors are the only two connectors that currently require additional processes. it is.2015/7/18 Building ManifoldCF          The following tags are available to specify your connectors and authorization domains: <repositoryconnector name="pretty_name" class="connector_class"/> <authorityconnector name="pretty_name" class="connector_class"/> <mappingconnector name="pretty_name" class="connector_class"/> <outputconnector name="pretty_name" class="connector_class"/> <transformationconnector name="pretty_name" class="connector_class"/> <authorizationdomain name="pretty_name" domain="domain_name"/> The connectors.apache. This has affected the design of the ManifoldCF UI.manifoldcf. The strategy for getting optimal query plans from the database is not abstracted. There are a number of reasons for this.html#Running+ManifoldCF 12/17 . The connectors you build against the proprietary libraries you supply will not have their connectors­proprietary. retry after some period of time. DFC requires the DOCUMENTUM environment variable to be set.apache. to avoid catastrophically bad plans.1/en_US/how­to­build­and­deploy.registry.xml file. this is not true. The choice of database is largely orthogonal to the choice of deployment model.apache.xml file typically has some connectors commented out ­ namely the ones build with stubs which require you to supply a third­party library in order for the connector to run. If you build ManifoldCF yourself. For the server startup scripts to work properly. (It will. The ManifoldCF deployment examples provided can thus be readily altered to use the database you desire. these jars are copied from the lib­proprietary directories underneath the documentum or filenet connector directories. Configuring a PostgreSQL database Despite having an internal architecture that cleanly abstracts from specific database details.manifoldcf.filenet. the database table must be analyzed very frequently. The choice of query form influences the query plan. which places a significant load on it. PostgreSQL always does a sequential scan in order to count the number of rows in a table.bat] org.) The scripts all require an MCF_HOME environment variable pointing to the place where properties. But luckily.Filenet processes/filenet­server/run[. PostgreSQL 8.registry.server.bat] org. and stop them with SIGTERM (or ^C.xml is found. in some cases. however.apache.xml. So. http://manifoldcf. Oracle.bat] org. while the FileNet server script requires the WASP_HOME environment variable. as well as a JAVA_HOME environment variable pointing the JDK.sh|. For example.3+ is very sensitive to certain statistics about a database table.  and will display a useful "maintenance in progress" message if that file is found.conf settings as described in the table below pg_hba.xml property descriptions for configuration details. and the logging configuration file.2. manual vacuum. such as when counting outstanding documents on the job status page.4. Performance at this time is about half that of PostgreSQL. Nevertheless.configfile". which do not interfere with its performance but do bloat the database over time. which is what happens when a manual full vacuum is performed.org/release/release­2. The usage pattern of ManifoldCF is such that it can cause significant bloat to occur to the underlying PostgreSQL database in only a few days. and manual full vacuum. The form of the property file is XML. scheduled maintenance operations instead. We have found that PostgreSQL's autovacuum feature is inadequate under such conditions.1. and 9. because it not only fights for database resources pretty much all the time.conf parameter standard_conforming_strings shared_buffers checkpoint_segments maintenanceworkmem tcpip_socket max_connections checkpoint_timeout datestyle autovacuum Tested value on 1024MB 300 2MB true 400 900 ISO.European off Note well: The standard_conforming_strings parameter setting is important to prevent any possibility of SQL injection attacks. ManifoldCF requires two configuration files: the main configuration property file.1/en_US/how­to­build­and­deploy. Nevertheless. or in external fashion. ManifoldCF has been tested against version 8. While ManifoldCF uses parameterized queries in almost all cases. We therefore recommend periodic. so tables that have had a lot of activity may benefit from being reindexed at the time of maintenance. consisting of the following: VACUUM FULL VERBOSE; REINDEX DATABASE <the_db_name>; During maintenance. called vacuuming. ManifoldCF thus has the ability to check for the existence of a file prior to such sensitive operations.2015/7/18 Building ManifoldCF PostgreSQL has a high degree of parallelism and lack of internal single­threadedness. 9.apache. properties. PostgreSQL's in­place manual vacuum functionality is a bit better. with a database instance running in a separate process.conf settings to allow password access for TCP/IP connections from ManifoldCF A maintenance strategy involving cronjob­style vacuuming. its name is presumed to be <user_home>/lcf/properties. under sufficient load. but is still much. HSQLDB can be used with ManifoldCF in either an embedded fashion (which only works with single­process deployments). It is in general good practice to set this parameter when working with PostgreSQL for this reason.apache. Configuring a MySQL database MySQL is not quite as fast as PostgreSQL. 9. If not specified through a ­D operation.5.manifoldcf. This comes in three varieties: autovacuum. when it does do string quoting it presumes that the SQL standard for quoting is adhered to. 8. More details will be added to this section as information and experience becomes available. See the properties. PostgreSQL locks tables one at a time. The ManifoldCF configuration files Currently.xml. A note about PostgreSQL database maintenance PostgreSQL's architecture causes it to accumulate dead tuples in its data files.html#Running+ManifoldCF 13/17 .7.conf parameters postgresql. Configuring an HSQLDB database HSQLDB's performance seems closely tied to how much of the database can be actually held in memory.3 of PostgreSQL.xml file properties The properties. but it falls further and further behind as well. but it is a relatively close second in performance tests. We recommend the following configuration parameter settings to work optimally with ManifoldCF: A default database encoding of UTF­8 postgresql. PostgreSQL has a feature to address this bloat. of the following basic form: <?xml version="1. the crawler ui may become unresponsive for some operations. much slower than actually making a new copy of the database files.xml property file path can be specified by the system property "org.0" encoding="UTF‐8" ?> <configuration>  (clauses) </configuration> http://manifoldcf. rather than PostgreSQL autovacuum Postgresql. the ManifoldCF team does not have a large amount of experience with this database at this time. Dead­tuple bloat also occurs in indexes in PostgreSQL. This allows a user to set up a maintenance system that provides adequate feedback for an ManifoldCF user of the overall status of the system.3. login.lockmanager.apache. org.manifoldcf.manifoldcf.apache. Defaults to 500000.dbsuperusername No Database superuser name.1/en_US/how­to­build­and­deploy.xml file allows properties to be specified.apiservicewarpath org. org. using the org.org/release/release­2.database.DBInterfaceHSQLDB org.manifoldcf. org.database. HSQLDB connection org. If not present.apache.apache. for Jetty true for single­process example.postgresql. org. Defaults to 2000.manifoldcf.apache.manifoldcf.hsqldbdatabaseport No The HSQLDB remote server port.apache.manifoldcf.login.apache. You may want to set this to '%' for a multi­machine setup. via a ­D switch.maxhandles No Specifies the maximum number of database connection handles Property org.manifoldcf. org.manifoldcf.zookeeper. org.DBInterfacePostgreSQL. If both methods of setting the property are used.server No The MySQL or MariaDB server name. and what they do: property. This property's name is "org.database.apipassword org.apache.hsqldbdatabasepath No Absolute or relative path to HSQLDB database; default is '.login.login.ssl No Set to "true" for ssl communication with PostgreSQL. org.manifoldcf.manifoldcf.apache.core. Note that all properties described below can also be specified on the command line. A property clause has the form: <property name="property_name" value="property_value"/> One of the optional properties is the name of the logging configuration file. for QuickStart. Defaults to 'localhost'.xml file.lockmanager. synchronization class is specified org.zookeeper.manifoldcf.manifoldcf.dbsuperuserpassword.lockmanagerclass No Specifies the class to use to implement synchronization. for remote The HSQLDB remote server name. the ­D switch value will override the property file value.maxstatuscount No The maximum number of documents ManifoldCF will try to count for the job status display. so ManifoldCF can create database instance.2015/7/18 Building ManifoldCF            The properties. org.connectstring Yes.manifoldcf. for remote The HSQLDB JDBC protocol; choices are 'hsql'.synchdirectory Yes. No Location of connectors.apache.mysql. if ZooKeeperLockManager is specified.obfuscatedNo Obfuscated database superuser password. org.manifoldcf.manifoldcf. so ManifoldCF can create database instance.core.ini.manifoldcf.manifoldcf.sessiontimeout No Specifies the ZooKeeper session timeout.manifoldcf.'. Options include org.apache.manifoldcf.apipassword.apache. org.logconfigfile".apache.manifoldcf.apache.core.apiname org.apache.DBInterfaceMariaDB.password org. The following table describes the configuration property file properties.apache. or 'https'.apache.apache.apache. the logging configuration file will be assumed to be <user_home>/manifoldcf/logging.password. org. org. 'http'.hsqldbdatabaseinstance No The HSQLDB remote database instance name. or localhost if not specified. for Jetty Location of Crawler UI war Yes. and org.apache.apache. if Specifies the ZooKeeper connection string. org. Supported choices are: org.obfuscated org.apache.apache. or standard port if not specified.mysql.core. Default is a built­in Hsqldb implementation.manifoldcf.apache.postgresql.apache.apache.manifoldcf. All ManifoldCF based process owners must have read/write privileges to this directory.apache.login.apache.apache.apache. org. for Jetty Location of API Service war Yes.apache.FileLockManager.name org.core.authorityservicewarpath org.hostname No PostgreSQL server host name.core.LockManager class.apache. Default is either file­based synchronization or in­memory synchronization.manifoldcf. for QuickStart. org.apache.manifoldcf. so ManifoldCF can register connectors.manifoldcf. based synchronization class is specified org.DBInterfaceMySQL.obfuscated org.manifoldcf.manifoldcf. for Jetty Location of Authority Service war Yes.manifoldcf.postgresql. org.manifoldcf.BaseLockManager.lockmanager.manifoldcf.manifoldcf.apache.manifoldcf.manifoldcf.login.client No The MySQL or MariaDB client property. and should be formatted accordingly. consisting of comma­ ZooKeeper­ separated hostname:port pairs.apache.usejettyparentclassloader org.connectorsconfigurationfile http://manifoldcf. false for multiprocess example.manifoldcf. The logging configuration file is a standard commons­logging property file.manifoldcf.database.xml properties Required? Function No Crawler UI login user ID (defaults to "admin") No Crawler UI login user password (defaults to "admin") No Obfuscated crawler UI login user password (defaults to "admin") No API login user ID (defaults to "") No API login user password (defaults to "") No Obfuscated API login user password (defaults to "") Yes.apache. org. for QuickStart. org.manifoldcf.databaseimplementationclass No Specifies the class to use to implement database access.apache. so ManifoldCF can create database instance.hsqldbdatabaseprotocol Yes.ZooKeeperLockManager.apache.apache.hsqldbdatabaseserver Yes.manifoldcf.html#Running+ManifoldCF 14/17 .port No PostgreSQL server port.ui.core.core.apache. for QuickStart.dbsuperuserpassword No Database superuser password. Defaults to 'localhost'. HSQLDB Default is blank (which means an embedded instance) connection org. if file­ Specifies the path of a synchronization directory.database.crawleruiwarpath org.manifoldcf.apache.manifoldcf. org.manifoldcf.  which is the maximum allowable. Default is 0.hopcount No org.mysql. WARN. WARN.db.manifoldcf. Suggest a value of 10.apache.manifoldcf.crawler.crawler. or DEBUG. or DEBUG.crawler. org.apache.username No org. or DEBUG.manifoldcf. Number of crawler worker threads created.manifoldcf.manifoldcf.database. Number of crawler expiration threads created. The following table describes 'advanced' configuration property file properties.html#Running+ManifoldCF 15/17 . specify how many changes should be carried <tablename> out before carrying out an 'REINDEX' on the specified table.apache.jobs org. org. or DEBUG. Legal values INFO.crawler. specify how many changes should be carried out before carrying out an 'ANALYZE' on the specified table.apache.<tablename> No org.apache.database.manifoldcf.apache.maxstatuscount No 2000 For MySql or MariaDB.postgres.manifoldcf. WARN. Legal values INFO.apache.manifoldcf. Suggest a value of 10.apache.logconfigfile org. Number of crawler cleanup threads created.apache. WARN.manifoldcf.apache. Milliseconds to retain history records.manifoldcf.misc No org.crawlerthreads No org. ". Specify the salt value to be used for encrypting the file to which the crawler configuration is exported. or DEBUG. Describes database user name for ManifoldCF; defaults to "manifoldcf" if not specified.apache.manifoldcf.apache. org. and will dump an allocation stack trace when the pool is exhausted.manifoldcf.apache. or DEBUG. They shouldn't need to be changed but provide a greater level of customization: Advanced property." means the directory in which the properties. Log job activity. Suggest a value of 30.database.apache. This can increase throughput and reduce the rate of growth of the database. Specifies location of logging configuration file.historycleanupinterval No No org.apache.database.password. Legal values INFO.cleanupthreads No org.manifoldcf.connectiontracking No org.postgres. or DEBUG.db No org. Log connector activity.manifoldcf. Agent management debugging output.handletimeout No org.store_historyNo true If you do not require reports from within this will disable logging to the repository history (although the reports will still run they will not contain any content).repository.authorityservice No org.salt Yes.manifoldcf.lock No org.database.crawler.deletethreads org. Obfuscated database user's password for ManifoldCF; defaults to "local_pg_password" if not specified.manifoldcf. WARN.manifoldcf.apache.manifoldcf.manifoldcf.apache.apache. Log document scheduling activity. Legal values INFO. WARN. 500000 Set the upper limit for the precise document count to be returned on the 'Status and Job Management' page. WARN. specify how many changes should be carried <tablename> out before carrying out an 'ANALYZE' on the specified table. Legal values INFO.apache.name No No org.org/release/release­2. WARN. if file encryption is used Specifies the maximum time a handle is to live before it is presumed dead. Suggest a value of 10. Legal values INFO. Miscellaneous debugging output. or DEBUG.database. or DEBUG.2015/7/18 Building ManifoldCF that will by pooled.ui.apache. Describes database name for ManifoldCF; defaults to "dbname" if not specified. Legal values INFO.apache. No 2000 For postgresql. Legal values are INFO. Recommended value is 200.apache. True or false. Zero means "forever".manifoldcf. or DEBUG. The configuration file can also specify a set of directories which will be searched for connector jars.apache.manifoldcf.apache.manifoldcf. Log authority connector activity.manifoldcf.manifoldcf. No 250000 For postgresql. org.apache. Cache management debugging output.manifoldcf.reindex. Useful for diagnosing connection leaks.perf No org.apache. Log authority service activity. or DEBUG. WARN.1/en_US/how­to­build­and­deploy.obfuscated No org. Log crawler thread activity.apache. For the purposes of path resolution.apache.manifoldcf. WARN. Legal values INFO. When "true". Legal values INFO.scheduling No No No org.crawler. or DEBUG. WARN. Recommend a value of 604800. Performance logging debugging output. will track all allocated database connection handles. Legal values INFO.apache. Database debugging output. The directive that adds to the class path is: <libdir path="path"/> Note that the path can be relative.threads org.manifoldcf. Legal values INFO.apache.password No org. Lock management debugging output.xml file is itself http://manifoldcf.apache. Number of crawler delete threads created.manifoldcf.apache.db. Legal values INFO.agents No org.analyze.expirethreads No No org.xml properties Property Required?Default Function org.cache No org.db. Describes database user's password for ManifoldCF; defaults to "local_pg_password" if not specified.analyze. WARN.manifoldcf.connectors org.manifoldcf. WARN. or DEBUG.authorityconnectors No org.manifoldcf. Log hopcount tracking activity.  as a nicety. the command classes that register connectors are very small and should be easy to understand. You currently don't get a lot of options here; the only model offered is the QuickStart single process model. Similarly. The service receives a user identity (as a set of authorization domain/user name tuples). Logging configuration file properties The logging. "Off" The authority URL The authority URL The authority URL The authority URL Running ManifoldCF with Apache Maven If you build ManifoldCF with Maven. that if you start the ManifoldCF agents process within a web application. Integrating ManifoldCF with a search engine ManifoldCF's Authority Service is designed to allow maximum flexibility in integrating ManifoldCF security with search engines. These access tokens are then passed to a (not included) search engine UI. but not ID queries Point to an authority service that supports ACL queries.manifoldcf.conf file.conf file.html#Running+ManifoldCF 16/17 .g. The following connectors are expected to make use of this authority: FileNet CIFS SharePoint Configuring the ManifoldCF Apache2 plug in mod­authz­annotate understands the following httpd. you can either use this class to start them under Jetty.g. which uses authority connections defined in the crawler UI to obtain appropriate access tokens. This project includes only one such service: the java authority service.ManifoldCFJettyRunner class. It also returns a summary of the status of all authorities that were involved in the assembly of the set of tokens. as are any loggers that ManifoldCF doesn't explicitly define (e. and produces a set of tokens. loggers for Apache commons­httpclient). mod­authz­annotate.jettyrunner. Other resources are therefore best suited to describe the parameters that can be used and to what effect. passed as URL arguments and properly URL encoded: Authority Service URL Authority Service URL parameters Meaning http://manifoldcf. In order for mod­authz­annotate to be used. If you want to try the single­process integration. The Authority Service expects the following arguments. Note: The ManifoldCF project now contains support for converting a Kerberos principal to a list of Active Directory SIDs. A search engine user interface could thus signal the user when the results they might be seeing are incomplete. all of the ManifoldCF processes might as well exist on their own. We'll cover these below.apache. and query a set of authority services for access tokens using an HTTP request. however. from mod­auth­kerb). Integrating the Quick Start example The Quick Start example can readily be integrated into a single­process application. Running the ManifoldCF Apache2 plug in The ManifoldCF Apache2 plugin. and configured appropriately in the httpd. you are effectively not running a single­process version of ManifoldCF anymore. then you will need to run ManifoldCF under Maven. The way the ManifoldCF logging output is formatted is controlled through this file.ini file contains Apache commons­logging properties in a standard Java <name>=<value> format. it must be placed into Apache2's extensions directory. Please note.2015/7/18 Building ManifoldCF located.1/en_US/how­to­build­and­deploy. or you can choose to deploy them yourself.apache. by using the support methods found in the org.org/release/release­2. which can use them to help compose a search that properly excludes content that the user is not supposed to see.conf commands: Command AuthzAnnotateEnable AuthzAnnotateAuthority AuthzAnnotateACLAuthority AuthzAnnotateIDAuthority AuthzAnnotateIDACLAuthority Meaning Turn on/off the plugin Point to an authority service that supports ACL queries. The list of authority services so queried is configured in Apache's httpd. You can learn how to programmatically start the agents process by looking at the code in the AgentRun command class. For the web application components of ManifoldCF. but not ID queries Point to an authority service that supports ID queries. all you need to do is: cd framework/jetty‐runner mvn exec:exec          Integrating ManifoldCF into another application ManifoldCF can be integrated into another application through a variety of methods. as described above. is designed to convert an authenticated principle (e. but not ACL queries Point to an authority service that supports both ACL queries and ID queries Values "On". because each web application will effectively have its own set of static classes. To run it. Integrating a multi‐process setup In a multi process setup. This functionality is contained in the Active Directory Authority. and why. you should learn what you need by reading the Javadoc for the ManifoldCFJettyRunner class.  the Apache Forrest logo. Apache ManifoldCF. you will not need know any of the above.html#Running+ManifoldCF 17/17 . http://manifoldcf.1/en_US/how­to­build­and­deploy. the Apache feather logo. Solr. since part of the plugin's purpose is to communicate with the Authority Service and apply the access tokens that are returned to the search query automatically. where XX is an integer starting at zero Access tokens and authority statuses are returned in the HTTP response separated by newline characters. Inc. LiveLink and OpenText are trademarks of OpenText. Some plugins. Alfresco is a trademark of Alfresco Software. where XX is an integer starting at zero authorization domain XX. the Solr plugin). Forrest. and the Apache ManifoldCF logo are trademarks of The Apache Software Foundation. If you choose to deploy a search­engine plugin supplied by the Apache ManifoldCF project (for example. SharePoint. however. are more or less like toolkits. ManifoldCF. if there is only one authorization domain the optional authorization domain if there is only one authorization domain (defaults to empty string) username number XX. Windows. Apache. Apache Solr. Apache Forrest. Inc.   Last Published: 05/05/2015 08:23:01 Copyright © 2009­2015 The Apache Software Foundation. QBase. Documentum and EMC are a trademarks of EMC Corporation. the set of tokens returned by the Authority Service will be correctly supplied in order to apply appropriate security to documents being searched.org/release/release­2. MetaCarta. but still hide most of the above from the integrator. Inc. Meridio and Autonomy are trademarks of Hewlett Packard. you may need to develop your own code which interacts with the Authority Service in order to meet your goals. Jira is a trademark of Atlassian. and Microsoft are trademarks of Microsoft. Even if any of the error conditions apply.2015/7/18 Building ManifoldCF parameter username domain username_XX domain_XX the username. FileNet P8 and IBM are trademarks of IBM.apache. Each line has a prefix as follows: Authority Service response prefixes Authority Service response prefix TOKEN: AUTHORIZED: UNREACHABLEAUTHORITY: UNAUTHORIZED: USERNOTFOUND: Meaning An access token The name of an authority that found the user to be authorized The name of an authority that was found to be unreachable or unusable The name of an authority that found the user to be unauthorized The name of an authority that could not find the user It is important to remember that only the "TOKEN:" lines actually matter for security. such as the ElasticSearch plugin. and GTS are trademarks of QBase. Inc. In a more highly customized system. Inc. Inc. Inc.