Git-Mirrors/onionshare
1
0
Fork 0
mirror of https://github.com/onionshare/onionshare.git synced 2024-12-25 23:39:43 -05:00
Code Issues Packages Projects Releases Wiki Activity

Advanced Usage documentation reworked

Browse Source
This commit is contained in:
Allan Nordhøy 2020-09-23 10:14:57 +00:00 committed by GitHub
parent 437beef098
commit eff6d180b2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 38 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/source/advanced.rst
View File

@ -1,63 +1,72 @@
Advanced usage
Advanced Usage
==============
.. _save_tabs:
Save tabs
Save Tabs
---------
By default, everything in OnionShare is temporary. As soon as you close an OnionShare tab its address no longer exists and can't be used again. But sometimes you might want an OnionShare service to be persistent. For example, this would be useful if you want to host a website that can keep the same URL even if you reboot your computer.
Everything in OnionShare is temporary by default. If yoy close an OnionShare tab, its address no longer exists and it can't be used again.
Sometimes you might want an OnionShare service to be persistent.
This is useful if you want to host a website available from the same URL even if you reboot your computer.
To make any tab persistent, check the "Save this tab, and automatically open it when I open OnionShare" box before starting the server. When a tab is saved a purple pin icon appears to the left of its server status.
To make any tab persistent, check the "Save this tab, and automatically open it when I open OnionShare" box before starting the server.
When a tab is saved a purple pin icon appears to the left of its server status.
.. image:: _static/screenshots/advanced-save-tabs.png
When you quit OnionShare and then open it again, your saved tabs will start out open. You'll have to manually start each service, but when you do they will start with the same OnionShare address, and with the same password.
When you quit OnionShare and then open it again, your saved tabs will start opened.
You'll have to manually start each service, but when you do they will start with the same OnionShare address and password.
If you save a tab, a copy of that tab's onion service secret key will be stored on your computer with your OnionShare settings.
.. _disable_passwords:
Disable passwords
Disable Passwords
-----------------
By default, all OnionShare services are protected with the username `onionshare` and a randomly-generated password. If someone makes 20 wrong guesses of the password, your onion service is automatically stopped to prevent a brute force attack against the OnionShare service.
By default, all OnionShare services are protected with the username `onionshare` and a randomly-generated password.
If someone takes 20 wrong guesses at the password, your onion service is automatically stopped to prevent a brute force attack against the OnionShare service.
But sometimes you might want your OnionShare service to be accessible to the public. For example, if you want to set up an OnionShare receive service so the public can securely and anonymously send you files. In this case, it's better to disable the password altogether. If you don't do this, someone can force your server to stop just by making 20 wrong guesses of your password, even if they know the correct password.
Sometimes you might want your OnionShare service to be accessible to the public, like if you want to set up an OnionShare receive service so the public can securely and anonymously send you files. In this case, it's better to disable the password altogether.
If you don't do this, someone can force your server to stop just by making 20 wrong guesses of your password, even if they know the correct password.
To disable the password for any tab, just check the "Don't use a password" box before starting the server. Then the server will be public and won't have a password.
Scheduled times
Scheduled Times
---------------
OnionShare supports scheduling exactly when a service should start and stop. Before starting server, click "Show advanced settings" in its tab and then check the boxes next to either "Start onion service at scheduled time", "Stop onion service at scheduled time", or both, and set the desired dates and times.
OnionShare supports scheduling exactly when a service should start and stop.
Before starting server, click "Show advanced settings" in its tab and then check the boxes next to either "Start onion service at scheduled time", "Stop onion service at scheduled time", or both, and set the respective desired dates and times.
If you scheduled a service to start in the future, when you click the start button you will see a timer counting down until it will start. If you scheduled it to stop in the future, after it's started you will see a timer counting down to when it will stop automatically.
If you scheduled a service to start in the future, when you click the "Start sharing" button you will see a timer counting down until it starts.
If you scheduled it to stop in the future, after it's started you will see a timer counting down to when it will stop automatically.
**Scheduling an OnionShare service to automatically start can be used as a dead man's switch**, where your service will be made public at a given time in the future if anything happens to you. If nothing happens to you, you can cancel the service before it's scheduled to start.
**Scheduling an OnionShare service to automatically start can be used as a dead man's switch**, where your service will be made public at a given time in the future if anything happens to you.
If nothing happens to you, you can cancel the service before it's scheduled to start.
.. image:: _static/screenshots/advanced-schedule-start-timer.png
**Scheduling an OnionShare service to automatically stop can be useful to limit exposure**, like if you want to share secret documents while making sure they're not available on the internet for more than a few days.
**Scheduling an OnionShare service to automatically stop can be useful to limit exposure**, like if you want to share secret documents while making sure they're not available on the Internet for more than a few days.
.. image:: _static/screenshots/advanced-schedule-stop-timer.png
Command line interface
Command-line Interface
----------------------
In addition to its graphical interface, OnionShare has a command line interface.
In addition to its graphical interface, OnionShare has a command-line interface.
Linux
^^^^^
If you installed OnionShare using the Flatpak package, unfortunately the command line interface isn't supported.
If you installed OnionShare using the Flatpak package, unfortunately the command-line interface isn't supported.
If you installed OnionShare using an operating system package, you can just run ``onionshare`` from the terminal.
macOS
^^^^^
Make a symbolic link to the OnionShare command line binary like this::
Make a symbolic link to the OnionShare command-line binary like this::
ln -s /Applications/OnionShare.app/Contents/MacOS/onionshare /usr/local/bin
@ -66,7 +75,7 @@ Now you can run ``onionshare`` from the terminal.
Windows
^^^^^^^
The command line interface isn't supported in Windows.
The command-line interface isn't supported in Windows.
If you really want to use it anyway, you can set up a Windows development environment (see :ref:`starting_development`) and then run this in a command prompt::
@ -75,7 +84,7 @@ If you really want to use it anyway, you can set up a Windows development enviro
Usage
^^^^^
You can see command line documentation by running ``onionshare --help``::
You can browse the command-line documentation by running ``onionshare --help``::
$ onionshare --help
OnionShare 2.3 | https://onionshare.org/
@ -109,7 +118,7 @@ You can see command line documentation by running ``onionshare --help``::
filename List of files or folders to share
optional arguments:
-h, --help show this help message and exit
-h, --help Show this help message and exit
--receive Receive files
--website Publish website
--chat Start chat server
@ -130,19 +139,23 @@ You can see command line documentation by running ``onionshare --help``::
--disable_csp Publish website: Disable Content Security Policy header (allows your website to use third-party resources)
-v, --verbose Log OnionShare errors to stdout, and web errors to disk
Legacy addresses
Legacy Addresses
----------------
OnionShare uses v3 Tor onion services by default. These are modern onion addresses that have 56 characters, for example::
OnionShare uses v3 Tor onion services by default.
These are modern onion addresses that have 56 characters, for example::
uf3wmtpbstcupvrrsetrtct7qcmnqvdcsxqzxthxbx2y7tidatxye7id.onion
But it still has support for v2 onion addresses, the old type of onion addresses that have 16 characters, for example::
OnionShare still has support for v2 onion addresses, the old type of onion addresses that have 16 characters, for example::
lc7j6u55vhrh45eq.onion
OnionShare calls v2 onion addresses "legacy addresses". v3 onion addresses are more secure, and using legacy addresses is not recommended.
OnionShare calls v2 onion addresses "legacy addresses", and they are not recommended, as v3 onion addresses are more secure.
To use legacy addresses, before starting a server click "Show advanced settings" in its tab and check the "Use a legacy address (v2 onion service, not recommended)" box. In legacy mode you can optionally enable Tor client authentication. Once you start a server in legacy mode you cannot remove legacy mode in that tab. Instead you must start a separate service in a separate tab.
To use legacy addresses, before starting a server click "Show advanced settings" from its tab and check the "Use a legacy address (v2 onion service, not recommended)" box.
In legacy mode you can optionally turn on Tor client authentication.
Once you start a server in legacy mode you cannot remove legacy mode in that tab.
Instead you must start a separate service in a separate tab.
Tor Project plans to `completely deprecate v2 onion services <https://blog.torproject.org/v2-deprecation-timeline>`_ on October 15, 2021, and legacy onion services will soon be removed from OnionShare as well.