OpenVPN:Raspberry Pi Auto Connect - Revision history

Josh: Major update - troubleshooting guide: Raspberry Pi OpenVPN Auto-Connect Setup (44 sections)

2026-01-01T13:44:50Z

Major update - troubleshooting guide: Raspberry Pi OpenVPN Auto-Connect Setup (44 sections)

← Older revision		Revision as of 13:44, 1 January 2026
Line 1:		Line 1:
	~~= Raspberry Pi OpenVPN Auto-Connect Setup =~~

	This guide walks through setting up a Raspberry Pi to automatically connect to the OpenVPN server when it boots. This assumes the Raspberry Pi is being set up from scratch with only the OS installed.		This guide walks through setting up a Raspberry Pi to automatically connect to the OpenVPN server when it boots. This assumes the Raspberry Pi is being set up from scratch with only the OS installed.

Line 144:		Line 142:

	<pre>		<pre>
	= Auto-reconnect settings =		== Auto-reconnect settings ==
	keepalive 10 120		keepalive 10 120
	persist-key		persist-key
Line 197:		Line 195:

	<pre class="lang-bash">		<pre class="lang-bash">
	= Ping the VPN server (adjust IP based on your VPN subnet) =		==== Ping the VPN server (adjust IP based on your VPN subnet) ====
	ping -c 4 10.8.0.1		ping -c 4 10.8.0.1
	</pre>		</pre>
Line 226:		Line 224:

	<pre class="lang-bash">		<pre class="lang-bash">
	= Check service status =		==== Check service status ====
	sudo systemctl status openvpn-client@client.service		sudo systemctl status openvpn-client@client.service

	= Check VPN interface =		== Check VPN interface ==
	ip addr show tun0		ip addr show tun0

	= Check routing =		== Check routing ==
	ip route show		ip route show
	</pre>		</pre>
Line 255:		Line 253:
	<pre class="lang-bash">		<pre class="lang-bash">
	sudo systemctl enable NetworkManager-wait-online.service		sudo systemctl enable NetworkManager-wait-online.service
	# Or for systemd-networkd:		=== Or for systemd-networkd: ===
	sudo systemctl enable systemd-networkd-wait-online.service		sudo systemctl enable systemd-networkd-wait-online.service
	</pre>		</pre>
Line 364:		Line 362:

	<pre>		<pre>
	= Redirect all traffic through VPN (remove or comment this line) =		==== Redirect all traffic through VPN (remove or comment this line) ====
	= redirect-gateway def1 =		== redirect-gateway def1 ==
	</pre>		</pre>

Josh: Major update - troubleshooting guide: Raspberry Pi OpenVPN Auto-Connect Setup (36 sections)

2026-01-01T13:28:31Z

Major update - troubleshooting guide: Raspberry Pi OpenVPN Auto-Connect Setup (36 sections)

← Older revision		Revision as of 13:28, 1 January 2026
Line 6:		Line 6:

	* Raspberry Pi with Raspberry Pi OS installed (Raspberry Pi OS Lite or Desktop)		* Raspberry Pi with Raspberry Pi OS installed (Raspberry Pi OS Lite or Desktop)

	* SSH access to the Raspberry Pi (or physical access with keyboard/monitor)		* SSH access to the Raspberry Pi (or physical access with keyboard/monitor)

	* OpenVPN client configuration file (<code>.ovpn</code>) from the server administrator		* OpenVPN client configuration file (<code>.ovpn</code>) from the server administrator

	* Network connectivity on the Raspberry Pi		* Network connectivity on the Raspberry Pi

Line 36:		Line 39:

	* Client certificate		* Client certificate

	* Client private key		* Client private key

	* CA certificate		* CA certificate

	* TLS-Crypt key		* TLS-Crypt key

	* Server connection details		* Server connection details

Line 146:		Line 153:
	'''Explanation''':		'''Explanation''':
	* <code>keepalive 10 120</code>: Sends a ping every 10 seconds, restarts if no response for 120 seconds		* <code>keepalive 10 120</code>: Sends a ping every 10 seconds, restarts if no response for 120 seconds

	* <code>persist-key</code>: Keeps trying to read key files if they're temporarily unavailable		* <code>persist-key</code>: Keeps trying to read key files if they're temporarily unavailable

	* <code>persist-tun</code>: Keeps the TUN/TAP interface open across restarts		* <code>persist-tun</code>: Keeps the TUN/TAP interface open across restarts

	* <code>resolv-retry infinite</code>: Keeps trying to resolve the server hostname if DNS fails		* <code>resolv-retry infinite</code>: Keeps trying to resolve the server hostname if DNS fails

