blob: 2653446e33fb85f1a25562a6742d42ef307e89d4 [file] [log] [blame]
<p>Easily provide repository data to a Google Search Appliance (GSA).
<p> Note: If instead of Java you'd like to use another language take a look
at {@link}.
<h1>Table Of Contents</h1>
<li> <a href=#gsasetup>Basic GSA Setup </a></li>
<li> <a href=#runtempl>Running the Adaptor Template, as an initial test </a></li>
<li> <a href=#createown>Creating your own Adaptor </a></li>
<li> <a href=#testtip>Testing Tip </a></li>
<li> <a href=#admintip>Admin Tip </a></li>
<li> <a href=#service>Running as a Windows Service </a></li>
<li> <a href=#secure>Enabling Security </a></li>
<h1><a name=gsasetup>Basic GSA Setup </a></h1>
<li>Add the IP address of the computer that hosts the adaptor to the <b>List
of Trusted IP Addresses</b> on the GSA.
<p>In the GSA's Admin Console, go to <b>Content Sources &gt; Feeds</b>,
and scroll down to <b>List of Trusted IP Addresses</b>. Add the IP address
for the adaptor to the list.</p>
<li>Add the URLs provided by the adaptor to the <b>Follow Patterns</b> on the GSA.
<p>In the Admin console, go to <b>Content Sources &gt; Web Crawl &gt Start and
Block URLs </b>, and scroll down to <b>Follow Patterns</b>. Add an entry like
{@code hostname:port/} where {@code hostname} is the hostname of the machine
that hosts the adaptor and {@code port} defaults to 5678 (read on to
change port number).</p>
<h1><a name=runtempl>Running the Adaptor Template, as an initial test </a></h1>
<li>You should have already installed JDK 6 or higher and gotten a plexi
release (download from From the
downloaded release zip file, use the extracted adaptor jar
(eg: {@code adaptor-20130612-withlib.jar}) and extracted adaptor
examples jar (eg: {@code examples/adaptor-20130612-examples.jar}).
If instead of working from a release you are
working from source code you can build the required jars by running:
<pre>ant dist
cd dist</pre>
<p>The needed jars will be in a zip file
within the current directory (eg: will have
adaptor-20130612-withlib.jar and examples/adaptor-20130612-examples.jar).
<li>Create an <code></code> text file in the
current directory that looks like:
<p>You should replace <code>mygsahostname</code> with the hostname or IP
of your GSA. This file allows you to do other configuration of the adaptor
library like changing the server port and feed name:
<p>Later, if you have trouble with the adaptor library incorrectly
auto-detecting your computer's hostname, then you may need to add a line
<p>For a list and explanation of available configruation options view
<li>Start the Adaptor Template. Note that the jar files you have may have a
different date in their names. For Windows:
<pre>java -cp adaptor-20130612-withlib.jar;examples/adaptor-20130612-examples.jar</pre>
For all other OSes:
<pre>java -cp adaptor-20130612-withlib.jar:examples/adaptor-20130612-examples.jar</pre>
<li> Ensure crawling is enabled on your GSA.
Go to <b>Content Sources &gt; Diagnostics &gt; Crawl Status </b>
and click <b>Resume Crawl</b> if crawling system is currently paused.
<li> Confirm things ran successfully.
In the GSA, go to <b>Contents Sources &gt; Feeds</b>.
In the <b>Current Feeds</b> section, you should see an entry for a
"adaptor_HOSTNAME_PORT" (which can be changed by setting the
<code></code> configuration variable).
In the adaptor log look to see document ids being pushed and
requests for document contents being served.
<h1><a name=createown>Creating your own Adaptor </a></h1>
<li>Review JavaDoc for {@link}
and {@link}.
<li>From the zip file (eg:{@code}),
make a copy of {@code
to your own package and name. You will need to modify the contents
appropriately for the new package and name.
<li>Compile, run, and verify the copied adaptor using your favorite IDE. You
will only need {@code adaptor-20130612-withlib.jar} in your classpath.
Note that the date may be different.
<li>Modify it further for your own repository.
<li>Declare success for getting content from your custom repository to the
<h1><a name=testtip>Testing Tip </a></h1>
<p>An adaptor, by default, will deny all document accesses, except from the
GSA. To allow debugging and testing an adaptor without a GSA, you can add a
hostname to the <code>server.fullAccessHosts</code> config key to allow that
computer full access to all adaptor content. In addition, this setting
allows that computer to see metadata and other GSA-specific information as
HTTP headers. This can be very useful when combined with Firebug or the Web
Inspector in your browser to observe an Adaptor's behavior.
<h1><a name=admintip>Admin Tip </a></h1>
<p>You can set configuration variables on the command line instead of in
<code></code>. You are allowed multiple arguments
of the form "-Dconfigkey=configvalue". When providing a value on the command
line, it overrides the default value and the value (if any) in the
configuration file. For example:
<pre>java -cp adaptor-20130612-withlib.jar:examples/adaptor-20130612-examples.jar -Dgsa.hostname=mygsahostname
<h1><a name=service>Running as a Windows Service </a></h1>
<p>Download and extract prunsrv.exe from the
<a href="">
latest Windows binary download</a> of Apache Commons Daemon. If you are
running on 64-bit Windows and will use a 64-bit JVM, then you should use the
prunsrv.exe in the amd64/ directory. Place prunsrv.exe in the same directory
of the Adaptor you would like to run as a service.
<p>You can then register the service:
<pre>prunsrv install <b>someadaptor</b> --StartPath="%CD%" ^
--Classpath=<b>someadaptor-withlib.jar</b> ^
--StartMode=jvm ^
--StartMethod=serviceStart --StartParams=<b>package.SomeAdaptor</b>
--StopMode=jvm ^
--StopMethod=serviceStop --StdOutput=stdout.log --StdError=stderr.log ^ ^
<p>Where {@code someadaptor} is a unique, arbitrary service name.
<p>To start the service, use the Windows service management tool or run:
<pre>prunsrv start <b>someadaptor</b></pre>
<p>Where {@code someadaptor} is the same service name used during
<h1><a name=secure>Enabling Security </a></h1>
<p>Security is not enabled by default because it requires a reasonable amount
of setup, on both the GSA and adaptor. The GSA needs a valid certificate for
the hostname you are accessing it with (<code>gsa.hostname</code>). Thus,
the default one it ships with cannot be valid and you need to generate a new
one. Setting up security is required before users can access non-public
documents directly from the adaptor.
<h3>Creating Self-Signed Certificates</h3>
<p>In the GSA's Admin Console, go to <b>Administration &gt; SSL Settings</b>.
Under the <b>Create a New SSL Certificate</b> heading change <b>Host
Name</b> to GSA's hostname written exactly as the adaptor will use.
Then click <b>Create
Self-Signed Certificate</b> and wait for the operation to complete.
Then click <b>Install SSL Certificate</b> and wait for that operation
to complete (about 1 minute).
You now have a valid self-signed certificate, but it is not available to be
trusted by the adaptor.
<p>You need to get the GSA's freshly-created certificate to add it as a
trusted host for the adaptor:
<li><b>Using Firefox:</b> Navigate to the GSA's secure search:
https://gsahostname/. You should see a warning page that says, "This
Connection is Untrusted." This message is because the certificate is
self-signed and not signed by a trusted Certificate Authority. Click, "I
Understand the Risks" and "Add Exception." Wait until the "View..."
button is clickable, then click it. Change to the "Details" tab and
click "Export...". Save the certificate in your adaptor's directory with
the name "gsa.crt". You can then hit "Close" and "Cancel" to close the
dialog windows.
<li><b>Using Chrome:</b> Navigate to the GSA's secure search:
https://gsahostname/. You should see a warning page that says, "The
site's security certificate is not trusted!" In the location bar, there
should be a pad lock with a red 'x' on it. Click the pad lock and then
click "Certificate Information." Change to the "Details" tab and click
"Export...". Save the certificate in your adaptor's directory with the
name "gsa.crt". You can then hit "Close" and "Cancel" to close the
dialog windows.
<li><b>Using OpenSSL:</b> Execute:
<pre>openssl s_client -connect gsahostname:443 &lt; /dev/null</pre>
Copy the section that begins with <code>-----BEGIN CERTIFICATE-----</code>
and ends with <code>-----END CERTIFICATE-----</code> (including the BEGIN
and END CERTIFICATE portions) into a new file. Save the file in your
adaptor's directory with the name "gsa.crt".
<p>Now you should generate a self-signed certificate for the adaptor and
export the newly created certificate. Within the adaptor's directory, you
should run:
<pre>keytool -genkeypair -keystore keys.jks -storepass changeit -keypass changeit -alias adaptor -keyalg RSA -validity 365</pre>
<p>For "What is your first and last name?", you should enter the hostname of
the adaptor's computer. You are free to answer the other questions however
you wish (including not answering them). When you are happy with your
answers, answer "yes" to "Is CN=yourcomputershostname, OU=... correct?"
<p>Then, still in adaptor's directory, you should run:
<pre>keytool -exportcert -alias adaptor -keystore keys.jks -storepass changeit -keypass changeit -rfc -file adaptor.crt</pre>
<p>Copy cacerts from Java to the adaptor's directory. For Windows:
<pre>copy PATH\TO\JRE\lib\security\cacerts cacerts.jks</pre>
<p>For all other OSes:
<pre>cp PATH/TO/JRE/lib/security/cacerts cacerts.jks</pre>
<p>To allow the adaptor to trust itself, execute:
<pre>keytool -importcert -keystore cacerts.jks -storepass changeit -file adaptor.crt -alias adaptor</pre>
<p>Answer "yes" to "Trust this certificate?"
<h3>Exchanging Certificates</h3>
<p>To allow the adaptor to trust the GSA, execute:
<pre>keytool -importcert -keystore cacerts.jks -storepass changeit -file gsa.crt -alias gsa</pre>
<p>Answer "yes" to "Trust this certificate?"
<p>To allow the GSA to trust the adaptor, within the GSA's Admin Console, go
to <b>Administration &gt; Certificate Authorities</b>. Click the <b>Choose
File</b> button (this button could be called "Browse...") under the
<b>Add more Cerificate Authorities</b> heading.
Choose "adaptor.crt" in the adaptor's directory and click <b>Save
<h3>Flipping the Switch</h3>
<p>Now that everything is prepared, you can flip the security switch with the
adaptor by adding a line to your <code></code>:
<p>The adaptor can now use the GSA's authentication configuration and will use
HTTPS for all communication.</p>
<p> Example command line to run secure:
java \
-Djava.util.logging.config.file=src/ \ \ \ \ \ \ \
-classpath 'adaptor-20130612-withlib.jar:examples/adaptor-20130612-examples.jar' \
<h3>Enable Stricter Security (optional)</h3>
<p>There are additional security options you can control on the GSA.
You may want to try running an adaptor with set before
enabling these stricter features.
Within the GSA's Admin Console, go to <b>Administration &gt; SSL
Settings</b>. There you can:<ul>
<li> uncheck <b>Enable HTTP (non-SSL) access for Feedergate</b>. With this
field unchecked only HTTPS communications will be accepted by feedergate.
Adaptors send document ids to feedergate.
<li> check <b>Enable Client Certificate Authentication for Feedergate</b>.
<li> check <b>Enable Server Certificate Authentication</b>. Note: Does not
work at this time (Oct 4 2011).
Click <b>Save Setup</b> to save your changes.
Note: By using these settings you improve security, but also require
all adaptors to be configured for security and have
<code></code> in their configuration.