From Whonix

OnionShare Logo


OnionShare is an open source program that allows a file of any size to be shared securely and anonymously using the Tor network. [1] OnionShare is installed by default as of Whonix ™ 15. The OnionShare wiki succinctly describes the design: [2]

It works by starting a web server, making it accessible as a Tor Onion Service, and generating an unguessable URL to access and download the files. It does not require setting up a separate server or using a third party file-sharing service. You host the files on your own computer and use a Tor Onion Service to make it temporarily accessible over the internet. The receiving user just needs to open the URL in Tor Browser to download the file.

As of OnionShare 2 it is also possible to run the program in Receive mode. This means you can receive files via OnionShare after they are uploaded by Tor Browser users; this is a sort of 'SecureDrop Lite' or personal dropbox. v2.2 of OnionShare also permits the easy hosting of anonymous websites [archive]:

In addition to the “Share Files” and “Receive Files” tabs, OnionShare 2.2 introduces the “Publish Website” tab. You drag all of the files that make up your website into the OnionShare window and click “Start sharing.” It will start a web server to host your static website and give you a .onion URL. This website is only accessible from the Tor network, so people will need Tor Browser to visit it. People who visit your website will have no idea who you are – they won’t have access to your IP address, and they won’t know your identity or your location. And, so long as your website visitors are able to access the Tor network, the website can’t be censored.

OnionShare Version[edit]

At the time of writing, Debian buster supports v1.3.2 of OnionShare. This means the following instructions will only enable files to be shared or received anonymously using legacy v2 onion addresses; this is a known security risk [archive].

Users with higher security needs should follow the optional instructions to manually install a later version of OnionShare from GitHub (v2.2 at the time of writing) to enable v3 onion connections.

Whonix VM Configuration[edit]

Ambox notice.png This application requires incoming connections through a Tor onion service. Supported Whonix-Gateway ™ modifications are therefore necessary for full functionality; see instructions below.

For better security, consider using Multiple Whonix-Gateway ™ and Multiple Whonix-Workstation ™. In any case, Whonix ™ is the safest choice for running it. [3]

1. Extend the onion-grater whitelist in Whonix-Gateway ™ (sys-whonix).

Extend onion-grater Whitelist

On Whonix-Gateway ™.

Create a new directory. [4]

sudo mkdir -p /usr/local/etc/onion-grater-merger.d/

Symlink the onion-grater profile to the onion-grater settings folder.

sudo ln -s /usr/share/doc/onion-grater-merger/examples/40_onionshare.yml /usr/local/etc/onion-grater-merger.d/

Restart onion-grater.

sudo service onion-grater restart

2. Modify the Whonix-Workstation ™ (anon-onionshare) user firewall settings and reload them.

Modify Whonix-Workstation ™ User Firewall Settings

Note: If no changes have yet been made to Whonix Firewall Settings, then the Whonix User Firewall Settings File /etc/whonix_firewall.d/50_user.conf appears empty (because it does not exist). This is expected.

If using Qubes-Whonix ™, complete these steps.
In Whonix-Workstation ™ AppVM. Make sure folder /usr/local/etc/whonix_firewall.d exists.

sudo mkdir -p /usr/local/etc/whonix_firewall.d

Qubes App Launcher (blue/grey "Q")Whonix-Workstation ™ AppVM (commonly called anon-whonix)Whonix User Firewall Settings

If using a graphical Whonix-Workstation ™, complete these steps.

Start MenuApplicationsSystemUser Firewall Settings

If using a terminal-only Whonix-Workstation ™, complete these steps.

Open /usr/local/etc/whonix_firewall.d/50_user.conf with root rights.

sudoedit /usr/local/etc/whonix_firewall.d/50_user.conf

For more help, press on Expand on the right.

Note: This is for informational purposes only! Do not edit /etc/whonix_firewall.d/30_whonix_workstation_default.conf.

