Internet is heavily restricted on mobile (3G/4G) and residential (ADSL/TD-LTE) networks and connecting to VPNs and websites outside Iran is close to impossible, Tor is not working reliably as the Tor bridges are outside Iran and mostly inaccessible to people inside Iran. On the other hand, the government has not yet blocked the Internet access on machines located inside Iranian data centers, and people can easily connect to these websites and servers.

We need servers and we need help setting those servers up.

To get around the restrictions, you need to have two servers:

• Machine A: a machine outside Iran (e.g. on DigitalOcean or other providers). We’ll use 100.0.0.0 as the IP address of this machine througout this document. This document assumes the OS running on Machine A is Ubuntu Server 20.04.
• Machine B: a machine inside an Iranian datacenter with a public address. We’ll use 200.0.0.0 as the IP address of this machine throughout this document. This document assumes the OS running on Machine B is Ubuntu Server 20.04.

We're going to install a VPN server on Machine A (outside Iran) and connect to this VPN server from Machine B (inside an Iranian datacenter). Then we can install a VPN server and a Tor bridge on Machine B, and share the connection details with people we know.

By following this document and setting up these machines, you will need to share the IP address of Machine B with other people in order for them to be able to connect to the VPN or Tor bridge that you set up. The government can connect this IP address with your identity through the provider that you purchased Machine B from.

For example, you buy Machine B from Afranet, and share the VPN connection details with your friends which includes the IP address 200.0.0.0. One of your friends who has this information on his phone gets arrested and the security forces find this IP address on his phone, they can easily check with Afranet and find out the identity of the person who purchased this machine from them and come after you.

As much as possible, try to get one of your friends outside Iran (or a use the identity and debit card of a recently diseased person) to purchase Machine B so that even if the identity of the owner of the machine is leaked, no one can be arrested.

Also, make sure to disable access logs on Machine B as soon as you get access to it (otherwise your own IP address will be logged on the Machine B, and if the machine is compromised it can be traced back to you). We'll explain how to do this later.

We recommend that you buy and use a new machine for doing this with nothing else on it. But it can be done on an existing machine as well. We are using Docker to set up the VPN server and it shouldn't have side effects on the rest of your system.

This is the server that is outside Iran. You might have issue connecting to this server directly using your residential or mobile network connections. If that’s the case, you can first ssh into Server B and then ssh into Server A from there.

you@localhost:~$ ssh [email protected]
Welcome to Ubuntu 20.04.1 LTS (GNU/Linux 5.4.0-48-generic x86_64)
[email protected]:~# ssh [email protected]
Welcome to Ubuntu 20.04.1 LTS (GNU/Linux 5.4.0-48-generic x86_64)
[email protected]:~# 

Deploy and run ocserv using Docker. Ocserv will act as the OpenConnect server:

[email protected]:~# mkdir ocserv
[email protected]:~# cd ocserv
[email protected]:~/ocserv# wget -qO- https://pastebin.com/raw/WZymtWi2 > ocserv.conf
[email protected]:~/ocserv# touch ocpasswd
[email protected]:~/ocserv# cd 
[email protected]:~# docker run --name ocserv --privileged -e NO_TEST_USER=1 -v $PWD/ocserv/:/etc/ocserv/ -p 8443:443 -p 8443:443/udp -d tommylau/ocserv

This should start the docker container running the OpenConnect server. Now you need to create a new user for connecting this this server - replace USERNAME with whatever username you want:

[email protected]:~# docker exec -ti ocserv ocpasswd -c /etc/ocserv/ocpasswd -g "Route,All" USERNAME
Enter password: 
Re-enter password:

It won't show the password you're typing, don't get confused.

Use a brand new machine for this part. The changes we make to the routes and the VPN connection we initiate from Machine B will cause disruptions for other software you might be running on this machine.

Connect to Machine B:

