lixonet-ee/README.md

230 lines
15 KiB
Markdown
Raw Permalink Normal View History

2020-04-28 05:23:25 +00:00
# Lixonet Enterprise Edition (LIXONET 3)
2020-04-27 17:30:30 +00:00
This is the semi-official, testing Lixonet EE repository.
2020-04-27 22:18:08 +00:00
Custom configurations should be supplied in a `lixonet.conf` file in the `name=value` format, such as your subnet. Additionally, a tinc keypair is also be required.
2021-09-21 12:41:01 -06:00
# Setup, Installation, and Updating
#### Prerequisites/Setup:
2023-01-08 19:43:54 -07:00
WARNING: On some systems (i.e. Raspberry Pi) with integrated Ethernet, it seems promiscuous (PROMISC) mode is required on your `eth0` (see #1 next). Otherwise you won't see traffic getting passed to the tinc, wireguard, etc. containers from devices in your network.
2023-01-08 19:43:11 -07:00
2021-09-21 12:41:01 -06:00
1. `eth0` is the **LAN** or **WAN** interface supporting external routing, DNS, etc., and is the **bridged** interface to a router that will statically route the entire desired network subnet (i.e. x.x.0.0/21) through it. You may also have an `eth1` (and so on, so forth) that you statically configure for your entire, wide subnet (i.e. x.x.0.0/21) if you want to use two physical adapters. If you do have more than one interface, make sure that `internal_gateway` is set to the router IP address that can route your personal Lixonet subnets, and not your WAN gateway (unless they're the same).
2. `tun` and `tap` are in `/etc/modules` to load at boot (https://www.cyberciti.biz/faq/linux-how-to-load-a-kernel-module-automatically-at-boot-time/) and the system has been rebooted afterwards.
3. IPv4 forwarding is on: `sysctl -w net.ipv4.ip_forward=1`
4. Clone this repository: `git clone <url>`
2021-09-21 12:47:32 -06:00
5. `mkdir /etc/lixonet/(mesh)/` where `(mesh)` is something like `teamlixo` if you're planning to use `teamlixo.mesh`.
6. Fill out `/etc/lixonet/(mesh)/lixonet.conf` (see: **Configuration options**)
7. Supply `/etc/lixonet/(mesh)/tinc.key` (see: **Generating keypairs for tinc**)
2021-09-21 12:48:07 -06:00
8. Supply `/etc/lixonet/id_rsa` and `/etc/lixonet/(mesh)/id_rsa` for each mesh you'll be connected to (see: **Generating SSH keys**). Remember each id_rsa is unique!
2021-09-21 12:47:32 -06:00
9. Supply `/etc/lixonet/known_hosts` (see: **Setting `known_hosts`**)
2021-09-21 12:41:01 -06:00
**Generating keypairs for tinc (`tinc.key`)**:
Source: https://www.tinc-vpn.org/documentation/Generating-keypairs.html
Run: `tincd -n lixonet -K`
2021-09-21 12:45:50 -06:00
**Generating SSH keys (`id_rsa`)**:
1. I recommend PuTTYgen (https://www.puttygen.com/) on Windows, ssh-genkey on Linux.
2. Generate at least **two** keys. One will be for `lixonet-ee`, one will be for whichever repositories you're a part of (i.e. `teamlixo.mesh`).
2021-09-21 12:49:47 -06:00
3. Share the public keys (starting with something like `ssh-rsa`) with the repository owner(s) listed below so they can add a "Deploy key" to the repository for you.
2021-09-21 12:45:50 -06:00
**Setting `known_hosts`**
For GitHub, at this time the contents would be:
```
|1|hW/UPBCtfR0M/2GejxakBvoqGNY=|DXk4SRaJXzawNdHyBe9mrxvWYvk= ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
```
Don't take my word for it, see: https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints
2021-09-21 18:06:00 -06:00
**Optional: Generate a WireGuard key**
You only need to do this if you are setting `wg_enabled`=1, for example when you want to service VPN clients from a "master" node. See **Wireguard Options** for more information on how to do that.
See: https://www.wireguard.com/quickstart/
```
apk add -U wireguard-tools
wg genkey | tee privatekey | wg pubkey > publickey
```
2021-09-21 12:41:01 -06:00
#### Install/Update:
1. Read and follow the prerequisites above and make sure you are ready to install.
2. Clone or navigate to a cloned repository folder you already have.
3. Run `chmod +x install.sh && ./install.sh`
4. Enjoy!
# Configuration options
2020-04-27 22:18:08 +00:00
2020-05-21 20:39:55 +00:00
#### Location
A `lixonet.conf` file should be under each **network** directory you'd like to create. Create one directory for each mesh you'll be joining, under `/etc/lixonet`. If you want to join the `teamlixo` mesh for example, do this:
1. Create `/etc/lixonet/teamlixo/lixonet.conf` and specify at least all **required** options in this file.
2. Create or save `/etc/lixonet/teamlixo/tinc.key`
#### Available networks
Official networks:
| Name | Git clone URL(s) | Subnet | ASN format | Administsration |
| ------ | ------ | ------ | ------ | ------ |
| teamlixo | http://git.team.lixo/lixonet/teamlixo.mesh.git | 172.31.0.0/16 | 4206969XXXX | Manevolent, Nurd |
| colorado | http://git.team.lixo/lixonet/colorado.mesh.git | 172.29.0.0/16 | 4206970XXXX | Manevolent |
#### Format
2020-04-27 22:18:08 +00:00
All options are supplied in the `name=value` format on individual lines, i.e. `name=test_name_lixo`
## Required options
You **MUST** specify these options, or Lixonet will not work.
2020-05-21 20:39:55 +00:00
* `git` - The Git clone repository URL, used for peer configurations.
* `tinc_peer_name` - The global neighbor name. Tinc and Bird use this to identify a peer in the network, and to exclude your own pre-packed config automagically from Tinc and BIRD dialing out so you don't connect to yourself over and over again.
* `tinc_peer_address` - The *router* address to use. This is your Lixonet routing layer address: 172.xxx.0.xxx
* `network_address` - The *network* address to use. This is your Lixonet routing layer address: 172.xxx.0.0 (especially take note of the last two 0's: `0.0` -- it _MUST_ end with zeros corresponding to the network size)
2020-05-21 20:39:55 +00:00
* `bgp_asn` - The BGP ASN to use. We usually follow the format `4206969XXX` where _XXX_ is the last octet of your `address`, zero-padded (i.e. 008 or 212)
* `internal_address` - The internal address to use. MUST be unique to this Lixonet EE instance; if the address of the host is 172.31.16.2, you should _NOT_ use that IP address, and instead pick another static address.
* `internal_gateway` - The internal gateway to use. This is the IP address, directly upstream from the Lixonet EE router, that can be used as a next hop to reach your own subnets.
#### Configuration example
A copy of the live configuration (`/etc/lixonet/teamlixo/lixonet.conf`) used by `denco_mane_lixo`:
```
git=http://git.team.lixo/lixonet/teamlixo.mesh.git
tinc_peer_name=denco_mane_lixo
tinc_peer_address=172.31.0.8
tinc_bind_address=172.31.8.2
bgp_asn=4206969008
bgp_routes=172.31.8.0/21,172.31.254.0/24
network_address=172.31.0.0
netmask=255.255.255.0
internal_gateway=172.31.8.1
```
(A key exists at `/etc/lixonet/teamlixo/tinc.key`)
`cat /etc/network/interfaces`:
```
auto lo
iface lo inet loopback
auto eth0
iface eth0 inet dhcp
hostname lixonet
```
`ifconfig eth0`:
```
lixonet:/home/manevolent# ifconfig eth0
eth0 Link encap:Ethernet HWaddr xx:xx:xx:xx:xx:xx
inet addr:172.31.8.2 Bcast:0.0.0.0 Mask:255.255.255.0
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:313268 errors:0 dropped:0 overruns:0 frame:0
TX packets:266835 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:223824994 (213.4 MiB) TX bytes:145971829 (139.2 MiB)
```
`docker ps -a | grep teamlixo` (built by `./build.sh`):
```
646e3b6b5456 teamlixo_tinc "sh -c '/usr/sbin/ti…" 17 minutes ago Up 15 minutes teamlixo_tinc_1
84fda16f829b teamlixo_bird "/bin/sh -c 'bird -c…" 17 minutes ago Up 9 minutes teamlixo_bird_1
```
2020-05-22 00:26:20 +00:00
`route`
```
Kernel IP routing table
Destination Gateway Genmask Flags Metric Ref Use Iface
default 172.31.8.1 0.0.0.0 UG 202 0 0 eth0
172.17.0.0 * 255.255.0.0 U 0 0 0 docker0
172.18.0.0 * 255.255.0.0 U 0 0 0 br-b91440553ab5
172.31.0.0 * 255.255.255.0 U 0 0 0 teamlixo
172.31.0.0 * 255.255.0.0 ! 32 0 0 *
172.31.8.0 * 255.255.255.0 U 0 0 0 eth0
172.31.8.0 172.31.8.1 255.255.248.0 UG 32 0 0 eth0
172.31.16.0 172.31.0.16 255.255.248.0 UG 32 0 0 teamlixo
172.31.200.0 172.31.0.200 255.255.248.0 UG 32 0 0 teamlixo
172.31.208.0 172.31.0.208 255.255.252.0 UG 32 0 0 teamlixo
172.31.212.0 172.31.0.212 255.255.252.0 UG 32 0 0 teamlixo
172.31.254.0 172.31.8.1 255.255.255.0 UG 32 0 0 eth0
```
(Note the use of the `internal_gateway` variable to set the local `172.31.8.0 172.31.8.1 255.255.248.0 UG 32 0 0 eth0` route!)
## Non-required options:
2020-05-21 20:39:55 +00:00
#### General network options
* `global_prefix`: global network prefix: defaults to `16`.
* `router_prefix`: router network prefix: defaults to `24`. If you change this you _SHOULD_ change `netmask` too.
* `netmask`: router netmask: defaults to `255.255.255.0` (`/24`); _SHOULD_ be the bitmask that corresponds to the `router_prefix`
* `internal_interface`: the interface to route your _OWN_ networks to. This should be the interface where your personal Lixonet subnets are reachable at, or in other words the interface at which the Lixonet EE router can send packets destined to networks you own. Defaults to `eth0`.
* `internal_subnet`: the internal subnet that your Lixonet EE router is connected to, defaults to "`internal_gateway`/24".
* `vip`: virtual IP: a virtual IP address to assign to the Lixonet EE router directly, aside from 172.31.0.8.
2020-05-21 20:39:55 +00:00
#### Tinc options
* `network_name` - The name of the interface that Tinc should create when it's started. Defaults to `lixonet`. Set this for multiple networks.
* `tinc_bind_address` - The address that Tinc should bind to to _listen_ for incoming public Internet connections (i.e. 10.0.0.1). This is _not_ the Lixonet router IP (i.e. 172.31.0.8). Use this if you have an `eth1` that you _don't_ want to use for binding tinc to, and would prefer to bind tinc exclusivley to `eth0` instead. Defaults to `internal_address`.
2020-06-22 00:18:11 +00:00
* `tinc_bind_port` - The Tinc server port to listen on. Defaults to `9994`.
2020-05-21 20:39:55 +00:00
* `tinc_connect_to` - A comma-separated list of well-known/pre-defined hosts to connect to (i.e. `denco_mane_lixo`). If not supplied, this is automatically set to all core routers that aren't yourself (`name`).
#### BGP options
For options we expose here, for information see: https://bird.network.cz/?get_doc&v=20&f=bird-6.html#ss6.3
* `bgp_path_metric`: Enable comparison of path lengths when deciding which BGP route is the best one (`0` or `1`): defaults to `1`
* `bgp_aigp`: BGP AIGP state (`enable`, `disable`, or `originate`): defaults to `originate` (see BIRD documentation)
* `bgp_rpki_retry`: If RPKI cache data cannot be obtained, the time period in seconds between a failed query the next attempt. Defaults to `90`.
* `bgp_rpki_refresh`: How long to wait in seconds before attempting to poll RPKI cache data after the last successful poll. Defaults to `900`.
* `bgp_rpki_expire`: How long to keep any records locally cached before they are deleted. Defaults to `172800` (2 days).
* `bgp_rpki_known_hosts`: The file path for the SSH key `known_hosts` file to use when validating remote RPKI hosts. Defaults to `/etc/bird/rpki/known_hosts` (provided by Lixonet; don't change this unless you need to!).
2020-05-21 05:35:44 +00:00
* `bgp_passwd_*`: The password for a specific BGP peer (i.e. `bgp_passwd_denco_mane_lixo`). If not specified, no password is used for the host.
* `bgp_routes`: A comma-delimited list of route prefixes (CIDR) to advertise to other BGP peers. If not specified, no routes are propagated.
2020-05-21 04:48:14 +00:00
2020-06-13 04:22:42 +00:00
#### BIND options
These settings are optional, and are already defaulted to general network common practices.
2021-09-21 17:28:39 -06:00
* `bind_forward_enable`: Enable BIND DNS forwarding when DNS queries are received from other nodes Lixonet for a domain that you control (i.e. lkwco.mane.lixo on that Lixonet box). `1`/enabled, `0`/disabled. Defaults to `1`.
2020-06-13 04:22:42 +00:00
* `bind_forward_address`: The overridden DNS server IP address to forward all requests for your own domain to. Defaults to the value of `internal_gateway`, which is proper in most if not all cases. Your BIND zone is automatically converted from your `tinc_peer_name` (i.e. `lkwco_mane_lixo` becomes `lkwco.mane.lixo`).
* `tld`: The network-wide TLD to use. Defaults to `lixo`.
#### Wireguard options
2020-06-13 04:22:42 +00:00
2021-09-21 18:06:00 -06:00
Keep in mind that Wireguard is presently an auxilliary satellite connection point. Because of this, you shouldn't re-use any IP addresses related to WG. Consider planning a piece (/32, see `wg_prefix`) of your network (i.e. 172.31.1.z) where `z` is an unused address (or your ASN number, like 8, 16, so on) and setting that to `wg_address`. This is generally only desired on "master" or globally-reachable/hosted nodes to construct an overlay VPN. If a node is hosting WireGuard clients, they can send traffic into other nodes but likely won't receive any traffic back unless `wg_routes` is set so BIRD can export peer addresses into the BGP routing framework.
2020-06-21 06:47:58 +00:00
2021-09-21 15:08:09 -06:00
* `wg_enabled`: Set to 1 to enable WireGuard. Defaults to 0/disabled.
* `wg_key`: Required if `wg_enabled`=1. The private key to use for the Wireguard peering point.
* `wg_address`: Required if `wg_enabled`=1. The address to assign to the Wireguard interface. Should be unique.
* `wg_prefix`: The prefix to assign to Wireguard, defaults to 32.
2021-09-21 15:08:09 -06:00
* `wg_port`: Port for WireGuard to listen to connections on (UDP). Defaults to 51820.
* `wg_routes`: A comma-delimited list of WireGuard route prefixes (CIDR) to advertise to other BGP peers. If not specified, no routes are propagated. If specified, only specific connected WireGuard peers added to the kernel routing table are advertised.
2022-12-22 10:10:41 -07:00
#### IPv6 options (dual-stack)
2022-12-22 12:04:17 -07:00
Enabling IPv6 allows you to be more easily/natively reached by IPv6 native clients such as mobile phones on LTE. Keep in mind this doesn't switch on IPv6 inside the VPN itself. This is typically something you want to do if you are using Wireguard and plan to allow mobile phones to reach you.
2022-12-22 10:10:41 -07:00
* `ipv6_enabled`: Set to `true` to enable IPv6 support. Defaults to `false`.
2022-12-22 10:12:00 -07:00
* `internal_address6`: Optional; if unset, SLAAC is used. Specify a static IPv6 address to bind to `internal_interface`.
2022-12-27 20:26:34 -07:00
* `internal_mask6`: Required if `internal_address6` is set. Specify a static IPv6 subnet mask (i.e. `64` for a /64) that is associated to your `internal_interface`.
2022-12-22 14:52:15 -07:00
* `internal_gateway6`: Required if `internal_address6` is set. Specify a static IPv6 gateway that is reachable at your `internal_interface`.
2024-02-21 22:29:04 -07:00
#### Syslog options
Enabling Syslog allows you to export logs to an remote logging server, coalescing all your logs into one place for easy diagnostics (i.e. Graylog)
2024-02-21 22:38:19 -07:00
Log messages will always be tagged with the format `NETNAME-CONTAINERNAME`, i.e. "teamlixo-tinc" or "teamlixo-bird".
2024-02-21 22:37:23 -07:00
* `syslog_enabled`: Set to `1` to enable Syslog support. Defaults to `0`.
* `syslog_address`: Set to your preferred remote Syslog server, i.e. `udp://192.168.1.1:512`.
* `syslog_format`: Set to your preferred Syslog format. Defaults to `rfc5424micro`, the best option with highest precision, but may not be supported by all Syslog servers (see: https://docs.docker.com/config/containers/logging/syslog/).
* `syslog_facility`: Set to your preferred Syslog facility. Defaults to `news`, AKA 'Network News', a good category for network devices (see: https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1).
2024-02-21 22:29:04 -07:00