runGatherLogsTask
Use this method to create a task that collects diagnostic logs from an online endpoint. The task retrieves log files from the target endpoint and stores them according to the specified storage configuration: locally on the endpoint, on a network share, or in an S3-compatible bucket.
For more information on gathering logs, refer to the Troubleshooting tab section in Viewing endpoint details.
If you choose to upload results to an S3 bucket (AWS), you need to set up your AWS cloud platform in advance. For a step-by-step guide, refer to Set up AWS for Live Search, runLiveSearchQuery, and runGatherLogsTask.
Important
API URL: CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/network
Parameters
Parameter | Description | Included in request | Type | Values |
|---|---|---|---|---|
| The ID of the target endpoint to collect logs from. | Mandatory | String | Must be a valid managed endpoint ID. |
| The type of logs to collect from the endpoints. | Mandatory | Integer |
|
| Defines where the collected logs are stored. | Mandatory | Object | Refer to |
Value | Description |
|---|---|
| Product general issues. Collects support-tool or product diagnostic logs (settings, modules, policy, general troubleshooting). Use when the issue is unclear or product-related. |
| Malware infection (no cloud services). Collects BDSyslog forensic archive for suspected infection or attack, without contacting Bitdefender Cloud (no cloud threat-intel, hash, or DNS checks). |
| Malware infection. Same BDSyslog forensic collection with Bitdefender Cloud Services enabled for threat intelligence. |
storageOptions
Parameter | Description | Included in request | Type |
|---|---|---|---|
| The storage destination type. | Mandatory | Integer |
| The local path on the endpoint where logs are saved. | Depends on | String |
| UNC path to the network share. | Mandatory (if | String |
| Username for network share authentication. | Mandatory (if | String |
| Password for network share authentication. | Mandatory (if | String |
| S3 upload configuration. | Mandatory (if | Object |
storageType values:
Value | Description | localCopyPath |
|---|---|---|
| Local storage on the endpoint. | Required |
| Network share. | Optional (omit for share only) |
| Custom S3 bucket (AWS or OVH). | Required |
s3UploadConfig
Used when storageType = 3. Two authentication modes are available depending on the cloud provider:
AWS (Security Token Service - assume role):
Parameter | Description | Included in request | Type |
|---|---|---|---|
| The name of the S3 bucket where the data is stored. | Mandatory | String |
| The AWS region where the bucket is located. | Mandatory | String |
| The Amazon Resource Name (ARN) of the IAM role GravityZone will assume when accessing the bucket. | Mandatory | String |
| The unique identifier set in the role trust policy. It is used to enable secure cross-account access by verifying that the requester is authorized to assume the IAM role. | Mandatory | String |
OVH (presigned PUT - access keys):
Parameter | Description | Included in request | Type |
|---|---|---|---|
| Name of the S3-compatible bucket. | Mandatory | String |
| OVH region (for example: | Mandatory | String |
| OVH S3 access key. | Mandatory | String |
| OVH S3 secret key. | Mandatory | String |
Return value
Attribute | Description | Type |
|---|---|---|
| The ID of the task created by the request. | String |
Example 1 - Local storage (storageType: 1)
Request:
{
"jsonrpc": "2.0",
"method": "runGatherLogsTask",
"id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
"params": {
"endpointId": "559bd152b1a43d291b7b23d8",
"logType": 1,
"storageOptions": {
"storageType": 1,
"localCopyPath": "C:\\Bitdefender\\SupportLogs"
}
}
}
Response:
{
"id": "123-456-789-1011",
"jsonrpc": "2.0",
"result": "000000000000000000000000"
}Example 2 - Network share (storageType: 2)
Request:
{
"jsonrpc": "2.0",
"method": "runGatherLogsTask",
"id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
"params": {
"endpointId": "559bd152b1a43d291b7b23d8",
"logType": 2,
"storageOptions": {
"storageType": 2,
"networkSharePath": "\\\\10.17.20.70\\MyShareFile",
"username": "bdvm",
"password": "12wq!@WQ"
}
}
}Response:
{
"id": "123-456-789-1011",
"jsonrpc": "2.0",
"result": "000000000000000000000000"
}With optional local copy:
Request:
{
"jsonrpc": "2.0",
"method": "runGatherLogsTask",
"id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
"params": {
"endpointId": "559bd152b1a43d291b7b23d8",
"logType": 2,
"storageOptions": {
"storageType": 2,
"networkSharePath": "\\\\10.17.20.70\\MyShareFile",
"username": "bdvm",
"password": "12wq!@WQ",
"localCopyPath": "C:\\Logs"
}
}
}Response:
{
"id": "123-456-789-1011",
"jsonrpc": "2.0",
"result": "000000000000000000000000"
}Example 3 - Custom S3, AWS (storageType: 3, STS)
Request:
{
"jsonrpc": "2.0",
"method": "runGatherLogsTask",
"id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
"params": {
"endpointId": "559bd152b1a43d291b7b23d8",
"logType": 1,
"storageOptions": {
"storageType": 3,
"localCopyPath": "C:\\Logs",
"s3UploadConfig": {
"bucket": "my-company-logs-bucket",
"region": "eu-west-1",
"roleArn": "arn:aws:iam::123456789012:role/GravityZoneLogsUpload",
"externalId": "my-external-id-12345"
}
}
}
}Response:
{
"id": "123-456-789-1011",
"jsonrpc": "2.0",
"result": "000000000000000000000000"
}Example 4 - Custom S3, OVH (storageType: 3, presigned PUT)
Request:
{
"jsonrpc": "2.0",
"method": "runGatherLogsTask",
"id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
"params": {
"endpointId": "559bd152b1a43d291b7b23d8",
"logType": 1,
"storageOptions": {
"storageType": 3,
"localCopyPath": "C:\\Logs",
"s3UploadConfig": {
"bucket": "my-ovh-logs-bucket",
"region": "gra",
"accessKey": "my-ovh-access-key",
"secretKey": "my-ovh-secret-key"
}
}
}
}Response:
{
"id": "123-456-789-1011",
"jsonrpc": "2.0",
"result": "000000000000000000000000"
}