Latest revision as of 19:08, 29 December 2023

External

Internal

Installation

Install Elasticsearch first. Use the latest version of the recommended major version. At the time of the writing, CirrusSearch for MediaWiki 1.35 recommended Elasticsearch 6.5.4, and 6.8.20 worked fine. Elasticsearch 7.x did not.

Elasticsearch Installation

Install Elastica extension:

Elastica Extension Installation

Download the correct CirrusSearch version from https://www.mediawiki.org/wiki/Special:ExtensionDistributor/CirrusSearch

Unzip it in the extensions directory:

tar -xzf CirrusSearch-REL1_35-95b958b.tar.gz -C /var/www/mediawiki-x.y.z/extensions

Add the following statement to LocalSettings.php:

wfLoadExtension( 'CirrusSearch' );

Smoke test: go to Special:Version and verify that the extension is successfully installed.

Follow the installation instructions delivered with /var/www/mediawiki-1.35.0/extensions/CirrusSearch/README.

In LocalSettings.php:

wfLoadExtension( 'Elastica' );
wfLoadExtension( 'CirrusSearch' );
$wgDisableSearchUpdate = true;

If SELinux is enabled, make sure it is configured to allow the httpd user to connect to elasticsearch, otherwise the setup will fail. See SELinux Setup below.

SELinux Setup

If SELinux is enabled on the host, the httpd process may not be able to invoke into the elasticsearch server, with the following symptoms:

[CirrusSearch] Search backend error during near_match search for 'test' after 5: unknown: Couldn't connect to host, Elasticsearch down?

/var/log/audit/audit.log will contain something similar to:

type=AVC msg=audit(1637546254.160:75): avc:  denied  { name_connect } for  pid=1216 comm="httpd" dest=9200 scontext=system_u:system_r:httpd_t:s0 tcontext=system_u:object_r:wap_wsp_port_t:s0 tclass=tcp_socket permissive=0

Use audit2allow to generate the SELinux policy to allow the denied operation. Follow:

Troubleshooting, Diagnosing and Fixing SELinux Problems

The summary is there:

Try a search operation that will fail.
grep httpd /var/log/audit/audit.log | audit2allow -M mysepolicy
semodule -i mysepolicy.pp

Initialization

As root:

php /var/www/mediawiki-.../extensions/CirrusSearch/maintenance/UpdateSearchIndexConfig.php

Remove

$wgDisableSearchUpdate = true;

from LocalSettings.php.

php /var/www/mediawiki-.../extensions/CirrusSearch/maintenance/maintenance/ForceSearchIndex.php --skipLinks --indexOnSkip
php /var/www/mediawiki-.../extensions/CirrusSearch/maintenance/maintenance/ForceSearchIndex.php --skipParse

In LocalSettings.php:

$wgSearchType = 'CirrusSearch';

Troubleshooting

Enable debugging as shown in:

MediaWiki Troubleshooting

[CirrusSearchRequests] near_match search for 'test' against {index} took 5 millis. Requested via web for 5b7883dcb7cd761f62397caa67819012 by executor 2078481799
[CirrusSearch] Search backend error during near_match search for 'test' after 5: unknown: Couldn't connect to host, Elasticsearch down?

Direct CirrusSearch error logs to a specific file. In LocalSettings.php:

$wgDebugLogGroups['CirrusSearch'] = "/tmp/cirrus-errors.log";

Did not work

Add the following query parameters to dump: &cirrusDumpQuery=true, &cirrusDumpResult=true.

@@ Line 4: / Line 4: @@
 =Internal=
