NAME

appjail-logs — Log management for jails

SYNOPSIS

appjail logs

appjail logs list [-eHp] type[/entity[/subtype[/log]]]

appjail logs read type/entity/subtype/log [args ...]

appjail logs remove all

appjail logs remove [-g] type[/entity[/subtype[/log]]]

appjail logs tail type/entity/subtype/log [args ...]

DESCRIPTION

The appjail logs utility lists, reads, or removes logs created by AppJail. The idea is to have a centralized form to manage static log files created by some AppJail subcommands or by AppJail itself.

Having just files scattered around the filesystem doesn't make sense, since you probably want to know which part of AppJail generates them, when, and you also want to keep them for a long time until you don't really need them. AppJail solves this with a very simple approach:

type: Refers to a group of entities with the same meaning in a context.
entity: Refers to an individual in a group.
subtype: Refers to a group of logs with the same meaning in a context.
log: Log filename.

types:

commands: Logs created by commands.
jails: Logs created by jails.
nat: Logs created by commands that perform NAT or are related to this operation.

entity:

The entities can be a network, a jail or something similar. They are dynamic.

subtype:

jails/ENTITY/build: Logs created when building the FreeBSD source tree using the jail subcommand of appjail-update(1).
jails/ENTITY/console: Logs created by the exec.consolelog parameter of jail(8) and configured by appjail-start(8) when not specified by the user in a Template.
jails/ENTITY/container: Logs generated by the background processes in the appjail-oci(1) exec command.
jails/ENTITY/healthcheckers: Logs created by Healthcheckers.
(jails|nat)/ENTITY/(startup-start|startup-stop): Logs created by appjail-startup(1).
releases/ENTITY/build: Same as jails/ENTITY/build but for releases.
commands/ENTITY/output: If ENABLE_LOGGING_OUTPUT is enabled, an AppJail session is logged to this file.
(jails|release)/ENTITY/etcupdate: An appjail-etcupdate(1) session is logged to this file.

log:

Log filename can be changed as desired. See appjail.conf(5) for details.

The options are as follows:

list [-eHp] type[/entity[/subtype[/log]]]

List current logs. You can limit the list by specifying the type, entity, subtype, and log.

-e: Don't escape tab (‘\t’) characters.
-H: Don't display the colums.
-p: Don't print the table in pretty mode.

read type/entity/subtype/log [args ...]

The program specified by the PAGER environment variable is open to read the log you specify. args are passed to this program.

remove all

Removes all logs.

remove [-g] type[/entity[/subtype[/log]]]

Remove a specific recursively.

-g: Use shell glob patterns. This is valid only for log.

tail type/entity/subtype/log [args ...]

tail(1) is open to read the log you specify. args are passed to this program.

If no subcommand is specified, list is used by default.

EXAMPLES

Example 1: List current logs