Line 382:		Line 392:

	* Automatically connect to the OpenVPN server on boot		* Automatically connect to the OpenVPN server on boot

	* Automatically reconnect if the connection drops		* Automatically reconnect if the connection drops

	* Maintain the VPN connection as long as the device is powered on		* Maintain the VPN connection as long as the device is powered on

	'''Key Files''':		'''Key Files''':
	* Configuration: <code>/etc/openvpn/client/client.conf</code>		* Configuration: <code>/etc/openvpn/client/client.conf</code>

	* Service: <code>openvpn-client@client.service</code>		* Service: <code>openvpn-client@client.service</code>

	* Logs: <code>journalctl -u openvpn-client@client.service</code>		* Logs: <code>journalctl -u openvpn-client@client.service</code>

	'''Useful Commands''':		'''Useful Commands''':
	* Start VPN: <code>sudo systemctl start openvpn-client@client.service</code>		* Start VPN: <code>sudo systemctl start openvpn-client@client.service</code>

	* Stop VPN: <code>sudo systemctl stop openvpn-client@client.service</code>		* Stop VPN: <code>sudo systemctl stop openvpn-client@client.service</code>

	* Restart VPN: <code>sudo systemctl restart openvpn-client@client.service</code>		* Restart VPN: <code>sudo systemctl restart openvpn-client@client.service</code>

	* Check Status: <code>sudo systemctl status openvpn-client@client.service</code>		* Check Status: <code>sudo systemctl status openvpn-client@client.service</code>

	* View Logs: <code>sudo journalctl -u openvpn-client@client.service -f</code>		* View Logs: <code>sudo journalctl -u openvpn-client@client.service -f</code>

Josh: Added troubleshooting guide: Raspberry Pi OpenVPN Auto-Connect Setup

2026-01-01T13:16:13Z

Added troubleshooting guide: Raspberry Pi OpenVPN Auto-Connect Setup

New page

= Raspberry Pi OpenVPN Auto-Connect Setup =

This guide walks through setting up a Raspberry Pi to automatically connect to the OpenVPN server when it boots. This assumes the Raspberry Pi is being set up from scratch with only the OS installed.

== Prerequisites ==

* Raspberry Pi with Raspberry Pi OS installed (Raspberry Pi OS Lite or Desktop)
* SSH access to the Raspberry Pi (or physical access with keyboard/monitor)
* OpenVPN client configuration file (<code>.ovpn</code>) from the server administrator
* Network connectivity on the Raspberry Pi

== Step 1: Initial System Setup ==

=== 1.1 Update System Packages ===

First, ensure your Raspberry Pi is up to date:

<pre class="lang-bash">
sudo apt update
sudo apt upgrade -y
</pre>

=== 1.2 Install Required Packages ===

Install OpenVPN and other necessary tools:

<pre class="lang-bash">
sudo apt install -y openvpn network-manager-openvpn resolvconf
</pre>

'''Note''': The <code>network-manager-openvpn</code> package is optional but can be useful for GUI-based management. The <code>resolvconf</code> package helps manage DNS resolution when connected to the VPN.

== Step 2: Obtain OpenVPN Configuration File ==

You need to obtain the <code>.ovpn</code> configuration file for your Raspberry Pi from the server administrator. This file contains:

* Client certificate
* Client private key
* CA certificate
* TLS-Crypt key
* Server connection details

'''Common file locations on the server''': <code>/root/<client-name>.ovpn</code>

=== 2.1 Transfer Configuration File to Raspberry Pi ===

You can transfer the file using one of these methods:

'''Method 1: Using SCP (from your local machine)'''

<pre class="lang-bash">
scp <username>@<raspberry-pi-ip>:/path/to/client.ovpn ~/client.ovpn
</pre>

'''Method 2: Using SFTP'''

<pre class="lang-bash">
sftp <username>@<raspberry-pi-ip>
put /path/to/client.ovpn ~/client.ovpn
exit
</pre>

'''Method 3: Copy and paste (if you have the file contents)'''

Create the file manually:

<pre class="lang-bash">
nano ~/client.ovpn
</pre>

Paste the contents and save (Ctrl+X, then Y, then Enter).

== Step 3: Install Configuration File ==

=== 3.1 Copy Configuration to System Directory ===

Copy the <code>.ovpn</code> file to <code>/etc/openvpn/client/</code>:

<pre class="lang-bash">
sudo cp ~/client.ovpn /etc/openvpn/client/client.conf
</pre>