you@localhost:~$ ssh [email protected]
Welcome to Ubuntu 20.04.1 LTS (GNU/Linux 5.4.0-48-generic x86_64)
[email protected]:~#

Edit /etc/ssh/sshd_config:

nano /etc/ssh/sshd_config

and find the # LogLevel INFO. Change it to:

LogLevel QUIET

Reload ssh and sshd services:

[email protected]:~# systemctl reload ssh 
[email protected]:~# systemctl reload sshd

Logout and ssh into the server again.

[email protected]:~# exit
Connection to YOUR_LOCAL_IP closed.
you@localhost:~$ ssh [email protected]

After logging in, clear out the existing access logs:

[email protected]:~# echo > /var/log/auth.log
[email protected]:~# rm /var/log/auth.log.*

logout and log back in again, check and make sure sshd is not logging your IP in /var/log/auth.log:

[email protected]:~# tail /var/log/auth.log

You should see entries like

localhost systemd-logind[706]: Session 12 logged out. Waiting for processes to exit.

but no IP addresses.

Please note that this does not guarantee that the government cannot find your local IP address. Once everything is set up, you should first activate your VPN connection, then ssh into Machine A and ssh into Machine B from Machine A.

Some providers (such as Afranet) deploy the machines with their own version of sources.list which causes Ubuntu to download packages from providers' repository mirrors. To increase security, we need to change it back to the official Ubuntu repository mirrors:

[email protected]:~# nano /etc/apt/sources.list

Make sure all lines start with

deb http://archive.ubuntu.com/ubuntu

or

deb http://archive.ubuntu.com/ubuntu

If you see lines like

deb http://ubuntu.mirror.afranet.com/ubuntu

change ubuntu.mirror.afranet.com on those lines to archive.ubuntu.com and you should be good.

Then update the apt repositories:

[email protected]:~# apt update

To maintain ssh connection from your local network to Machine A after connecting it to the VPN server on Machine B, you need to add direct routes to Iranian IP addresses on Machine A. To do that we'll create a bash script and a systemd service to make sure that it's executed on boot.

First create the bash script and move it to /usr/local/sbin:

[email protected]:~# wget -qO- https://pastebin.com/raw/isEgF5tv > iran_ip_range.json
[email protected]:~# GATEWAY=`ip route show | grep 'default via' | cut -d' ' -f3`
[email protected]:~# apt install jq
[email protected]:~# for range in $(jq .[] iran_ip_range.json | sed 's/"//g' | xargs); do   echo "ip route add $range via $GATEWAY" >> /usr/local/sbin/add-routes.sh ; done;
[email protected]:~# chmod +x /usr/local/sbin/add-routes.sh

Replace DEFAULT_GATEWAY_IP with your gateway ip.

Now create the systemd service:

[email protected]:~# nano /etc/systemd/system/add-routes.service

Paste the following in this file and save:

[Unit]
Description=Router configuration service
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=no
RestartSec=3600min
User=root
ExecStart=/bin/bash /usr/local/sbin/add-routes.sh

[Install]
WantedBy=multi-user.target

Enable the add-routes service and start it:

[email protected]:~# systemctl daemon-reload
[email protected]:~# systemctl enable add-routes.service
[email protected]:~# systemctl start add-routes.service

OpenConnect is a VPN software that uses SSL for connecting and transferring network data. You need to install and configure OpenConnect client to connect to the OpenConnect server that you previously installed on Machine A:

[email protected]:~# apt install openconnect

Open a screen to be able to start the OpenConnect VPN client and leave it running after you log out of Machine B:

[email protected]:~# screen

Inside the screen, start the OpenConnect client:

[email protected]:~# openconnect --user test 100.0.0.0:8443 

POST https://100.0.0.0:8443/
Connected to 100.0.0.0:8443
SSL negotiation with 100.0.0.0
Server certificate verify failed: signer not found

Certificate from VPN server "100.0.0.0" failed verification.
Reason: signer not found
To trust this server in future, perhaps add this to your command line:
    --servercert pin-sha256:xxxxxxxxxxxxxxxxxxxxx
