|
1 | 1 | # solid-syslog-example |
2 | 2 |
|
3 | | -A worked integration of [SolidSyslog](https://github.com/cososo-ltd/solid-syslog), built up in |
4 | | -stages — from a device with no syslog at all to one whose records are authenticated and encrypted. |
| 3 | +An example of integrating [SolidSyslog](https://github.com/cososo-ltd/solid-syslog) into an |
| 4 | +application that already exists, starting from a realistic device rather than an empty one. |
5 | 5 |
|
6 | | -Each stage is one commit. It says what it does, what it changes, what it gives you, and what it |
7 | | -costs. The costs are measured by the device itself, not estimated. |
| 6 | +Each pull request merged to `main` is one stage of that integration, and each raises the security |
| 7 | +posture of the logging path. A stage states what it changes, what it gives you, and what it costs, |
| 8 | +measured by the device itself rather than estimated. |
8 | 9 |
|
9 | | -It builds on a baseline that simulates the sort of device you might be adding this to, and that |
10 | | -measures itself: see [docs/baseline.md](docs/baseline.md) for what the baseline is, how the |
11 | | -figures are made, and how to run it. |
| 10 | +The purpose is to show the process of integration, the cost of each step and the benefit it brings, |
| 11 | +so that all three can be set against your own threat model when you plan your own. |
12 | 12 |
|
13 | | -## This stage — Right-sized |
| 13 | +The baseline is the sort of device this might be added to: it already networks, mounts a filesystem |
| 14 | +and holds a mutual-TLS session to its broker before any syslog exists. See |
| 15 | +[docs/baseline.md](docs/baseline.md) for what it is, how the figures are made, and how to run it. |
14 | 16 |
|
15 | | -Fit the compile-time sizes to what this device uses, now that every collaborator is in place. |
| 17 | +## Where it ends up |
16 | 18 |
|
17 | | -The message cap comes first, because the ring, the store's record buffer and the formatter frame on |
18 | | -both task stacks all follow it. |
19 | | - |
20 | | -```c |
21 | | -/* app/config/solid_syslog_tunables.h */ |
22 | | -#define SOLIDSYSLOG_MAX_MESSAGE_SIZE 400U |
23 | | - |
24 | | -#define SOLIDSYSLOG_ADDRESS_POOL_SIZE 1U |
25 | | -#define SOLIDSYSLOG_TCP_STREAM_POOL_SIZE 1U |
26 | | -#define SOLIDSYSLOG_STREAM_SENDER_POOL_SIZE 1U |
27 | | -``` |
28 | | -
|
29 | | -The worst case measured here is 345 octets: the four SD-ELEMENTs with both counters at full 32-bit |
30 | | -width and both addresses at fifteen characters, plus a short message. 400 allows for longer messages |
31 | | -on this device. Anything longer is truncated rather than dropped. |
32 | | -
|
33 | | -The pool defaults suit a device running several transports at once. This one runs a single sender |
34 | | -over a single stream to a single destination. |
35 | | -
|
36 | | -The overrides reach the library through `SOLIDSYSLOG_USER_TUNABLES_FILE`, which the library carries |
37 | | -on an INTERFACE target, so Core, the platform packs and this application all compile against the |
38 | | -same values. They change struct sizes, and a build where only some translation units saw them would |
39 | | -disagree about how big those structs are. |
40 | | -
|
41 | | -The ring drops from eight records to four. The store holds a backlog, so the ring only has to absorb |
42 | | -what can be logged while the service task is sending. |
43 | | -
|
44 | | -The task stacks go last, at twice their measured high-water marks rounded up to a whole |
45 | | -`configMINIMAL_STACK_SIZE`. |
46 | | -
|
47 | | -**When you need it.** Once the pipeline is complete. Sizing earlier means sizing against a device |
48 | | -that is still missing collaborators. |
| 19 | +The device logs one RFC 5424 record carrying four SD-ELEMENTs: sequence number and uptime, time |
| 20 | +quality, origin, and a private element naming the protection its own log pipeline is under. The |
| 21 | +record goes to the collector over mutual TLS and is spooled to a local store encrypted with |
| 22 | +AES-256-GCM, so records survive a failed send and a disk that leaves the device gives nothing away. |
49 | 23 |
|
50 | 24 | <!-- STAGE-COST:START (generated by scripts/gen-cost-table.py — do not edit by hand) --> |
51 | 25 |
|
52 | 26 | **Cost above baseline: Flash +13,788 B, RAM +36,048 B.** |
53 | 27 |
|
54 | 28 | <!-- STAGE-COST:END --> |
55 | 29 |
|
56 | | -The full report for this stage — what the device did, every figure, and the self-check — is |
57 | | -committed as [`run-report.md`](run-report.md), and rewritten by every stage. |
| 30 | +Most devices want less than that. The table below prices every stage, and the cheapest row that does |
| 31 | +anything useful — a valid, timestamped record on the wire — is a fraction of it. |
| 32 | + |
| 33 | +**Read it as a sequence.** Start at the Baseline commit and step forward. `git show` on any stage |
| 34 | +gives the diff to apply to your own build, the reasoning behind it, and the measured cost of applying |
| 35 | +it; each stage's run is committed alongside it as [`run-report.md`](run-report.md). Stop where your |
| 36 | +device's threat model does. |
| 37 | + |
| 38 | +This history is rebuilt against each SolidSyslog release, which means a force-push. An existing clone |
| 39 | +or fork needs re-cloning rather than pulling. |
58 | 40 |
|
59 | 41 | ## Every stage |
60 | 42 |
|
|
0 commit comments