The Whonix Global Firewall Settings File /etc/whonix_firewall.d/30_whonix_workstation_default.conf contains default settings and explanatory comments about their purpose. By default, the file is opened read-only and is not meant to be directly edited. Below, it is recommended to open the file without root rights. The file contains an explanatory comment on how to change firewall settings.

## Please use "/etc/whonix_firewall.d/50_user.conf" for your custom configuration,
## which will override the defaults found here. When Whonix is updated, this
## file may be overwritten.

See also Whonix modular flexible .d style configuration folders.

To view the file, follow these instructions.

If using Qubes-Whonix ™, complete these steps.

Qubes App Launcher (blue/grey "Q")Template: whonix-ws-15Whonix Global Firewall Settings

If using a graphical Whonix-Workstation ™, complete these steps.

Start MenuApplicationsSettingsGlobal Firewall Settings

If using a terminal-only Whonix-Workstation ™, complete these steps.

In Whonix-Workstation ™, open the whonix_firewall configuration file in an editor.

nano /etc/whonix_firewall.d/30_whonix_workstation_default.conf

Add. [5]

EXTERNAL_OPEN_PORTS+=" $(seq 17600 17659) "


Reload Whonix-Workstation ™ Firewall.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Workstation ™ AppVM (commonly named anon-whonix)Reload Whonix Firewall

If you are using a graphical Whonix-Workstation ™, complete the following steps.

Start MenuApplicationsSystemReload Whonix Firewall

If you are using a terminal-only Whonix-Workstation ™, run.

sudo whonix_firewall

Start OnionShare[edit]

Launch OnionShare in Whonix-Workstation ™ by either running the command line interface or GUI version.



Advanced users can also build an OnionShare package to install. [6] [7]

Figure: First Start of OnionShare GUI


OnionShare Configuration[edit]

On the first run of OnionShare:

  1. Ignore the initial "Cannot connect to Tor" error which may or may not be shown. [8]
  2. Select the settings button/icon (cog symbol) in the GUI.
  3. Under “How should OnionShare connect to Tor?” choose “Connect using socket file”, and set the socket file to /var/run/tor/control
  4. Under “Tor authentication options” choose “No authentication, or cookie authentication”.

To test OnionShare is running correctly:

  • Click the “Test Settings” button. If all steps were completed correctly, Tor will successfully connect.
  • The GUI should say it supports both ephemeral onion services and stealth onion services.

Figure: OnionShare Settings Window


  • You can check “Create stealth onion services” (Client Auth) to make OnionShare operations more secure - however, this currently only works with legacy 'v2' (shorter) style onions. Support for Client Auth with v3/prop224/next-gen onions will be possible in a future release.
    • Note: Using Stealth mode makes it harder for the end user to connect to the share, because they must first edit their torrc file. Please see the official documentation [archive] for further information.
  • By default, if OnionShare 2.0 or higher is installed and the version of Tor in use is or greater (as it is in Whonix ™), OnionShare will use next-gen or 'v3' (sometimes referred to as prop224) onion addresses by default. [9] These are recognizable by their longer address. You can enable Legacy Mode in the settings if for some reason you want to use the shorter (but less secure) v2 onion addresses.

How-to: Use OnionShare[edit]

Once OnionShare has been installed correctly and the Tor check is successful, sharing files anonymously is easy: [10]

Open OnionShare, drag and drop files and folders you wish to share into it, and click Start Sharing. After a moment, it will show you a .onion URL such as http://asxmi4q6i7pajg2b.onion/egg-cain [archive]. This is the secret URL that can be used to download the file you're sharing.

Send this URL to the person you're sending the files to. If the files you're sending aren't secret, you can use normal means of sending the URL, like by emailing it, or sending it in a Facebook or Twitter private message. If you're sending secret files then it's important to send this URL securely.

The person who is receiving the files doesn't need OnionShare. All they need is to open the URL you send them in Tor Browser to be able to download the file.

Figure: Select File to Share


Figure: Secret Onion URL for Downloaders


