autopsy-flatpak/docs/doxygen-user/installSolr.dox

/*! \page install_solr Install and Configure Solr
A central Solr server is needed to store keyword indexes, and its embedded Zookeeper is used as a coordination service for Autopsy. To install Solr, perform the following steps:

\section install_solr_prereq Prerequisites

You will need:
- A 64-bit version of the Java Runtime Environment (JRE) from http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html. 
- The Apache Solr 4.10.3-0 installation package from https://sourceforge.net/projects/autopsy/files/CollaborativeServices/Solr or Direct Download Link
- Access to an installed version of Autopsy so that you can copy files from it. 
- A network-accessible machine to install Solr on. Note that the Solr process will need to write data out to the main shared storage drive, and needs adequate permissions to write to this location, which may be across a network.

\section install_solr_install Installation

\subsection install_solr_install_java JRE Installation
1. JREs are normally installed under "C:\Program Files\Java\jre(version)", so check there to see if you have one installed already. If not, get the installer from the link in the \ref install_solr_prereq and install it with the default settings.

\subsection install_solr_install_solr Solr Installation

The following steps will configure Solr to run using an account that will have access to the network storage.

1.	Run the Bitnami installer, <i>"bitnami-solr-4.10.3-0-windows-installer.exe"</i>
2.	If Windows prompts with User Account Control, click _Yes_
3.	Follow the prompts through to completion. You do not need to <i>"Learn more about Bitnami cloud hosting"</i> so you can clear the check box.
4.	If you see an error dialog like the following, you may safely ignore it.
<br><br>
\image html apachebadmessage.PNG
<br>
5.	When the installation completes, clear the <i>"Launch Bitnami Apache Solr Stack Now?"</i> checkbox and click _Finish_.

\subsection install_solr_config Solr Configuration
1.	Stop the _solrJetty_ service by pressing _Start_, typing _services.msc_, pressing _Enter_, and locating the _solrJetty_ Windows service. Select the service and press _Stop the service_. If the service is already stopped and there is no _Stop the service_ available, this is okay.
2.	Edit the <i>"C:\Bitnami\solr-4.10.3-0\apache-solr\scripts\serviceinstall.bat"</i> script. You need administrator rights to change this file. The easiest way around this is to save a copy on the Desktop, edit the Desktop version, and copy the new one back over the top of the old. Windows will ask for permission to overwrite the old file; allow it. You should make the following changes to this file:
    <br>
    <br>
    - Add the following options in the line that begins with <i>"C:\Bitnami\solr-4.10.3-0/apache-solr\scripts\prunsrv.exe"</i> :
        + <i>++JvmOptions=-Dcollection.configName=AutopsyConfig</i>
	+ <i>++JvmOptions=-Dbootstrap_confdir="C:\Bitnami\solr-4.10.3-0\apache-solr\solr\configsets\AutopsyConfig\conf"</i>
	+ <i>++JvmOptions=-DzkRun </i>
               <br>
    - Replace the path to JavaHome with the path to your 64-bit version of the JRE. If you do not know the path, the correct JavaHome path can be obtained by running the command "where java" from the Windows command line. An example is shown below. The text in yellow is what we are interested in. Do not include the "bin" folder in the path you place into the JavaHome variable. A correct example of the final result will look something like this: <i>–-JavaHome="C:\Program Files\Java\jre1.8.0_111"</i>
	<br><br>
	A portion of an updated _serviceinstall.bat_ is shown below, with the changes marked in yellow.
     <br><br>
     \image html serviceinstall.PNG
	     <br><br>
3. Edit <i>"C:\Bitnami\solr-4.10.3-0\apache-solr\solr\solr.xml"</i> to set the _transientCacheSize_ to the maximum number of cases expected to be open concurrently. If you expect ten concurrent cases, the text to add is
 <i>\<int name="transientCacheSize">10\</int></i>
 <br><br>
 The added part is highlighted in yellow below. Ensure that it is inside the <i>\<solr></i> tag as follows:
 <br>
 \image html transientcache.PNG
 <br><br>
4. Edit <i>"C:\Bitnami\solr-4.10.3-0\apache-solr\resources/log4j.properties"</i> to configure Solr log settings:
     - Increase the log rotation size threshold (_log4j\.appender\.file\.MaxFileSize_) from 4MB to 100MB.
     - Remove the _CONSOLE_ appender from the _log4j\.rootLogger_ line.
 <br><br>
 The log file should end up looking like this (modified lines are highlighted in yellow
 <br><br>
 \image html log4j.PNG
 <br><br>
5. From an Autopsy installation, copy the folder <i>"C:\Program Files\Autopsy-XXX(current version)\autopsy\solr\solr\configsets"</i> to <i>"C:\Bitnami\solr-4.10.3-0\apache-solr\solr"</i>.
6. From an Autopsy installation, copy the folder <i>"C:\Program Files\Autopsy-XXX(current version)\autopsy\solr\solr\lib"</i> to <i>"C:\Bitnami\solr-4.10.3-0\apache-solr\solr"</i>.  
7. From an Autopsy installation, copy the file <i>"C:\Program Files\Autopsy-XXX(current version)\autopsy\solr\solr\zoo.cfg"</i> to <i>"C:\Bitnami\solr-4.10.3-0\apache-solr\solr"</i>.
8. Stop the <i>solrJetty</i> service by pressing <i>Start</i>, typing <i>services.msc</i>, pressing Enter, and locating the <i>solrJetty</i> Windows service. Select the service and press <i>Stop the service</i>. If the service is already stopped and there is no <i>Stop the service</i> available, this is okay.
9. Start a Windows command prompt as administrator by pressing Start, typing <i>command</i>, right clicking on <i>Command Prompt</i>, and clicking on <i>Run as administrator</i>. Then run the following command to uninstall the solrJetty service:

              cmd /c C:\Bitnami\solr-4.10.3-0\apache-solr\scripts\serviceinstall.bat UNINSTALL

       You will very likely see a result that says "The solrJetty service is not started." This is okay.
10. Start a Windows command prompt as administrator by pressing Start, typing <i>command</i>, right clicking on <i>Command Prompt</i>, and clicking on <i>Run as administrator</i>. Then run the following command to install the solrJetty service:

               cmd /c C:\Bitnami\solr-4.10.3-0\apache-solr\scripts\serviceinstall.bat INSTALL
<br> Note the argument "INSTALL" is case sensitive. Your command prompt should look like the screenshot below. Very likely your command prompt will say "The solrJetty service could not be started." This is okay.
 <br><br>
 \image html solrinstall1.PNG
 <br><br>
 
\subsection running_solr Running Solr
 
To run Solr, first you'll need to choose which account should run the service. Once you've decided, you'll start the service through the Windows Service Manager. Both of these steps are described below.
 
\subsubsection solr_user Choosing the User Account for the Solr Service

Solr will run as a Windows service as a specific user. If the wrong user account is used, Solr will not have permissions to write indexes.

Generally, you'll want to run Solr as a Windows Domain account. You will NOT want to use the default setup, which is to run Solr as a "Local Service Account", because this account does not have access to network-based shared storage. The one exception is if the computer running Solr is also the computer that hosts the shared storage. In that is the case, then the "Local Service Account" will still be able to access the shared storage since the network is not required.
 
\subsubsection start_solr Starting Solr
<ol>
<li>You should be able to see the Solr service in a web browser via the URL http://localhost:8983/solr/#/ as shown in the screenshot below.  If you can, you should skip the next step. If you cannot, proceed to the next step.

<li>Press _Start_, type _services.msc_, and press _Enter_. Find _solrJetty_. If the service is running, press _Stop the service_, then double click it, and switch to the _Log On_ tab to change the logon credentials to a user who will have access to read and write the primary shared drive. Refer to the \ref solr_user section to see which account type is appropriate for your case.

If the machine is on a domain, the Account Name will be in the form of _DOMAINNAME\\username_ as shown in the example below. Note that in the screenshot below, the domain name is _DOMAIN_ and the user name is _username_. These are just examples, not real values.

\image html solrinstall2.PNG

If the machine is on a domain, **make sure** to select the domain with the mouse by going to the _Log On_ tab, clicking _Browse_, then clicking _Locations_ and selecting the domain of interest. Then enter the user name desired and press _Check Names_. When that completes, press _OK_, type in the password once for each box and press _OK_. You may see "The user has been granted the log on as a service right."

<li>You should be able to see the Solr service in a web browser via the URL <i>http://localhost:8983/solr/#/</i> as shown in the screenshot below.
 <br><br>
 \image html solrinstall3.PNG
 <br><br>
If the service is appropriately started and you are unable to see the screenshot above, contact your network administrator to open ports in the firewall.
<br><br>
<b>Warning: The Solr process must have adequate permissions to write data to the main shared storage drive where case output will be stored.</b>
</ol>
*/