'''Note''': OpenVPN looks for <code>.conf</code> files in <code>/etc/openvpn/client/</code>, so we rename it to <code>client.conf</code>. If you have multiple VPN configurations, you can use descriptive names like <code>raspberry-pi.conf</code>.

=== 3.2 Set Proper Permissions ===

Ensure the configuration file has the correct permissions:

<pre class="lang-bash">
sudo chmod 600 /etc/openvpn/client/client.conf
sudo chown root:root /etc/openvpn/client/client.conf
</pre>

== Step 4: Configure Auto-Start on Boot ==

=== 4.1 Enable OpenVPN Service ===

Enable the OpenVPN client service to start automatically on boot:

<pre class="lang-bash">
sudo systemctl enable openvpn-client@client.service
</pre>

'''Note''': The service name format is <code>openvpn-client@<config-name>.service</code>, where <code><config-name></code> is the name of your <code>.conf</code> file without the extension. Since we named it <code>client.conf</code>, the service is <code>openvpn-client@client.service</code>.

=== 4.2 Start the Service ===

Start the OpenVPN service immediately (without rebooting):

<pre class="lang-bash">
sudo systemctl start openvpn-client@client.service
</pre>

=== 4.3 Verify Service Status ===

Check that the service is running:

<pre class="lang-bash">
sudo systemctl status openvpn-client@client.service
</pre>

You should see output indicating the service is active and running.

== Step 5: Configure Auto-Reconnect ==

OpenVPN should automatically reconnect if the connection drops, but we can enhance this by modifying the configuration file.

=== 5.1 Add Auto-Reconnect Options ===

Edit the configuration file:

<pre class="lang-bash">
sudo nano /etc/openvpn/client/client.conf
</pre>

