Feature-rich onion service manager for UNIX-like operating systems written in POSIX compliant shellscript
OnionJuggler is a minimal requirement, portable collection of scripts and documentation to help the service operator juggle (manage) his onion(s).
WARNING: do not trust this repo yet
, backup your hs keys in another location. This project has not been released and should be considered for development only.
Quick link to this repository: git.io/onionjuggler
Table of Contents
Introduction
Images
History
This project was started after seeing the amazing OnionShare CLI python scripts, which possibilitates ephemeral onion services that never touch the disk and can be run on Tails or Whonix easily. Then after seeing the RaspiBlitz onion service bash script for the Raspberry Pi, the idea to port it to any Debian distribution started. As the idea grew, using GNU Bash and Linux was a single point of failure 1 2, so the making the script POSIX compliant to be compatible with any Unix-like system was a definitive goal.
Goal
The goal of this project is:
- facilitate onion service management, from activating a service to adding client authorization to it, giving the full capabilities of editing files manually would have but with less tipying.
- show the that managing the onion service is much more than just using a webserver with your pages.
- distribution, from the source code level (FOSS) to the effect it takes when it allows anyone to run the code on any operating system, shell or service manager. Mitigation from a single point of failure
Mitigation from a single point of failure:
- Kernel from predominant
Linux
to alsoBSD
and any other Unix-like system. - Shell from predominant
Bash
to also any POSIX shell such asksh
,(y,d)ash
andZsh
(emulating sh). - Service manager from predominant
Systemd
to alsoOpenRC
,SysVinit
,Runit
.
Editing the tor configuration file (torrc) is not difficult, but automation solves problem of misconfiguration and having:
- less time spent
- complete uniformity
- graphical interface to help newbies
Features
- Enable service - Create directory if not existent (HiddenServiceDir), select onion version (HiddenServiceVersion), custom socket type being unix or tcp, up to two virtual ports, up to two targets (HiddenServicePort).
- Disable service - Remove service configuration from the torrc, the service will not be acessible anymore, but you can enable it again any time you want. Optionally purge the service, deleting its configuration and directory, which will delete its keys permanently.
- Renew service address - Focused on private onion services, if you ever leak its address, you can change its hostname, beware all of your authorized clients will be disconnected and the service keys will be permanently deleted.
- Credentials - Show hostname, clients, torrc block, qrencoded hostname.
- Onion authentication - For v3 onion services only. This depends on client and server side configuration and works with a key pair, the client holds the private key part either generate by him (more safe) or given by the service operator and the onion service operator holds the public part. If any if
- Server - Generate key pair or add public part, list client names and their public keys from
<HiddenServiceDir>/authorized_clients/<client>.auth
. If any client is configured, the service will not be acessible without authentication. - Client - Generate key pair or add public part, list your
<ClientOnionAuthDir>/<SOME_ONION>.auth_private
.
- Server - Generate key pair or add public part, list client names and their public keys from
- Onion-Location - For public onion services You can redirect your plainnet users to your onion service with this guide for nginx, apache2 and html header attributes.
- Backup - Better be safe.
- Create - Backup of your
torrc
lines containing hidden service configuration, all of your directories ofHiddenServiceDir
andClientOnionAuthDir
. - Integrate - Integrate hidden serivces lines configuration from
torrc
and the directoriesHiddenServiceDir
andClientOnionAuthDir
to your current system. This option should be used after creating a backup and importing to the current host.
- Create - Backup of your
- OpSec - Operation Security
- Vanguards - This addon protects against guard discovery and related traffic analysis attacks. A guard discovery attack enables an adversary to determine the guard node(s) that are in use by a Tor client and/or Tor onion service. Once the guard node is known, traffic analysis attacks that can deanonymize an onion service (or onion service user) become easier.
- Unix socket - Support for enabling an onion service over unix socket to avoid localhost bypasses.
- Web server - Serve files with your hidden service using Nginx or Apache2 web server.
- Usability - There are two dialog boxes compatible with the project,
dialog
andwhiptail
. - Bulk - Some commands can be bulked with the argument
@all
to include all services or clients depending on the option--service
or--client
, list enabled arguments[SERV1,SERV2,...]
and[CLIENT1,CLIENT2,...]
, the command will loop the variables and apply the combination. - Fool-proof - The script tries its best to filter invalid commands and incorrect syntax. The commands are not difficult but at first sight may scare you. Don’t worry, if it is invalid, it won’t run to avoid tor daemon failing to reload because of invalid configuration. If an invalid command runs, please open an issue.
Requirements
- General:
- Unix-like system.
- superuser privileges to call commands as root and the tor user, with
doas
orsudo
.
- Required programs:
- sh - any POSIX shell:
dash
0.5.4+,bash
2.03+,ksh
88+,mksh
R28+,yash
2.29+, busyboxash
1.1.3+,zsh
3.1.9+ (zsh --emulate sh
) etc. - doas/sudo (must be already configured)
- tor >= 0.3.5.7
- grep >=0.9
- sed
- tar (Backup)
- openssl >= 1.1 (Client Authorization - requires algorithm x25519, so it can’t be LibreSSL)
- basez >= 1.6.2 (Client Authorization)
- git (Vanguards)
- python(3)-stem >=1.8.0 (Vanguards)
- dialog/whiptail (TUI)
- nginx/apache2 (Web server)
- sh - any POSIX shell:
- Optional programs:
- (lib)qrencode >= 4.1.1 (List)
- Development programs:
- pandoc (Manual)
- shellcheck (Review)
If using Vanguards, python2.x
is needed, but it is not in the requirements to be installed by default.
The packages are downloaded when setting up the environment with configure.sh. The absolute minimum you can go to is doas/sudo tor grep sed
, and you will be limited to enable, disable and renew services.
Instructions
Clone the repository
git clone https://github.com/nyxnor/onionjuggler.git cd onionjuggler
Set custom variables
You should not modify the default configuration on /etc/onionjuggler/onionjuggler.conf
, it will be modified on every update. Your local configurations should be on /etc/onionjuggler/conf.d/*.conf
.
To assign values to the variables, yyou can either:
- Open the mentioned configuration file with your favorite editor:
“${EDITOR:-vi}” /etc/onionjuggler/cond.d/local.conf
- or insert configuration to the end of the file with tee:
printf “su_cmd="sudo"\n” | tee -a /etc/onionjuggler/cond.d/local.conf
- or edit with sed:
sed -i’’ “s|^su_cmd=.*|su_cmd="doas"|” /etc/onionjuggler/cond.d/local.conf
Setup the enviroment
Run from inside the cloned repository to create the tor directories, create manual pages and copy scripts to path:
./configure.sh --install
Usage
TUI
onionjuggler-tui wraps the CLI in a Terminal User Interface. Some TUI options will let you edit the authorization files, which is recommended to set your favorite text editor to an environment variable that will be tried on the following order: DOAS_EDITOR
/SUDO_EDITOR
, if empty will try VISUAL
, if empty will try EDITOR
, if empty WILL fallback to Vi
.
To use the TUI, just run:
onionjuggler-tui
CLI
onionjuggler-cli is the main script that manages the HiddenServices. Take a look at the documentation inside docs
folder, there are many other onion services management guides. Read:
Don’t forget the cli manual and the conf manual for advanced usage:
man onionjuggler-cli man onionjuggler.conf
To create a service named terminator
, it is as easy as possible:
onionjuggler-cli on -s terminator
But can be as advanced as specifying all the parameters:
onionjuggler-cli on --service terminator --socket unix --version 3 --port 80,127.0.0.1:80
VITOR
vitor helps the user edit the tor configuration files in a safe manner, making a temporary copy of the desired file, opening the editor with this temporary file, after existing the editor, the validity check will be done with tor -f FILE --verify-config
and if it doesn’t pass, will warn about the error and give the option to open the editor again and fix the problems or interrupt to exit vitor and delete changes.
You must run vitor as root using sudo
or doas
. Root privilege is necessary to edit the configuration files and the programs to run as another user are used to run tor a the tor user if it is not specified on the configuration file.
To open the default file on /etc/tor/torrc, just run:
doas vitor
To open an alternative file, specify it with the -f
option:
doas vitor -f /usr/local/etc/tor/torrc
You may need to run tor as another user if the User
option is not already on the configuration file, specify it with the -t
option:
doas vitor -t _tor
Featured on
- TorBox >= v.0.5.0