-* [[Media Wiki Configuration#Subjects|Media Wiki Configuration]]
+* [[Media_Wiki_Operations#CirrusSearch|Media Wiki Operations]]
 * [[Elasticsearch]]
 =Installation=
-Install elasticsearch: {{Internal|Elasticsearch#Installation|Elasticsearch Installation}}
+Install Elasticsearch first. Use the latest version of the recommended major version. At the time of the writing, CirrusSearch for MediaWiki 1.35 recommended Elasticsearch 6.5.4, and 6.8.20 worked fine. Elasticsearch 7.x did not.
+{{Internal|Elasticsearch#Installation|Elasticsearch Installation}}
 Install Elastica extension: {{Internal|MediaWiki Elastica Extension#Installation|Elastica Extension Installation}}
@@ Line 18: / Line 21: @@
 tar -xzf CirrusSearch-REL1_35-95b958b.tar.gz -C /var/www/mediawiki-x.y.z/extensions
 </syntaxhighlight>
-Add the following statement to LocalSettings.php:
+Add the following statement to <tt>[[Media_Wiki_Concepts#LocalSettings.php|LocalSettings.php]]</tt>:
 <syntaxhighlight lang='php'>
 wfLoadExtension( 'CirrusSearch' );
@@ Line 27: / Line 30: @@
 Follow the installation instructions delivered with <code>/var/www/mediawiki-1.35.0/extensions/CirrusSearch/README</code>.
-In LocalSettings.php:
+In <code>[[Media_Wiki_Concepts#LocalSettings.php|LocalSettings.php]]</code>:
 <syntaxhighlight lang='php'>
@@ Line 35: / Line 38: @@
 </syntaxhighlight>
+If SELinux is enabled, make sure it is configured to allow the httpd user to connect to elasticsearch, otherwise the setup will fail. See [[#SELinux_Setup|SELinux Setup]] below.
+==SELinux Setup==
+If [[SELinux_Operations#How_to_Find_Out_Whether_SELinux_is_Enabled|SELinux is enabled]] on the host, the httpd process may not be able to invoke into the elasticsearch server, with the following symptoms:
+<syntaxhighlight lang='text'>
+[CirrusSearch] Search backend error during near_match search for 'test' after 5: unknown: Couldn't connect to host, Elasticsearch down?
+</syntaxhighlight>
+<code>/var/log/audit/audit.log</code> will contain something similar to:
+<syntaxhighlight lang='text'>
+type=AVC msg=audit(1637546254.160:75): avc:  denied  { name_connect } for  pid=1216 comm="httpd" dest=9200 scontext=system_u:system_r:httpd_t:s0 tcontext=system_u:object_r:wap_wsp_port_t:s0 tclass=tcp_socket permissive=0
+</syntaxhighlight>
+Use <code>audit2allow</code> to generate the SELinux policy to allow the denied operation. Follow: {{Internal|SELinux_Operations#Troubleshooting.2C_Diagnosing_and_Fixing_SELinux_Problems|Troubleshooting, Diagnosing and Fixing SELinux Problems}}
+The summary is there:
+* Try a search operation that will fail.
+* <code>grep httpd /var/log/audit/audit.log | audit2allow -M mysepolicy</code>
+* <code>semodule -i mysepolicy.pp</code>
+==Initialization==
 As root:
@@ Line 46: / Line 66: @@
 </syntaxhighlight>
-from LocalSettings.php.
+from <code>[[Media_Wiki_Concepts#LocalSettings.php|LocalSettings.php]]</code>.
 <syntaxhighlight lang='bash'>
@@ Line 53: / Line 73: @@
 </syntaxhighlight>
-In LocalSettings.php:
+In <tt>[[Media_Wiki_Concepts#LocalSettings.php|LocalSettings.php]]</tt>:
 <syntaxhighlight lang='php'>
 $wgSearchType = 'CirrusSearch';
 </syntaxhighlight>
+==Troubleshooting==
+Enable debugging as shown in: {{Internal|Media_Wiki_Troubleshooting#Debugging|MediaWiki Troubleshooting}}
+<syntaxhighlight lang='text'>
+[CirrusSearchRequests] near_match search for 'test' against {index} took 5 millis. Requested via web for 5b7883dcb7cd761f62397caa67819012 by executor 2078481799
+[CirrusSearch] Search backend error during near_match search for 'test' after 5: unknown: Couldn't connect to host, Elasticsearch down?
+</syntaxhighlight>
+Direct CirrusSearch error logs to a specific file. In <code>LocalSettings.php</code>:
+<syntaxhighlight lang='php'>
+$wgDebugLogGroups['CirrusSearch'] = "/tmp/cirrus-errors.log";
+</syntaxhighlight>
+<font color=darkgray>Did not work</font>
+Add the following query parameters to dump: <code>&cirrusDumpQuery=true</code>, <code>&cirrusDumpResult=true</code>.

Media Wiki CirrusSearch: Difference between revisions