<commit_before># tor

#### Table of Contents

* [Overview](#overview)
  * [Upgrade Notice](#upgrade-notice)
* [Dependencies](#dependencies)
* [Usage](#usage)
  * [Installing tor](#installing-tor)
  * [Configuring SOCKS](#configuring-socks)
  * [Installing torsocks](#installing-torsock)
  * [Configuring relays](#configuring-relays)
  * [Configuring the control](#configuring-control)
  * [Configuring hidden services](#configuring-hidden-services)
  * [Configuring directories](#configuring-directories)
  * [Configuring exit policies](#configuring-exit-policies)
* [Polipo](#polipo)
* [Munin](#munin)

# Overview<a name="overview"></a>

This module tries to manage tor, making sure it is installed, running, has
munin graphs if desired and allows for configuration of relays, hidden services,
exit policies, etc.

## Upgrade Notice<a name="upgrade-notice"></a>

 * Previously, if you did not set the `$outbound_bindaddress` variable, it was
   being automatically set to the `$listen_address variable`. Now this is not
   being done and instead you will need to set the `$outbound_bindaddress`
   explicitly for it to be set.

 * The `tor::relay{}` variables `$bandwidth_rate` and `$bandwidth_burst` were
   previously used for the tor configuration variables `RelayBandwidthRate` and
   `RelayBandwidthBurst`, these have been renamed to `$relay_bandwidth_rate`
   and `$relay_bandwidth_burst`. If you were using these, please rename your
   variables in your configuration.

 * The variables `$bandwidth_rate` and `$bandwidth_burst` are now used for the
   tor configuration variables `BandwidthRate` and `BandwidthBurst`. If you
   used `$bandwidth_rate` or `$bandwidth_burst` please be aware that these
   values have changed and adjust your configuration as necessary.

 * The `$tor_ensure_version` was converted to a parameter for the tor and
   `tor::daemon` classes.

 * The `$torsocks_ensure_version` was converted to a parameter for the
   `tor::torsocks` class.

 * The options that used to be settable with the `tor::daemon::global_opts`
   define now are parameters for the `tor::daemon class`, and
   `tor::daemon::global_opts` was removed accordingly.


# Dependencies<a name="dependencies"></a>

This module needs:

 * the [concat module](https://github.com/puppetlabs/puppetlabs-concat.git)

# Usage<a name="usage"></a>

## Installing tor<a name="installing-tor"></a>

To install tor, simply include the 'tor' class in your manifests:

    class { 'tor': }

You can specify the `$ensure_version` class parameter to get a specific
version installed.

However, if you want to make configuration changes to your tor daemon, you will
want to instead include the `tor::daemon` class in your manifests, which will
inherit the `tor` class from above:

    class { '::tor::daemon': }

You have the following class parameters that you can specify:

    data_dir    (default: '/var/lib/tor')
    config_file (default: '/etc/tor/torrc')
    use_bridges (default: 0)
    automap_hosts_on_resolve (default: 0)
    log_rules   (default: ['notice file /var/log/tor/notices.log'])

The `data_dir` will be used for the tor user's `$HOME`, and the tor
`DataDirectory` value.

The `config_file` will be managed and the daemon restarted when it changed.

`use_bridges` and `automap_hosts_on_resolve` are used to set the `UseBridges`
and `AutomapHostsOnResolve` torrc settings.

The `log_rules` can be an array of different Log lines, each will be added to
the config, for example the following will use syslog:

    class { '::tor::daemon':
        log_rules => [ 'notice syslog' ],
    }

If you want to set specific options for the tor class, you may pass them
directly to the tor::daemon in your manifests, e.g.:

    class { '::tor::daemon':
      use_munin                 => true,
      automap_hosts_on_resolve  => 1,
    }

## Configuring SOCKS<a name="configuring-socks"></a>

To configure tor socks support, you can do the following:

    tor::daemon::socks { "listen_locally":
      listen_addresses => [ '127.0.0.1' ];
    }

This will setup the `SocksListenAddress` to be `127.0.0.1`. You also can pass
the following options to `tor::daemon::socks`:

    $port = 0       - SocksPort
    $listen_address - can pass multiple values to configure SocksListenAddress lines
    $policies       - can pass multiple values to configure SocksPolicy lines

## Installing torsocks<a name="installing-torsocks"></a>

To install torsocks, simply include the `torsocks` class in your manifests:

    class { 'tor::torsocks': }

You can specify the `$ensure_version` class parameter to get a specific
version installed.

# Configuring relays<a name="configuring-relays"></a>

An example relay configuration:

   tor::daemon::relay { "foobar":
     port             => '9001',
     listen_addresses => '192.168.0.1',
     address          => '192.168.0.1',
     bandwidth_rate   => '256',
     bandwidth_burst  => '256',
     contact_info     => "Foo <collective at example dot com>",
     my_family        => '<long family string here>';
   }

You have the following options that can be passed to a relay, with the defaults
shown:
 
    $port                    = 0,
    $listen_addresses        = [],
    $portforwarding          = 0,     # PortForwarding 0|1, set for opening ports at the router via UPnP.
                                      # Requires 'tor-fw-helper' binary present.
    $bandwidth_rate          = '',    # KB/s, defaulting to using tor's default: 5120KB/s
    $bandwidth_burst         = '',    # KB/s, defaulting to using tor's default: 10240KB/s
    $relay_bandwidth_rate    = 0,     # KB/s, 0 for no limit.
    $relay_bandwidth_burst   = 0,     # KB/s, 0 for no limit.
    $accounting_max          = 0,     # GB, 0 for no limit.
    $accounting_start        = [],
    $contact_info            = '',
    $my_family               = '', # TODO: autofill with other relays
    $address                 = "tor.${domain}",
    $bridge_relay            = 0,
    $ensure                  = present
    $nickname                = $name

## Configuring the control<a name="configuring-control"></a>

To pass parameters to configure the ControlPort and the HashedControlPassword,
you would do something like this:

    tor::daemon::control { "foo-control": 
      port                    => '80',
      hashed_control_password => '<<PASSWORD>>',
      ensure                  => present;
    }<commit_msg>a few markdown fixes<commit_after># tor

#### Table of Contents

* [Overview](#overview)
  * [Upgrade Notice](#upgrade-notice)
* [Dependencies](#dependencies)
* [Usage](#usage)
  * [Installing tor](#installing-tor)
  * [Configuring SOCKS](#configuring-socks)
  * [Installing torsocks](#installing-torsocks)
  * [Configuring relays](#configuring-relays)
  * [Configuring the control](#configuring-control)
  * [Configuring hidden services](#configuring-hidden-services)
  * [Configuring directories](#configuring-directories)
  * [Configuring exit policies](#configuring-exit-policies)
* [Polipo](#polipo)
* [Munin](#munin)

# Overview<a name="overview"></a>

This module tries to manage tor, making sure it is installed, running, has
munin graphs if desired and allows for configuration of relays, hidden services,
exit policies, etc.

## Upgrade Notice<a name="upgrade-notice"></a>

 * Previously, if you did not set the `$outbound_bindaddress` variable, it was
   being automatically set to the `$listen_address variable`. Now this is not
   being done and instead you will need to set the `$outbound_bindaddress`
   explicitly for it to be set.

 * The `tor::relay{}` variables `$bandwidth_rate` and `$bandwidth_burst` were
   previously used for the tor configuration variables `RelayBandwidthRate` and
   `RelayBandwidthBurst`, these have been renamed to `$relay_bandwidth_rate`
   and `$relay_bandwidth_burst`. If you were using these, please rename your
   variables in your configuration.

 * The variables `$bandwidth_rate` and `$bandwidth_burst` are now used for the
   tor configuration variables `BandwidthRate` and `BandwidthBurst`. If you
   used `$bandwidth_rate` or `$bandwidth_burst` please be aware that these
   values have changed and adjust your configuration as necessary.

 * The `$tor_ensure_version` was converted to a parameter for the tor and
   `tor::daemon` classes.

 * The `$torsocks_ensure_version` was converted to a parameter for the
   `tor::torsocks` class.

 * The options that used to be settable with the `tor::daemon::global_opts`
   define now are parameters for the `tor::daemon class`, and
   `tor::daemon::global_opts` was removed accordingly.


# Dependencies<a name="dependencies"></a>

This module needs:

 * the [concat module](https://github.com/puppetlabs/puppetlabs-concat.git)

# Usage<a name="usage"></a>

## Installing tor<a name="installing-tor"></a>

To install tor, simply include the 'tor' class in your manifests:

    class { 'tor': }

You can specify the `$ensure_version` class parameter to get a specific
version installed.

However, if you want to make configuration changes to your tor daemon, you will
want to instead include the `tor::daemon` class in your manifests, which will
inherit the `tor` class from above:

    class { '::tor::daemon': }

You have the following class parameters that you can specify:

    data_dir    (default: '/var/lib/tor')
    config_file (default: '/etc/tor/torrc')
    use_bridges (default: 0)
    automap_hosts_on_resolve (default: 0)
    log_rules   (default: ['notice file /var/log/tor/notices.log'])

The `data_dir` will be used for the tor user's `$HOME`, and the tor
`DataDirectory` value.

The `config_file` will be managed and the daemon restarted when it changed.

`use_bridges` and `automap_hosts_on_resolve` are used to set the `UseBridges`
and `AutomapHostsOnResolve` torrc settings.

The `log_rules` can be an array of different Log lines, each will be added to
the config, for example the following will use syslog:

    class { '::tor::daemon':
        log_rules => [ 'notice syslog' ],
    }

If you want to set specific options for the tor class, you may pass them
directly to the tor::daemon in your manifests, e.g.:

    class { '::tor::daemon':
      use_munin                 => true,
      automap_hosts_on_resolve  => 1,
    }

## Configuring SOCKS<a name="configuring-socks"></a>

To configure tor socks support, you can do the following:

    tor::daemon::socks { "listen_locally":
      listen_addresses => [ '127.0.0.1' ];
    }

This will setup the `SocksListenAddress` to be `127.0.0.1`. You also can pass
the following options to `tor::daemon::socks`:

    $port = 0       - SocksPort
    $listen_address - can pass multiple values to configure SocksListenAddress lines
    $policies       - can pass multiple values to configure SocksPolicy lines

## Installing torsocks<a name="installing-torsocks"></a>

To install torsocks, simply include the `torsocks` class in your manifests:

    class { 'tor::torsocks': }

You can specify the `$ensure_version` class parameter to get a specific
version installed.

# Configuring relays<a name="configuring-relays"></a>

An example relay configuration:

    tor::daemon::relay { "foobar":
      port             => '9001',
      listen_addresses => '192.168.0.1',
      address          => '192.168.0.1',
      bandwidth_rate   => '256',
      bandwidth_burst  => '256',
      contact_info     => "Foo <collective at example dot com>",
      my_family        => '<long family string here>';
    }

You have the following options that can be passed to a relay, with the defaults
shown:
 
    $port                    = 0,
    $listen_addresses        = [],
    $portforwarding          = 0,     # PortForwarding 0|1, set for opening ports at the router via UPnP.
                                      # Requires 'tor-fw-helper' binary present.
    $bandwidth_rate          = '',    # KB/s, defaulting to using tor's default: 5120KB/s
    $bandwidth_burst         = '',    # KB/s, defaulting to using tor's default: 10240KB/s
    $relay_bandwidth_rate    = 0,     # KB/s, 0 for no limit.
    $relay_bandwidth_burst   = 0,     # KB/s, 0 for no limit.
    $accounting_max          = 0,     # GB, 0 for no limit.
    $accounting_start        = [],
    $contact_info            = '',
    $my_family               = '', # TODO: autofill with other relays
    $address                 = "tor.${domain}",
    $bridge_relay            = 0,
    $ensure                  = present
    $nickname                = $name

## Configuring the control<a name="configuring-control"></a>

To pass parameters to configure the `ControlPort` and the
`HashedControlPassword`, you would do something like this:

    tor::daemon::control { "foo-control": 
      port                    => '80',
      hashed_control_password => '<<PASSWORD>>',
      ensure                  => present;
    }
{'fraction_non_alphanumeric': 0.10707337950354058, 'fraction_numerical': 0.009960314372422379, 'mean_word_length': 3.2598607888631093, 'pattern_counts': {'":': 6, '<': 47, '<?xml version=': 0, '>': 75, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4450456', 'n_tokens_mistral': 4015, 'n_tokens_neox': 3770, 'n_words': 1309}