Enter 'yes' to accept, 'no' to abort; anything else to view: yes 
Connected to HTTPS on 100.0.0.0
XML POST enabled
Please enter your username.
Group: [Route[Exclude CN]|All Proxy|All]:All
POST https://100.0.0.0:8443/auth
XML POST enabled
Please enter your username.
POST https://100.0.0.0:8443/auth
Please enter your password.
Password:
POST https://100.0.0.0:8443/auth
Got CONNECT response: HTTP/1.1 200 CONNECTED
CSTP connected. DPD 90, Keepalive 32400
Connected as 192.168.xx.xx, using SSL + LZ4, with DTLS + LZ4 in progress
DTLS handshake failed: Error in the push function.
(Is a firewall preventing you from sending UDP packets?)

You are now connected to the VPN server on machine A. To exit the screen, press Ctrl+A+D. You can resume the screen connection (to see the VPN connection output or stop the connection by pressing Ctrl+C) by running the following command:

[email protected]:~# screen -r

This can be done using the exact same process as was done on Machine A:

[email protected]:~# mkdir ocserv
[email protected]:~# cd ocserv
[email protected]:~/ocserv# wget -qO- https://pastebin.com/raw/WZymtWi2 > ocserv.conf
[email protected]:~/ocserv# touch ocpasswd
[email protected]:~/ocserv# cd 
[email protected]:~# docker run --name ocserv --privileged -e NO_TEST_USER=1 -v $PWD/ocserv/:/etc/ocserv/ -p 8443:443 -p 8443:443/udp -d tommylau/ocserv

This should start the docker container running the OpenConnect server. Now you need to create a new user for connecting this this server - replace USERNAME with whatever username you want:

[email protected]:~# docker exec -ti ocserv ocpasswd -c /etc/ocserv/ocpasswd -g "Route,All" USERNAME
Enter password: 
Re-enter password:

It won't show the password you're typing, don't get confused.

OpenConnect usually has problems connecting on Apple products. You can use Algo to install Wireguard and IPSec VPNs on Machine B so that Apple products can connect as well. Follow the instructions on https://github.com/trailofbits/algo and choose Local installation mode to install it locally on Machine B. More information here: https://github.com/trailofbits/algo/blob/master/docs/deploy-to-ubuntu.md

You can download and use this file as config.cfg for the Algo installation: https://pastebin.com/raw/iARF0fGL
This configuration file includes 100 users by default and has WireGuard and IPSec enabled.

Tor connections are unstable. There are two methods for getting it work, and each method might work at different times. You can do both and test their connection to see which one works for you best.

Installing a Tor bridge will help people connect to Tor through Machine B which is easily accessible from within Iran. First make sure that the VPN is connnected (step 3.4). Then install Tor from the Ubuntu repositories to get an initial Tor connection up and runnning, then add the official Tor repository and reinstall/update Tor from the official repo.

[email protected]:~# apt install tor 
[email protected]:~# apt install apt-transport-tor
[email protected]:~# CODENAME=`lsb_release -c | grep Codename | cut -d: -f2 | tr -d [:space:] `
[email protected]:~# ARCH=`dpkg --print-architecture`
[email protected]:~# echo "deb [arch=$ARCH signed-by=/usr/share/keyrings/tor-archive-keyring.gpg] tor://apow7mjfryruh65chtdydfmqfpj5btws7nbocgtaovhvezgccyjazpqd.onion/torproject.org $CODENAME main" > /etc/apt/sources.list.d/tor.list
[email protected]:~# apt update
[email protected]:~# apt install tor obfs4proxy

Now empty out /etc/tor/torrc and open it using an editor:

[email protected]:~# echo > /etc/tor/torrc
[email protected]:~# nano /etc/tor/torrc

and paste this into the file, making sure to replace 200.0.0.0 with the real IP address of Machine B and [email protected] with an email address that you have access to but cannot be traced back to you:

