Skip to main content
Version: 2.0.0 (Latest)

Quickstart: Core only

This quickstart brings up Padas Core without the management UI and proves a minimal source → task → sink path using the Core HTTPS API and a small local TCP harness.

padas_tcp_quickstart_server.py is a long-lived process: it accepts the sink connector’s outbound TCP connection and forwards synthetic syslog-style lines toward the source listener Core exposes once the bundle is applied. padas_quickstart_push_to_core.py is a one-shot control-plane client: it POSTs padas-quickstart-core-api.json to create streams, connectors, and the task, then walks starts_in_order so the runtime wires source → task → sink.

Default Core API base is https://<host>:8999/api/v1/...; use http:// when API TLS is disabled in padas.toml. The same logical pipeline with the UI is documented in Quickstart: Core + UI.

Outcomes and constraints​

OutcomeDetail
Proven pathRegistry objects and lifecycle are driven only through the API bundle—no UI import.
Co-locationThe TCP helper is expected on the same host as Core (or routable equivalent) so the sink’s configured endpoint matches 127.0.0.1:8081 by default.
Hand-off to UIIf you later run Quickstart: Core + UI on this engine, remove quickstart objects first (Tear down). Leaving API-created rows in place can desynchronize the console from engine state.

Helper and bundle behavior (architecture)​

RoleBehavior
Sink connector (Core)After start, opens an outbound TCP client to the helper’s listen address (0.0.0.0:8081 default). The helper must already be accepting connections on that port.
HelperListens for the sink; forwards generated lines to Core’s source side (127.0.0.1:8080 by default). Override with PADAS_TCP_SOURCE_HOST / PADAS_TCP_SOURCE_PORT when Core is not loopback-local.
Source connector (Core)Listens for inbound syslog-style payloads; the helper’s sender retries against that port until Core is up—still expect failures until the bundle starts the source.
Push scriptIdempotent only at the HTTP layer for new id values; re-run against the same ids yields 409 Conflict until objects are deleted.

Prerequisites​

  1. Installation — Linux completed; operator padas.toml present under $PADAS_HOME/etc/ (Runtime configurations).
  2. Core running under padas-core.service or foreground equivalent (Installation — Linux).
  3. python3, curl, and jq available on the host used for API and helper commands.

Step 1 — Start Core and verify the API​

Start Core if it is not already running (foreground example; use systemctl when installed as a service):

/opt/padas/bin/padas start --config /opt/padas/core/etc/padas.toml

When [api.auth] is enabled, read the service-account token (Core must have started at least once so the file exists):

export TOKEN="$(jq -r '.token' /opt/padas/core/data/security/service-account.token)"

Verify the control plane responds (--insecure for self-signed lab TLS; omit when curl trusts the Core cert; use http:// when TLS is off):

curl -sS --insecure -H "Authorization: Bearer ${TOKEN}" \
  https://127.0.0.1:8999/api/v1/status

Confirm system.status is running. With auth disabled in lab configs, omit the Authorization header.

Step 2 — Start the TCP helper (before the bundle push)​

On the same machine as Core (or adjusted host env vars), start the helper and keep the helper process running for the remainder of the quickstart:

python3 padas_tcp_quickstart_server.py
  • Listen (sink side): 0.0.0.0:8081 by default (PADAS_TCP_SINK_BIND / PADAS_TCP_SINK_PORT optional).
  • Forward (toward Core source): 127.0.0.1:8080 by default.
  • Rate: PADAS_QUICKSTART_EVENT_INTERVAL_SEC (see script header).

Step 3 — Push the quickstart bundle​

padas_quickstart_push_to_core.py resolves padas-quickstart-core-api.json next to the script or under config/ / ../config/ (mirrors static/assets/scripts and static/assets/config in this repository). It creates registry objects, then executes starts_in_order, and prints a compact status table.

python3 padas_quickstart_push_to_core.py \
  --core-url "https://127.0.0.1:8999" \
  --token "${TOKEN}"

For lab APIs with TLS disabled, pass --core-url "http://127.0.0.1:8999". For https://, the script performs normal verification first, then one retry without certificate verification for typical self-signed lab cores.

Re-applying the same object id values returns 409 Conflict—delete prior objects or point Core at a clean config_dir before a second run.

Step 4 — Validate runtime traffic​

With the helper still running, observe its stdout for [SINK] lines. The bundled PDL filters (parse_kv, action = "login", eval) emit a subset of synthetic events; if you see [SOURCE] without [SINK], allow more wall time or reduce PADAS_QUICKSTART_EVENT_INTERVAL_SEC.

Troubleshooting​

See Troubleshooting & Logs → Quickstart: Core only.

Reference and tear down​

Tear down: padas_quickstart_delete_from_core.sh reads padas-quickstart-core-api.json (default: adjacent to the script), issues POST …/stop in reverse starts_in_order, then DELETE for connectors, tasks, streams, and related ids. Prefer --token-file /opt/padas/core/data/security/service-account.token over embedding secrets in shell history.

./padas_quickstart_delete_from_core.sh \
  --core-url "https://127.0.0.1:8999" \
  --token-file /opt/padas/core/data/security/service-account.token \
  --bundle padas-quickstart-core-api.json \
  --insecure