Skip to content

Commit

Permalink
moved readme into getting started
Browse files Browse the repository at this point in the history
  • Loading branch information
@rubo77
rubo77 committed May 29, 2017
1 parent 2c8f12c commit 561213b
Show file tree
Hide file tree
Showing 2 changed files with 224 additions and 245 deletions.
235 changes: 4 additions & 231 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,236 +28,9 @@ There are types for setting up monitoring, icvpn, anonymous vpn and alfred annou
* Bird IPv4 Route exchange
* Apply firewall rules automatially, when all rules are defined.

## Usage
### Getting started

Install as a puppet module, then include with node-specific parameters.
A detailed instruction and an example puppet manifest can be found at:
https://github.com/ffnord/ffnord-puppet-gateway/blob/master/docs/admin/getting_started.rst

### Dependencies

Install Puppet and some required modules with:

```
apt-get install --no-install-recommends puppet git apt-transport-https
puppet module install puppetlabs-stdlib --version 4.15.0
puppet module install puppetlabs-apt --version 1.5.1
puppet module install puppetlabs-vcsrepo --version 1.3.2
puppet module install saz-sudo --version 4.1.0
puppet module install torrancew-account --version 0.1.0
```

Then add this module (which is not in the puppet forge, so it has to be
downloaded manually):

```
cd /etc/puppet/modules
git clone https://github.com/ffnord/ffnord-puppet-gateway ffnord
```

### Parameters

Now include the module in your manifest and provide all parameters.
Basically there is one type for mesh network, which pulls
in all the magic and classes for the icvpn connection, monitoring and
anonymous vpn uplink.

Please make sure that the content of your fastd key-file looks like this:
```
secret "**************************";
```
The stars are replaced by your privat fastd key


Example puppet code (save e.g. as `/root/gateway.pp`) can be found at:
https://github.com/ffnord/ffnord-puppet-gateway/blob/master/docs/admin/getting_started.rst#a-first-manifest

#### Mesh Type
```
ffnord :: mesh {
'<mesh_code>':
mesh_name, # Name of your community, e.g.: Freifunk Gotham City
mesh_code, # Code of your community, e.g.: ffgc
mesh_as, # AS of your community
mesh_mac, # mac address mesh device: 52:54:00:bd:e6:d4
vpn_mac, # mac address vpn device, ideally != mesh_mac and unique
mesh_ipv4, # ipv4 address of mesh device in cidr notation, e.g. 10.35.0.1/19
mesh_mtu, # mtu used, default only suitable for fastd via ipv4
range_ipv4, # ipv4 range allocated to community, this might be different to
# the one used in the mesh in cidr notation, e.g. 10.35.0.1/18
mesh_ipv6, # ipv6 address of mesh device in cidr notation, e.g. fd35:f308:a922::ff00/64
mesh_peerings, # path to the local peerings description yaml file
fastd_secret, # fastd secret
fastd_port, # fastd port
fastd_peers_git, # fastd peers repository
dhcp_ranges = [], # dhcp pool
dns_servers = [], # other dns servers in your network
}
```

#### Named Zone Type

This type enables you to receive a zone file from a git repository, include
it into the named configuration and setup a cron job for pulling changes in.
By default the cronjob will pull every 30min.

The provided configuration should not rely on relative path but use
the absolute path prefixed with '/etc/bind/zones/${name}/'.

```
ffnord::named::zone {
'<name>':
zone_git; # zone file repo
}
```

#### DHCPd static type

This type enables you to receive a file with static dhcp assignments from a git repository, include
it into the dhcp configuration and setup a cron job for pulling changes in.
By default the cronjob will pull every 30min.

The provided configuration should not rely on relative path but use
the absolute path prefixed with '/etc/dhcp/statics/${name}/'.
The name should be the same as the community the static assignments belong to.
There has to be a file named static.conf in the repo.

```
ffnord::dhcpd::static {
'<name>':
static_git; # dhcp static file repo
}
```

#### ICVPN Type
```
ffnord :: icvpn::setup {
icvpn_as, # AS of the community peering
icvpn_ipv4_address, # transfer network IPv4 address
icvpn_ipv6_address, # transfer network IPv6 address
icvpn_peerings = [], # Lists of icvpn names
tinc_keyfile, # Private Key for tinc
}
```

#### IPv4 Uplink via GRE Tunnel
This is a module for an IPv4 Uplink via GRE tunnel and BGP.
This module and the VPN module are mutually exclusive.
Define the ffnord::uplink::ip class once and ffnord::uplink::tunnel
for each tunnel you want to use. See http://wiki.freifunk.net/Freifunk_Hamburg/IPv4Uplink
for a more detailed description.

```
class {
'ffnord::uplink::ip':
nat_network, # network of IPv4 addresses usable for NAT
tunnel_network, # network of tunnel IPs to exclude from NAT
}
ffnord::uplink::tunnel {
'<name>':
local_public_ip, # local public IPv4 of this gateway
remote_public_ip, # remote public IPv4 of the tunnel endpoint
local_ipv4, # tunnel IPv4 on our side
remote_ip, # tunnel IPv4 on the remote side
remote_as, # ASN of the BGP server announcing a default route for you
}
```

#### Peering description
Be aware that currently the own system mesh address will not be filtered.

```
gc-gw1:
ipv4: "10.35.5.1"
ipv6: "fd35:f308:a922::ff01"
gc-gw2:
ipv4: "10.35.10.1"
ipv6: "fd35:f308:a922::ff02"
gc-gw3:
ipv4: "10.35.15.1"
ipv6: "fd35:f308:a922::ff03"
gc-gw4:
ipv4: "10.35.20.1"
ipv6: "fd35:f308:a922::ff04"
```

### Firewall

The firewall rules created are collected in `/etc/iptables.d`, they are not applied
automatically! You have to call `build-firewall` to apply them.

### On Debian jessie
you have to load the ip_tables and ip_conntrack module manally before applying the puppet manifest:

modprobe ip_tables
modprobe ip_conntrack

On Debian jessie add it to autoĺoad on reboot:

echo ip_conntrack >> /etc/modules

### Run Puppet

To apply the puppet manifest (e.g. saved as `/root/gateway.pp`) run:

```
puppet apply --verbose /root/gateway.pp
build-firewall
```

The verbose flag is optional and shows all changes. To be even more catious you can
also add the `--noop` flag to only show changes but not apply them.
**This should be run best inside a `screen` session!**

### Re-run Puppet

To run puppet again, you have to ensure that old fastd-configurations are deleted before you start:
```
rm -Rf /etc/fastd/
puppet apply --verbose /root/gateway.pp
build-firewall
```

### First time: start services

```
/etc/init.d/fastd restart
```

## Maintenance Mode

To allow administrative operations on a gateway without harming user connections
you should bring the gateway into maintenance mode:

```
maintenance on
```

This will deactivate the gateway feature of batman in the next run of check-gateway (cronjob every minute).
And after DHCP-Lease-Time (usually one hour) there should be no user device left with a default route to
the gateway.

To deactivate maintenance mode and reactivate the batman-adv gateway feature:

```
maintenance off
```

check with

```
maintenance status
```

## FASTD Query

For debugging purposes we utilize the status socket of fastd using a little
helper script called `fastd-query`, which itself is a wrapper around `socat`
and `jq`. An alias `fastd-query-${mesh_code}` is created for every
mesh network. For example you can retrieve the status for some node, where
the node name is equivalent to the peers filename:

```
# fastd-query-ffgc peers name gc-gw0
```
Now create your puppet manifest code and save it e.g. as `/root/gateway.pp`
Loading

0 comments on commit 561213b

Please sign in to comment.