xapian-core/docs/remote.rst

   1 Remote Backend
   2 ==============
   3
   4 This document describes how to make use of the facilities in Xapian for
   5 distributed searches.
   6
   7 Overview
   8 --------
   9
  10 There are two sides to the distributed searching. The client end is the
  11 program initiating the search on behalf of a user, and the server end is
  12 the program which provides a searching interface over a set of databases
  13 for the client. There can be many servers, with many clients sharing
  14 them. In theory, a server can also be a client to other servers, but
  15 this may not be very useful or efficient.
  16
  17 The client runs queries in the same way that it would on local databases
  18 - the difference is in how the database is opened. Once the database is
  19 opened, the query process is identical to any other. Using a stub
  20 database with "auto" backend is a good way to wrap up access to a remote
  21 database in a neat way.
  22
  23 The remote backend currently support two client/server methods: prog and
  24 tcp. They both use the same protocol, although different means to
  25 contact the server.
  26
  27 The Prog Method
  28 ---------------
  29
  30 The prog method spawns a program when the database is opened, and
  31 communicates with it over a pipe. This can be used to connect to a
  32 remote Xapian database across an SSH tunnel for example, providing
  33 authentication and encryption. The xapian-progsrv program is designed to
  34 be the program at the far end of the connection.
  35
  36 From the client end, create the database with
  37 ``Xapian::Database database(Xapian::Remote::open(program, args));`` -
  38 for example::
  39
  40     Xapian::Database database(Xapian::Remote::open("ssh", "search.example.com xapian-progsrv /var/lib/xapian/data/db1"));
  41
  42 If the program has no path, the PATH environment variable is used.
  43
  44 The TCP Method
  45 --------------
  46
  47 The tcp method uses TCP/IP sockets to connect to a running server on a
  48 remote machine (or indeed a local one, but that's rather pointless!)
  49
  50 From the client end, create the database with
  51 ``Xapian::Database database(Xapian::Remote::open(host, port));`` - for
  52 example:
  53 ::
  54
  55     Xapian::Database database(Xapian::Remote::open("searchserver", 33333));
  56
  57 The host is the server's hostname, the port is the tcp port on the
  58 server to use.
  59
  60 The server is xapian-tcpsrv, which is installed by xapian-core's
  61 "``make install``". This should be started and left running in the
  62 background before searches are performed.
  63
  64 One or more databases need to be specified by listing their paths.
  65
  66 There's also one required command line option for xapian-tcpsrv: ``--port
  67 PORTNUM``, which specifies the port to listen on.  For the full list of
  68 accepted command line options, run ``xapian-tcpsrv --help`` or see the
  69 xapian-tcpsrv man page.
  70
  71 Once started, the server will run and listen for connections on the
  72 specified port. Each connection is handled by a forked child process
  73 (or a new thread under Windows), so concurrent read access is supported.
  74
  75 Notes
  76 -----
  77
  78 A remote search should behave just like the equivalent local one, except
  79 a few features aren't currently implemented (e.g. spelling, synonyms,
  80 user metadata).
  81
  82 Exceptions are propagated across the link and thrown again at the client
  83 end.
  84
  85 The remote backend now support writable databases. Just start
  86 ``xapian-progsrv`` or ``xapian-tcpsrv`` with the option ``--writable``.
  87 Only one database may be specified when ``--writable`` is used.