74c795eaa9
rename() needs write permission on the DIRECTORY; without it rotation fails silently while appends succeed, growing log.txt unbounded. Documents the correct ownership/mode, the health check, and the Nov 2021 - Jul 2026 production incident (945MB log.txt filled the 15GB disk and truncated a Solr reindex). Also notes that these logs contain raw authenticate() passwords and must be treated as secrets.
55 lines
2.2 KiB
Markdown
55 lines
2.2 KiB
Markdown
# php-bsrutils (`bsr/utils`)
|
|
|
|
Shared utilities for the Callio API family: `Configuration`, `Logger`,
|
|
`FileSystem`, `WhichEnv`. Consumed by `php-callioapi`, `bsr/webservice`,
|
|
`bsr/db`.
|
|
|
|
## Logger
|
|
|
|
Request/diagnostic logger writing plain-text lines to the file configured as
|
|
`log.file` (see `Configuration`). Used by `bsr/webservice` to log every API
|
|
call as:
|
|
|
|
```
|
|
<ip> - [<date>] - <status> - <ms> - <func>(<params>)
|
|
```
|
|
|
|
### Built-in daily rotation — directory must be writable by the PHP user
|
|
|
|
The Logger rotates its own file: on the first write after midnight it renames
|
|
`log.txt` → `log.txt.2` (shifting older files up) and keeps roughly ten days
|
|
(`log.txt.2` … `log.txt.9`; higher numbers are deleted). There is **no
|
|
logrotate involvement** — do not add a logrotate entry for these files, it
|
|
would race the built-in rotation.
|
|
|
|
**Critical operational requirement:** `rename()` needs *write permission on
|
|
the log directory*, not just the file. The PHP process (typically `www-data`)
|
|
can happily keep appending to a `log.txt` it owns while every rotation
|
|
attempt silently fails, because the directory denies it — PHP's `rename()`
|
|
warning is not surfaced anywhere.
|
|
|
|
Known real-world failure (production `callioapi`, Nov 2021 → Jul 2026): the
|
|
log directory was owned `guillermo:users` mode `755`, so `www-data` could not
|
|
rename. Rotation died silently and `log.txt` grew to ~945 MB, eventually
|
|
filling the 15 GB disk and truncating a Solr reindex. The rotated-file dates
|
|
freeze at the moment the directory permissions broke — that is the telltale
|
|
sign to look for.
|
|
|
|
Correct setup (matches the vhosts where rotation works):
|
|
|
|
```sh
|
|
chown <deploy-user>:www-data /var/www/<vhost>/log
|
|
chmod g+w /var/www/<vhost>/log
|
|
```
|
|
|
|
Health check: `ls /var/www/<vhost>/log` — if `log.txt.2`'s mtime is older
|
|
than yesterday while `log.txt` keeps growing, rotation is broken; check the
|
|
directory permissions first.
|
|
|
|
### Security note
|
|
|
|
`bsr/webservice` logs every API call **with raw parameters**, which for
|
|
`authenticate(user, password)` means plaintext passwords end up in these
|
|
files. Treat the log directory as secret-bearing: never make it
|
|
world-readable, and scrub/redact before copying logs elsewhere.
|