Add these lines at the end of the file (if they're not already present):

<pre>
= Auto-reconnect settings =
keepalive 10 120
persist-key
persist-tun
resolv-retry infinite
</pre>

'''Explanation''':
* <code>keepalive 10 120</code>: Sends a ping every 10 seconds, restarts if no response for 120 seconds
* <code>persist-key</code>: Keeps trying to read key files if they're temporarily unavailable
* <code>persist-tun</code>: Keeps the TUN/TAP interface open across restarts
* <code>resolv-retry infinite</code>: Keeps trying to resolve the server hostname if DNS fails

Save and exit (Ctrl+X, then Y, then Enter).

=== 5.2 Restart the Service ===

Apply the changes:

<pre class="lang-bash">
sudo systemctl restart openvpn-client@client.service
</pre>

== Step 6: Verify Connection ==

=== 6.1 Check VPN Interface ===

Verify that the VPN interface (typically <code>tun0</code>) is up:

<pre class="lang-bash">
ip addr show tun0
</pre>

You should see output showing the VPN interface with an IP address in the VPN subnet (e.g., <code>10.8.0.x</code>).

=== 6.2 Check Routing ===

Verify that traffic is being routed through the VPN:

<pre class="lang-bash">
ip route show
</pre>

You should see routes indicating traffic is going through the <code>tun0</code> interface.

=== 6.3 Test Connectivity ===

Test connectivity to the VPN server:

<pre class="lang-bash">
= Ping the VPN server (adjust IP based on your VPN subnet) =
ping -c 4 10.8.0.1
</pre>

=== 6.4 Check OpenVPN Logs ===

View OpenVPN logs to ensure everything is working:

<pre class="lang-bash">
sudo journalctl -u openvpn-client@client.service -f
</pre>

Press Ctrl+C to exit the log viewer.

== Step 7: Test Auto-Start on Boot ==

=== 7.1 Reboot the Raspberry Pi ===

Reboot to verify the VPN connects automatically:

<pre class="lang-bash">
sudo reboot
</pre>

=== 7.2 Verify After Reboot ===

After the Raspberry Pi reboots, SSH back in and verify:

<pre class="lang-bash">
= Check service status =
sudo systemctl status openvpn-client@client.service

= Check VPN interface =
ip addr show tun0

= Check routing =
ip route show
</pre>

== Troubleshooting ==

=== VPN Not Connecting on Boot ===

If the VPN doesn't connect automatically on boot, check:

# '''Service Status''':
<pre class="lang-bash">
sudo systemctl status openvpn-client@client.service
</pre>

# '''Service Logs''':
<pre class="lang-bash">
sudo journalctl -u openvpn-client@client.service -n 50
</pre>

# '''Network Timing''': The VPN service might be starting before the network is ready. Check if <code>network-online.target</code> is enabled:
<pre class="lang-bash">
sudo systemctl enable NetworkManager-wait-online.service
# Or for systemd-networkd:
sudo systemctl enable systemd-networkd-wait-online.service
</pre>

=== VPN Interface Not Appearing ===

If <code>tun0</code> doesn't appear:

# '''Check if OpenVPN is running''':
<pre class="lang-bash">
ps aux | grep openvpn
</pre>

# '''Check configuration file syntax''':
<pre class="lang-bash">
sudo openvpn --config /etc/openvpn/client/client.conf --verb 4
</pre>

# '''Verify TUN/TAP module is loaded''':
<pre class="lang-bash">
lsmod | grep tun
</pre>

If not loaded, load it:
<pre class="lang-bash">
sudo modprobe tun
</pre>

=== DNS Resolution Issues ===

If DNS isn't working after connecting:

# '''Check DNS settings''':
<pre class="lang-bash">
cat /etc/resolv.conf
</pre>

# '''Install resolvconf if not already installed''':
<pre class="lang-bash">
sudo apt install resolvconf
</pre>

# '''Restart the OpenVPN service''':
<pre class="lang-bash">
sudo systemctl restart openvpn-client@client.service
</pre>

=== Connection Drops Frequently ===

If the connection drops frequently:

# '''Check network stability''':
<pre class="lang-bash">
ping -c 10 <vpn-server-ip>
</pre>

# '''Review keepalive settings''' in the configuration file

# '''Check firewall rules''' that might be blocking OpenVPN traffic

# '''Review server logs''' on the VPN server for any issues

=== Permission Denied Errors ===

If you see permission errors:

# '''Verify file permissions''':
<pre class="lang-bash">
ls -l /etc/openvpn/client/client.conf
</pre>

Should show <code>-rw-------</code> (600) and owned by <code>root:root</code>

# '''Check directory permissions''':
<pre class="lang-bash">
ls -ld /etc/openvpn/client/
</pre>

== Advanced Configuration ==

=== Multiple VPN Configurations ===

If you need multiple VPN configurations:

# Copy additional <code>.ovpn</code> files to <code>/etc/openvpn/client/</code> with different names:
<pre class="lang-bash">
sudo cp ~/vpn2.ovpn /etc/openvpn/client/vpn2.conf
</pre>

# Enable the additional service:
<pre class="lang-bash">
sudo systemctl enable openvpn-client@vpn2.service
sudo systemctl start openvpn-client@vpn2.service
</pre>

=== Custom DNS Servers ===

To use custom DNS servers when connected to the VPN, add to your configuration file:

<pre>
dhcp-option DNS 8.8.8.8
dhcp-option DNS 8.8.4.4
</pre>

=== Route Specific Traffic Through VPN ===

To route only specific traffic through the VPN (split tunneling), modify the configuration file to remove or comment out:

<pre>
= Redirect all traffic through VPN (remove or comment this line) =
= redirect-gateway def1 =
</pre>

Then add specific routes:

<pre>
route 192.168.1.0 255.255.255.0
</pre>

== Security Considerations ==

# '''Protect Configuration Files''': The <code>.ovpn</code> file contains private keys. Ensure it has restrictive permissions (600) and is owned by root.

# '''Regular Updates''': Keep your Raspberry Pi OS and OpenVPN client updated:
<pre class="lang-bash">
sudo apt update && sudo apt upgrade -y
</pre>

# '''Firewall''': Consider configuring a firewall (ufw) to allow only necessary traffic.

# '''Monitor Logs''': Regularly check OpenVPN logs for any suspicious activity.

== Summary ==

After completing these steps, your Raspberry Pi will:

* Automatically connect to the OpenVPN server on boot
* Automatically reconnect if the connection drops
* Maintain the VPN connection as long as the device is powered on

'''Key Files''':
* Configuration: <code>/etc/openvpn/client/client.conf</code>
* Service: <code>openvpn-client@client.service</code>
* Logs: <code>journalctl -u openvpn-client@client.service</code>

'''Useful Commands''':
* Start VPN: <code>sudo systemctl start openvpn-client@client.service</code>
* Stop VPN: <code>sudo systemctl stop openvpn-client@client.service</code>
* Restart VPN: <code>sudo systemctl restart openvpn-client@client.service</code>
* Check Status: <code>sudo systemctl status openvpn-client@client.service</code>
* View Logs: <code>sudo journalctl -u openvpn-client@client.service -f</code>

[[Category:Documentation]]
[[Category:Documentation/OpenVPN]]