Jump to content

* * * * * 2 votes

[How-To] AirVPN via SSL/stunnel on Android 6/7/8

stunnel android openvpn termux ssl howto tutorial

  • Please log in to reply
7 replies to this topic

#1 sheivoko


    Advanced Member

  • Members
  • PipPipPip
  • 207 posts
  • LocationPGP 0x823762e626318758

Posted 07 December 2017 - 08:24 PM


We want to use AirVPN's SSL tunneling mode on Android. SSL tunneling can be very useful, especially to defeat firewalls that block OpenVPN or SSH on a protocol level. We will use the Termux Terminal Emulator to install and run stunnel and OpenVPN for Android to manage the OpenVPN connection.




  • Android 6.0 or newer (5.0 and derivatives thereof such as FireOS should work too)
  • the Android device does not have to be rooted
  • Google PlayStore or the free & open source F-Droid market (recommended)
  • OpenVPN for Android (FOSS)
  • Termux Terminal Emulator (FOSS)
  • stunnel (FOSS), via Termux repository
  • a separate computer to download/edit the config files (entirely optional, but recommended)




Setup instructions

Part 1: generate AirVPN config files

1/7: open AirVPN's config generator. When asked for your operating system, pick Linux:





2/7: Choose servers: Pick a single server. Do not select more than one. Do not select a whole region.





3/7: Protocols: First, enable Advanced Mode:






Now select the SSL mode, port 443:





4/7: Accept Terms of Service and generate the config files:







5/7: Download the generated zip archive:







6/7: unzip AirVPN.zip and open the *.ssl file in a text editor.
find this line:

pid = /tmp/stunnel4.pid


replace it with:

pid = /data/data/com.termux/files/home/stunnel4.pid



7/7: Now transfer the AirVPN folder to your phone's sdcard / main storage directory. For ease of use, don't put it into any subdirectories. Instead, put it into your "root" storage directory, meaning on the same level as your other default Android folders such as Documents, Download and Movies.


Part 2: Install and prepare Android software

1/3: Install OpenVPN for Android, via F-Droid or Play Store. Don't configure anything just yet.
2/3: Install Termux Terminal Emulator, via F-Droid or PlayStore


  • open Termux and run:
  • Allow Termux to access files on your device. (Android 8.0 Oreo users, please read the note at the end of this tutorial).
  • The pkg command is used to install und update software packages. Make sure your base packages are all up to date:
    pkg upgrade
  • now install stunnel:
    pkg install stunnel


3/3: Still in Termux, jump to the AirVPN folder you copied to your phone:

cd storage/shared/AirVPN

The command


should list 3 files:

  • AirVPN*.ovpn (the OpenVPN config file)
  • AirVPN*.ssl  (the stunnel config file)
  • stunnel.crt (stunnel certificate)

Now start stunnel:

stunnel AirVPN*.ssl


  • press the Home button to get out of Termux.
  • Start OpenVPN and import the AirVPN*.ovpn config file
  • Edit your new OpenVPN connection (tap the "pencil button")
  • in the ALLOWED APPS tab, tick the box next to Termux
  • return to OpenVPN's connection list
  • your VPN connection is now configured. A tap on its name will establish the connection.
  • verify that a connection has been established by looking for the log entry Initialization Sequence Completed
  • browse to ipleak.net (or any similar site) to verify that your traffic is indeed routed through the VPN tunnel

Here's a short video, demonstrating the steps above: https://vimeo.com/246306477





Part 3: Usage instructions


Now that everything is configured, future usage will be much easier:


  • open Termux
  • navigate to your AirVPN folder:
  • cd storage/shared/AirVPN
  • now run stunnel:
  • stunnel AirVPN*.ssl
  • Press the Home button and open the OpenVPN app
  • Connect to your VPN profile


