Hooks

Hooks are small executable files stored in the box file system. They are a lightweight way to make a box do a little setup when it wakes or a little cleanup before it stops. A database daemon is the most common example, but the mechanism is not database-specific.

Paths

⌘Copy/etc/run9_on_start.sh
/etc/run9_on_stop.sh

The files run as root. run9 executes them directly, so include a shebang if they are shell scripts.

Timing

• on_start runs once when run9 wakes the box into a fresh runtime.
• Later box exec or box exec-bg calls that reuse the already-awake box do not rerun on_start.
• Stop the box and wake it again when you want on_start to run on a new runtime.
• on_stop runs during box stop, after run9 cancels active execs and file transfers and before shutdown finishes.

Timeouts

• on_start: 30 seconds
• on_stop: 15 seconds

Failures and timeouts are recorded, but they do not take over the whole box workflow. If hook-managed setup does not appear after wake or stop, start with the diagnostics files before you change the scripts.

Diagnostics

run9 writes the latest on_start and on_stop run records to these files. When a hook-managed service does not come up or shut down the way you expect, this is the first place to look:

⌘Copy/etc/run9-hooks/on_start.json
/etc/run9-hooks/on_start.stdout
/etc/run9-hooks/on_start.stderr
/etc/run9-hooks/on_stop.json
/etc/run9-hooks/on_stop.stdout
/etc/run9-hooks/on_stop.stderr

The .json files summarize the run status. The .stdout and .stderr files keep the captured script output.