Remote debug (#564)

* Extend the trouble shooting with remote debug
2026-05-04 00:06:36 +00:00 · 2026-01-22 11:01:21 +01:00
parent 38eb2925c8
commit b5ce088750
3 changed files with 859 additions and 3 deletions
--- a/src/pages/ipa/resources/peers.mdx
+++ b/src/pages/ipa/resources/peers.mdx
@@ -1597,8 +1597,807 @@ echo $response;
 }
 ```
    </CodeGroup>
-    
- 
+
+
+  </Col>
+</Row>
+
+---
+
+
+## Create Peer Debug Bundle Job  {{ tag: 'POST' , label: '/api/peers/{peerId}/jobs' }}
+
+<Row>
+  <Col>
+    Triggers a remote debug bundle generation on the specified peer. The peer must be online and connected to receive
+    the job. Once generated, the bundle is automatically uploaded to the configured storage location.
+
+    ### Path Parameters
+    <Properties>
+
+          <Property name="peerId" type="string" required={true}>
+            The unique identifier of a peer
+          </Property>
+            </Properties>
+
+    ### Request-Body Parameters
+
+    <Properties><Property name="workload" type="object" required={true}>
+
+            The job workload configuration
+
+        </Property>
+    </Properties>
+
+    #### Workload Object
+    <Properties>
+    <Property name="type" type="string" required={true}>
+
+            Job type. Use "bundle" for debug bundle generation
+
+        </Property>
+    <Property name="parameters" type="object" required={false}>
+
+            Job-specific parameters
+
+        </Property>
+    </Properties>
+
+    #### Parameters Object (for debug bundle)
+    <Properties>
+    <Property name="anonymize" type="boolean" required={false}>
+
+            Anonymize IP addresses and non-netbird.io domains in logs and status output (default: false)
+
+        </Property>
+    <Property name="bundle_for" type="boolean" required={false}>
+
+            Enable time-based log collection before generating bundle (default: false)
+
+        </Property>
+    <Property name="bundle_for_time" type="number" required={false}>
+
+            Duration in minutes for log collection (1-5 minutes). Only used if bundle_for is true
+
+        </Property>
+    <Property name="log_file_count" type="number" required={false}>
+
+            Number of log files to include (1-1000, default: 10)
+
+        </Property>
+    </Properties>
+
+
+       </Col>
+
+  <Col sticky>
+    <CodeGroup title="Request" tag="POST" label="/api/peers/{peerId}/jobs">
+```bash {{ title: 'cURL' }}
+curl -X POST https://api.netbird.io/api/peers/{peerId}/jobs \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Token <TOKEN>' \
+--data-raw '{
+  "workload": {
+    "type": "bundle",
+    "parameters": {
+      "anonymize": true,
+      "bundle_for": true,
+      "bundle_for_time": 2,
+      "log_file_count": 10
+    }
+  }
+}'
+```
+
+```js
+const axios = require('axios');
+let data = JSON.stringify({
+  "workload": {
+    "type": "bundle",
+    "parameters": {
+      "anonymize": true,
+      "bundle_for": true,
+      "bundle_for_time": 2,
+      "log_file_count": 10
+    }
+  }
+});
+let config = {
+  method: 'post',
+  maxBodyLength: Infinity,
+  url: '/api/peers/{peerId}/jobs',
+  headers: {
+    'Accept': 'application/json',
+    'Content-Type': 'application/json',
+    'Authorization': 'Token <TOKEN>'
+  },
+  data : data
+};
+
+axios(config)
+.then((response) => {
+  console.log(JSON.stringify(response.data));
+})
+.catch((error) => {
+  console.log(error);
+});
+```
+
+```python
+import requests
+import json
+
+url = "https://api.netbird.io/api/peers/{peerId}/jobs"
+payload = json.dumps({
+  "workload": {
+    "type": "bundle",
+    "parameters": {
+      "anonymize": True,
+      "bundle_for": True,
+      "bundle_for_time": 2,
+      "log_file_count": 10
+    }
+  }
+})
+headers = {
+  'Content-Type': 'application/json',
+  'Accept': 'application/json',
+  'Authorization': 'Token <TOKEN>'
+}
+
+response = requests.request("POST", url, headers=headers, data=payload)
+
+print(response.text)
+```
+
+```go
+package main
+
+import (
+  "fmt"
+  "strings"
+  "net/http"
+  "io/ioutil"
+)
+
+func main() {
+
+  url := "https://api.netbird.io/api/peers/{peerId}/jobs"
+  method := "POST"
+
+  payload := strings.NewReader(`{
+  "workload": {
+    "type": "bundle",
+    "parameters": {
+      "anonymize": true,
+      "bundle_for": true,
+      "bundle_for_time": 2,
+      "log_file_count": 10
+    }
+  }
+}`)
+  client := &http.Client {
+  }
+  req, err := http.NewRequest(method, url, payload)
+
+  if err != nil {
+    fmt.Println(err)
+    return
+  {
+
+  req.Header.Add("Content-Type", "application/json")
+  req.Header.Add("Accept", "application/json")
+  req.Header.Add("Authorization", "Token <TOKEN>")
+
+  res, err := client.Do(req)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  defer res.Body.Close()
+
+  body, err := ioutil.ReadAll(res.Body)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  fmt.Println(string(body))
+}
+```
+
+```ruby
+require "uri"
+require "json"
+require "net/http"
+
+url = URI("https://api.netbird.io/api/peers/{peerId}/jobs")
+
+https = Net::HTTP.new(url.host, url.port)
+https.use_ssl = true
+
+request = Net::HTTP::Post.new(url)
+request["Content-Type"] = "application/json"
+request["Accept"] = "application/json"
+request["Authorization"] = "Token <TOKEN>"
+
+request.body = JSON.dump({
+  "workload": {
+    "type": "bundle",
+    "parameters": {
+      "anonymize": true,
+      "bundle_for": true,
+      "bundle_for_time": 2,
+      "log_file_count": 10
+    }
+  }
+})
+response = https.request(request)
+puts response.read_body
+```
+
+```java
+OkHttpClient client = new OkHttpClient().newBuilder()
+  .build();
+MediaType mediaType = MediaType.parse("application/json");
+RequestBody body = RequestBody.create(mediaType, '{
+  "workload": {
+    "type": "bundle",
+    "parameters": {
+      "anonymize": true,
+      "bundle_for": true,
+      "bundle_for_time": 2,
+      "log_file_count": 10
+    }
+  }
+}');
+Request request = new Request.Builder()
+  .url("https://api.netbird.io/api/peers/{peerId}/jobs")
+  .method("POST", body)
+  .addHeader("Content-Type", "application/json")
+  .addHeader("Accept", "application/json")
+  .addHeader("Authorization: Token <TOKEN>")
+  .build();
+Response response = client.newCall(request).execute();
+```
+
+```php
+<?php
+
+$curl = curl_init();
+
+curl_setopt_array($curl, array(
+  CURLOPT_URL => 'https://api.netbird.io/api/peers/{peerId}/jobs',
+  CURLOPT_RETURNTRANSFER => true,
+  CURLOPT_ENCODING => '',
+  CURLOPT_MAXREDIRS => 10,
+  CURLOPT_TIMEOUT => 0,
+  CURLOPT_FOLLOWLOCATION => true,
+  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
+  CURLOPT_CUSTOMREQUEST => 'POST',
+  CURLOPT_POSTFIELDS => '{
+  "workload": {
+    "type": "bundle",
+    "parameters": {
+      "anonymize": true,
+      "bundle_for": true,
+      "bundle_for_time": 2,
+      "log_file_count": 10
+    }
+  }
+}',
+  CURLOPT_HTTPHEADER => array(
+    'Content-Type: application/json',
+    'Accept: application/json',
+    'Authorization: Token <TOKEN>'
+  ),
+));
+
+$response = curl_exec($curl);
+
+curl_close($curl);
+echo $response;
+```
+
+    </CodeGroup>
+
+
+    <CodeGroup title="Response">
+```json {{ title: 'Example' }}
+{
+  "id": "chacbco6lnnbn6cg5s91",
+  "peer_id": "chacbco6lnnbn6cg5s90",
+  "status": "pending",
+  "created_at": "2026-01-21T10:30:00.000Z",
+  "updated_at": "2026-01-21T10:30:00.000Z",
+  "workload": {
+    "type": "bundle",
+    "parameters": {
+      "anonymize": true,
+      "bundle_for": true,
+      "bundle_for_time": 2,
+      "log_file_count": 10
+    }
+  }
+}
+```
+```json {{ title: 'Schema' }}
+{
+  "id": "string",
+  "peer_id": "string",
+  "status": "string",
+  "created_at": "string",
+  "updated_at": "string",
+  "workload": {
+    "type": "string",
+    "parameters": {
+      "anonymize": "boolean",
+      "bundle_for": "boolean",
+      "bundle_for_time": "number",
+      "log_file_count": "number"
+    },
+    "result": {
+      "upload_key": "string"
+    }
+  }
+}
+```
+    </CodeGroup>
+
+
+  </Col>
+</Row>
+
+---
+
+
+## List Peer Jobs  {{ tag: 'GET' , label: '/api/peers/{peerId}/jobs' }}
+
+<Row>
+  <Col>
+    Returns a list of all jobs for the specified peer, including debug bundle generation jobs.
+
+    ### Path Parameters
+    <Properties>
+
+          <Property name="peerId" type="string" required={true}>
+            The unique identifier of a peer
+          </Property>
+            </Properties>
+              </Col>
+
+  <Col sticky>
+    <CodeGroup title="Request" tag="GET" label="/api/peers/{peerId}/jobs">
+```bash {{ title: 'cURL' }}
+curl -X GET https://api.netbird.io/api/peers/{peerId}/jobs \
+-H 'Accept: application/json' \
+-H 'Authorization: Token <TOKEN>'
+```
+
+```js
+const axios = require('axios');
+
+let config = {
+  method: 'get',
+  maxBodyLength: Infinity,
+  url: '/api/peers/{peerId}/jobs',
+  headers: {
+    'Accept': 'application/json',
+    'Authorization': 'Token <TOKEN>'
+  }
+};
+
+axios(config)
+.then((response) => {
+  console.log(JSON.stringify(response.data));
+})
+.catch((error) => {
+  console.log(error);
+});
+```
+
+```python
+import requests
+import json
+
+url = "https://api.netbird.io/api/peers/{peerId}/jobs"
+
+headers = {
+  'Accept': 'application/json',
+  'Authorization': 'Token <TOKEN>'
+}
+
+response = requests.request("GET", url, headers=headers)
+
+print(response.text)
+```
+
+```go
+package main
+
+import (
+  "fmt"
+  "strings"
+  "net/http"
+  "io/ioutil"
+)
+
+func main() {
+
+  url := "https://api.netbird.io/api/peers/{peerId}/jobs"
+  method := "GET"
+
+  client := &http.Client {
+  }
+  req, err := http.NewRequest(method, url, nil)
+
+  if err != nil {
+    fmt.Println(err)
+    return
+  {
+
+  req.Header.Add("Accept", "application/json")
+  req.Header.Add("Authorization", "Token <TOKEN>")
+
+  res, err := client.Do(req)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  defer res.Body.Close()
+
+  body, err := ioutil.ReadAll(res.Body)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  fmt.Println(string(body))
+}
+```
+
+```ruby
+require "uri"
+require "json"
+require "net/http"
+
+url = URI("https://api.netbird.io/api/peers/{peerId}/jobs")
+
+https = Net::HTTP.new(url.host, url.port)
+https.use_ssl = true
+
+request = Net::HTTP::Get.new(url)
+request["Accept"] = "application/json"
+request["Authorization"] = "Token <TOKEN>"
+
+response = https.request(request)
+puts response.read_body
+```
+
+```java
+OkHttpClient client = new OkHttpClient().newBuilder()
+  .build();
+
+Request request = new Request.Builder()
+  .url("https://api.netbird.io/api/peers/{peerId}/jobs")
+  .method("GET")
+  .addHeader("Accept", "application/json")
+  .addHeader("Authorization: Token <TOKEN>")
+  .build();
+Response response = client.newCall(request).execute();
+```
+
+```php
+<?php
+
+$curl = curl_init();
+
+curl_setopt_array($curl, array(
+  CURLOPT_URL => 'https://api.netbird.io/api/peers/{peerId}/jobs',
+  CURLOPT_RETURNTRANSFER => true,
+  CURLOPT_ENCODING => '',
+  CURLOPT_MAXREDIRS => 10,
+  CURLOPT_TIMEOUT => 0,
+  CURLOPT_FOLLOWLOCATION => true,
+  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
+  CURLOPT_CUSTOMREQUEST => 'GET',
+  CURLOPT_HTTPHEADER => array(
+    'Accept: application/json',
+    'Authorization: Token <TOKEN>'
+  ),
+));
+
+$response = curl_exec($curl);
+
+curl_close($curl);
+echo $response;
+```
+
+    </CodeGroup>
+
+
+    <CodeGroup title="Response">
+```json {{ title: 'Example' }}
+[
+  {
+    "id": "chacbco6lnnbn6cg5s91",
+    "peer_id": "chacbco6lnnbn6cg5s90",
+    "status": "succeeded",
+    "created_at": "2026-01-21T10:30:00.000Z",
+    "updated_at": "2026-01-21T10:31:15.000Z",
+    "workload": {
+      "type": "bundle",
+      "parameters": {
+        "anonymize": true,
+        "bundle_for": true,
+        "bundle_for_time": 2,
+        "log_file_count": 10
+      },
+      "result": {
+        "upload_key": "1234567890ab27fb37c88b3b4be7011e22aa2e5ca6f38ffa9c4481884941f726/12345678-90ab-cdef-1234-567890abcdef"
+      }
+    }
+  },
+  {
+    "id": "chacbco6lnnbn6cg5s92",
+    "peer_id": "chacbco6lnnbn6cg5s90",
+    "status": "pending",
+    "created_at": "2026-01-21T11:00:00.000Z",
+    "updated_at": "2026-01-21T11:00:00.000Z",
+    "workload": {
+      "type": "bundle",
+      "parameters": {
+        "anonymize": false,
+        "log_file_count": 10
+      }
+    }
+  }
+]
+```
+```json {{ title: 'Schema' }}
+[
+  {
+    "id": "string",
+    "peer_id": "string",
+    "status": "string",
+    "created_at": "string",
+    "updated_at": "string",
+    "workload": {
+      "type": "string",
+      "parameters": {
+        "anonymize": "boolean",
+        "bundle_for": "boolean",
+        "bundle_for_time": "number",
+        "log_file_count": "number"
+      },
+      "result": {
+        "upload_key": "string"
+      }
+    }
+  }
+]
+```
+    </CodeGroup>
+
+
+  </Col>
+</Row>
+
+---
+
+
+## Get Peer Job  {{ tag: 'GET' , label: '/api/peers/{peerId}/jobs/{jobId}' }}
+
+<Row>
+  <Col>
+    Returns details of a specific job for the peer, including the upload key if the debug bundle generation is complete.
+
+    ### Path Parameters
+    <Properties>
+
+          <Property name="peerId" type="string" required={true}>
+            The unique identifier of a peer
+          </Property>
+          <Property name="jobId" type="string" required={true}>
+            The unique identifier of a job
+          </Property>
+            </Properties>
+              </Col>
+
+  <Col sticky>
+    <CodeGroup title="Request" tag="GET" label="/api/peers/{peerId}/jobs/{jobId}">
+```bash {{ title: 'cURL' }}
+curl -X GET https://api.netbird.io/api/peers/{peerId}/jobs/{jobId} \
+-H 'Accept: application/json' \
+-H 'Authorization: Token <TOKEN>'
+```
+
+```js
+const axios = require('axios');
+
+let config = {
+  method: 'get',
+  maxBodyLength: Infinity,
+  url: '/api/peers/{peerId}/jobs/{jobId}',
+  headers: {
+    'Accept': 'application/json',
+    'Authorization': 'Token <TOKEN>'
+  }
+};
+
+axios(config)
+.then((response) => {
+  console.log(JSON.stringify(response.data));
+})
+.catch((error) => {
+  console.log(error);
+});
+```
+
+```python
+import requests
+import json
+
+url = "https://api.netbird.io/api/peers/{peerId}/jobs/{jobId}"
+
+headers = {
+  'Accept': 'application/json',
+  'Authorization': 'Token <TOKEN>'
+}
+
+response = requests.request("GET", url, headers=headers)
+
+print(response.text)
+```
+
+```go
+package main
+
+import (
+  "fmt"
+  "strings"
+  "net/http"
+  "io/ioutil"
+)
+
+func main() {
+
+  url := "https://api.netbird.io/api/peers/{peerId}/jobs/{jobId}"
+  method := "GET"
+
+  client := &http.Client {
+  }
+  req, err := http.NewRequest(method, url, nil)
+
+  if err != nil {
+    fmt.Println(err)
+    return
+  {
+
+  req.Header.Add("Accept", "application/json")
+  req.Header.Add("Authorization", "Token <TOKEN>")
+
+  res, err := client.Do(req)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  defer res.Body.Close()
+
+  body, err := ioutil.ReadAll(res.Body)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  fmt.Println(string(body))
+}
+```
+
+```ruby
+require "uri"
+require "json"
+require "net/http"
+
+url = URI("https://api.netbird.io/api/peers/{peerId}/jobs/{jobId}")
+
+https = Net::HTTP.new(url.host, url.port)
+https.use_ssl = true
+
+request = Net::HTTP::Get.new(url)
+request["Accept"] = "application/json"
+request["Authorization"] = "Token <TOKEN>"
+
+response = https.request(request)
+puts response.read_body
+```
+
+```java
+OkHttpClient client = new OkHttpClient().newBuilder()
+  .build();
+
+Request request = new Request.Builder()
+  .url("https://api.netbird.io/api/peers/{peerId}/jobs/{jobId}")
+  .method("GET")
+  .addHeader("Accept", "application/json")
+  .addHeader("Authorization: Token <TOKEN>")
+  .build();
+Response response = client.newCall(request).execute();
+```
+
+```php
+<?php
+
+$curl = curl_init();
+
+curl_setopt_array($curl, array(
+  CURLOPT_URL => 'https://api.netbird.io/api/peers/{peerId}/jobs/{jobId}',
+  CURLOPT_RETURNTRANSFER => true,
+  CURLOPT_ENCODING => '',
+  CURLOPT_MAXREDIRS => 10,
+  CURLOPT_TIMEOUT => 0,
+  CURLOPT_FOLLOWLOCATION => true,
+  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
+  CURLOPT_CUSTOMREQUEST => 'GET',
+  CURLOPT_HTTPHEADER => array(
+    'Accept: application/json',
+    'Authorization: Token <TOKEN>'
+  ),
+));
+
+$response = curl_exec($curl);
+
+curl_close($curl);
+echo $response;
+```
+
+    </CodeGroup>
+
+
+    <CodeGroup title="Response">
+```json {{ title: 'Example' }}
+{
+  "id": "chacbco6lnnbn6cg5s91",
+  "peer_id": "chacbco6lnnbn6cg5s90",
+  "status": "succeeded",
+  "created_at": "2026-01-21T10:30:00.000Z",
+  "updated_at": "2026-01-21T10:31:15.000Z",
+  "workload": {
+    "type": "bundle",
+    "parameters": {
+      "anonymize": true,
+      "bundle_for": true,
+      "bundle_for_time": 2,
+      "log_file_count": 10
+    },
+    "result": {
+      "upload_key": "1234567890ab27fb37c88b3b4be7011e22aa2e5ca6f38ffa9c4481884941f726/12345678-90ab-cdef-1234-567890abcdef"
+    }
+  }
+}
+```
+```json {{ title: 'Schema' }}
+{
+  "id": "string",
+  "peer_id": "string",
+  "status": "string",
+  "created_at": "string",
+  "updated_at": "string",
+  "workload": {
+    "type": "string",
+    "parameters": {
+      "anonymize": "boolean",
+      "bundle_for": "boolean",
+      "bundle_for_time": "number",
+      "log_file_count": "number"
+    },
+    "result": {
+      "upload_key": "string"
+    }
+  }
+}
+```
+    </CodeGroup>
+
+
  </Col>
 </Row>