# appjail logs
TYPE   ENTITY     SUBTYPE        LOG
jails  debian     console        2023-02-03.log
jails  debian     console        2023-02-04.log
jails  debian     startup-start  2023-02-03.log
jails  debian     startup-start  2023-02-04.log
jails  debian     startup-stop   2023-02-03.log
jails  debian     startup-stop   2023-02-04.log
jails  jalias     console        2023-02-03.log
jails  jalias     console        2023-02-04.log
jails  jalias     startup-start  2023-02-03.log
jails  jalias     startup-start  2023-02-04.log
jails  jalias     startup-stop   2023-02-03.log
jails  jalias     startup-stop   2023-02-04.log
jails  jalias46   console        2023-02-03.log
jails  jalias46   console        2023-02-04.log
jails  jalias46   startup-start  2023-02-03.log
jails  jalias46   startup-start  2023-02-04.log
jails  jalias46   startup-stop   2023-02-03.log
jails  jalias46   startup-stop   2023-02-04.log
jails  jalias6    console        2023-02-03.log
jails  jalias6    console        2023-02-04.log
jails  jalias6    startup-start  2023-02-03.log
jails  jalias6    startup-start  2023-02-04.log
jails  jalias6    startup-stop   2023-02-03.log
jails  jalias6    startup-stop   2023-02-04.log
jails  jbridge    console        2023-02-03.log
jails  jbridge    console        2023-02-04.log
jails  jbridge    startup-start  2023-02-04.log
jails  jbridge    startup-stop   2023-02-04.log
jails  jdb        console        2023-02-03.log
jails  jdb        console        2023-02-04.log
jails  jdb        startup-start  2023-02-04.log
jails  jdb        startup-stop   2023-02-03.log
jails  jdb        startup-stop   2023-02-04.log
jails  jdev       console        2023-02-03.log
jails  jdev       console        2023-02-04.log
jails  jdev       startup-start  2023-02-04.log
jails  jdev       startup-stop   2023-02-04.log
jails  jdhcp      console        2023-02-03.log
jails  jdhcp      startup-start  2023-02-04.log
jails  jdhcp      startup-stop   2023-02-03.log
jails  jdisable   console        2023-02-03.log
jails  jdisable   console        2023-02-04.log
jails  jdisable   startup-start  2023-02-04.log
jails  jdisable   startup-stop   2023-02-03.log
jails  jdisable   startup-stop   2023-02-04.log
jails  jds        console        2023-02-03.log
jails  jds        startup-start  2023-02-04.log
jails  jinherit   console        2023-02-03.log
jails  jinherit   console        2023-02-04.log
jails  jinherit   startup-start  2023-02-04.log
jails  jinherit   startup-stop   2023-02-03.log
jails  jinherit   startup-stop   2023-02-04.log
jails  jmultinet  console        2023-02-03.log
jails  jmultinet  startup-stop   2023-02-03.log
jails  jnat       console        2023-02-04.log
jails  jnat       startup-start  2023-02-04.log
jails  jnat       startup-stop   2023-02-04.log
jails  jng        console        2023-02-03.log
jails  jng        startup-start  2023-02-04.log
jails  jnonat     console        2023-02-04.log
jails  jpriv      console        2023-02-04.log
jails  jpub       console        2023-02-04.log
jails  jslaac     console        2023-02-03.log
jails  jslaac     console        2023-02-04.log
jails  jslaac     startup-start  2023-02-04.log
jails  jslaac     startup-stop   2023-02-04.log
jails  jtest      console        2023-02-03.log
jails  jtest      console        2023-02-04.log
jails  jtest      startup-start  2023-02-03.log
jails  jtest      startup-stop   2023-02-03.log
jails  jvirtnet   console        2023-02-03.log
jails  jvnet      console        2023-02-03.log
jails  jvnet      startup-start  2023-02-04.log
jails  jweb       console        2023-02-03.log
jails  jweb       console        2023-02-04.log
jails  jweb       startup-start  2023-02-04.log
jails  jweb       startup-stop   2023-02-03.log
jails  jweb       startup-stop   2023-02-04.log
jails  myjail     console        2023-02-03.log
jails  myjail     console        2023-02-04.log
jails  myjail     startup-start  2023-02-03.log
jails  myjail     startup-start  2023-02-04.log
jails  myjail     startup-stop   2023-02-03.log
jails  myjail     startup-stop   2023-02-04.log
jails  nginx      console        2023-02-04.log
jails  otherjail  console        2023-02-03.log
jails  otherjail  console        2023-02-04.log
jails  otherjail  startup-start  2023-02-03.log
jails  otherjail  startup-start  2023-02-04.log
jails  otherjail  startup-stop   2023-02-03.log
jails  otherjail  startup-stop   2023-02-04.log
jails  php        console        2023-02-04.log
jails  php        console        2023-02-04.log
jails  php        startup-start  2023-02-04.log
jails  php        startup-stop   2023-02-04.log
nat    db         startup-start  2023-02-03.log
nat    db         startup-stop   2023-02-03.log
nat    web        startup-start  2023-02-03.log
nat    web        startup-stop   2023-02-03.log

Example 2: Read a log

The following example reads a log file, but the PAGER environment variable is modified to pass the -R parameter since the log we will read has ANSI colors.

# export PAGER="less -R" appjail logs read jails/php/startup-start/2023-02-04.log
[00:00:05] [ debug ] [php] Locking php ...
[00:00:05] [ info  ] [php] Starting php...
[00:00:10] [ debug ] [php] Using `/usr/local/appjail/jails/php/conf/template.conf` as the template.
[00:00:12] [ debug ] [php] Checking for invalid parameters...
[00:00:14] [ debug ] [php] Writing `/usr/local/appjail/jails/php/conf/template.conf` content to `/usr/local/appjail/cache/tmp/.appjail/appjail.wkX25nfm` ...
[00:00:14] [ debug ] [php] Checking for parameters marked as required...

Example 3: Remove a log

# appjail logs remove jails/jpriv

Example 4: Remove a log using shell glob patterns

# appjail logs remove -g jails/otherjail/startup-start/2023-02-0[34].log

Example 5: Read the last part of a log and wait for new changes

# appjail logs tail jails/jalias6/startup-stop/2023-02-04.log -f

FILES

/var/log/appjail.log: Log file used by the rc(8) script.

AUTHORS

Jesús Daniel Colmenares Oviedo <DtxdF@disroot.org>

CAVEATS

Remove logs in ZFS

When using ZFS as the backend file system appjail logs remove will recursively remove all datasets including all references, such as clones. Be careful.