| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
|---|
| 2 | <HTML> |
|---|
| 3 | <HEAD> |
|---|
| 4 | <TITLE>Xapian: Remote Backend</TITLE> |
|---|
| 5 | </HEAD> |
|---|
| 6 | <BODY BGCOLOR="white" TEXT="black"> |
|---|
| 7 | |
|---|
| 8 | <H1>Remote Backend</H1> |
|---|
| 9 | |
|---|
| 10 | <P>This document describes how to make use of the facilities in Xapian |
|---|
| 11 | for distributed searches. |
|---|
| 12 | |
|---|
| 13 | <H2>Overview</H2> |
|---|
| 14 | |
|---|
| 15 | <P>There are two sides to the distributed searching. The client end is the |
|---|
| 16 | program initiating the search on behalf of a user, and the server end is |
|---|
| 17 | the program which provides a searching interface over a set of databases |
|---|
| 18 | for the client. There can be many servers, with many clients sharing |
|---|
| 19 | them. In theory, a server can also be a client to other servers, but |
|---|
| 20 | this may not be very useful or efficient. |
|---|
| 21 | |
|---|
| 22 | <P>The client runs queries in the same way that it would on local databases, |
|---|
| 23 | but with different database arguments. Instead of type, eg, "quartz", |
|---|
| 24 | use "remote". The extra parameters describe how to connect to the server. |
|---|
| 25 | Once the database is opened, the query process is identical to any other. |
|---|
| 26 | Using a stub database with autobackend is a good way to wrap up access to |
|---|
| 27 | a remote database in a neat way. |
|---|
| 28 | |
|---|
| 29 | <P>The remote backend currently support two client/server methods: prog and |
|---|
| 30 | tcp. They both use the same protocol, although different means to contact |
|---|
| 31 | the server. |
|---|
| 32 | |
|---|
| 33 | <H2>The Prog Method</H2> |
|---|
| 34 | |
|---|
| 35 | <P>The prog method spawns a program when the database is opened, and |
|---|
| 36 | communicates with it over a pipe. This can be used to connect to a |
|---|
| 37 | remote Xapian database across an SSH tunnel for example, providing |
|---|
| 38 | authentication and encryption. The xapian-progsrv program is designed |
|---|
| 39 | to be the program at the far end of the connection. |
|---|
| 40 | |
|---|
| 41 | <P>From the client end, create the database with <code>Xapian::Database database(Xapian::Remote::open(<i>program</i>, <i>args</i>));</code> - for example: |
|---|
| 42 | |
|---|
| 43 | <pre> |
|---|
| 44 | Xapian::Database database(Xapian::Remote::open("ssh", "search.example.com xapian-progsrv /var/lib/xapian/data/db1")); |
|---|
| 45 | </pre> |
|---|
| 46 | |
|---|
| 47 | <P>If the program has no path, the PATH environment variable is used. |
|---|
| 48 | |
|---|
| 49 | <h2>The TCP Method</h2> |
|---|
| 50 | |
|---|
| 51 | <P>The tcp method uses TCP/IP sockets to connect to a running server on a remote |
|---|
| 52 | machine (or indeed a local one, but that's rather pointless!) |
|---|
| 53 | |
|---|
| 54 | <P>From the client end, create the database with <code>Xapian::Database database(Xapian::Remote::open(<i>host</i>, <i>port</i>));</code> - for example: |
|---|
| 55 | |
|---|
| 56 | <pre> |
|---|
| 57 | Xapian::Database database(Xapian::Remote::open("searchserver", 33333)); |
|---|
| 58 | </pre> |
|---|
| 59 | |
|---|
| 60 | The host is the server's hostname, the port is the tcp port on the server to |
|---|
| 61 | use. |
|---|
| 62 | |
|---|
| 63 | <P>The server is xapian-tcpsrv, which is installed by xapian-core's |
|---|
| 64 | "<code>make install</code>". |
|---|
| 65 | This should be started and left running in the background before searches |
|---|
| 66 | are performed. |
|---|
| 67 | |
|---|
| 68 | <P>The arguments xapian-tcpsrv currently knows are: |
|---|
| 69 | <dl> |
|---|
| 70 | <dt> --port PORTNUM |
|---|
| 71 | <dd> (required) the port to listen on. |
|---|
| 72 | <dt> --one-shot |
|---|
| 73 | <dd> Handle one connection, and then exit. If --one-shot is not used, |
|---|
| 74 | then the server runs until it is killed manually. |
|---|
| 75 | <dt> --idle-timeout MSECS |
|---|
| 76 | <dd> Set the timeout on a idle connection. |
|---|
| 77 | <dt> --active-timeout MSECS |
|---|
| 78 | <dd> Set the timeout waiting for responses when the connection is active. |
|---|
| 79 | <dt> --timeout MSECS |
|---|
| 80 | <dd> Set the idle and active timeouts to the same value. |
|---|
| 81 | <dt> --quiet |
|---|
| 82 | <dd> Minimal output. |
|---|
| 83 | </dl> |
|---|
| 84 | One or more databases need to be specified by listing their directories - they |
|---|
| 85 | are opened using the "auto" pseudo-backend. |
|---|
| 86 | |
|---|
| 87 | <P>Once started, the server will run and listen for connections on the |
|---|
| 88 | configured port. Each connection is handled by a forked child process |
|---|
| 89 | (or a new thread under Windows), so concurrent read access is supported. |
|---|
| 90 | |
|---|
| 91 | <H2>Notes</H2> |
|---|
| 92 | |
|---|
| 93 | <P>A remote search should behave just like the equivalent local one, except |
|---|
| 94 | a few features aren't currently implemented (e.g. spelling, synonyms, user |
|---|
| 95 | metadata). |
|---|
| 96 | |
|---|
| 97 | <P>Exceptions are propagated across the link and thrown again at the client end. |
|---|
| 98 | |
|---|
| 99 | <P>The remote backend now support writable databases. Just start |
|---|
| 100 | <code>xapian-progsrv</code> or <code>xapian-tcpsrv</code> with the |
|---|
| 101 | option <code>--writable</code>. Only one database may be specified. |
|---|
| 102 | <!-- FOOTER $Author$ $Date$ $Id$ --> |
|---|
| 103 | </BODY> |
|---|
| 104 | </HTML> |
|---|
