OpenSearch/docs/plugins/ingest-user-agent.asciidoc

[[ingest-user-agent]]
=== Ingest user agent processor plugin

The `user_agent` processor extracts details from the user agent string a browser sends with its web requests.
This processor adds this information by default under the `user_agent` field.

The ingest-user-agent plugin ships by default with the regexes.yaml made available by uap-java with an Apache 2.0 license. For more details see https://github.com/ua-parser/uap-core.

[[ingest-user-agent-install]]
[float]
==== Installation

This plugin can be installed using the plugin manager:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin install ingest-user-agent
----------------------------------------------------------------

The plugin must be installed on every node in the cluster, and each node must
be restarted after installation.

This plugin can be downloaded for <<plugin-management-custom-url,offline install>> from
{plugin_url}/ingest-user-agent/ingest-user-agent-{version}.zip.

[[ingest-user-agent-remove]]
[float]
==== Removal

The plugin can be removed with the following command:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin remove ingest-user-agent
----------------------------------------------------------------

The node must be stopped before removing the plugin.

[[using-ingest-user-agent]]
==== Using the user_agent Processor in a Pipeline

[[ingest-user-agent-options]]
.User-agent options
[options="header"]
|======
| Name                   | Required  | Default                                                                                         | Description
| `field`                | yes       | -                                                                                               | The field containing the user agent string.
| `target_field`         | no        | user_agent                                                                                      | The field that will be filled with the user agent details.
| `regex_file`           | no        | -                                                                                               | The name of the file in the `config/ingest-user-agent` directory containing the regular expressions for parsing the user agent string. Both the directory and the file have to be created before starting Elasticsearch. If not specified, ingest-user-agent will use the regexes.yaml from uap-core it ships with (see below).
| `properties`           | no        | [`name`, `major`, `minor`, `patch`, `build`, `os`, `os_name`, `os_major`, `os_minor`, `device`] | Controls what properties are added to `target_field`.
| `ignore_missing`       | no        | `false`                                                                                         | If `true` and `field` does not exist, the processor quietly exits without modifying the document
|======

Here is an example that adds the user agent details to the `user_agent` field based on the `agent` field:

[source,js]
--------------------------------------------------
PUT _ingest/pipeline/user_agent
{
  "description" : "Add user agent information",
  "processors" : [
    {
      "user_agent" : {
        "field" : "agent"
      }
    }
  ]
}
PUT my_index/my_type/my_id?pipeline=user_agent
{
  "agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
}
GET my_index/my_type/my_id
--------------------------------------------------
// CONSOLE

Which returns

[source,js]
--------------------------------------------------
{
  "found": true,
  "_index": "my_index",
  "_type": "my_type",
  "_id": "my_id",
  "_version": 1,
  "_source": {
    "agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
    "user_agent": {
      "name": "Chrome",
      "major": "51",
      "minor": "0",
      "patch": "2704",
      "os_name": "Mac OS X",
      "os": "Mac OS X 10.10.5",
      "os_major": "10",
      "os_minor": "10",
      "device": "Other"
    }
  }
}
--------------------------------------------------
// TESTRESPONSE

===== Using a custom regex file
To use a custom regex file for parsing the user agents, that file has to be put into the `config/ingest-user-agent` directory and
has to have a `.yaml` filename extension. The file has to be present at node startup, any changes to it or any new files added
while the node is running will not have any effect.

In practice, it will make most sense for any custom regex file to be a variant of the default file, either a more recent version
or a customised version.

The default file included in `ingest-user-agent` is the `regexes.yaml` from uap-core: https://github.com/ua-parser/uap-core/blob/master/regexes.yaml