nano-connect CLI
Generate local collectors with the Bash nano-connect client, issue a per-source ingest token for each, and verify that events land under the right source
The Bash nano-connect client onboards data sources into nano. It generates local Vector collectors for syslog devices, Linux journald and log files, and Windows Event Log and Sysmon. It issues one ingest token per source, and checks in Search that events arrive under that source.
It works the same way on every deployment: Open and Self-run. Both expose the same Log Sources, ingest-token, parser and search APIs. The only difference is where events are sent; see Ingest destination.
Download the client
You need Bash 3.2 or later, curl and standard Unix tools. jq is optional, and Node.js isn't used. Download the script, review it, and check its version:
curl -fsSL https://github.com/nano-rs/connect/releases/latest/download/connect.sh -o connect.sh
bash connect.sh --version
bash connect.sh --helpFor automation, fetch connect.sh and connect.sh.sha256 from the same versioned release. Run sha256sum --check connect.sh.sha256 before you execute it.
Before you start
Set your nano URL and supply an API key through your secret manager:
export NANO_URL="https://nano.example.com"
export NANO_API_KEY="..." # from your secret managerThe key needs these permissions:
| Action | Permission |
|---|---|
| Discover sources, tokens and the ingest destination | log_sources:view |
| Issue, bind, rotate and revoke ingest tokens | settings:system |
Import and publish a parser (--deploy-parsers) | parser_repositories:import, log_sources:create, source_configs:edit, log_sources:deploy |
Prove delivery (connect, verify) | search:execute, plus visibility of the source |
Alternatively, set NANO_EMAIL. The client signs in and, after you confirm, creates an API key named nano-connect with these permissions. The API key never authenticates events: each collector uses its source's ingest token.
Ingest destination
Self-run on Kubernetes receives events on a dedicated ingest frontend with its own hostname, for example https://ingest.example.com. This keeps ingest load away from the app. A dedicated ingest frontend is coming to Self-run on Docker Compose; until then, Compose installs (open core and Self-run) receive events at /ingest on the app host.
The client chooses the destination in this order:
--ingest-url: the exact URL for the chosen transport.--ingest-base: your ingest frontend's origin, for examplehttps://ingest.example.com.- The ingest base your deployment reports (
NANO_INGEST_PUBLIC_BASE_URL), when it differs from the app URL. - The app host, only when the deployment reports no dedicated ingest base. On a Self-run deployment the client warns you when it falls back.
When a dedicated ingest base is configured, the client never sends events to the app host. It refuses an --ingest-url or --ingest-base that points there. If the key can't read the ingest endpoint on a Self-run deployment, pass --ingest-base.
bash connect.sh add-source --sources cisco_asa \
--ingest-base https://ingest.example.com --non-interactiveGenerate a collector
List the sources you can collect. The output shows the built-in syslog sources, your deployment's log sources, and syslog-capable parsers from its parser registry:
bash connect.sh list-sourcesSyslog devices
bash connect.sh add-source --sources cisco_asa,palo_alto:tcp \
--deploy-parsers --out-dir ./fw-collector --non-interactiveFor each source that isn't a log source yet, --deploy-parsers imports and publishes its parser from the registry. The client then issues an ingest token bound to that source, and writes vector.toml, docker-compose.yml and a private secrets/ directory. Append :tcp, :udp or :http to choose the local listener. Built-in sources keep their usual ports, for example UDP 5514 for Cisco ASA and TCP 5515 for Palo Alto. Other sources get a stable port in 5600–5699. The generated files list them.
On the collector host, start it with --run, or review the files and start it yourself:
docker compose -f ./fw-collector/docker-compose.yml up -dPoint your devices at that host. The listeners have no authentication, so keep them on a trusted network.
Linux endpoints
bash connect.sh add-agent --os linux \
--files '/var/log/myapp/*.log' --file-source json_generic \
--out-dir ./linux-agent --non-interactiveThe agent collects journald (linux_journald, and linux_sysmon for Sysmon for Linux) plus any files you list. --file-source names the source the files land in, and must have a parser or log source. Install Vector 0.59 on the endpoint. Copy vector.toml to /etc/nano-collector/vector.toml and secrets/ to /etc/vector/secrets (mode 0700, files 0600), then install the generated nano-collector.service. Use --no-journald to collect files only.
Windows endpoints
bash connect.sh add-agent --os windows --out-dir ./windows-agent --non-interactiveThe agent reads Application, System, Security, Sysmon, PowerShell and Defender event logs. It sends Sysmon events to windows_sysmon and everything else to windows_event. Run the generated install-agent.ps1 as Administrator on the endpoint. It verifies the signed Vector MSI, restricts the secrets directory to Administrators and SYSTEM, and installs the service.
Aggregators
To fan many endpoints into one collector:
bash connect.sh add-aggregator --sources cisco_asa --out-dir ./hub --non-interactive
bash connect.sh add-agent --os linux --target hub.internal:9000 --out-dir ./linux-agent --non-interactiveAgents generated with --target need no API key. The agent-to-aggregator hop isn't authenticated, so keep it on a private network. The aggregator forwards each source with its own ingest token.
Transports
HEC and HTTP are both fully supported. Both use the source's ingest token, send the original log line, buffer to disk, and store events under the same source. HEC is the default.
| Transport | Flag | Destination | Auth |
|---|---|---|---|
| HEC (default) | --transport hec | your deployment's HEC listener, port 8088 by default | Authorization: Splunk <token> |
| HTTP | --transport http | <ingest>/ingest | Authorization: Bearer <token> |
The token decides which source an event is stored under, whatever the sender declares.
HTTP goes through the ingest edge, which terminates TLS like the app. HEC uses whatever your deployment puts in front of the HEC listener; on open core it's plain HTTP by default. Choose HTTP if the collector crosses a network you don't trust and your HEC listener has no TLS, or if only the ingest edge is reachable.
Prove delivery
Send a test event through nano's ingest path and wait until it appears in Search under the source:
bash connect.sh connect --source cisco_asa --non-interactiveThis doesn't test the hop from your device to the collector. After real events flow, check for fresh events under the source:
bash connect.sh verify --source cisco_asa --non-interactiveverify searches metadata.log_source over the last 15 minutes (--window changes this). It reports how many events arrived and how many were mapped to an OCSF class, and exits nonzero if none arrived. In Search:
metadata.log_source="cisco_asa" | stats count by class_nameTo prove specific requests through a collector, send a distinct marker in each request. List them in a private file, one source marker pair per line, then run:
bash connect.sh verify --evidence-file /private/request-evidence.txt --wait-seconds 120Tokens
Each source gets its own named ingest token. The client saves it privately in ~/.config/nano-connect-bash and reuses it on later runs. In a collector, Vector reads tokens from secrets/; they never appear in vector.toml or on screen.
--token-dir DIRuses tokens you already have, one file per source. An unbound token is bound to the source. A token bound to another source, or a revoked token, is refused.rotate-token --source cisco_asa --out-dir ./fw-collectorissues a replacement and saves it, then revokes the old token. Restart the collector afterwards.revoke-token --source cisco_asarevokes the token the client issued. Vector refuses it within seconds.
You can also manage tokens in Log Sources.
OpenTelemetry exporters
bash connect.sh otlp-config --source myservice --out-dir ./otel --non-interactiveThis writes a private otel.env with OTEL_EXPORTER_OTLP_ENDPOINT=<ingest>/otlp and the source's Bearer token. Use one exporter configuration for each source. See OTLP.
Troubleshoot
| Symptom | Check |
|---|---|
403 during discovery | The key needs log_sources:view. Issuing tokens needs settings:system. |
token delivery is not configured | The deployment can't deliver tokens to Vector (NANO_INGEST_TOKENS_DELIVERY). Ask your operator. |
refusing to send events to the app host | Your deployment has a dedicated ingest frontend. Drop the app-host --ingest-url or --ingest-base. |
Self-run deployment asks for --ingest-base | The key can't read the ingest endpoint. Pass your ingest frontend's origin. |
No bindable source or registry parser | Run bash connect.sh sync-parsers, or create the log source first. |
| Accepted but not searchable | Check the collector logs and the source's parser. Search for the marker without the source filter to see where it landed. |
| Searchable but unparsed | Check the raw format against the source's parser. Parser changes apply to new events only. |
What's next
Air-Gapped Deployment
Run nano inside a disconnected network with zero egress, a signed image tarball, offline content and AI, and an offline license.
nanodac CLI
Manage nano detections as version-controlled YAML with @nano-rs/dac-cli — validate, test, diff, and sync detection rules from your terminal or CI