When running OpenVPN as part of your CircleCI workflow, you may encounter intermittent issues where the VPN connection times out and the workflow eventually fails after the default timeout period (10 minutes). This guide outlines best practices for troubleshooting these scenarios and increasing visibility into what’s happening during the VPN connection attempt.
Key recommendations for troubleshooting
-
Check the OpenVPN log file
Ensure you are logging OpenVPN’s output to a file for detailed debugging. For example:
sudo openvpn --config /tmp/config.ovpn > /tmp/openvpn.log 2>&1 &
Once the connection attempt has been made, review the contents of
Refer to the CircleCI Artifacts documentation for guidance on uploading artifacts./tmp/openvpn.log
to identify any errors or issues. Uploading this log file as an artifact in CircleCI will allow you to inspect it after the job completes.
-
Use
tee
to improve visibilityRedirecting all output to a log file makes it difficult to see what’s happening in real time. Instead, use the
tee
command to send OpenVPN’s output both to the log file and the job step output:sudo openvpn --config /tmp/config.ovpn 2>&1 | tee /tmp/openvpn.log &
This approach ensures that the OpenVPN output is visible in the CircleCI job step logs, which helps prevent timeout issues caused by a lack of visible output.
-
Increase verbosity for debugging
To gain more insights into what’s happening during the VPN connection, increase OpenVPN’s verbosity level using the
--verb
argument:sudo openvpn --config /tmp/config.ovpn --verb 4 2>&1 | tee /tmp/openvpn.log &
Adjust the verbosity level (
4
in the example above) based on your needs. Higher values provide more detailed logs, which can be useful for diagnosing complex issues. -
Optimize OpenVPN retry behavior
Modify OpenVPN’s command-line arguments to improve its retry behavior and avoid premature failures. For example:
sudo openvpn --config /tmp/config.ovpn --auth-retry nointeract --connect-retry 5 --connect-retry-max 10 2>&1 | tee /tmp/openvpn.log &
-
--auth-retry nointeract
: Ensures OpenVPN will retry authentication without user interaction. -
--connect-retry 5
: Sets the retry interval to 5 seconds. -
--connect-retry-max 10
: Allows up to 10 retries before failing.
-
-
Extend the timeout for no output
If the VPN connection process takes longer than 10 minutes (the default timeout for no output), increase the
no_output_timeout
value in your CircleCI configuration. Refer to the CircleCI support article "Build has Hit Timeout Limit" for detailed instructions.
Final recommended command
Combining all of the above, the following command provides optimal logging, visibility, and retry behavior:
sudo openvpn --config /tmp/config.ovpn --auth-retry nointeract --connect-retry 5 --connect-retry-max 10 2>&1 | tee /tmp/openvpn.log &
Conclusion
By implementing these recommendations, you can improve visibility into your OpenVPN connection attempts and resolve issues related to timeouts. Uploading logs as artifacts and enabling real-time output ensures you have all the necessary information to debug failures effectively.
References
- Reference manual for OpenVPN 2.6
- Support article: Build has Hit Timeout Limit
Comments
Please sign in to leave a comment.