snic/README.md

# snic - Switch network interface mode

Toggle between client and router mode on network interface (Linux)

Switch client network interface (NIC), such as eth0 or wlan0, from the default
client mode to router mode. Basically, you can use the selected interface to act as a
router for your other network devices.

In client mode, the interface acts normally, as it does in your daily usage.

In router mode, a DHCP server kicks in and allocated IPv4 addresses for any connected devices which use a DHCP client. This is equivalent to normal home router behavior.

----------------------

## Requirements

- Linux OS

- Software:

    - sudo

        - root permissions required to configure NIC settings

    - bash

        - the main script uses bash environment

    - systemd

        - the core functionality is implemented partly into systemd service files

    - iproute2

        - 'ip' command which is required for NIC configuration

    - dhcp (server)

        - DHCP server is required to allocate IPv4 addresses for connected clients

    - hostapd (for wireless router)

        - hostapd is required to establish a Wi-Fi hotspot (wireless interfaces)

**NOTE:** Although this repository includes PKGBUILD + tar.xz files, this is not dependent on Arch Linux. You can use this repository on other Linux distributions as well. However, you should adapt the settings properly as configuration and file locations may differ.

----------------------

## Files

- snic.sh = main script. See section "Snic main script" below

- snic/ = Snic configuration files. See section "Snic configuration files" below

- systemd/ = Snic systemd service files. See section "systemd service files" below

- conf-templates/ = Snic templates for iptables & hostapd. See section "Templates folder" below

----------------------

## Pre-configuration

### Find your network interfaces

First you need to know which network interfaces you have in your system. You can check the output of `ip address` or `ifconfig` commands or simply take a look into `/sys/class/net` folder.

### Snic main script

Snic main script is a bourne shell script (bash) `snic.sh`. It can be run individually, but for global purposes location such as `/usr/bin/` or `/usr/local/bin` is recommended. If you put the script in these locations (in your $PATH), it is recommended to rename the script from `snic.sh` to `snic` for convenience.

Make sure the main script file is executable, i.e. run `chmod +x snic.sh`

### Snic configuration files

This repository includes some sample configurations for wlan0 and eth0. Please be aware that these network interface names may not be the same you have in your system.

Configuration files of snic should be placed at `/etc/snic/` folder on a Linux system. The *required* files are:

- `/etc/snic/dhcpd4-<nic>.conf`

    - e.g. `/etc/snic/dhcpd4-eth0.conf`

- `/etc/snic/snic-<nic>.conf`

    - e.g. `/etc/snic/snic-eth0.conf`

Please take a look into these files to find correct configuration for your Linux system.

### systemd service files

Additionally, `systemd` service files are usually placed at `/usr/lib/systemd/system/` on a Linux system.

**NOTE:** It is not recommended to `enable` (read: autostart) systemd service files provided by snic! These service files are used by the snic main script for its internal operations.

### Templates folder

This repository includes templates for `iptables.rules` and `hostapd` configuration.

#### iptables.rules

This is a sample `iptables` ruleset file. Change contents as you want. This file includes basic configuration to route traffic from network interface to another one.

#### hostapd.conf

This is a sample `hostapd` configuration file. Change contents as you want. Usually this file is located at `etc/hostapd/hostapd.conf` on Linux system. On some Linux systems, different locations are used.

----------------------

## Usage

The script syntax is as follows:

- `snic <nic> <mode> <wireless (optional)>`

<wireless> parameter is required only for wireless interfaces.

For instance:

- `snic eth0 router`

    - Set eth0 interface to router mode

    - Set a static IPv4 address for eth0, defined in `/etc/snic/snic-eth0.conf`

    - Start DHCP server on subnet where eth0 belongs to.

    - Disable NetworkManager for this interface because it interferes the connection

- `snic eth0 client`

    - Set eth0 interface to client mode

    - Do not set any IPv4 address, let a DHCP server in our network to give one (requires DHCP client daemon on the computer for which eth0 belongs to. Common clients on Linux are `dhcpcd` and `dhclient`)

    - Enable NetworkManager for this interface, let it handle the connection

- `snic wlan0 router wireless`

    - Set wlan0 interface to router mode.

    - Tell snic script that this is a wireless interface (starts hostapd service)

    - Set a static IPv4 address for eth0, defined in `/etc/snic/snic-wlan0.conf`

    - Start DHCP server on the subnet where wlan0 belongs to.

    - Disable NetworkManager for this interface because it interferes the connection

- `snic wlan0 client wireless`

    - Set wlan0 interface to client mode

    - Tell snic script that this is a wireless interface (stops hostapd service)

    - Do not set any IPv4 address, let a DHCP server in our network to give one (requires DHCP client daemon on the computer for which eth0 belongs to. Common clients on Linux are `dhcpcd` and `dhclient`)

    - Enable NetworkManager for this interface, let it handle the connection

----------------------

## Issues

For any connectivity issues, please check the output of following programs/commands:

- program: Wireshark (check traffic of relevant network interfaces)

    - Any weird network traffic such as ARP broadcast requests flooding the whole subnet

- command: `journalctl -xe`

    - Any weird log entries

- command: `route`

    - Network route tables

- command (router mode): `systemctl status snic-dhcpd4@<nic>`

    - Any weird DHCP server log entries

- command (wireless router mode): `systemctl status hostapd`

    - Any weird hostapd log entries

- `ip addr` and/or `ifconfig`

    - Network interface misconfigurations (missing IPv4 addresses or interfaces, etc.)

And double check contents of all relevant snic configuration files described above in "Pre-configuration" section.

## Do not use if...

- **Snic? WTF is it? Useless crap!** Basically, you don't know what the hell snic does, you don't care to find out or you don't find it useful in your setup.

- **Predefined network configuration** Do not use snic for absolutely static Linux network interfaces, in environments where client/router mode switching for a single computer is not required/allowed/recommended

- **DHCP settings are in danger** Be aware that this script may alter your current DHCP server setup. However, your current *DHCP server setup configuration files are **NOT** overwritten (or even touched)* but snic configuration may cause conflicts in your setup, anyway.

Just be careful when adapting snic settings, thank you. Debug your setup if needed.