Staying Connected When Iran Went Dark : Exploring anti-censorship tool

The goal of this blog post is to provide a solution to help people and families in Iran being able to connect to internet in a safe, secure and stable way.

If you are a software engineer and know a bit about AWS, this will help you setup Outline server on AWS Lightsail & Ubuntu server.

Over the past few weeks, Iran has been going through something heavy and painful.

Protests spread across cities. People were killed by the government. Families lost sons and daughters. Fear became part of daily life. And then, almost automatically, the internet went dark.

Not slow.

Not unstable.

Dark.

This post comes from that place, from a very human basic need, to stay connected when connection is deliberately taken away.

In today’s world, shutting down the internet isn’t a technical decision. It’s a political and human one. Access to the internet is no longer a luxury. It’s part of safety, dignity, and basic human rights.

So, I found myself on a mission to do something about this situation (just like my previous effort when I was at Vodafone, championing 60 minutes free calls for Iran during previous uprising during Women, Life, Freedom movement)

Now into the technical aspect:

I started with WireGuard. In most countries, it works beautifully. I set it up properly. Keys were correct. QR codes scanned. Since the application is open-source I was able to build the debug version from the repository without signing it and then send it over to my family to instal (In Iran Google Play Store is also blocked).

The outcome after generating the Access QR code was, the app was Connecting but no packet was coming into server nor going out.

So basiclly:

“It connects… but nothing opens.”

After a couple of hours of investigation and also reviewing limited documents about how internet censorship has been established in Iran, it turned out WireGuard relies on UDP, and in heavily restricted environments, UDP traffic is often throttled, filtered, or silently dropped. Deep packet inspection makes things even harder. The tunnel exists, but packets never come back.

I started looking at tools that can work on TCP rather than UDP. That’s when I moved to Outline.

Outline in a nutshell:

• works over TCP
• blends into normal HTTPS traffic
• it survives where UDP-based VPNs don’t

Now for the tech guys with access to AWS who want to create a same thing for their families (of course it will incur some cost for outbound traffic but when it comes to safety we can bare the cost)

You don’t need to be a networking expert. You just need a small cloud server and about 20 minutes.

Step-by-step: Set up Outline on AWS Lightsail (Ubuntu)

What you’ll need

• An AWS account
• A laptop (Mac/Windows) to run Outline Manager
• A Lightsail instance (Ubuntu)
• Basic SSH access

1) Create the Lightsail instance

1. Go to AWS Lightsail (https://lightsail.aws.amazon.com/)
2. Click Create instance
3. Choose Linux/Unix
4. Choose Ubuntu 22.04 LTS (or 24.04 LTS)
5. Pick a plan (small is fine for a family)
6. Name it (e.g. family-outline)
7. Click Create instance

Wait until status is Running.

2) Get SSH access

SSH from your machine using key

Lightsail lets you download an SSH key pair.

• Instance → Connect tab → Download default key
• Then from your terminal:

chmod 400 ~/Downloads/LightsailDefaultKey-*.pem ssh -i ~/Downloads/LightsailDefaultKey-*.pem ubuntu@YOUR_PUBLIC_IP

Your public IP is in the Lightsail instance overview.

3) Install Docker on the server

Run on the server:

sudo apt update
sudo apt install -y ca-certificates curl
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
docker --version

4) Install Outline Server

Run:

curl -fsSL https://raw.githubusercontent.com/Jigsaw-Code/outline-server/master/src/server_manager/install_scripts/install_server.sh | sudo bash

At the end it prints a JSON blob like:

{"apiUrl":"https://YOUR_PUBLIC_IP:63664/xxxxx","certSha256":"xxxxxxxx"}

Copy and save this JSON.

This is what Outline Manager uses to control your server.

If you lose it, it’s annoying (you typically reinstall), so store it safely.

5) Open the required Lightsail firewall ports

The installer will also tell you which ports to open. Typically two ports:

• Management port (TCP) — example: 63664
• Access key port (TCP + optional UDP) — example: 25380

Now in Lightsail:

1. Click your instance
2. Go to Networking
3. Under IPv4 firewall, click Add rule
4. Add rules:

Required

• TCP → Management port (example 63664) → Anywhere
• TCP → Access key port (example 25380) → Anywhere

Optional (can keep or skip)

• UDP → Access key port (example 25380) → Anywhere

For Iran/restricted networks, TCP is the important one.

Make sure you’re doing this under IPv4 firewall (not only IPv6), because your server IP is IPv4.

At the end it should look like this:

6) Install Outline Manager on your laptop

On your laptop (Mac/Windows), install Outline Manager from the official Outline site.

Open it, then:

1. Click Add server
2. Paste the JSON blob you copied from the installer output
3. Approve the certificate

If the firewall rules are correct, it should connect immediately.

7) Create access keys (one per family member)

In Outline Manager:

• Click Add key
• Rename it (e.g., Dad, Daughter, etc.)
• Copy the invite link or simply the access code

Each key can be revoked independently.

8) Install Outline Client on phones

good news is Outline provides direct download for Android APK, so your family does’t need to go Google Play Store (I know it is a pain)

Download link : https://s3.amazonaws.com/outline-releases/client/android/stable/Outline-Client.apk

On the phone:

• Install Outline Client from the package
• Add server via access code
• Toggle ON

9) Quick verification

On the phone:

• Open a few websites (should load)
• Optionally check IP with any “what is my IP” site

On the server (optional):

docker ps

You should see containers like:

• shadowbox
• watchtower

I hope it helps others run their own VPN proxy and give quicker, safer access for their families.

If you need any help setting this up you know how to reach out :).