Commit 24bd5ca4 authored by mh's avatar mh
Browse files

Merge remote-tracking branch 'shared/master'

parents 1fcbe721 228ae4a5
fixtures:
repositories:
"concat":
"repo": "https://github.com/puppetlabs/puppetlabs-concat.git"
symlinks:
"tor": "#{source_dir}"
image: ruby:2.3
# Test job template
.test_template: &test_definition
stage: test
script:
- bundle install --jobs $(nproc) --without docs --path vendor
- bundle exec rake tests
- bundle exec rake spec
# Test with version present on Debian stable
test:puppet48:
variables:
PUPPET_VERSION: "~> 4.8.2"
FACTER_VERSION: '~> 2.4.6'
HIERA_VERSION: '~> 3.2.0'
<<: *test_definition
# Test with latest Puppet release
test:puppetlatest:
<<: *test_definition
source ENV['GEM_SOURCE'] || 'https://rubygems.org'
def location_for(place, fake_version = nil)
if place =~ /^(git[:@][^#]*)#(.*)/
[fake_version, { :git => $1, :branch => $2, :require => false }].compact
elsif place =~ /^file:\/\/(.*)/
['>= 0', { :path => File.expand_path($1), :require => false }]
else
[place, { :require => false }]
end
end
group :development, :unit_tests do
# rspec must be v2 for ruby 1.8.7
if RUBY_VERSION >= '1.8.7' and RUBY_VERSION < '1.9'
gem 'rspec', '~> 2.0'
else
gem 'rspec', '~> 3.1.0', :require => false
end
gem 'rake', '~> 10.1.0', :require => false
gem 'rspec-puppet', '~> 2.2', :require => false
gem 'mocha', :require => false
# keep for its rake task for now
gem 'puppetlabs_spec_helper', :require => false
gem 'puppet-lint', :require => false
gem 'librarian-puppet', :require => false
gem 'metadata-json-lint', :require => false
gem 'pry', :require => false
gem 'simplecov', :require => false
end
facterversion = ENV['GEM_FACTER_VERSION'] || ENV['FACTER_GEM_VERSION']
if facterversion
gem 'facter', *location_for(facterversion)
else
gem 'facter', :require => false
end
# vim:ft=ruby
source 'https://rubygems.org'
puppetversion = ENV['GEM_PUPPET_VERSION'] || ENV['PUPPET_GEM_VERSION']
if puppetversion
gem 'puppet', *location_for(puppetversion)
else
gem 'puppet', :require => false
end
gem 'rake'
# 5.3.4 is currently broken
# https://github.com/rodjek/rspec-puppet/issues/647
gem 'puppet', ENV['PUPPET_VERSION'] || '< 5.3.4'
gem 'base32'
# vim:ft=ruby
group :tests do
gem 'facter', ENV['FACTER_VERSION']
gem 'hiera', ENV['HIERA_VERSION']
gem 'puppetlabs_spec_helper'
gem 'librarian-puppet'
gem 'metadata-json-lint'
gem 'semantic_puppet'
end
puppet module for managing tor
==============================
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 !
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
============
This module needs:
- the concat module: https://gitlab.com/shared-puppet-modules-group/concat
- the apt module https://gitlab.com/shared-puppet-modules-group/apt or https://github.com/puppetlabs/puppetlabs-apt/
Usage
=====
Installing tor
--------------
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
-----------------
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
-------------------
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
==================
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
-----------------------
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 => '<somehash>',
ensure => present
}
Note: you must pass a hashed password to the control port, if you are going to
use it.
Configuring hidden services
---------------------------
To configure a tor hidden service you can do something like the following:
tor::daemon::onion_service { "onion_ssh": ports => 22 }
The HiddenServiceDir is set to the ${data_dir}/${name}.
Configuring directories
-----------------------
An example directory configuration:
tor::daemon::directory { 'ssh_directory':
port => 80, listen_address => '192.168.0.1',
port_front_page => '/etc/tor/tor.html'
}
Configuring exit policies
--------------------------
To configure exit policies, you can do the following:
tor::daemon::exit_policy { "ssh_exit_policy":
accept => "192.168.0.1:22",
reject => "*:*";
}
}
Polipo
======
Polipo support can be enabled by doing:
include tor::polipo
this will inherit the tor class by default, remove privoxy if its installed, and
install polipo, making sure it is running.
Munin
=====
If you are using munin, and have the puppet munin module installed, you can set
the use_munin parameter to true when defining the tor::daemon class to have
graphs setup for you.
Functions
=========
This module comes with 2 functions specific to tor support. They require the base32 gem to be installed on the master or wherever they are executed.
onion_address
-------------
This function takes a 1024bit RSA private key as an argument and returns the onion address for a hidden service for that key.
generate_onion_key
------------------
This function takes a path (on the puppetmaster!) and an identifier for a key and returns an array containing the matching onion address and the private key. The private key either exists under the supplied `path/key_identifier` or is being generated on the fly and stored under that path for the next execution.
# 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 onion services](#configuring-onion-services)
* [Configuring directories](#configuring-directories)
* [Configuring exit policies](#configuring-exit-policies)
* [Configuring transport plugins](#configuring-transport-plugins)
* [Functions](#functions)
* [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, onion services,
exit policies, etc.
## Upgrade Notice<a name="upgrade-notice"></a>
* All of the `listen_address` variables have been deprecated, since they have
been deprecated in tor since 0.2.3.x-alpha. Please read the new tor man page
if you were using those variables.
* 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":
port => 0,
policies => 'your super policy';
}
## 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',
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,
$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 => '<somehash>',
ensure => present;
}
Note: you must pass a hashed password to the control port, if you are going to
use it.
## Configuring onion services<a name="configuring-onion-services"></a>
To configure a tor onion service you can do something like the following:
tor::daemon::onion_service { "onion_ssh":
ports => 22;
}
The `HiddenServiceDir` is set to the `${data_dir}/${name}`, but you can override
it with the parameter `datadir`.
If you wish to enable v3-style onion services to correspond with the v2-style
onion services (the same configuration will be applied to both), you can pass
the parameter `v3 => true`. The default is `false`.
If you wish to enable single-hop onion addresses, you can enable them by
passing `single_hop => true`. The default is `false`.
Onion services used to be called hidden services, so an old interface
`tor::daemon::hidden_service` is still available, with the feature
set of that time.
## Configuring directories<a name="configuring-directories"></a>
An example directory configuration:
tor::daemon::directory { 'ssh_directory':
port => '80',
port_front_page => '/etc/tor/tor.html';
}
## Configuring exit policies<a name="configuring-exit-policies"></a>
To configure exit policies, you can do the following:
tor::daemon::exit_policy { "ssh_exit_policy":
accept => "192.168.0.1:22",
reject => "*:*";
}
## Configuring transport plugins<a name="configuring-transport-plugins"></a>
To configure transport plugins, you can do the following:
tor::daemon::transport_plugins { "obfs4":
ext_port => '80',
servertransport_plugin => 'obfs4 exec /usr/bin/obfs4proxy',
}
If you wish to use `obfs4proxy`, you will also need to install the required
Debian package, as the puppet module will not do it for you.
Other options for transport plugins are also available but not defined by
default:
$servertransport_listenaddr #Set a different address for the transport plugin mechanism
$servertransport_options #Pass a k=v parameters to the transport proxy
# Functions<a name="functions"></a>
This module comes with 2 functions specific to tor support. They require the base32 gem to be installed on the master or wherever they are executed.
## onion_address
This function takes a 1024bit RSA private key as an argument and returns the onion address for an onion service for that key.
## generate_onion_key
This function takes a path (on the puppetmaster!) and an identifier for a key and returns an array containing the matching onion address and the private key. The private key either exists under the supplied `path/key_identifier` or is being generated on the fly and stored under that path for the next execution.
# Polipo<a name="polipo"></a>
Polipo support can be enabled by doing:
include tor::polipo
This will inherit the `tor` class by default, remove `privoxy` if it's
installed, and install `polipo`, making sure it is running.
# Munin<a name="munin"></a>
If you are using `munin`, and have the puppet munin module installed, you can
set the `use_munin` parameter to `true` when defining the `tor::daemon` class
to have graphs setup for you.
require 'rubygems'
# keep for compatibility for now
require 'puppetlabs_spec_helper/rake_tasks'
require 'puppet-lint/tasks/puppet-lint'
PuppetLint.configuration.send('disable_80chars')
PuppetLint.configuration.ignore_paths = ["spec/**/*.pp", "pkg/**/*.pp"]
task :tests do
# run syntax checks on manifests, templates and hiera data
# also runs :metadata_lint
Rake::Task[:validate].invoke
# runs puppet-lint
Rake::Task[:lint].invoke
end
# use librarian-puppet to manage fixtures instead of .fixtures.yml
# offers more possibilities like explicit version management, forge downloads,...
......@@ -14,4 +19,5 @@ task :librarian_spec_prep do
sh "ln -s #{pwd} #{pwd}/spec/fixtures/modules/tor"
end
end
task :spec_prep => :librarian_spec_prep
......@@ -3,12 +3,10 @@ class tor::base {
package {'tor':
ensure => $tor::version,
}
case $osfamily {
'Debian': {
package {'tor-geoipdb':
ensure => $tor::version,
before => Service['tor'],
}
if $facts['osfamily'] == 'Debian' {
package {'tor-geoipdb':
ensure => $tor::version,
before => Service['tor'],
}
}
......
......@@ -3,7 +3,7 @@
class tor::compact {
include ::tor
include tor::torsocks
if $osfamily == 'Debian' {
if $facts['osfamily'] == 'Debian' {
include tor::polipo
}
}
......@@ -13,8 +13,8 @@ define tor::daemon::control(
fail('You need to define the tor control password')
}
if $cookie_authentication == 0 and ($cookie_auth_file != '' or $cookie_auth_file_group_readable != '') {
notice('You set a tor cookie authentication option, but do not have cookie_authentication on')
if $cookie_authentication == 0 and ($cookie_auth_file != '' or $cookie_auth_file_group_readable != '') { # lint:ignore:80chars
notice('You set a tor cookie authentication option, but do not have cookie_authentication on') # lint:ignore:80chars
}
concat::fragment { '04.control':
......
......@@ -2,7 +2,6 @@
define tor::daemon::directory (
$ensure = 'present',
$port = 0,
$listen_addresses