Changes between Version 1 and Version 2 of doc/TorBOX/Dev/BuildDocumentation/0.2.1

Sep 27, 2012, 11:35:36 PM (7 years ago)



  • doc/TorBOX/Dev/BuildDocumentation/0.2.1

    v1 v2  
    1 [[TOC(noheading, depth=0)]]
    2 [ Main Article - TorBOX]
     1TorBOX has been renamed to Whonix.
    4 {{{
    5 # Version: TorBOX 0.2.1
     3This page has been moved. The History of this page might still be interesting.
    7 # Copyright: proper
    8 #
    9 # License: GPL v3 or any later
    10 #
    11 # Any changes you pull changes into this source will be also licensed
    12 # under GPL v3 or any later. Additionally you grant proper the right to
    13 # re-license your work under a different license. If that is not acceptable,
    14 # you can either fork this source under GPL v3 or any later or contact proper.
    15 # Contact proper, if you require this source code under different license.
    16 }}}
    18 This page documents how the [ binary distribution images] are built. If you have any questions or need help let us know on [ /TorBOX/Dev#Question].
    20 The scripts used to build a certain version of a TorBOX-Gateway or TorBOX-Workstation image can be found in the VM at /usr/share/doc/torbox (in TorBox 0.2 at /usr/local/bin/tor-*) and through the wiki history.
    22 Following these instructions will build version TorBOX 0.2.1 based on Tor 0.2.3 and Ubuntu Precise.
    24 Knowledge assumed: Virtualization and networking basic principles; operation of your platform; Linux knowledge: how to install Ubuntu and basic command line knowledge.
    26 Only one prerequisites: you need a working internet connection.
    28 For discussion related to the development and build process of TorBOX images go [ TorBOX/Dev/].
    30 = Build Anonymity =
    31 While downloading the required tools for building TorBOX your internet service provider could if he want notice that you want to build TorBOX. This is esspecially interesting, if you want to redistribute TorBOX, but still want to stay anonymous. The full story can be read in the chapter [ Build Anonymity].
    33 = Build Security =
    34  * Build on a dedicated build system, install security updates...
    35  * All install media and all downloaded/used code must be verified (including all software on the host).
    36  * Hashes or fingerprints listed on the wiki are not to be trusted, same goes for the scripts, verify them (and make use of the history feature).
    37  * Read [ TorBOX/Trust]
    39 = Host preparation =
    40 '''Read and apply if necessary [ "Network Time Syncing"]!
    42 We recommend you use a dedicated OS installation just for hosting the TorBOX VMs (See [ TorBOX/SecurityAndHardening])
    44 You need to use Ubuntu. The build scripts could be adapted to run on other *NIX systems as well but currently they assume apt-get to be available. You need about 15 GB of free space.
    46 Install the latest security updates, install VirtualBox (and qemu-kvm which is required to mount the Virtual Box .vdi images). Reboot to apply kernel updates.
    47 {{{
    48 sudo apt-get update && sudo apt-get dist-upgrade
    49 sudo apt-get install virtualbox qemu genisoimage
    50 sudo reboot
    51 }}}
    53 If you are going to use Virtual Box inside Virtual Box, be sure to change your host key. Virtual Box -> Preferences -> Input -> Host Key. The "outside" and the "inside" Host Key must differ, otherwise you can not leave the VM "inside" anymore. The "outside" Virtual Box hostkey may NOT be ''ctrl''.^1^ [[BR]]
    54 ,, ^1^ Because the one is used by VBoxSDL "inside".
    56 Building on Windows is no longer supported. Redistributed TorBOX builds should be build on Linux. If you want to port the TorBOX build scripts to Windows, please contact us. Running TorBOX on a Windows host with Virtual Box installed should still be possible.
    58 == Using an apt cacher to speed up downloading ==
    59 '''OPTIONAL''
    61 Does only work with TorBOX-Gateway.
    62 ,, Does not work for TorBOX-Workstation because it never gets direct access to the host by design. We could think about installing apt-cacher-ng on TorBOX-Gateway, if there are any security implications.
    64 Go to TorBOX_Gateway script and comment in the line ''Acquire::http { Proxy ""; };'', i.e. remove the # (hash) in front of it.
    66 If you want to build multiple times (for debugging etc.), it might make sense to install a local apt proxy on your build machine. That safes download time and traffic. ,,Thanks to [ source].
    68 {{{
    69 sudo apt-get install apt-cacher-ng
    70 }}}
    72 {{{
    73 sudo nano /etc/apt/apt.conf
    74 }}}
    76 {{{
    77 Acquire::http { Proxy ""; };
    78 }}}
    80 {{{
    81 sudo apt-get update
    82 }}}
    84 = Source Code Intro =
    85 '''If you prefer to read and understand the source code just by reading scripts you may skip this optional chapter.''' This chapter is dedicated to give an introduction into the TorBOX source code. It can be quite difficult to get started with hacking existing big complex projects.
    87 ''TorBOX_Build'' is a script, which simply runs all other scripts. Actually it's "optional". It has very little functionality beside running all other scripts. You are free to run all scripts one by one. That is useful for learning and for debugging purposes. In case you want to fix a bug or in case you want to upgrade the distribution or in case you want to switch the operating system or whatever you are better off running the steps manually. You can use the Build script as a reference for which steps have to be run in which order.
    89 Ironically currently most scripts are used to create a virtual machine image, which contains the operating system and the either the TorBOX_Gateway or the TorBOX_Workstation script. Scripts needed for creation the virtual machine image are TorBOX_GetISO, TorBOX_ModifyISO, TorBOX_CreateVM and TorBOX_Image. GetISO downloads and verifies the operating system iso image.
    91 ModifyISO mounts the downloaded iso image as read only, copies it, modifies the copied iso image by adding preseeding (unattended installation), unmounts the iso and finally creates preseed.iso, which contains the operating system installer disc modified not to require any user interaction while installing. This process already sets up lots of important privacy settings and other stuff, such as UTC timezone, hostname ubuntu, US language, username user and so on. (See [ TorBOX/SecurityAndHardening] and the ModifyISO script itself for a list of all changes and why.) Preseed.iso is configured to power off itself when it's done installing so the TorBOX_Build script can continue.
    93 TorBOX_CreateVM creates VirtualBox machines with all settings required for secure networking, devices, security settings. Which those settings are in details can be again read in Security And Hardening or the script itself. CreateVM is also responsible for starting virtual machines while building. That happens two times, the first time the operating system will be installed and the second time either the TorBOX_Gateway or the TorBOX_Workstation script will be installed.
    95 TorBOX_Image allow to mount the virtual hdd images. This is required because we have to somehow get the TorBOX_Gateway or the TorBOX_Workstation script into the virtual hdds, so we can install them. With TorBOX 0.1.3 we used ssh, but that was suboptimal. ^1^ ''Image'' also allows to copy the TorBOX_Gateway or the TorBOX_Workstation script to /usr/local/bin/ inside the virtual hdd images. It also adds autostarting them only once as soon as the virtual machine gets started next time. This is done by adding the script to /etc/rc.local. rc.local will look if the installer log exists and if that is so, the script will not be run again. rc.local will also power off the VM if the TorBOX_Gateway or TorBOX_Workstation script finished. ^2^
    97 ,, ^1^ It required manually installing an ssh server just for getting the script into the virtual hdds. Ok, that could also be done with preseed. But it involves weakening the isolation of the VM from the host. The MAC address of the host could be seen my the VM. [[BR]]
    98 ,, ^2^ /etc/rc.local will be reverted by the TorBOX_Gateway or the TorBOX_Workstation script.
    100 TorBOX_Gateway or the TorBOX_Workstation will transform the installed operating system into the TorBOX-Gateway or into the TorBOX-Workstation. They update the system, install security relevant software, install useful applications for an anonymous general purpose operating system, set up all relevant privacy and anonymity required settings, desktop manager etc.
    102 Thus, given the nature of the build step orientated scripts, you can easily work on the the different aspects of TorBOX. For example, once you have created a clean virtual machine with the operating system only, you can make a clone or snapshot, run either the TorBOX_Gateway or the TorBOX_Workstation script as often as you need to test your changes and if something goes wrong, go back to the clone or snapshot. You don't have to build everything from scratch again. ^3^
    104 ,, ^3^ For example, we could add the TorBOX_Gateway or TorBOX_Workstation script to the preseed.iso and let it run after installing. If something would go wrong, you would have to reinstall the whole operating system every time again. That's why we use separate steps.
    106 The ''torcheck'' script will only be copied into TorBOX-Workstation and is supposed to be run in TorBOX-Workstation only. Checks network connection, Tor Browser version, SocksPort and TransPort IP and stream isolation.
    108 = Get the TorBOX source code =
    109 Get all our scripts (currently 8) and save them in one folder, it's best to create a new folder called TorBOX_src in your home directory. It is important that they are all named correctly!
    111 Check the source code for error or malicious edits. Make use of the history feature of's wiki.
    113 "TorBOX_Build" script [[BR]]
    116 "TorBOX_GetISO" script [[BR]]
    119 "TorBOX_ModifyISO" script [[BR]]
    122 "TorBOX_CreateVM" script [[BR]]
    125 "TorBOX_Image" script [[BR]]
    128 "TorBOX-Gateway" script [[BR]]
    131 "TorBOX-Workstation" script [[BR]]
    134 "torcheck" script [[BR]]
    137 = Create the Images =
    138 == Preparations ==
    139 Make the build script executable:
    140 {{{
    141 chmod +x ~/TorBOX_source/TorBOX_*
    142 }}}
    144 Make sure there aren't any VMs in VirtualBox already called "TorBOX-Gateway" or "TorBOX-Workstation" (TODO: automate that)
    146 == VM Creation ==
    147 ,, -all not supported yet.
    149 1. Open a shell and type:
    150 {{{
    151 sudo ~/TorBOX_source/TorBOX_Build -tg
    152 }}}
    154 2. Check if all went ok.
    156 3. Power on TorBOX_Gateway
    158 4. Open a shell and type:
    159 {{{
    160 sudo ~/TorBOX_source/TorBOX_Build -tw
    161 }}}
    163 The scripts can fail for many reasons, please report back any issues!
    165 = How to use the ova images =
    166 Reboot both VMs. Please read the [ Readme]!
    168 = Final Steps (Only Required For Redistribution) =
    169  * [ Leak Testing]!
    170  * [ Test] the images before release! TODO: Needs big revision with all TorBOX features.
    171  * Update the [ Changelog].
    172  * Create hash sums for verification.
    173 {{{
    174 sha512sum TorBOX-Gateway.ova
    175 sha512sum TorBOX-Workstation.ova
    176 }}}
    177  * Upload the images.
    178  * Post hash sums to build documentation.
    179  * Post download links to build documentation.
    180  * At least a few testers should test before posting a news. Testers may be found by posting a news.
    181  * Finally announce: Post a news.