From 5ccc62ece239d4900ebf7d506345436d0426ac4f Mon Sep 17 00:00:00 2001 From: DrMaxNix Date: Fri, 16 Aug 2024 23:42:11 +0200 Subject: [PATCH] :memo: document usage --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/README.md b/README.md index 47fc1ad..db5d554 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,84 @@ # XYNat KVM NAT blocking access to local networks + +## Setup Instructions +Install required tools (Debian): +```console +# apt update +# apt install grep sed iptables iproute2 +``` + +Install required tools (Fedora): +```console +# dnf install grep sed iptables iproute2 +``` + +Clone git repository: +```console +# cd /opt +# git clone https://git.tjdev.de/DrMaxNix/xynat.git +``` + +## Usage +``` +Usage: ./xynat [OPTIONS] + +Options: + -a, --add - Add new firewall (default, fallback: MODE=start) + -r, --remove - Remove existing firewall (fallback: MODE=stop) + + -i, --iface=iface - Interface name for virtual switch (required, fallback: IFACE) + -s, --vm-address=ip - IP address of virtual machine (required when adding new fw) + -p, --public-ip=ip - IP address to use for outgoing traffic and DNAT + + -b, --block=ip-or-net - Block address(es) for all connections (multi-use allowed) + + -w, --allow=ip-or-net - Allow local address(es) for all connections (multi-use allowed) + -x, --allow-in=ip-or-net - Allow local address(es) for incomming connections only (multi-use allowed) + -y, --allow-host - Allow local host for all connections + -z, --allow-host-in - Allow local host for incomming connections only + + -h, --help - Display this help message and exit + -v, --version - Display version information and exit + +Examples: + Add a new firewall and NAT for a VM which has IP address '192.168.234.2' and is a member of the bridge interface 'br2' + All traffic to and from local addresses will be blocked; Traffic to public addresses will be allowed + ./xynat --add --iface "br2" --vm-address "192.168.234.2" + + Same as first example, but use '192.168.123.99' as source address for outgoing connections + ./xynat --add --iface "br2" --vm-address "192.168.234.2" --public-ip "192.168.123.99" + + Same as first example, but also block all traffic to and from '233.252.0.0/24' + ./xynat --add --iface "br2" --vm-address "192.168.234.2" --block "233.252.0.0/24" + + Same as second example, but allow incomming and outgoing connections from host device + The VM will also be accessible from devices in '192.168.137.64/30' via its public address + ./xynat --add --iface "br2" --vm-address "192.168.234.2" --public-ip "192.168.123.99" --allow-host --allow-in "192.168.137.64/30" + + Remove all firewall and NAT rules for iface 'br2' + ./xynat --remove --iface "br2" +``` + +## Example `/etc/network/interfaces` +#### Host +```bash +auto br-vm-test +iface br-vm-test inet static + bridge_ports none + address 192.168.234.1 + network 192.168.234.0 + netmask 255.255.255.252 + pre-up /opt/xynat/xynat -s 192.168.234.2 -p 10.0.0.4 -x 10.0.0.0/8 -z + post-down /opt/xynat/xynat +``` + +#### Guest +```bash +auto eth0 +iface eth0 inet static + address 192.168.234.2 + network 192.168.234.0 + netmask 255.255.255.252 + gateway 192.168.234.1 +```