Did the OpenVPN up script run too early, or was it never ready?

The up script runs, exits zero, and the task inside it fails to reach a private service that works perfectly two seconds later from a terminal. The instinct is timing, and the usual repair is a sleep, which hides the race without understanding it. The more useful reading is that "up" names a hook, not a readiness guarantee. It fires when the tunnel device is configured, which is earlier than routes, DNS, and certainly earlier than any application behind the tunnel.

The shell test succeeded because it ran after everything settled. The hook ran at one specific moment.

Where up sits in the startup order

OpenVPN configures the tunnel device and then runs the up hook. Route installation is a later stage, and it has its own hook, which is why a route-dependent task placed in up can see a device with no useful path. Place route work in route-up and the timing problem usually disappears.

The manual documents this ordering and the environment each hook receives. That ordering is the whole explanation for the classic "works from my shell" report, and it is also why the same script can pass on one machine and fail on another with a slower route stage. Neither result says anything about the quality of the script.

DNS and application readiness come later still. Even installed routes are not proof that the far endpoint is listening, that a name resolves, or that a desktop session exists for a user-scoped task.

What the hook actually inherits

A hook runs under the account and environment of the OpenVPN process, which is not the same as your interactive shell. It may lack a user's session bus, a desktop environment, or a credential that is unlocked only at login. Write down which of those the task actually needs.

That matters for tasks that look like networking but depend on a user context: mounting a share with a user credential, setting a per-user proxy, or configuring a printer. A privileged tunnel hook is the wrong place for them, and no amount of waiting fixes a missing session.

When a task fails in a hook, record the account, the environment, and the first operation that failed. That separates premature timing from a permission or context problem, and the two have completely different repairs. Guessing between them is how a five-minute fix becomes an afternoon.

Why adding a sleep is not a readiness check

A sleep delays the script and shifts the race window. On a fast day the task succeeds; on a slow day it fails again, and the failure becomes harder to reproduce because the delay appears to work. A delay that only works under light load is a coincidence, not a repair.

If the dependency is a route, use the hook that corresponds to route installation. If the dependency is a service behind the tunnel, use a bounded check that waits for that specific condition and fails clearly when it never arrives.

Keep the failure explicit. A hook that exits zero while its actual work failed is worse than a hook that fails, because the service manager records a success and nobody looks again. A log line from the script itself is the cheapest way to keep that honest.

Cleanup and reconnect deserve the same care

A script that changes shared state needs a matching undo path. Routes, resolver entries, and firewall marks added by a hook should be idempotent and reversible, or a reconnect will stack a second copy on top of the first.

Reconnects can also run hooks more often than a full service start. A persistent interface that re-establishes a session may trigger the up and route-up cycle again, so a script that assumes one execution per boot will eventually misbehave. Count the executions in the log across a day of flapping to see how often it really runs. Then make the script safe to run that many times.

Test the lifecycle that failed, not a later command. Reproduce the boot or the reconnect, watch the hook execute, and confirm the task succeeded at the moment it actually runs. A success from an interactive shell afterwards is evidence about the dependency, not proof that the startup path works.

Name the event each task depends on, then attach it to that event. Everything else is a delay pretending to be a check.