Mediator API / mediator.pl
Background
Mediator is an API containing a number of administrative tasks that can be triggered via a REST API, or via the command line.
Command line usage
mediator.pl
is used to trigger administrative actions, either locally or on a remote Funnelback server:
mediator.pl TaskToRun[@host[:port]] arg1=value1 ... argN=valueN
Where:
TaskToRun
Name of the task / action to run.
host
Optional host where the task should be run (fully-qualified hostname). If not set the task is run locally.
port
Optional port to use to contact the remote host.
argN=valueN
Arguments specific to the taskThe list of available tasks can be obtained by running:
mediator.pl --list-tasks
For the remote invocation to work the remote and local server must share the same server_secret
in $SEARCH_HOME/conf/global.cfg
. Special care must be taken when changing the server secret, see the server_secret
page for details.
Examples
Obtain the list of collections on the local server (--verbose
is required there to get the return value of the task, which is the collection list):
mediator.pl --verbose ListCollections
Obtain the list of collections from a remote server:
mediator.pl --verbose ListCollections@server.domain.com
Push the complete intranet collection from the local server to a remote host:
mediator.pl PushCollection collection=intranet host=server.domain.com
Push the complete intranet collection from the server1 host to the server2 host (The task will be invoked on server1, and server1 will push its intranet collection to server2):
mediator.pl PushCollection@server1.domain.com collection=intranet host=server2.domain.com
REST API endpoint
The mediator tasks can also be triggered through a REST endpoint, available at https://FUNNELBACK-SERVER/search/admin/mediator/ . This URL returns a list of all available tasks and their parameters. To call a specific task, use
https://FUNNELBACK-SERVER/search/admin/mediator/Task?param1=value1...
The example below uses the REST endpoint to push the 'intranet' collection to the server.domain.com
remote host:
https://FUNNELBACK-SERVER/search/admin/mediator/PushCollection?collection=intranet&host=server.domain.com
This endpoint requires authentication, and the user must have the sec.service.mediator
permission.
The output format is XML by default, but JSON is also available since v13.2. To choose an output format:
- Either suffix the REST call with
.json
or.xml
:mediator/PushCollection.json?collection=...
- Set the appropriate
Accept: ...
header in the HTTP request:Accept: text/xml
orAccept: application/json
Mediator tasks
Task: AllCollectionsConfiguration
Get the configurations of all collections on the server
Arguments:
No arguments
Task: ArchiveLogs
Archive the queries and clicks logs of a collection
Arguments:
collection
(String) : (Required) Identifier of a collectionview
([live
|offline
]) : Which view to archive (offline
orlive
)
Task: ClearLocks
Clear the update locks and status of a collection
Arguments:
collection
(String) : (Required) Identifier of a collection
Task: GetConfiguration
Get the configuration of a collection
Arguments:
collection
(String) : (Required) Identifier of a collection
Task: GetFunnelbackVersion
Get the version of Funnelback
Arguments:
No arguments
Task: GetIndexTime
Get the last time an index was updated (based on the index_time file)
Arguments:
collection
(String) : (Required) Identifier of a collectionview
([live
|offline
]) : Which view to get the time from (offline
orlive
)
Task: GetProgress
Get the current update progress of a collection
Arguments:
collection
(String) : (Required) Identifier of a collection
Task: ListCollections
Get the list of all existing collection IDs
No arguments
Task: PullLogs
Pull queries and clicks logs of a collection from a remote server
Arguments:
collection
(String) : (Required) Identifier of a collectionhost
(String) : (Required) Hostname of the target to pull fromport
(int) : Port of the remote target WebDAV servicerecursive
(boolean) : Should the pull be recursive (default=true
), if set folders will replace files in local.
Task: PushCollection
Push a complete collection (configuration + data) to a remote server
Arguments:
collection
(String) : (Required) Identifier of a collectionhost
(String) : (Required) Hostname of the target to push todelete
(boolean) : Whether to delete remote files that don't exist locallymediatorPort
(int) : Port of the mediator service (Admin UI port)mediatorProtocol
([http
|https
]) : Protocol of the mediator service (Admin UI protocol)pushType
([COMPLETE_COLLECTION
|QP
|ADMIN
|ADMIN_AND_QP
]) : Describes what is to be pushed, Defaults toQP
smart
(boolean) : Whether to send only files that have changed based on their filesizewebdavPort
(int) : Port of the remote target WebDAV service
Task: PushConfigFile
Push a collection config file to a remote server
Arguments:
collection
(String) : (Required) Identifier of a collectionfilePath
(String) : (Required) Path of the file to push, relative to the collection or profile configuration folderhost
(String) : (Required) Hostname of the target to push toport
(int) : Port of the remote target WebDAV serviceprofile
(String) : Which profile to push (_default
,_default_preview
, or a custom one). If not set the file will be taken from the collection config directory.
Task: PushInstantUpdate
Push instant update changes to a remote server
Arguments:
collection
(String) : (Required) Identifier of a collectionhost
(String) : (Required) Hostname of the target to push todelete
(boolean) : Whether to delete remote files that don't exist locallymediatorPort
(int) : Port of the mediator service (Admin UI port)mediatorProtocol
([http
|https
]) : Protocol of the mediator service (Admin UI protocol)port
(int) : Port of the remote target WebDAV service
Task: PushLogs
Push queries and clicks logs of a collection to a remote server
Arguments:
collection
(String) : (Required) Identifier of a collectionhost
(String) : (Required) Hostname of the target to push toport
(int) : Port of the remote target WebDAV service
Task: PushView
Push a view of the index and data of a collection to a remote server
Arguments:
collection
(String) : (Required) Identifier of a collectionhost
(String) : (Required) Hostname of the target to push toview
([live
|offline
]) : (Required) Which view to push (offline
orlive
)delete
(boolean) : Whether to delete remote files that don't exist locallyport
(int) : Port of the remote target WebDAV servicepushAll
(boolean) : Whether to push ALL folders in the view, in addition to the one required to serve queriesremoteView
([live
|offline
]) : Which remote view to write in (offline
orlive
). Defaults to the value ofview
smart
(boolean) : Whether to send only file that have changed based on their filesize
Task: RecordStatistics
Record the given statistics
Arguments:
collection
(String) : (Required) Identifier of a collectionphase
([pre_gather_command
|gather
|post_gather_command
|pre_instant_gather_command
|instant_gather
|post_instant_gather_command
|pre_convert_command
|convert
|post_convert_command
|pre_instant_convert_command
|instant_convert
|post_instant_convert_command
|pre_index_command
|index
|post_index_command
|pre_instant_index_command
|instant_index
|post_instant_index_command
|pre_report_command
|report
|post_report_command
|pre_swap_command
|swap
|post_swap_command
|pre_meta_dependencies_command
|meta_dependencies
|post_meta_dependencies_command
|pre_archive_command
|archive
|post_archive_command
|pre_delete_prefix_command
|delete_prefix
|post_delete_prefix_command
|pre_delete_list_command
|delete_list
|post_delete_list_command
|pre_vacuum_command
|vacuum
|post_vacuum_command
|pre_update_command
|update
|post_update_command
|recommender
|post_update_tasks
]) : (Required) Update phase (e.g.pre_crawl
,index
etc.)updateStartTime
(String) : (Required) Start time for overall updateendTime
(String) : End time for operationexitCode
(String) : Exit code for operationstartTime
(String) : Start time for operationupdateType
(String) : Update type (e.g.incremental
,refresh
etc.)
Task: SetupViews
Setup the offline and live views (symlinks) for a collection
Arguments:
collection
(String) : (Required) Identifier of a collectionliveFolder
([one
|two
]) : (Required) Which folder to assign to thelive
view (offline
will be set accordingly)collectionRoot
(File) : A pre configured collection root for testing
Task: StartFilecopySlave
Start a filecopy slave process
Arguments:
collection
(String) : (Required) Identifier of a collection
Task: StopUpdate
Stop a currently running update
Arguments:
collection
(String) : (Required) Identifier of a collection
Task: SwapInstantUpdate
Moves instant update files from the instant update temporary directory into the live index
Arguments:
collection
(String) : (Required) Identifier of a collectiontimeOutMS
(int) : Timeout in milliseconds for waiting to acquire the index lock. High query volume may prevent acquiring this lock
Task: SwapViews
Swap the offline and live view for a collection
Arguments:
collection
(String) : (Required) Identifier of a collectionforce
(boolean) : Whether to ignore the changeover conditions
Task: ValidateExternalMetadata
Validate per-profile external_metadata.cfg
files and concatenate them into the collection configuration folder
Arguments:
collection
(String) : (Required) Identifier of a collectionerrorThreshold
(float) : Maximum error threshold before failingmode
([check
|concatenate
]) : Mode of operation,check
orconcatenate