Figure: OnionShare Download with Tor Browser [11]


As of OnionShare 2, a new feature exists called 'Receive Mode'. With this mode, you can start an onion service and allow other users to upload files to you via Tor Browser (rather than Share Mode, in which you share files from your OnionShare to others). To learn more about Receive Mode, refer to this OnionShare wiki entry [archive].

A complete user guide, along with advanced topics, hardening options [12] and development documentation is available on the official website [archive]. Do not change settings without fully understanding their function, otherwise onion addresses might be re-used, shares might be left open even after multiple downloads are performed, and so on.

OnionShare AppArmor Profiles[edit]

AppArmor profiles are available to better contain OnionShare, but they have not yet been tested in Whonix ™. [13] Profile development is reported to be lagging behind the master and development branches of the OnionShare git repository. Therefore, willing testers should be knowledgeable about AppArmor profiles before attempting this procedure.

Advanced users are encouraged to help progress the open OnionShare AppArmor ticket [archive] and help complete this wiki section. Successes or failures can also be reported in the Whonix ™ AppArmor forum [archive].

TODO: Test profiles and expand this section.


OnionShare Installation from GitHub[edit]

1. Optional: Create a separate Whonix-Workstation ™ (Qubes-Whonix ™: anon-onionshare AppVM).

Note: This is not strictly necessary, but best practice is to separate anonymous activities of a different nature in distinct VMs (AppVMs). [14]

In Qubes-Whonix ™, to clone the existing anon-whonix:

Qube ManagerRight-click on anon-vmSelect "Clone qube"Rename to "anon-onionshare"

2. Install git in Whonix-Workstation ™ (anon-onionshare).

Open a terminal (Konsole) in Whonix-Workstation ™ (anon-onionshare) and navigate to the persistent home directory.

cd /home/user

Next install git which is not available by default in the VM (AppVM). [15]

sudo apt-get install git

3. Clone the OnionShare directory.

This will pull the OnionShare source code directly from GitHub.

git clone

Next navigate to the OnionShare directory.

cd onionshare

4. Retrieve the OnionShare PGP signing key.

This step retrieves the OnionShare developer's PGP key using the long key ID. [16]

gpg --keyserver --recv-keys 0x927F419D7EC82C2F149C1BD1403C2657CD994F73

5. Examine and verify the git tags and commit.

These steps list the available git tags, and verifies the latest version and its commit (v2.0 at the time of writing).

Ambox warning pn.svg.png Good signature messages should appear for each verify command below. Do not proceed if signatures are bad! In that case, remove the OnionShare directory and repeat step 3.

git tag

git verify-tag v2.2

git verify-commit v2.2^{commit}

Qubes-Whonix ™ users should shut down anon-onionshare prior to the next step.

6. Install OnionShare dependencies.

Several dependencies must be installed in Whonix-Workstation ™ (whonix-ws-15 TemplateVM) for OnionShare to work correctly. Locate the file in the OnionShare repository and run the necessary apt-get commands in the "Debian-like distros" section.

For example, for OnionShare v2.2 run in a terminal (Konsole). [6]

sudo apt install -y python3-flask python3-stem python3-pyqt5 python3-crypto python3-socks python-nautilus tor obfs4proxy python3-pytest build-essential fakeroot python3-all python3-stdeb dh-python python3-flask-httpauth python3-distutils

Qubes-Whonix ™ users should shutdown the whonix-ws-15 TemplateVM after dependencies have installed, and restart the anon-onionshare AppVM.

