Juju documentation

Debugging hooks

The juju debug-hooks command accepts a unit and an optional list of hooks to debug, which must each be named individually -- or all omitted, causing all hooks to be debugged.

When you start a debug-hooks session, juju creates a tmux session on the machine running the requested unit; while that session persists, all hook executions will be replaced with new windows in that session, which run an environment matching that of the appropriate hook (with one addition: $JUJU_HOOK_NAME) and which are marked as succeeded or failed depending on the exit code of the window.

You can stop debugging by closing all windows in the tmux session.

Debugging early hooks

The install, config-changed, and start hooks often execute quite soon after the unit comes up, making it difficult to start a debug-hooks session in time to intercept them. If you're having difficulties, you can temporarily return an error code from your install hook, and start your session only when the unit reports an error status; then run juju resolved --retry for the affected unit, and go back to the debug-hooks session to interact.

Special considerations

While you're debugging hooks for one unit on a machine, you're blocking execution of all hooks on that machine. This is generally helpful, because you don't want to have to contend with concurrent changes to the machine's software, but you should be aware that multiple debug-hooks sessions for units assigned to the same machine will block one another, and that you can't control relative execution order directly (other than by erroring out of hooks you don't want to run yet, and retrying them later).