Vidalia for Debian
-------------------


 Default Configuration: Simplest and Painless
 =============================================



 Currently, Vidalia speaks against Tor directly through a local (unix) socket. 
 This is recommended and Debian's default configuration.

 Only two (even only one) steps are required to be performed:

  1. Answer debconf question at Vidalia's config/upgrade time with the proper
     user/list of users that you'll allow to connect/configure/monitor your 
     local instance of Tor, and,

  2. If the user/any of the users from the list below is currently logged in, 
     he/she will have to restart his/her X session before starting Vidalia.


 That would be all!

 ------------------------------------------------------------------------------
   This is default and recommended configuration because the bast majority of 
    the users will find here the most suitable choice for a local Tor daemon.
                Please keep reading for further explanation 
 ------------------------------------------------------------------------------



  Debian Security Enhancements
  ============================

  The first new feature on Vidalia is a general-purpose set of code compiler
  enhancements that at both, compile and run time, intend to provide security
  protection feature. 

  In a nutshell, it helps Vidalia software to be more resistant to memory 
  corruption attacks. This attacks are very easy to find on untrusted third
  party data coming from the network, data that could have been forged to look
  like Tor's but associated to malicious remote attacker.
  
  The second one is a security profile for AppArmor, a mandatory access control
  software that confines processes to certain resources.

  The basic idea behind AppArmor is that you lock an application to a certain
  minimal well-known predefined list of resources, making certain amount of
  attacks to be unable to succeed.
  
  Please note that this AppArmor profile is prepared to cover only the
  "default's installation" scenario, in which you use a system's wide Tor
  instance started by regular Tor init scripts (this configuration is described
  above as "Default Configuration: Simplest and Painless"). 

  Any other role is not supported, mainly because of the complex amount of
  scenarios you may find to run Vidalia.

  Note that this AppArmor profile is of no use unless AppArmor is enabled
  system-wide, which is not the case by default on Debian Wheezy. 

  For more information about testing / using AppArmor on Debian, see 
  https://wiki.debian.org/AppArmor

  Sadly enough, current status of AppArmor on Debian Unstable is broken when
  using stock kernels (Check out status on #676515).
 


 The 'But...' Scenarios
 ======================

 On the other hand, there could be a few situations in which you wont be able 
  to use this configuration profile, some of them being:

  - You couldn't convince an admin to add you into the list of local system 
    users allowed to control Tor 
  - The Tor instance you're willing to control runs on a remote host
  - Some old manuscripts have been recently revealed vulnerabilities on the 
    unixsocket implementation, or simply you just don't wish to use it because 
    you dislike the word 'unix' on 'unixsocket'.


 In this cases, or whichever ones you may find, you can still make use any of
  the following alternatives:

  1. If facing a local Tor daemon situation in which you are unable to connect
     for some reason to the system-wide Tor's Control Socket (as the example 
     explained below), you can still launch a personal Tor session and manually
     configure Vidalia to use it.

  2. Enable Tor's ControlPort and enable CookieAuthentication in Tor's config,
    then grab the cookie file from /var/lib/tor/control_auth_cookie, profit!

  3. Enable Tor's ControlPort, get a hashed password at 'tor --hash-password',
    load back the output into the HashedControlPassword Tor's config field, 
    profit!



  'Two Tor instances on the same machine' Issue
  ==============================================


  Be aware that if you choose to connect to Tor using a different method that 
   Debian's default, you'll be hitting a bug on Vidalia. This will also happen
   if you have two instances of Tor running on the same maching.

  See https://trac.torproject.org/projects/tor/ticket/4823 and 
   http://bugs.debian.org/654644 for more information.


    
  
  
  Detailed description 
  ---------------------

    Vidalia provides a graphical graphical user interface to configure
     different aspects of the Tor Network, check its status at a glance,
     monitor its bandwidth usage or maybe just view Tor's event logs. 
    This means that Vidalia needs to talk to the Tor daemon.


    If for some reason you decide/are forced not to go by the default profile
     which configures everything for you at Vidalia's installation time, you
     may use any of this different approaches to have Vidalia and Tor working.




    1. Launch your own personal Tor session
       ------------------------------------

   *********************** FOR PARANOIDS ONLY ***************************
   |								                                	|
   |									                                |
   |	In the remote and unlikely event of a bug existing in the   	|
   |	Tor routing algorithm or implementation itself, it might be  	|
   |	_relatively_ easy, or at least possible, for a remote user to	|
   |	gain access to the data of the user launching Vidalia.      	|
   |								                                	|
   |									                                |
   |	This will be much more difficult if you run Vidalia using	    |
   |    either of the two alternatives described below.			        |
   |									                                |
   |									                                |
   |          ** Please consider using them if possible! **	        	|
   |								                                	|
   |								                                	|
   *********************** FOR PARANOIDS ONLY ***************************


    Required Steps:

    # Start your own personal Tor session binary, create proper paths:
      $ mkdir ~/.tor 
      $ chown $USER. ~/.tor && chmod go-rwx ~/.tor 
      $ /usr/sbin/tor ControlSocket ~/.tor/socket SocksPort $RANDOM ControlPort 0

    # Make a note on the $RANDOM port it has used. You'll see something like:
      Feb 13 12:28:20.819 [notice] Tor v0.2.2.35 (git-73ff13ab3cc9570d). This is experimental software. Do not rely on it for strong anonymity. (Running on Linux x86_64)
      Feb 13 12:28:20.820 [notice] Initialized libevent version 2.0.16-stable using method epoll. Good.
      Feb 13 12:28:20.820 [notice] Opening Socks listener on 127.0.0.1:3771

      In this case, 3771 is your lucky number and you'll use it as socks port
        for your favourite browser network preferences, polipo or privoxy, etc.

    # Launch Vidalia process. It will fail trying to start, because it's 
      unable to connect or because some other reason. 

    # Manually configure your Vidalia instance:
      # Go to "Settings" 
      # Click on "Advanced" icon
      # At "Tor Control" block, choose "Use Unix domain socket (ControlSocket)"
      # Set "Path" to "/home/$USER$/.tor/socket" and click on "OK"
      # Now click on "Start Tor" and enjoy! :-)



    2. Enable Tor to use a control cookie to communicate with Vidalia.
       ---------------------------------------------------------------

      * The best password is the one you don't have to know about *

     This method consists of a password-less authentication. This means
     you won't have to remember any password, but you'll have to grab a
     very important and *SECRET* file from disk, called "Auth Cookie".

     To enable this profile, edit Tor's configuration file, by default at 
     '/etc/tor/torrc', add or uncomment both the 'ControlPort' and the 
     'CookieAuthentication' options, setting the last one to 1.

     You will end up having something like this:

     # egrep '(ControlPort|Auth)' /etc/tor/torrc
     ControlPort 9051
     CookieAuthentication 1


     Now start/reload/restart the Tor daemon, and start Vidalia (as a regular X
     user).  Vidalia will ask you for a "cookie file" at the next run:

     
     ------------------------------------------------------------------------
       You will have to fetch the "cookie file" from your local filesystem,
       by default at '/var/lib/tor/control_auth_cookie'

       DO NOT share this file with anyone, Tor's privacy depends on it!
     ------------------------------------------------------------------------


     This option might be simpler than all the others, but will require you
     to grab a different cookie file every time you restart the Tor process,
     in contrast to the next methods.

     This is my preferred and recommended method, simple and easy, no
     passwords.



    3. Enable Tor to use a control password to communicate with Vidalia.
       -----------------------------------------------------------------

     Edit the Tor configuration file, by default '/etc/tor/torrc', add or
     uncomment both the 'ControlPort' and 'HashedControlPassword' options
     and load 'tor --hash-password' hash got from the output into it, 
     as shown below:

     
     # tor --hash-password SOME_PASSWORD_HERE
     Sep 17 18:48:49.421 [notice] Tor v0.2.0.30 (r15956). This is experimental
     software. Do not rely on it for strong anonymity. (Running on Linux x86_64)
      
     16:167F667A98F859D2600BD708B48B95343FEF7800B479E2AA4284ACF029

     
     You will end up with something like this:
     
     # grep Control /etc/tor/torrc 
     ControlPort 9051
     HashedControlPassword 16:167F667A98F...4ACF029


     Now start/reload/restart the Tor daemon, and start Vidalia (as a regular X
     user). Vidalia will ask you for the set password ('SOME_PASSWORD_HERE' 
     as for the example) at the next run and it will start using a  secure 
     authentication.



   Last Minute Notes (Quoted from debian/NEWS)
   ===========================================

      A known bug has been introduced at this release point (in fact it was on
      0.2.16, see below), which produces a little undesired effect on very
      particular configuration sets.

      Bug description:
      If you use Vidalia to control Tor and change Tor's config but Vidalia's
      saveconf attempt fails (e.g. because Vidalia is controlling the system Tor
      and it can't write to /etc/tor/torrc, which is default), then Vidalia will
      tell Tor to quit reloading its torrc on hup.

      This is a feature by its own, because now the changes Vidalia made won't be
      silently overwritten at daily's Tor logrotation, but it's a bug too, because
      if you logrotate before hupping, Tor won't open any new logs.

      /As a resume/, this translates into an undesired effect on Tor's logging
      capacity, but it's highly unlikely this will affect any of your privacy
      properties at any point.

      See upstreams's bug report at:
      https://trac.torproject.org/projects/tor/ticket/5095

      For the curious, there was indeed a 0.2.16 upstrem release, which differs
      from the version you're now at by just a little policy change on Vidalia's
      user interface translations.



 -- Ulises Vitulli <dererk@debian.org>  Sun, 12 Jun 2012 19:21:02 -0300
