1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
Advanced Usage
==============
.. _save_tabs:
Save Tabs
---------
Everything in OnionShare is temporary by default. When OnionShare tabs are closed, addresses no longer exist and can't be used again.
Your OnionShare service can also be persistent.
If you host a website, persistence means it will be available on the same OnionShare address 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 your server.
A purple pin icon appears to the left of its server status to tell you the tab is saved.
.. image:: _static/screenshots/advanced-save-tabs.png
When opening OnionShare, your saved tabs from the prior session will start opened.
Each service then can be started manually, and will be available on the same OnionShare address and be protected by the same private key.
If you save a tab, a copy of its onion service secret key is stored on your computer.
.. _turn_off_private_key:
Turn Off Private Key
--------------------
By default, all OnionShare services are protected with a private key, which Tor calls "client authentication".
The Tor Browser will ask you to enter your private key when you load an OnionShare service.
If you want allow the public to use your service, it's better to disable the private key altogether.
To turn off the private key for any tab, check the "This is a public OnionShare service (disables private key)" box before starting the server.
Then the server will be public and a private key is not needed to load it in the Tor Browser.
.. _custom_titles:
Custom Titles
-------------
When people load OnionShare services in the Tor Browser they see the default title for each type of service.
For example, the default title for chat services is "OnionShare Chat".
If you edit the "Custom title" setting before starting a server you can change it.
Scheduled Times
---------------
OnionShare supports scheduling exactly when a service should start and stop.
Before starting a 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.
Services scheduled to start in the future display a countdown timer when when the "Start sharing" button is clicked.
Services scheduled to stop in the future display a countdown timer when started.
**Scheduling an OnionShare service to automatically start can be used as a dead man's switch**.
This means your service is made public at a given time in the future if you are not there to prevent it.
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 limits its exposure**.
If you want to share secret info or something that will be outdated, you can do so for selected limited time.
.. image:: _static/screenshots/advanced-schedule-stop-timer.png
.. _cli:
Command-line Interface
----------------------
In addition to its graphical interface, OnionShare has a command-line interface.
You can install just the command-line version of OnionShare using ``pip3``::
pip3 install --user onionshare-cli
Note that you will also need the ``tor`` package installed. In macOS, install it with: ``brew install tor``
Then run it like this::
onionshare-cli --help
Info about installing it on different operating systems can be found in the `CLI README file <https://github.com/onionshare/onionshare/blob/develop/cli/README.md>`_ in the Git repository.
If you installed OnionShare using the Snap package, you can also just run ``onionshare.cli`` to access the command-line interface version.
Usage
^^^^^
Browse the command-line documentation by running ``onionshare --help``::
$ onionshare-cli --help
╭───────────────────────────────────────────╮
│ * ▄▄█████▄▄ * │
│ ▄████▀▀▀████▄ * │
│ ▀▀█▀ ▀██▄ │
│ * ▄█▄ ▀██▄ │
│ ▄█████▄ ███ -+- │
│ ███ ▀█████▀ │
│ ▀██▄ ▀█▀ │
│ * ▀██▄ ▄█▄▄ * │
│ * ▀████▄▄▄████▀ │
│ ▀▀█████▀▀ │
│ -+- * │
│ ▄▀▄ ▄▀▀ █ │
│ █ █ ▀ ▀▄ █ │
│ █ █ █▀▄ █ ▄▀▄ █▀▄ ▀▄ █▀▄ ▄▀▄ █▄▀ ▄█▄ │
│ ▀▄▀ █ █ █ ▀▄▀ █ █ ▄▄▀ █ █ ▀▄█ █ ▀▄▄ │
│ │
│ v2.4.1 │
│ │
│ https://onionshare.org/ │
╰───────────────────────────────────────────╯
usage: onionshare-cli [-h] [--receive] [--website] [--chat] [--local-only] [--connect-timeout SECONDS] [--config FILENAME] [--persistent FILENAME] [--title TITLE] [--public]
[--auto-start-timer SECONDS] [--auto-stop-timer SECONDS] [--no-autostop-sharing] [--data-dir data_dir] [--webhook-url webhook_url] [--disable-text]
[--disable-files] [--disable_csp] [--custom_csp custom_csp] [-v]
[filename ...]
positional arguments:
filename List of files or folders to share
optional arguments:
-h, --help Show this help message and exit
--receive Receive files
--website Publish website
--chat Start chat server
--local-only Don't use Tor (only for development)
--connect-timeout SECONDS
Give up connecting to Tor after a given amount of seconds (default: 120)
--config FILENAME Filename of custom global settings
--persistent FILENAME Filename of persistent session
--title TITLE Set a title
--public Don't use a private key
--auto-start-timer SECONDS
Start onion service at scheduled time (N seconds from now)
--auto-stop-timer SECONDS
Stop onion service at scheduled time (N seconds from now)
--no-autostop-sharing Share files: Continue sharing after files have been sent (the default is to stop sharing)
--data-dir data_dir Receive files: Save files received to this directory
--webhook-url webhook_url
Receive files: URL to receive webhook notifications
--disable-text Receive files: Disable receiving text messages
--disable-files Receive files: Disable receiving files
--disable_csp Publish website: Disable the default Content Security Policy header (allows your website to use third-party resources)
--custom_csp custom_csp Publish website: Set a custom Content Security Policy header
-v, --verbose Log OnionShare errors to stdout, and web errors to disk
|
