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.
It is possible to automatically start OnionShare from the CLI using a systemd unit file.
You may find this particularly useful if you are operating in 'persistent' mode, and want to start the same onion service every time your machine starts.
To do this, you need to prepare some OnionShare json config first.
Here is the main OnionShare config. In this example, it's stored in ``/home/user/.config/onionshare/onionshare.json``. You may need to adjust some of the settings, but if you already have OnionShare installed, it probably looks much like this already::
{
"version": "2.6.2",
"connection_type": "bundled",
"control_port_address": "127.0.0.1",
"control_port_port": 9051,
"socks_address": "127.0.0.1",
"socks_port": 9050,
"socket_file_path": "/var/run/tor/control",
"auth_type": "no_auth",
"auth_password": "",
"auto_connect": true,
"use_autoupdate": true,
"autoupdate_timestamp": null,
"bridges_enabled": false,
"bridges_type": "built-in",
"bridges_builtin_pt": "obfs4",
"bridges_moat": "",
"bridges_custom": "",
"bridges_builtin": {},
"persistent_tabs": [
"my-persistent-onion"
],
"locale": "en",
"theme": 0
}
Notice the 'persistent_tabs' section. We will now create a file at ``/home/user/.config/onionshare/persistent/my-persistent-onion.json``, that looks like this::
**Don't actually use this private key, service_id or client_auth keys! They are shown only as an example. Never share the private_key with anyone.**
The easiest way to generate the onion address and private key is to first create a 'pinned' OnionShare tab in the desktop app and started the share for the first time. This will then have saved the persistent settings to your ``.config/onionshare/persistent/`` folder with a random name. You can unpin that tab once you've generated it the first time. Or, you can leave it where it is, and use that persistent file in your systemd unit file below.
Now you can create a systemd unit file in ``/etc/systemd/system/onionshare-cli.service``. Be sure to adjust the User and Group to your own user/group, as well as changes to any paths to the onionshare-cli binary or the paths to your JSON configs and shares.
Note that although ``/home/user/my-shared-file.txt`` was defined in the ``filenames`` section of the ``my-persistent-onion.json`` file, it's still necessary to specify it as the argument to the onionshare-cli command.
Be sure to run ``sudo systemctl daemon-reload`` after creating the unit file.
Now you can run ``sudo systemctl start onionshare-cli.service``. If you have ``journalctl`` installed, you can run ``sudo journalctl -f -t onionshare-cli``, and you should see some output of your service starting::
[...]
Feb 09 10:14:09 onionshare onionshare-cli[18852]: [6.5K blob data]
Feb 09 10:14:18 onionshare onionshare-cli[18852]: Compressing files.
Feb 09 10:14:18 onionshare onionshare-cli[18852]: Give this address and private key to the recipient:
Feb 09 10:14:18 onionshare onionshare-cli[18852]: http://niktadkcp6z7rym3r5o3j2hnmis53mno5ughvur357xo7jkjvmqrchid.onion
Feb 09 10:14:18 onionshare onionshare-cli[18852]: Private key: RHJSN4VI3NKGDSIWK45CCWTLYOJHA6DQQRQXUID3FXMAILYXWVUQ
Feb 09 10:14:18 onionshare onionshare-cli[18852]: Press Ctrl+C to stop the server
If you don't want your users to use a Private Key, set ``public`` to be ``true`` in the ``general`` settings of the my-persistent-onion.json file.
You may want to migrate your OnionShare data when switching to another computer. This is especially true if you had a 'persistent' onion address and you want to preserve it.
OnionShare stores all such data in a specific folder. Copy the relevant folder for your operating system below, to your new computer:
OnionShare stores its settings in a JSON file. Both the CLI and the Desktop versions use this configuration file. The CLI also lets you specify a path to a custom configuration file with ``--config``.
Below are the configuration file parameters and what they mean. If your configuration file has other parameters not listed here, they may be obsolete from older OnionShare versions.
==================== =========== ===========
Parameter Type Explanation
==================== =========== ===========
version ``string`` The version of OnionShare. You should not ever need to change this value.
connection_type ``string`` The way in which OnionShare connects to Tor. Valid options are 'bundled', 'automatic' (use Tor Browser's Tor connection), 'control_port' or 'socket_file'. Default: 'bundled'
control_port_address ``string`` The IP address of Tor's Control port, if ``connection_type`` is set to 'control_port'. Default: '127.0.0.1'
control_port_port ``integer`` The port number of Tor's Control port, if ``connection_type`` is set to 'control_port'. Default: '9051'
socks_address ``string`` The IP address of Tor's SOCKS proxy, if ``connection_type`` is set to 'control_port' or 'socket_file'. Default: '127.0.0.1'
socket_file_path ``string`` The path to Tor's socket file, if ``connection_type`` is set to 'socket_file'. Default: '/var/run/tor/control'
auth_type ``string`` If access to Tor's control port requires a password, this can be set to 'password', otherwise 'no_auth'. Default: 'no_auth'
auth_password ``string`` If access to Tor's control port requires a password, and ``auth_type`` is set to 'password', specify the password here. Default: ''
auto_connect ``boolean`` Whether OnionShare should automatically connect to Tor when it starts. Default: False
use_autoupdate ``boolean`` Whether OnionShare should automatically check for updates (over Tor). This setting is only valid for MacOS or Windows installations. Default: True.
autoupdate_timestamp ``integer`` The last time OnionShare checked for updates. Default: None
bridges_enabled ``boolean`` Whether to connect to Tor using bridges. Default: False
bridges_type ``string`` When ``bridges_enabled`` is True, where to load bridges from. Options are "built-in" (bridges shipped with OnionShare and which may get updated from Tor), "moat" (request bridges from Tor's Moat API), or "custom" (user-supplied bridges). Default: "built-in"
bridges_builtin_pt ``string`` When ``bridges_type`` is set to "built-in", this specifies which type of bridge protocol to use. Options are "obfs4", "meek-azure" or "snowflake". Default: "obfs4"
bridges_moat ``string`` When ``bridges_type`` is set to "moat", the bridges returned from Tor's Moat API are stored here. Default: ""
bridges_custom ``string`` When ``bridges_type`` is set to "custom", the bridges specified by the user are stored here. Separate each bridge line in the string with '\n'. Default: ""
bridges_builtin ``dict`` When ``bridges_type`` is set to "built-in", OnionShare obtains the latest built-in bridges recommended by Tor and stores them here. Default: {}
persistent_tabs ``list`` If the user has defined any tabs as 'saved' (meaning that they are persistent each time OnionShare starts, and their onion address doesn't change), these are given a random identifier which gets listed here. The persistent onion is stored as a JSON file with the same name as this identifier, in a subfolder of the OnionShare configuration folder called 'persistent'. Default: []
locale ``string`` The locale used in OnionShare. Default: None (which is the same as 'en'). For valid locale codes, see 'available_locales' in https://github.com/onionshare/onionshare/blob/main/cli/onionshare_cli/settings.py
theme ``boolean`` The theme for the OnionShare desktop app. Valid options are 0 (automatically detect the user's computer's light or dark theme), 1 (light) or 2 (dark).
==================== =========== ===========
Configuration file parameters for persistent onions
As described above, each 'persistent' onion has parameters of its own which are stored in its own JSON file. The path to this file can be specified for the CLI tool with ``--persistent``.
Here is an example persistent JSON configuration::
enabled ``boolean`` Whether persistence is enabled for this onion. When the persistent option is unchecked in the desktop, this entire JSON file is deleted. Default: true
autostart_on_launch ``boolean`` Whether to automatically start this persistent onion when OnionShare starts and once Tor is connected. Default: false
=================== =========== ===========
general
^^^^^^^
=============== =========== ===========
Parameter Type Explanation
=============== =========== ===========
title ``string`` An optional custom title for displaying on the onion service. Default: null ("OnionShare" will be shown instead)
public ``boolean`` Whether the onion service can be accessed with or without a Private Key (Client Authentication). If true, no Private Key is required.
autostart_timer ``boolean`` Whether the onion service is configured to start at a specific time. The time can be set in the desktop app or specified in seconds with ``--auto-start-timer`` with the CLI tool. Default: false
autostop_timer ``boolean`` Whether the onion service is configured to stop at a specific time. The time can be set in the desktop app or specified in seconds with ``--auto-stop-timer`` with the CLI tool. Default: false
