Table of Contents
This chapter provides all the information you need to get searchbox up and running in your production environment. Topics covered:
how to make a Deployment Plan for your environment
how to install searchbox on your server/s
how to start and stop the service
Before installing searchbox you have be clear in your mind the deployment model most suitable for your needs.
In the following picture a complete possible environment where searchbox Engine can be installed is shown.
searchbox can be accessed by any other component of the environment by its SOAP remote interface as any other standard Web Service. Its SOAP API is also .NET compliant so that can be easily integrated with all Microsoft applications and development tools.
In the above example searchbox can access both to Internet and Intranet information sources. Many organizations grant Internet access through a Proxy Server. During the installation process if you choose to use a Proxy a username and password must be provided.
Note
Only one proxy instance can be configured into searchbox so all the gathering protocols (ex. HTTP/S, FTP, etc.) that you are going to use with searchbox must be supported by the unique Proxy Server you configure.
In order to access both external and internal information sources you must be sure that they are reachable from the server where searchbox is installed on and it have the necessary authorization to read them. The most common authentication method are username/password but searchbox also support access with SSL certificate. In this case a searchbox reserved SSL certificate (PEM format) should be created. sarchbox make access to the information source exactly like any other user so the best approach is giving it its own credential for each source it has to gather.
Once properly installed and configured searchbox can be administered
remotely using its SOAP API and/or the provided Control
Panel application. The SOAP API need a specific port to be
used. It is configured by default to 2200
but can be modified during the installation process or editing the
configuration file focuseek.cfg. Any application that
need to communicate to searchbox (i.e. the Control Panel) through the SOAP
API must be able to use such reserved port. Be sure that the access is not
filtered by any firewall.
In the above picture a web based application running on application server uses searchbox and exposes its services both to the Intranet and to the Web. An administration client (Control Panel) located into the Intranet is also shown.
searchbox is a native application available for the three major operating system:
Windows 2000/XP
Red Hat Enterprise Linux AS 3 and AS 4, Suse Linux 10.0 (x86 Architecture)
Mac OS X 10.4 Tiger (PPC Architecture)
The three version differs only for the installation procedure. The feature set is exactly the same.
Before starting with the installation procedure please read carefully this section an be aware if you are in one of this cases.
If you are upgrading from searchbox 1.x, you must be aware that the document storage and the index format are not backward compatible: you will not be able to directly use your old datadir. You can however import the configurations stored in the older datadir in your new installation.
In order to correctly upgrade your installation, follow these steps:
Save the config directory found under your old datadir in a safe place.
Uninstall the previous version and remove any older file (including the datadir) that the uninstaller may have left.
Install the new version, including the activation key you may have acquired.
Import the old configurations from the config directory you saved in the first step. See "Import/export the configuration file" section in the Administration section of this manual for detailed instructions on how to do that.
Indexes and configuration data created by previous searchbox 2 releases are automatically updated the first time you start the searchbox service. Depending from the size of you document storage this operation can require many hours of platform downtime.[1].
Warning
Before launching the service for the first time be sure the free disk space on the volume where datadir is located is sufficient to perform the conversion. The required free amount is the same of the current datadir size.
searchbox 2.1.0 and later versions support a new, more efficient way to locally store the document cache. If you are upgrading a searchbox 2.0.x installation and you want to migrate the old document cache to this new format you need to perform an optimization procedure.[2]. The optimization procedure is suggested but not compulsory and, even if you don't perform it, new, updated or reprocessed documents will be stored in the new format anyway. For details on how to perform an optimization see the section called “Optimize the index”.
Warning
Before launching the optimization operation be sure to have enough free disk space on the volume where datadir is located. The required free amount is the same of the current datadir size.
Here they are detailed installation instructions for each supported platform:
Under Windows the procedure is completely driven by a standard installer.
Step 1: Download or locate in the distribution CD the installation package. It is an executable file named as searchbox-2.1.0.exe (if the version number of the searchbox you are going to install is different the file name is changed in accordance with it. The installation process starts with a double-click on the file icon.
Step 2: Start with the searchbox installer
Step 3: Accept the license agreement
Step 4: Select destination location.
Step 5: Select components to install
Step 6: Select Start Menu Folder
Step 7: Select Additional Task
Depending on your choice searchbox Engine service will be automatically started during last step of the installation procedure. The installer setup the service to be launched automatically at bootstrap. You can change this from Windows Service Administration Tool.
Step 8: Installation summary
Step 9: Installation progress
Step 10: Information about the installation
The basic searchbox installation procedure does not install any activation key. This searchbox version is identified as searchbox 2 Standard Edition. If you own a commercial version of searchbox you need to install the corresponding activation key in order to enable specific features.
Step 11: End of procedure
Step 11: Launching the Control Panel application
The desktop icon launches searchbox Control Panel, the graphical administration client of searchbox Engine. The Control Panel comes already configured to manage the current searchbox installation but can be used to administer other remote instances of searchbox. To verify that you have a successful local installation launch the Control panel and verify that a window like this is shown.
The activation key for searchbox is generated from some information generated from the hardware where searchbox has been installed.
Under Windows operating system file called
searchbox-req.fsreq is automatically generated at
the installation time into the installation folder. In order to obtain
the activation key such file must be sent to focuseek sales
office.
Once you have obtained a commercial activation key you have to install into your current searchbox installation following this simple procedure[3]:
Shutdown the searchbox Engine
Copy your activation key file named as
searchbox-key.fskeyinto the searchbox installation directory. By default it searchbox is installed inC:\Program Files\focuseek\searchbox\directory.Restart the searchbox engine
Warning
If you are upgrading from a 2.0.x version of searchbox you must remove the old activation key file named as focuseek.key
The installation procedure is the same as Windows 2000/XP apart that under Windows 2003 Server for security reasons the installer cannot automatically enable connections to searchbox on port X. After the installation procedure the administrator will have to enable such port with the usual tool.
Install the provided rpm file
searchbox-M.m.r.b.i686.rpm (M,
m, r and
b are the numbers making up the exact searchbox
release and build, e.g. 2.1.0.2021. Exact numbers will vary depending on
the version of searchbox you are installing) using a tool you are
comfortable with, for example run the following command as root[4]:
rpm -Uvh searchbox-2.1.0.2021-1.i686.rpmNote
When installing on Suse Linux you must pass also the
--nodeps switch to rpm.
Next you may run the /opt/searchbox/bin/searchbox-config program and tune some parameters. This step is sometimes necessary when upgrading to newer versions to provide sensible values for configuration parameters. To know if you have to run searchbox-config look at the output of rpm. If it says something like
Configuration saved to /opt/searchbox/bin/../lib/platform/config/focuseek.cfg
then you don't need to run it. If, on the contrary, it says something like
Could not automatically update the configuration You must manually run /opt/searchbox/bin/searchbox-config
then you must run it. Anyway, when you run searchbox-config the following screen appears:
SOAP/REST HTTP IP:port (* means all host IPs): *:2200Administrator user/password: admin /********
Path to focuseek lib dir: /opt/searchbox/lib/platform
Path to focuseek data dir: /opt/searchbox/data
User/group for focuseek to run as: /
DON'T set user to root! Proxy host:port (leave blank if not needed):
Proxy user:password: (leave blank if not needed)
Don't use proxy for: (leave blank if not needed)
Exit? (write "save" or "abort" here when you are done):
Use up and down arrows to move between fields, left and right arrow to move inside a field. When you are done you can press F10 to store the values or F9 not to store them. If your terminal doesn't have working function keys you can use the exit field.[5]
Note
searchbox cannot run without these configuration values. If the installer doesn't set them automatically and you don't set them at this point you will need to run /opt/searchbox/bin/searchbox-config later.
If you change your mind on the configuration values you can change
them later at any time provided focuseek searchbox is not
running. All you have to do is run the command
/opt/searchbox/bin/searchbox-config
You may optionally install the searchbox Control Panel, provided
in the searchbox-controlpanel-M.m.r.b.i686.rpm
rpm file (M, m,
r and b are the numbers
making up the exact searchbox release and build, e.g. 2.1.0.2021.
Exact numbers will vary depending on the version of searchbox you are
installing).
To install it install the rpm, for example run the following command as root[4]:
rpm -Uvh searchbox-controlpanel-2.1.0.2021-1.i686.rpmNote
The gui depends on the main package, so if you want to install the gui you have to install both packages even if you are going to use the client only.
Warning
The rpm package must be installed in its default location and not relocated.
The activation key for searchbox is generated from some information generated from the hardware where searchbox has been installed.
Under Linux operating system file called
searchbox-req.fsreq is automatically generated at
the installation time into the
/opt/searchbox/lib/platform folder. In order to
obtain the activation key such file must be sent to focuseek sales
office.
Once you have obtained a trial or a commercial activation key you have to install into your current searchbox installation following this simple procedure[6]:
Shutdown the searchbox engine
Optionally rename your old key file
searchbox-key.fskey, if any, assearchbox-key.fskey.old.Install your new key file in the
/opt/searchbox/lib/platform/directory. The key file name must besearchbox-key.fskeyRun the following command to ensure that the key file is readable by anybody:
chmod a+r /opt/searchbox/bin/searchbox-config/searchbox-key.fskeyRestart the searchbox engine
Under Mac OS X the procedure is completely driven by a standard installer.
Step 1: Download or locate in the distribution CD the installation archive. It is an executable file named as searchbox-2.1.0.dmg (if the version number of the searchbox you are going to install is different the file name is changed in accordance with it. The installation process starts with a double-click on the file icon and another double click on the installations package.
Step 2: Start with the searchbox installer
Step 3: Accept the license agreement
Step 4: Select destination location.
Step 5: Select components to install
Step 6: Select Start Menu Folder
Step 7: Select Additional Task
Depending on your choice searchbox Engine service will be automatically started during last step of the installation procedure. The installer setup the service to be launched automatically at bootstrap. You can change this from Windows Service Administration Tool.
Step 8: Installation summary
The basic searchbox installation procedure does not install any activation key. This searchbox version is identified as searchbox 2 Standard Edition. If you own a commercial version of searchbox you need to install the corresponding activation key in order to enable specific features.
Step 11: End of procedure
Step 12: Launching the Control Panel application
The desktop icon launches searchbox Control Panel, the graphical administration client of searchbox Engine. The Control Panel comes already configured to manage the current searchbox installation but can be used to administer other remote instances of searchbox. To verify that you have a successful local installation launch the Control panel and verify that a window like this is shown.
The activation key for searchbox is generated from some information generated from the hardware where searchbox has been installed.
Under Mac OS X operating system file called
searchbox-req.fsreq is automatically generated at
the installation time into the
/Applications/searchbox/lib/platform folder. In
order to obtain the activation key such file must be sent to focuseek
sales office.
Once you have obtained a trial or a commercial activation key you have to install into your current searchbox installation following this simple procedure[7]:
Shutdown the searchbox engine.
Copy your activation key file named as
searchbox-key.fskeyinto the searchbox installation directory. By default searchbox is installed in/Applications/searchbox/lib/platform/directory.Restart the searchbox engine
searchbox Engine is installed as a Windows service. Windows will take care of starting and stopping searchbox at system startup and shutdown. You can choose to not start it automatically using the Windows Service Manager (in the Administration Tools folder).
Locate the Searchbox Engine service in the Windows Service Manager service list, click on it and select the start button on the toolbar. You can start the service only when it isn't already running.
Locate the Searchbox Engine service in the Windows Service Manager service list, click on it and select the stop button on the toolbar.
The procedure requires that you have access to a system shell with root privileges.
focuseek searchbox should be installed as an init(8) service. You should at least let searchbox stop at system shutdown. If searchbox is not be halted correctly at system shutdown, incomplete or bad indexes may result.
When you install the rpm package it configures init to stop searchbox at system shutdown, no manual configuration is required. You may still want to setup your system to start searchbox at bootstrap.
As root user run the chkconfig(8) command:
# chkconfig --level levels searchbox onWhere levels is a string of digits, specifying the runlevels you want the searchbox to run in. For example:
# chkconfig --level 35 searchbox on
makes searchbox automatically run in runlevels 3 and 5.
As root user run the following command:
# /opt/searchbox/bin/searchboxd --status
Possible outputs are:
searchboxd not running: searchbox is not runningsearchboxd(<pid>) starting: searchbox is starting; this is only a transitory state; soon it will be “running”searchboxd(<pid>) running: searchbox is running[8]searchboxd(<pid>) stopping: searchbox is stopping; this is only a transitory state; soon it will be “not running”searchboxd(<pid>) uninterruptible operation: searchbox is performing some uninterruptible and possibly time consuming operation such as rebuilding the whole index. When running such operations searchboxd cannot be stopped but instead stops on its own when the operation is finished[9]. Uninterruptible operations must be explicitly stared running searchboxd with some special switch; see later.
searchbox will be installed as a SystemStarter-controlled service. Startup will be automatic, but due to a known limitation in OS X service control, service shutdown will not be automatically done at system shutdown. You must ensure that proper service shutdown is done before shutting down the system.
Run the following command:
$ sudo /Applications/searchbox/bin/searchboxd --status
Possible outputs are the same of the Linux version.
Warning
Depending on what searchbox is doing stopping it can take some time. Before manually kill searchbox processes wait some minutes to be sure that searchbox is not hanged. Most searchbox disk operations are journaled thus you won't lose any data even if you kill it abruptly, but you may end up with some corrupted data structures and might require a reindex operation, see the section called “Reindex” to know how to run it.
[1] A complete reindexing of the WT10G dataset (1.600.000 documents) on a Apple PowerMac 2.0GHz Dual G5 requires nearly 26 hours to be completed.
[2] A complete optimizing of the WT10G dataset (1.600.000 documents) on a Apple PowerMac 2.0GHz Dual G5 requires nearly 30 hours to be completed.
[3] If no activation key is installed searchbox will automatically use the internal one limited to 2000 documents.
[4] The actual rpm file name may differ depending on the release of searchbox you are installing.
[5] Note that if you don't have the permission to modify the configuration file searchbox-config will complain at exit and will not change the file.
[6] If no activation key is installed searchbox will automatically use the internal one limited to 2000 documents.
[7] If no activation key is installed searchbox will automatically use the internal one limited to 2000 documents.
[8] <pid> is the
process id of the running searchbox
[9] If you really have to you can stop searchboxd with a kill -KILL as uninterruptible operations are restartable. Do this sparingly, as it may corrupt the index. See the section called “Reindex” for details on how to recover from this problem