🎯API Stability
Long-TermThis API is stable and will remain supported across versions with minimal breaking changes.

Summary

The createIngestListenerV3() mutation creates a new ingest listener for a repository. An ingest listener opens a TCP, UDP, GELF, or NETFLOW socket on a specified network interface and port, accepts raw incoming data, and routes it through a parser for processing before storage. The V3 version adds the vHost field, which controls which host node opens the socket in a cluster deployment. To modify an existing listener, use updateIngestListenerV3().

Syntax

graphql
createIngestListenerV3(
      input: CreateIngestListenerV3Input!
   ): IngestListener!

The mutation accepts a single required input argument of type CreateIngestListenerV3Input!. The input requires the repository name, listener name, bind interface, port, protocol, parser, and character set. The vHost field is optional and defaults to all hosts opening a socket. The mutation returns an IngestListener! object for the created listener.

Example

Raw
graphql
mutation {
  createIngestListenerV3(input:
       { repositoryName: "humio",
         port: 8080, protocol: TCP,
         name: "listen-up",
         bindInterface: "12.127.18.88",
         parser: "kv", charset: "UTF-8" } )
  { id }
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  createIngestListenerV3(input:
       { repositoryName: \"humio\",
         port: 8080, protocol: TCP,
         name: \"listen-up\",
         bindInterface: \"12.127.18.88\",
         parser: \"kv\", charset: \"UTF-8\" } )
  { id }
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  createIngestListenerV3(input:
       { repositoryName: \"humio\",
         port: 8080, protocol: TCP,
         name: \"listen-up\",
         bindInterface: \"12.127.18.88\",
         parser: \"kv\", charset: \"UTF-8\" } )
  { id }
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  createIngestListenerV3(input: ^
       { repositoryName: \"humio\", ^
         port: 8080, protocol: TCP, ^
         name: \"listen-up\", ^
         bindInterface: \"12.127.18.88\", ^
         parser: \"kv\", charset: \"UTF-8\" } ) ^
  { id } ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  createIngestListenerV3(input:
       { repositoryName: \"humio\",
         port: 8080, protocol: TCP,
         name: \"listen-up\",
         bindInterface: \"12.127.18.88\",
         parser: \"kv\", charset: \"UTF-8\" } )
  { id }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  createIngestListenerV3(input:
       { repositoryName: \"humio\",
         port: 8080, protocol: TCP,
         name: \"listen-up\",
         bindInterface: \"12.127.18.88\",
         parser: \"kv\", charset: \"UTF-8\" } )
  { id }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  createIngestListenerV3(input:
       { repositoryName: \"humio\",
         port: 8080, protocol: TCP,
         name: \"listen-up\",
         bindInterface: \"12.127.18.88\",
         parser: \"kv\", charset: \"UTF-8\" } )
  { id }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  createIngestListenerV3(input:
       { repositoryName: \"humio\",
         port: 8080, protocol: TCP,
         name: \"listen-up\",
         bindInterface: \"12.127.18.88\",
         parser: \"kv\", charset: \"UTF-8\" } )
  { id }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();

Input Parameters

The input argument takes a CreateIngestListenerV3Input object. All fields except vHost are required.

Table: CreateIngestListenerV3Input Input Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
bindInterfaceStringyes Long-Term The IP address to which the listener socket binds. Specify 0.0.0.0 to bind to all available network interfaces. In environments with multiple network interfaces, specifying a single address restricts the socket to that interface only.
charsetStringyes Long-Term The character encoding used to decode the raw byte stream. UTF-8 is standard for most sources. Available encodings depend on the JVM running the LogScale instance; for valid names and aliases, see the IANA character sets registry.
nameStringyes Long-Term The display name for the listener in the LogScale UI and API responses. Choose a name that reflects the data source or network endpoint.
parserStringyes Long-Term The name or ID of the parser that processes raw incoming data into structured events. All data received by this listener passes through the specified parser on arrival. For parsers in packages, use the format packagescope/packagename:parsername.
portIntyes Long-Term The TCP or UDP port on which the listener accepts connections or datagrams. Ports below 1024 may require elevated OS permissions on the host.
protocolIngestListenerProtocolyes Long-Term The network protocol the listener accepts. Must match the protocol used by the sending system. Accepted values are TCP, UDP, GELF_TCP, GELF_UDP, and NETFLOW_UDP. See IngestListenerProtocol.
repositoryNameStringyes Long-Term The name of the repository that receives ingested data. The listener routes all incoming data to this repository.
vHostInt  Long-Term In a cluster deployment, specifies which host node opens the socket. If omitted, all hosts in the cluster open a socket on the configured port. Use this field to restrict socket binding to a single dedicated ingest node.

Returned Values

The mutation returns an IngestListener! object for the created listener. Request id to obtain the listener identifier needed for update and delete operations. The parser field returns null if the assigned parser is removed after the listener is created. The vHost field returns null if no vHost was specified, indicating all cluster hosts have opened a socket on the configured port. The following table describes the available fields:

Table: IngestListener Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
bindInterfaceStringyes Long-Term The ip address this listener will bind to. By default (leaving this field empty) it will bind to 0.0.0.0 - all interfaces. Using this field it is also possible to specify the address to bind to. In a cluster setup it is also possible to specify if only one machine should open a socket - The vhost field is used for that.
charsetStringyes Long-Term The character set used to decode the event stream. Available character sets depend on the JVM running the LogScale instance. Names and aliases can be found at http://www.iana.org/assignments/character-sets/character-sets.xhtml
idStringyes Long-Term The unique identifier for the ingest listener.
nameStringyes Long-Term The name of the ingest listener.
parserParser  Long-Term The parser configured to parse data for the listener. It returns null if the parser has been removed since the listener was created. See Parser.
portIntyes Long-Term The TCP/UDP port on which to listen.
protocolIngestListenerProtocolyes Long-Term The network protocol data is sent through. See IngestListenerProtocol.
repositoryRepositoryyes Long-Term The repository associated with the ingest listener. See Repository.
vHostInt  Long-Term Specify which host should open the socket. By default this field is empty and all hosts will open a socket. This field can be used to select only one host to open the socket.