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

1. 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 /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.
   Refer to the CircleCI Artifacts documentation for guidance on uploading artifacts.
    

2. User tee to improve visibility

   Redirecting 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.
    

3. 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 (<code>4</code> in the example above) based on your needs. Higher values provide more detailed logs, which can be useful for diagnosing complex issues.
    

4. Optimize OpenVPN retry behaviour
   Modify OpenVPN’s command-line arguments to improve its retry behavior and avoid premature failures. For example:
   
   --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.
    
5. Extend the timeout for no output
   
   If the VPN connection process takes longer than 10 minutes (the default timeout for no output), increase the <code>no_output_timeout</code> value in your CircleCI configuration. Refer to the CircleCI support article "Build has Hit Timeout Limit" for detailed instructions.
    

Final Recommended commands

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