BridgeRelay 1

# Replace "TODO1" with a Tor port of your choice.
# This port must be externally reachable.
# Avoid port 9001 because it's commonly associated with Tor and censors may be scanning the Internet for this port.
ORPort 200.0.0.0:8888

ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy

# This port must be externally reachable and must be different from the one specified for ORPort.
# Avoid port 9001 because it's commonly associated with Tor and censors may be scanning the Internet for this port.
ServerTransportListenAddr obfs4 0.0.0.0:9888

# Local communication port between Tor and obfs4.  Always set this to "auto".
# "Ext" means "extended", not "external".  Don't try to set a specific port number, nor listen on 0.0.0.0.
ExtORPort auto

# Replace "<[email protected]>" with your email address so we can contact you if there are problems with your bridge.
# This is optional but encouraged.
ContactInfo [email protected]

Restart Tor and get your bridge line:

[email protected]:~# systemctl restart tor
[email protected]:~# cat /var/lib/tor/pt_state/obfs4_bridgeline.txt 
# obfs4 torrc client bridge line
#
# This file is an automatically generated bridge line based on
# the current obfs4proxy configuration.  EDITING IT WILL HAVE
# NO EFFECT.
#
# Before distributing this Bridge, edit the placeholder fields
# to contain the actual values:
#  <IP ADDRESS>  - The public IP address of your obfs4 bridge.
#  <PORT>        - The TCP/IP port of your obfs4 bridge.
#  <FINGERPRINT> - The bridge's fingerprint.

Bridge obfs4 <IP ADDRESS>:<PORT> <FINGERPRINT> cert=yyyyyyyy iat-mode=0

Copy Bridge obfs4 <IP ADDRESS>:<PORT> <FINGERPRINT> cert=xxxxxxxx iat-mode=0 and replace <IP ADDRESS with 200.0.0.0 (Machine B IP address), replace <PORT> the port specified for ServerTransportListenAddr in /etc/tor/torrc (9888 by default), and <FINGERPRINT> with the output of this command:

[email protected]:~# cat /var/lib/tor/fingerprint
Unnamed xxxxxxxx

The bridge line should look like this now:

Bridge obfs4 200.0.0.0:9888 Unnamed xxxxxxxx cert=yyyyyyyy iat-mode=0

Currently the Tor fails to confirm reachability of the bridge and you'll see Your server has not managed to confirm reachability for its ORPort(s) in /var/log/syslog. But you can connect to your bridge by specifying a custom bridge in Orbot or Tor Browser.

This method was developed by @meskio and originally published here. We're just changing the vocabulary so that it matches the rest of this document.

First, you need to set up a bridge on Machine A (outside Iran). We'll do this using Docker - install it if you haven't already by following the instructions here https://docs.docker.com/engine/install/ubuntu/#set-up-the-repository

[email protected]:~# mkdir bridge
[email protected]:~# cd bridge
[email protected]:~/bridge# wget https://gitlab.torproject.org/tpo/anti-censorship/docker-obfs4-bridge/-/raw/main/docker-compose.yml

Edit bridge/.env with the following content, changing [email protected] with an email address that you have access to but cannot be traced back to you:

# Set required variables
OR_PORT=3344
PT_PORT=3355
EMAIL[email protected]

# If you want, you could change the nickname of your bridge
#NICKNAME=DockerObfs4Bridge

# Configure the bridge so it will not be distributed by bridgedb:
OBFS4_ENABLE_ADDITIONAL_VARIABLES=1
OBFS4V_BridgeDistribution=none

Start the bridge:

[email protected]:~/bridge# docker compose up -d

Get it's bridge line:

[email protected]:~/bridge# docker exec bridge-obfs4-bridge-1 get-bridge-line
obfs4 100.0.0.0:3355 AAABBBBCCCDDDD cert=abcdx iat-mode=0