Addendum: Tips


  • don't forget to periodically run
    pkg upgrade
    to keep all of Termux' packages, including stunnel, up-to-date.
  • To prevent leaks, it's recommended to let OpenVPN set the default route for both IPv4 and IPv6; as well disabling the LAN bypass:



  • you may want to take a look at Termux:Widget (via F-Droid or Play Store. It's an extension to Termux. If you put your stunnel commands into shell scripts, stored in $HOME/.shortcuts/ , you can launch them via Home screen widgets.
  • enable Termux' extended keyboard by sliding out the left-side menu and long-pressing the KEYBOARD button. This will enable a row of additional keys, such as CTRL, ALT and TAB which are very useful in a terminal environment -- especially the TAB key, allowing you to autocomplete command and path names. Here's a short video on Vimeo demonstrating the extended keyboard.
  • you may generate config files for as many servers as you like, put them into your AirVPN folder on your phone and add the *.ovpn profiles to OpenVPN.
  • you may want to consider AFWall+ for additional firewalling (root required)



Addendum: Caveats


  • Following this tutorial will add the Termux app to OpenVPN's exclusion list, allowing it connect to the VPN server. But this also means that anything else you may do via Termux will also bypass the VPN tunnel. If you need a VPN-tunneled terminal app, I recommend using Termux only to run stunnel; using another terminal emulator app for your other tasks.




Addendum: Testing and bugs

This tutorial has been tested on:

  • Stock Android 6.0
  • Stock Android 7.0
  • Stock Android 8.0
  • LineageOS 14.1 (~ Android 7.1.x)
  • Fire OS (~ Android 5.x), testing done by user steve74it


Important Notice for Android 8.0+ (Oreo) users:

The command termux-setup-storage does not work (yet). Instead, follow this workaround to access storage:

The workaround will no longer be necessary once this bug is resolved:





  • Thu Dec  7 20:24 UTC 2017: initial release
  • Thu Dec  7 20:40 UTC 2017: formatting corrections
  • Thu Dec  7 20:58 UTC 2017: spelling
  • Fri Dec 8 18:47 UTC 2017: add recommended route settings. credit and thanks to Darkspace-Harbinger
  • Fri Jan  5 17:30:54 UTC 2018: add note that this guide is functional on FireOS 5.6 (Android 5.x). testing done by user steve74it, thank you!


Any corrections, further testing, as well as general suggestions for improvement would be much appreciated.

all of my content is released under CC-BY-SA 2.0

PGP: A6440E1F195A962035455B22823762E626318758

#2 DarkSpace-Harbinger


    Advanced Member

  • Members
  • PipPipPip
  • 33 posts
  • LocationThe Bleak Lands

Posted 08 December 2017 - 07:07 PM

One other thing that should be mentioned, in OpenVPN for Android you have to have "Bypass VPN for local networks" unchecked.


This option has exposed my IPv6 address in the past.


Your also going to want use default route checked for IPv4 and IPv6 checked as well.

#3 LZ1


    It's nice to be nice to nice people

  • Members
  • PipPipPip
  • 1487 posts

Posted 30 December 2017 - 09:49 AM



Thank you. What an absolutely stellar guide. The formatting alone is fantastic!


I hope you won't mind that I add it to my own guide's index.

Open This Spoiler If: A Website Is Blocked, You Want To Help AirVPN, Find The Beta/Experimental Client Or You're A New User Wanting Help/Information


Did you make a guide or how-to for something? Then contact me if you want me to index it in my new user guide, so that the community can find it more easily.

Tired of Windows? Why Linux Is Better.

#4 B3nB3n



  • Members
  • PipPip
  • 13 posts

Posted 15 January 2018 - 09:08 AM

Amazing work! Again, thank you so much! Helped me a lot in China!


Only one question (sorry I am a real idiot):


you may want to take a look at Termux:Widget (via F-Droid or Play Store. It's an extension to Termux. If you put your stunnel commands into shell scripts, stored in $HOME/.shortcuts/ , you can launch them via Home screen widgets.


how is that working? how do I have to safe the commands as script? (which format/how to safe them/how to write them)


edit: so i found the .shortcuts folder, i added a file (AirVPN.sh) with the following lines:



cd storage/shared/AirVPN

stunnel AirVPN*.ssl


but when i run it with the widget, it says "Permission denied". Can anyone help me?

#5 sheivoko


    Advanced Member

  • Members
  • PipPipPip
  • 207 posts
  • LocationPGP 0x823762e626318758

Posted 15 January 2018 - 03:28 PM

but when i run it with the widget, it says "Permission denied". Can anyone help me?


I think I know why: You're calling /bin/bash which likely does not exist on your phone. The shebang line (#!/bin/bash) is not necessary here, just leave it out. I've created a quick tutorial for Termux:Widget, including a small video, please try it out and compare it to your approach:


Termux:Widget usage

The following steps assume that you have successfully followed the main tutorial.
Instead of manually typing the two commands necessary to launch stunnel, we can do the same with a script. A script is nothing more than a text file that contains the commands we need to run.

Here is a video on Vimeo that demonstrates steps 3 to 6.

1. Create a text file with the following contents. Please adjust the second line to whatever server you happen to be using! For this tutorial, I'll be using the server BE-Brussels_Capricornus:

cd storage/shared/AirVPN
stunnel AirVPN_BE-Brussels_Capricornus_SSL-443.ssl

2. Save the file; choose whatever file name you want, but make sure you use the .sh file extension. For this tutorial, I'll name the file:


Put your file into the AirVPN folder on your phone (the same folder you have already been using for the main tutorial).


3. Open Termux and run:


This makes sure we are in stunnel's home directory. Now run:

mkdir .shortcuts

This will create a (hidden) folder that is required for Termux:Widget. That's where we need to copy our script to:

cp storage/shared/AirVPN/capricornus.sh .shortcuts

4. Leave Termux. Now install Termux:Widget from your preferred app store (FDroid or Google Play)

5. On your phone's home screen, enter your widget/wallpaper settings by long-pressing on a free spot on your home screen. Tap the WIDGETS button and find the Termux:Widget item.
Drag one of the Termux:Widget items onto your home screen. For this tutorial, I'll use the "All shortcuts 2x2" option.

6. You should now see your script listed within that new widget on your home screen. Tap on your script to run it.

7. You can add and use as many .sh scripts for different stunnel connections as you like, as long as you also create/generate the corresponding .ovpn and .ssl files.

all of my content is released under CC-BY-SA 2.0

PGP: A6440E1F195A962035455B22823762E626318758

#6 sheivoko


    Advanced Member

  • Members
  • PipPipPip
  • 207 posts
  • LocationPGP 0x823762e626318758

Posted 15 January 2018 - 03:37 PM

[accidental double post]

all of my content is released under CC-BY-SA 2.0

PGP: A6440E1F195A962035455B22823762E626318758

#7 B3nB3n



  • Members
  • PipPip
  • 13 posts

Posted 16 January 2018 - 12:47 AM

Thank you very much. Works like charme! Thank you so much!

#8 mikevvl



  • New Members
  • Pip
  • 1 posts

Posted Yesterday, 02:46 AM

Thanks, sheivoko! Big help to start work. I want to suggest You a few additions for more Security and Ease of Use (EoU).


  1. Security:(Add:In2:3/3) Move work files *.ssl and stunnel.crt into Termux home (cd ~/; ->/data/data/com.termux/files/home/ - private Termux app data area, When OpenVPN import the *.ovpn - its saved into private OpenVPN app data area too)
    cd storage/shared/AirVPN
    mkdir ~/st
    cp -r *.ssl stunnel.crt ~/st/
  2. EoU:(Add:In2:6/7) Create:
    into Termux home (~/) file ".bash_profile":
    alias st1=". ~/st/1"
    alias st2=". ~/st/2"
    alias kist='killall stunnel'
    . ~/st/sthlp

    into ~/st/ file "sthlp":

    echo -e "For Stop(Kill) any/all of stunnels: Type kist & Press enter"
    echo -e "For (Re)Start stunnel: Type (st1 OR st2) & Press enter"
    echo -e "For Stop Termux: Type exit & Press enter twice" 


    into ~/st/ file "1":

    killall stunnel
    cd ~/st
    . ~/st/sthlp
    stunnel AirVPN_BE-Brussels_Capricornus_SSL-443.ssl

    may be into ~/st/ file "2":

    killall stunnel
    cd ~/st
    . ~/st/sthlp
    stunnel AirVPN_SG-Singapore_Reticulum_SSL-443.ssl
    As result - at the next start Termux stunnel will run automatically (in this case - AirVPN_BE-Brussels_Capricornus_SSL-443.ssl). If we commented "foreground = yes" into *.ssl then we will be able to stop(any), to restart and choose which *.ssl used (If foreground = no OR absent then we may be need add options log = overwrite and output = st1.log).
    (Add:In2:7/7 & 3/3) I think we can combine the additions 1.&2. by creating a folder "AirVPN/st/" with files: stunnel.crt, changed (*.ssl) and created (.bash_profile,1, 2, sthlp, ...). After "transfer the AirVPN folder to your phone's sdcard / main storage directory" & install termux with stunnel we can
    cp -r storage/shared/AirVPN/st ~/
    cp ~/st/.bash_profile ~/
    . ~/.bash_profile
    and use (st1, st2, kist, etc.) as command w/o restart Termux.

Similar Topics Collapse

0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users

Servers online. Online Sessions: 14891 - BW: 42733 Mbit/sYour IP: Access.