After installation is finished, follow the steps from the Whonix VM Configuration section.


  1. [archive]
  2. [archive]
  3. Security considerations:
    • By using Whonix ™, additional protections are in place for greater security.
    • This application requires access to Tor's control protocol.
    • In the Whonix ™ context, Tor's control protocol has dangerous features. The Tor control command GETINFO address reveals the real, external IP of the Tor client.
    • Whonix ™ provides onion-grater, a Tor Control Port Filter Proxy - filtering dangerous Tor Control Port commands.
    • When this application is run inside Whonix ™ with an onion-grater whitelist extension, this will limit application rights to Tor control protocol access only. Non-whitelisted Tor control commands such as GETINFO address are rejected by onion-grater in these circumstances.
    • During the application's normal operations it should not attempt to use dangerous Tor control commands such as GETINFO address. In the event the application or Whonix-Workstation ™ are compromised, this command would be rejected.
    • In comparison, if the application is run on a non-Tor focused operating system like Debian, it will have unlimited access to Tor's control protocol (a less secure configuration).
    • If the (non-)Whonix platform is used to host onion services, then running applications are more vulnerable to attacks against the Tor network compared to when Tor is solely used as a client; see also Onion Services Security.
    In conclusion, Whonix ™ is the safest and correct choice for running this application.
  4. Using /usr/local/etc/onion-grater-merger.d/ because that onion-grater settings folder is persistent in Qubes-Whonix ™ TemplateBased ProxyVMs i.e. Whonix-Gateway ™ (commonly called sys-whonix). Non-Qubes-Whonix ™ users could also utilize /etc/onion-grater-merger.d/. Qubes-Whonix ™ users could also utilize /etc/onion-grater-merger.d/ but then /etc/onion-grater-merger.d/ must be made persistent, which means doing this procedure inside the Whonix-Gateway ™ TemplateVM (commonly called whonix-gw-15) and then restarting the Whonix-Gateway ™ ProxyVM or using bind-dirs [archive]. Both techniques are more complicated than simply using /usr/local/etc/onion-grater-merger.d/, since it is persistent either way. Further, it even allows multiple Whonix-Gateway ™ ProxyVMs based on the same Whonix-Gateway ™ TemplateVM; for example, one Whonix-Gateway ™ ProxyVM extending and relaxing onion-grater's whitelist and the other Whonix-Gateway ™ ProxyVM having the default onion-grater whitelist which is more restrictive.
  5. As per [archive] OnionShare uses ports 17600 to 17659.
  6. 6.0 6.1 [archive]
  7. To create a .deb on Debian, run: ./
  8. Will be fixed after upgrades: [archive]
  9. [archive]
  10. [archive]
  11. [archive]
  12. Such as setting a Shutdown Timer to self-destruct shares if they are not downloaded within an acceptable time window. These topics are beyond the scope of this documentation.
  13. [archive]
  14. Qubes-Whonix ™ users should note the whonix-ws-15 TemplateVM will pull in over 70Mb of dependencies at step 6. Consider creating a separate, cloned whonix-ws-15 TemplateVM for this purpose beforehand.
  15. The git installation will not persist in Qubes-Whonix ™ following reboot. This method avoids polluting the whonix-ws-15 TemplateVM upon which it is based.
  16. The OnionShare core developer is Micah Lee. The key ID has been taken directly from [archive] -- micah.asc [archive]

text=Jobs in USA
Jobs in USA

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

Follow: 1024px-Telegram 2019 Logo.svg.png Iconfinder Apple Mail 2697658.png Twitter.png Facebook.png Rss.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Support: 1024px-Telegram 2019 Logo.svg.png Discourse logo.png Matrix logo.svg.png

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png Monero donate Whonix.png United Federation of Planets 1000px.png

Twitter-share-button.png Facebook-share-button.png Telegram-share.png

Want to make Whonix ™ safer and more usable? We're looking for helping hands. Check out the Open Issues and development forum.

https link onion link

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation. Policy of Whonix Website and Whonix Chat and Policy On Nonfreedom Software applies.

Copyright (C) 2012 - 2020 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee [archive] of the Open Invention Network [archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

Whonix ™ is a derivative of and not affiliated with Debian [archive]. Debian is a registered trademark [archive] owned by Software in the Public Interest, Inc [archive].

Whonix ™ is produced independently from the Tor® [archive] anonymity software and carries no guarantee from The Tor Project [archive] about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint, Contact.