Then on Machine B (inside Iran), you have two options for forwarding the Tor traffic to your bridge on Machine A:

1. Using SSH port forwarding
2. Using kcptun

[email protected]:~# ssh -L 4457:127.0.0.1:4457 100.0.0.0:3355

kcptun is a network enhancement proxy that tunnel a stream based traffic over a UDP transport protocol.

Run the following commands on Machine A:

[email protected]~# mkdir kcptun
[email protected]~# cd kcptun
[email protected]~/kcptun# wget https://github.com/xtaci/kcptun/releases/download/v20220628/kcptun-linux-amd64-20220628.tar.gz
[email protected]~/kcptun# server_linux_amd64 -t "127.0.0.1:3355" -l "0.0.0.0:7923" -mtu 1400 --nocomp -sndwnd 16384 --rcvwnd 16384 --datashard 0 --parityshard 0 --crypt aes --smuxver 2 --key "MY_PRE_SHARED_KEY"

Make sure to replace MY_PRE_SHARED_KEY for the --key parameter with a randomly generated string, and write it down. We'll need this value in a moment.

and then on Machine B:

[email protected]~# mkdir kcptun
[email protected]~# cd kcptun
[email protected]~/kcptun# wget https://github.com/xtaci/kcptun/releases/download/v20220628/kcptun-linux-amd64-20220628.tar.gz
[email protected]~/kcptun# client_linux_amd64 -l "0.0.0.0:3355" -r "100.0.0.0:7923" -mtu 1400 --nocomp -sndwnd 16384 --rcvwnd 16384 --datashard 0 --parityshard 0 --crypt aes --smuxver 2 --key "MY_PRE_SHARED_KEY"

Replace MY_PRE_SHARED_KEY with the same random string from the previous step. Also change 100.0.0.0 with the IP address of Machine A.

You can also set up a standalone Snowflake proxy on Machine B to help censored users connect to the Tor network.

The docker-compose version on Ubuntu 20.04 is a bit old, you need to first add the official docker registry and install docker from there: https://docs.docker.com/engine/install/ubuntu/#set-up-the-repository

Once the docker installation is done, run the container:

[email protected]:~# mkdir snowflake
[email protected]:~# cd snowflake
[email protected]:~# wget https://gitlab.torproject.org/tpo/anti-censorship/docker-snowflake-proxy/-/raw/main/docker-compose.yml
[email protected]:~# docker compose up -d

Your snowflake proxy is now up and running and will output some usage statistics every hour on docker logs (first output will appear one hour after starting the docker container):

[email protected]:~# docker compose logs snowflake-proxy

You need to install the OpenConnect app on your devices (Android, Windows and Linux) in order to connect to your VPN.

Once installed, use 200.0.0.0:8443 as host and the username and password you created in step 2.6.

Each OpenConnect VPN account can be used by multiple users simultaneously. There's no need to create multiple user profiles if you want the VPN to be used by multiple people at the same time.

Algo saves the connection profile configuration files in /path/to/algo/configs/200.0.0.0/ . Compress and copy this folder to your local machine and share them with your family and friends. More information here: https://github.com/trailofbits/algo#configure-the-vpn-clients

Each Wireguard and IPSec configuration profile (user) can only be used on a single device si multaneously. If want to connect with both your laptop and mobile phone at the same time, use two separate configuration profiles. Using a single profile for connecting from multiple devices causes connectivity issues.

This is for using the bridge created in section 3.7.1

In Orbot or Tor Browser, enable Use Bridges and select the Custom Bridges option, and enter the bridge line you constructed in section 3.7.1 in the Paste Bridges section. You should now be able to connect and use Tor in seconds.

This is for using the bridge created in section 3.7.2

distribute the bridgeline you got in section 3.7.2, replacing the IP address with the one of Machine B (200.0.0.0):

obfs4 200.0.0.0:3355 AAABBBBCCCDDDD cert=abcdx iat-mode=0