diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 98 |
1 files changed, 96 insertions, 2 deletions
@@ -13,13 +13,108 @@ The DTail binary operates in either client or server mode. The DTail server must  -If you like what you see [look here for more examples](doc/examples.md)! You can also read through the [DTail Mimecast Engineering Blog Post](https://medium.com/mimecast-engineering/dtail-the-distributed-log-tail-program-79b8087904bb). There is also a GitHub Page at [dtail.dev](https://dtail.dev). +If you like what you see [look here for more examples](doc/examples.md)! You can also read through the [DTail Mimecast Engineering Blog Post](https://medium.com/mimecast-engineering/dtail-the-distributed-log-tail-program-79b8087904bb). Installation and Usage ====================== * Check out the [DTail Documentation](doc/index.md) +Interactive Query Reload +======================== + +`dtail`, `dgrep`, `dcat`, and `dmap` accept `--interactive-query` to keep the +current run open and listen for control commands on the controlling TTY. + +Available control commands: + +* `:reload <flags>` apply a new workload by reusing the current session when the + active servers support it +* `:show` print the current interactive state, including capability counts +* `:help` print the interactive command help text +* `:quit` stop the interactive session + +Reload flags are mode-specific: + +* `dtail` and `dgrep`: `--grep`/`--regex`, `--before`, `--after`, `--max`, + `--invert`, plus shared flags such as `--files`, `--plain`, `--quiet`, and + `--timeout` +* `dmap`, and query-driven `dtail`: `--query` plus the shared flags above +* `dcat`: shared flags such as `--files`, `--plain`, `--quiet`, and `--timeout` + +Examples: + +```bash +dtail --servers app01 --files /var/log/app.log --grep ERROR --interactive-query +# then type: +:reload --grep WARN + +dgrep --servers app01 --files /var/log/app.log --grep ERROR --interactive-query +# then type: +:reload --grep WARN --before 2 --after 3 + +dmap --servers app01 --files /var/log/app.log \ + --query 'from STATS select count($line) group by hostname' \ + --interactive-query +# then type: +:reload --query "from STATS select count($line),avg(latency) group by hostname" +``` + +Compatibility and session reuse: + +* On startup, an interactive client first tries `SESSION START` when the remote + side advertises the `query-update-v1` capability +* If a server is older or does not advertise that capability, startup falls + back to the legacy command stream automatically, so mixed-version + client/server combinations still run the original workload normally +* Live `:reload` updates require every active server to advertise + `query-update-v1`; otherwise the reload is rejected and the current workload + keeps running unchanged +* On capable servers, DTail reuses the existing SSH session and sends + `SESSION UPDATE` messages instead of reconnecting +* Every successful reload advances a generation boundary; late output from the + previous workload is dropped so stale matches do not leak into the new result + stream + +Auth-Key Fast Reconnect +======================= + +DTail supports an optional SSH auth optimization for repeated reconnects. +After a normal authenticated SSH session is established, the client can +register a local public key with `dserver` using an `AUTHKEY` command. The +server stores this key in memory only and checks it before `authorized_keys` +on subsequent connections. + +This reduces repeated hardware-token signing (for example YubiKey-backed SSH +agent keys) while keeping transparent fallback to normal SSH authentication. + +Client options: + +* `--auth-key-path` path to the private key to offer first and register + (default: `~/.ssh/id_rsa`) +* `--no-auth-key` disable auth-key registration/fast-path and use normal SSH + behavior only + +Server configuration (`dtail.json`): + +```json +{ + "Server": { + "AuthKeyEnabled": true, + "AuthKeyTTLSeconds": 86400, + "AuthKeyMaxPerUser": 5 + } +} +``` + +Security notes: + +* Registered keys are stored in memory only (no disk persistence) +* Registration is accepted only over an already-authenticated session +* TTL expiry and per-user key limits bound key lifetime and memory growth +* If fast-path auth is unavailable (restart/expiry/mismatch), DTail falls back + to normal SSH auth automatically + More ==== @@ -34,4 +129,3 @@ Credits * Thank you [Mimecast](https://www.mimecast.com) for supporting this Open-Source project. * Thank you to **Vlad-Marian Marian** for creating the DTail (dog) logo. * The Gopher was generated at https://gopherize.me -* The animated Gifs were created using `asciinema` with `asciicast2gif`. Check out [how this was done](./doc/asciinema/README.md) for more information. |