Sub-menu: Onion Services

The upper part of the "Onion Services" sub-menu of TorBox v.0.5.0
The upper part of the “Onion Services” sub-menu of TorBox v.0.5.0

With the “Onion Services” sub-menu, it is easy to share a folder with a static webpage, files etc. on an .onion domain with our without client access control, even if the TorBox is located behind a firewall, a network translator or placed in a censoring country. With TorBox File Sharing (TFS), upload and/or download files can be allowed to the public or specific clients. To do so the first time, you have to follow a three-step process:

  • Toggle the Onion Service Mode from OFF to ON or create an Onion Service (menu entry 2 or 3). This will give you a public Onion Service – everyone can access it.
  • If you want to limit access to your Onion Service, you can control the client’s access by generating a key pair (menu entry 7), sending the client his private key or registering a client’s public key (menu entry 8), if he is providing you with it.
  • Start (or stop) sharing a folder on an Onion domain.

In the following, we look at all menu entries one by one:

  • Menu entry 1: Run an Onion Service – Read Me First: This brief introduction is intended to help new users, in particular, to understand and simplify the set-up and use of an Onion Service within TorBox. It is a summary of what has been written above.

  • Menu entry 2: Toggle Onion Service Mode: This entry switches the Onion Service on or off. Deactivating the Onion Service Mode will disable all Onion Services and automatically restarts Tor. The current configuration will be saved and reused with the next activation.

  • Menu entry 3: Create or reactivate an Onion Service: This entry creates or reactivates an Onion Service. To do so, you must type in the service’s name. If the service is not existing, it will be created (including a shared folder). If the service exists, it may be deactivated. You can try to reactivate it.
    Along with the Onion Service, a virtual port has to be defined. However, don’t worry about it, and just type in a number you wish to use (good numbers are 80, 8080, or something above 10000). When the Onion Service is successfully created, TorBox will present you with all the necessary information, including a QR code.

    Important
    .
    • A single Onion domain can only provide one service. This means that you can either share a static website from a folder or use TFS. You cannot do both with one unique Onion domain.
    • The newly created Onion Service is not accessible right away. Still, you have to share the newly created folder (menu entry 12 or 13). This method is a quick and good solution for statically sharing documents and websites. This shared folder will be publicly available without client authorization (menu entry 7-11). If you want to restrict the client’s access, you have to generate a key pair (menu entry 7), send the client his private key or register a client’s public key (menu entry 8) if he provides it.

  • Menu entry 4: List all Onion Services: Does what it says.

  • Menu entry 5: Delete or deactivate an Onion Service: This entry deletes or deactivates one or several specific Onion Services. Use entry 2 for deactivating all Onion Services at once.
    Deactivating means that the Onion Service, client authorizations, and hosted data will not be deleted and the actual configuration preserved. The same configuration will be applied if you activate the Onion Service Mode again.
    Deleting means that the Onion Service, client authorizations, and the hosted data in the shared folder will be irrevocably lost.

  • Menu entry 6: Enter the advanced configuration editor: This menu entry loads the Tor configuration file into a textual editor. You should know what you are doing before changing anything in the configuration file — here, you can break your TorBox. If you are unsure, then contact us. Did you something wrong? You can always overwrite this configuration with the default one, stored in ~/torbox/etc/tor/. After changing the configuration, use the following commands in the editor: CTRL-S and CTRL-X to exit the editor.

  • Menu entry 7: Generate a new key pair (public and private key) for a client: An Onion Service could be used to serve a website folder (menu entry 12 or 13). The served data will be publicly available without activated client authorization (menu entry 7-11). This is probably not the intention of the service operator. However, with a key pair (public and private key), access to an Onion Service can be limited to those with the private key. This menu entry will generate a key pair (public and private key) where the public key is automatically stored in the specific Onion Service. The private key should be sent to the client, which gives him access to the particular Onion Service. If the client has already a key pair and gives out a public key, you can register it to a specific Onion Service using menu entry 8.

  • Menu entry 8: Register a client with its public key: If the client sends a public key to the onion service operator, this menu entry will register this public key for a particular Onion Service. The onion service operator doesn’t have to send anything to the client- the client already has the private key. Alternatively, the onion service operator can generate a new key pair (public and private key) with menu entry 7.

  • Menu entry 9: Edit a client’s authorization: With this entry, you can directly edit a client’s authorization by starting an editor. After changing the authorization, use the following commands in the editor: CTRL-S and CTRL-X to exit the editor.

  • Menu entry 10: List all clients for a particular Onion Service: Does what it says.

  • Menu entry 11: Remove a client’s authorization: This entry removes one or several client authorization(s) from a particular Onion Service? Removing all client authorization(s) from a specific Onion Service makes the service public.

  • Menu entry 12: Start/stop sharing a folder on an Onion domain and list them: This entry starts, stops or lists website folders on Onion domains. After starting, it may take minutes until it is accessible through tor. The difference to TorBox’s File Sharing (TFS) capabilities (menu entry 13) is that TFS is focused on exchanging files, not serving a website.

  • Menu entry 13: Start/stop upload or/and download files (TorBox File Sharing): This menu entry starts, stops or lists TorBox File Sharing (TFS) capabilities on Onion domains. After starting, it may take minutes until it is accessible through tor. The difference between serving a website folder on Onion domains (menu entry 12) is that TFS is focused on exchanging files, not serving a website.

  • Menu entry 14: Backup Onion Services: This entry stores a backup of your ONION SERVICE configuration in /home/torbox/backup. You can access the backup file by downloading it from your TorBox by using a SFTP client (it uses the same login and password as your SSH client). Alternatively, you can retrieve the backup file by connecting an USB stick with your TorBox. You can probably mount the USB stick by “sudo mount /dev/sda /mnt” and then copy the backup file on your stick. With that backup, upgrading a TorBox with Onion Service support or moving it to another computer to keep all the configuration, key, and data is possible. Keeping backups of your Onion Services is the recommended way to ensure the availability of your data in case of a system crash.

    Important: If you choose to make a backup of your shared folders, you need enough space on your SD card. An already existing backup in the home directory will be overwritten without confirmation!

  • Menu entry 15: Restore Onion Services: This entry restores a backup of your Onion Service configuration, which is stored in your home directory (~). You can upload a backup file using a SFTP client (it uses the same login and password as your SSH client). Alternatively, you can transfer a backup file by connecting an USB stick with your TorBox. You can probably mount the USB stick by “sudo mount /dev/sda /mnt” and then copy the backup file from the stick to your home directory.

    Important: An already existing Onion Service configuration will be overwritten without confirmation!

• • •

Problems and questions

  • I set up an Onion Service and want to share a folder with or without client authorization, but the TorBrowser on another system shows only errors that it cannot connect to the Onion Service. What is wrong here? –> see here.
  • I’m connected to TorBox, and all is working as expected, but Firefox, Safari and any iOS device don’t display .onion sites. What’s wrong? –> see here.