v0.16.1 doc update
This commit is contained in:
+114
-63
@@ -1,49 +1,62 @@
|
||||
# Installation Guide
|
||||
|
||||
LogWisp installation and service configuration for Linux and FreeBSD systems.
|
||||
## Requirements
|
||||
|
||||
## Installation Methods
|
||||
- **Operating systems**: Linux (kernel 6.10+), FreeBSD (14.0+)
|
||||
- **Architecture**: amd64
|
||||
- **Go**: 1.26 or newer, to build from source
|
||||
|
||||
### Pre-built Binaries
|
||||
|
||||
Download the latest release binary for your platform and install to `/usr/local/bin`:
|
||||
## Building from Source
|
||||
|
||||
```bash
|
||||
# Linux amd64
|
||||
wget https://github.com/yourusername/logwisp/releases/latest/download/logwisp-linux-amd64
|
||||
chmod +x logwisp-linux-amd64
|
||||
sudo mv logwisp-linux-amd64 /usr/local/bin/logwisp
|
||||
|
||||
# FreeBSD amd64
|
||||
fetch https://github.com/yourusername/logwisp/releases/latest/download/logwisp-freebsd-amd64
|
||||
chmod +x logwisp-freebsd-amd64
|
||||
sudo mv logwisp-freebsd-amd64 /usr/local/bin/logwisp
|
||||
```
|
||||
|
||||
### Building from Source
|
||||
|
||||
Requires Go 1.24 or newer:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/logwisp.git
|
||||
git clone https://github.com/lixenwraith/logwisp.git
|
||||
cd logwisp
|
||||
go build -o logwisp ./src/cmd/logwisp
|
||||
sudo install -m 755 logwisp /usr/local/bin/
|
||||
make
|
||||
sudo make install # installs to $PREFIX/bin, default /usr/local/bin
|
||||
```
|
||||
|
||||
### Go Install Method
|
||||
The Makefile works with both GNU make and BSD make. Targets:
|
||||
|
||||
Install directly using Go (version information will not be embedded):
|
||||
| Target | Effect |
|
||||
|--------|--------|
|
||||
| `make` / `make build` | Build `bin/logwisp` with version metadata |
|
||||
| `make dev` | Build with the race detector enabled |
|
||||
| `make install` | Install the binary to `$(PREFIX)/bin` (default `/usr/local`) |
|
||||
| `make uninstall` | Intended to remove the installed binary — currently broken: it expands to `$(BINDIR)/bin/logwisp` instead of `$(BINDIR)/logwisp`, so it removes nothing. Delete the binary by hand |
|
||||
| `make clean` | Remove the built binary |
|
||||
| `make version` | Print the version, commit, and build time that would be embedded |
|
||||
|
||||
Version, commit hash, and build time are injected via `-ldflags` from `git
|
||||
describe` and `git rev-parse`. A plain `go build` produces a working binary that
|
||||
reports `dev` for all three:
|
||||
|
||||
```bash
|
||||
go install github.com/yourusername/logwisp/cmd/logwisp@latest
|
||||
go build -o bin/logwisp ./cmd/logwisp
|
||||
```
|
||||
|
||||
## Service Configuration
|
||||
`go install github.com/lixenwraith/logwisp/cmd/logwisp@latest` also works, with
|
||||
the same loss of version metadata.
|
||||
|
||||
## Configuration
|
||||
|
||||
Copy the annotated reference configuration and edit it:
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /etc/logwisp
|
||||
sudo cp config/logwisp.toml /etc/logwisp/logwisp.toml
|
||||
```
|
||||
|
||||
LogWisp searches, in order: `-c <path>`, `--config=<path>`,
|
||||
`$LOGWISP_CONFIG_DIR`/`$LOGWISP_CONFIG_FILE`, `~/.config/logwisp/logwisp.toml`,
|
||||
`./logwisp.toml`. See [Configuration](configuration.md).
|
||||
|
||||
## Running as a Service
|
||||
|
||||
LogWisp has no daemon mode; run it in the foreground under a supervisor.
|
||||
|
||||
### Linux (systemd)
|
||||
|
||||
Create systemd service file `/etc/systemd/system/logwisp.service`:
|
||||
`/etc/systemd/system/logwisp.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
@@ -55,30 +68,47 @@ Type=simple
|
||||
User=logwisp
|
||||
Group=logwisp
|
||||
ExecStart=/usr/local/bin/logwisp -c /etc/logwisp/logwisp.toml
|
||||
ExecReload=/bin/kill -HUP $MAINPID
|
||||
Restart=on-failure
|
||||
RestartSec=10
|
||||
WorkingDirectory=/var/lib/logwisp
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
WorkingDirectory=/var/lib/logwisp
|
||||
|
||||
# Hardening
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
ProtectSystem=strict
|
||||
ProtectHome=true
|
||||
ReadWritePaths=/var/log/logwisp /var/lib/logwisp
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Setup service user and directories:
|
||||
`ExecReload` gives you `systemctl reload logwisp` for configuration and
|
||||
certificate rotation without dropping the process.
|
||||
|
||||
If a pipeline binds a port below 1024, add
|
||||
`AmbientCapabilities=CAP_NET_BIND_SERVICE` rather than running as root.
|
||||
|
||||
Setup:
|
||||
|
||||
```bash
|
||||
sudo useradd -r -s /bin/false logwisp
|
||||
sudo useradd -r -s /usr/sbin/nologin logwisp
|
||||
sudo mkdir -p /etc/logwisp /var/lib/logwisp /var/log/logwisp
|
||||
sudo chown logwisp:logwisp /var/lib/logwisp /var/log/logwisp
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable logwisp
|
||||
sudo systemctl start logwisp
|
||||
sudo systemctl enable --now logwisp
|
||||
```
|
||||
|
||||
The service account needs **read** access to every directory a `file` source
|
||||
watches and **write** access to every directory a `file` sink or
|
||||
`logging.file` writes to.
|
||||
|
||||
### FreeBSD (rc.d)
|
||||
|
||||
Create rc script `/usr/local/etc/rc.d/logwisp`:
|
||||
`/usr/local/etc/rc.d/logwisp`:
|
||||
|
||||
```sh
|
||||
#!/bin/sh
|
||||
@@ -92,8 +122,9 @@ Create rc script `/usr/local/etc/rc.d/logwisp`:
|
||||
name="logwisp"
|
||||
rcvar="${name}_enable"
|
||||
pidfile="/var/run/${name}.pid"
|
||||
command="/usr/local/bin/logwisp"
|
||||
command_args="-c /usr/local/etc/logwisp/logwisp.toml"
|
||||
procname="/usr/local/bin/logwisp"
|
||||
command="/usr/sbin/daemon"
|
||||
command_args="-p ${pidfile} -f ${procname} -c /usr/local/etc/logwisp/logwisp.toml"
|
||||
|
||||
load_rc_config $name
|
||||
: ${logwisp_enable:="NO"}
|
||||
@@ -101,7 +132,7 @@ load_rc_config $name
|
||||
run_rc_command "$1"
|
||||
```
|
||||
|
||||
Setup service:
|
||||
Setup:
|
||||
|
||||
```bash
|
||||
sudo chmod +x /usr/local/etc/rc.d/logwisp
|
||||
@@ -112,45 +143,66 @@ sudo sysrc logwisp_enable="YES"
|
||||
sudo service logwisp start
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
Standard installation directories:
|
||||
## Directory Layout
|
||||
|
||||
| Purpose | Linux | FreeBSD |
|
||||
|---------|-------|---------|
|
||||
| Binary | `/usr/local/bin/logwisp` | `/usr/local/bin/logwisp` |
|
||||
| Configuration | `/etc/logwisp/` | `/usr/local/etc/logwisp/` |
|
||||
| Working Directory | `/var/lib/logwisp/` | `/var/db/logwisp/` |
|
||||
| Log Files | `/var/log/logwisp/` | `/var/log/logwisp/` |
|
||||
| PID File | `/var/run/logwisp.pid` | `/var/run/logwisp.pid` |
|
||||
| TLS material | `/etc/logwisp/tls/` | `/usr/local/etc/logwisp/tls/` |
|
||||
| Working directory | `/var/lib/logwisp/` | `/var/db/logwisp/` |
|
||||
| Application logs | `/var/log/logwisp/` | `/var/log/logwisp/` |
|
||||
|
||||
## Post-Installation Verification
|
||||
Key files should be mode `0600` and owned by the service account.
|
||||
|
||||
Verify the installation:
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# Check version
|
||||
logwisp version
|
||||
logwisp --version
|
||||
|
||||
# Test configuration
|
||||
logwisp -c /etc/logwisp/logwisp.toml --disable-status-reporter
|
||||
# start in the foreground with debug logging and watch pipelines come up
|
||||
logwisp -c /etc/logwisp/logwisp.toml --logging.level=debug --logging.output=stderr
|
||||
|
||||
# Check service status (Linux)
|
||||
sudo systemctl status logwisp
|
||||
|
||||
# Check service status (FreeBSD)
|
||||
sudo service logwisp status
|
||||
sudo systemctl status logwisp # Linux
|
||||
sudo service logwisp status # FreeBSD
|
||||
```
|
||||
|
||||
## Uninstallation
|
||||
Expect `Created source instance`, `Created sink instance`, and
|
||||
`Starting pipeline` for each configured pipeline. There is no validate-only
|
||||
mode; see [Operations](operations.md#checking-a-configuration).
|
||||
|
||||
## Test Scripts
|
||||
|
||||
Two end-to-end scripts under `test/` build multi-node chain topologies against a
|
||||
local build:
|
||||
|
||||
```bash
|
||||
make
|
||||
./test/chain-test.sh --auto # two independent relay pipelines
|
||||
./test/chain-aggregate-test.sh --auto # fan-in: both edges into one pipeline
|
||||
```
|
||||
|
||||
Without `--auto` they run the relay in the foreground for interactive
|
||||
inspection. They need bash 5+, coreutils, and curl, and they bind ports
|
||||
15801–15804. Generated configuration and logs land in `test/run/`.
|
||||
|
||||
> Two of the three `--auto` assertions currently report `FAIL` against a
|
||||
> working build. They grep the sink output for `"source":"edge-tcp/` and
|
||||
> `"node":"edge-http"`, but the JSON formatter emits the `node/source` label
|
||||
> under the key `trace`. The transport itself is healthy — the
|
||||
> `total_processed` assertion passes and the streamed entries carry
|
||||
> `"trace":"edge-tcp/random_rand"` as expected. Until the assertions are
|
||||
> updated, verify the streams by eye with `nc 127.0.0.1 15803` and
|
||||
> `curl -sN http://127.0.0.1:15804/stream`.
|
||||
|
||||
## Uninstall
|
||||
|
||||
### Linux
|
||||
|
||||
```bash
|
||||
sudo systemctl stop logwisp
|
||||
sudo systemctl disable logwisp
|
||||
sudo rm /usr/local/bin/logwisp
|
||||
sudo rm /etc/systemd/system/logwisp.service
|
||||
sudo systemctl disable --now logwisp
|
||||
sudo rm /usr/local/bin/logwisp /etc/systemd/system/logwisp.service
|
||||
sudo systemctl daemon-reload
|
||||
sudo rm -rf /etc/logwisp /var/lib/logwisp /var/log/logwisp
|
||||
sudo userdel logwisp
|
||||
```
|
||||
@@ -160,8 +212,7 @@ sudo userdel logwisp
|
||||
```bash
|
||||
sudo service logwisp stop
|
||||
sudo sysrc -x logwisp_enable
|
||||
sudo rm /usr/local/bin/logwisp
|
||||
sudo rm /usr/local/etc/rc.d/logwisp
|
||||
sudo rm /usr/local/bin/logwisp /usr/local/etc/rc.d/logwisp
|
||||
sudo rm -rf /usr/local/etc/logwisp /var/db/logwisp /var/log/logwisp
|
||||
sudo pw userdel logwisp
|
||||
```
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user