pybatmesh/README.md

# naxalnet

**naxalnet** is a program to create a wireless mesh network for
communicating with each other. It can be useful during an
[internet shutdown](#internet-shutdown), or to join
[online classes](#online-class) with a group of laptops.
It uses [B.A.T.M.A.N. Advanced][batman-adv], an implementation
of the B.A.T.M.A.N. routing protocol to communicate with peers.
The name naxal comes from Naxalbari, a village in Darjeeling,
West Bengal.

WARNING:
This program uses an **unencrypted** network. This means
you do not get any more privacy or security than with an open WiFi
network.

<!-- NOTE TO ACTIVISTS

Running this program in the world's largest (partly-free) democracy
may result in you getting arrested under the Act Which Must Not Be Named,
and not getting bail because of false evidence planted in your phone by
Pegasus, or by a forensic lab in Gujarat.

The author, much like the GoI, does not wish to take responsibility in your
well-being if you get arrested under a draconian national security law.

-->
<!-- UNCOMMENT WHEN NECESSARY

**Disclaimer**:
In case you are either 1) a complete idiot; or 2) a member of the saffron
brigade; or 3) both, please be aware that this project is not affiliated
with any human rights groups designated as "terrorist" groups in India.

Using the name naxal does not imply any form of connection
with anyone currently at risk of death in overcrowded prisons.

-->

## Requirements

- [systemd-networkd v248 or more][batman-systemd]
- Linux kernel with batman-adv module
- [iwd][] for controlling the WiFi adapter
- python3
- python3-setuptools, for building and installing naxalnet
- [python-systemd][], for logging to systemd journal
- [dasbus][], for communicating with iwd
- two or more machines with a WiFi adapter having ibss support, called
  nodes or peers
- batctl (optional, for debugging)
- python3-pip (for installing dasbus on Debian-based distributions)

## Installing

This program is available in the AUR for Arch users. Building
manually for other distributions may not always work.

### Arch Linux

Install [naxalnet][aur] (or [naxalnet-git][aur-devel] for the
development version) from the AUR with your favourite helper:

```sh
yay -S naxalnet
```

Optionally, [setup systemd-resolved][arch-resolved] for DNS if any
of the nodes have internet access. [Start naxalnet][startnx] when
you need it.

### Ubuntu

naxalnet is not packaged for Ubuntu, so you will have to build
and install it manually.
Currently, only the **unreleased 21.10** comes with the
required version of systemd. Therefore, naxalnet **won't work on Ubuntu
21.04 or older**.

<!-- TODO: remove this message if systemd 248 arrives in 21.04 -->

Install the requirements from the Ubuntu repositories:

```sh
# batctl is optional
sudo apt install python3-pip python3-systemd iwd batctl build-essential
# Now, install dasbus with pip
sudo pip3 install dasbus
```

Now follow the instructions in the
[manual installation section][install-manual]

### Fedora

naxalnet is not packaged for Fedora, so it should be installed
manually. naxalnet requires atleast systemd v248 which is only
available on **Fedora 34 and above**. Install the dependencies:

```sh
# systemd-resolved may be required for rawhide
sudo dnf install systemd-networkd iwd python3-dasbus python3-setuptools python3-systemd
```

Now head over to the [next section][install-manual] to install naxalnet.

### Manually

Install the [requirements][requirements].

Clone the naxalnet repo and cd into it.

```sh
git clone https://git.disroot.org/pranav/naxalnet.git
cd naxalnet
```

Now, build and install naxalnet:

```sh
make
sudo make install
```

After installing, reload systemd so that it detects the new
service files:

```sh
sudo systemctl daemon-reload
```

To upgrade, clean the build files, update the repo and reinstall:

```sh
make clean
git pull
make
sudo make uninstall install
```

This will keep the configuration files.

## How to use

You need more than one machine running naxalnet for the connection to work.

### Start naxalnet

Though naxalnet can run from the command line, it was designed to be
run as a systemd service.
To start naxalnet, do the command on all the nodes:

```sh
sudo systemctl start naxalnet.service
```

This will start a mesh network and connect to all nodes.
To test if it works, run `sudo batctl n -w` and check for
nodes. If there are any nodes, your network is up. Press
Ctrl+C to stop `batctl`.

### Getting internet access

Connect an ethernet cable from a router to any of the nodes and
renew the DHCP connection of all peers. To do this, type
`sudo networkctl renew bridge0` on all nodes.

### Tethering via WiFi AP

If there are two adapters in a peer, naxalnet will start a
WiFi ap (also called WiFi hotspot) on one of them.

Connect two WiFi adapters on a node.
Now an AP will be started on one of the adapters.
Type `naxalnet --print-wifi` to get the WiFi SSID and password.

If you had set up internet access on one of the nodes, internet
can be accessed from the AP.

### Running at boot

To run naxalnet at boot, enable the service on all the nodes:

```sh
sudo systemctl enable naxalnet.service
```

Now naxalnet will start a mesh on every boot.
Disable the service to stop running at boot:

```sh
sudo systemctl disable naxalnet.service
```

### Stopping the service

```sh
sudo systemctl stop naxalnet iwd systemd-networkd systemd-resolved
```

If your distribution uses NetworkManager, starting `naxalnet.service`
will have stopped it. Start NetworkManager again:

```sh
sudo systemctl start NetworkManager.service
```

### Configuration

naxalnet comes with a sample configuration file
`/etc/naxalnet/naxalnet.conf.example`. To change how the program
behaves, copy it to /etc/naxalnet/naxalnet.conf and edit it:

```sh
sudo cp /etc/naxalnet/naxalnet.conf{.example,}
# Now edit the file with your favourite editor as root
gedit admin:/etc/naxalnet/naxalnet.conf
```

Also, you can change its behaviour every time you run it using
arguments:

```sh
naxalnet --help
```

## How it works

There are three modes commonly supported by WiFi adapters - `ap` (WiFi
hotspot), `station` (for joining WiFi networks) and `ad-hoc` (or ibss, for
decentralised networks). There are other modes supported by some WiFi
adapters too, like `p2p` (WiFi direct), but this program doesn't use them.

naxalnet uses two modes - `ad-hoc` and `ap`, for connecting to the
mesh. naxalnet uses iwd to start an `ad-hoc` network and configures
systemd-networkd to setup a BATMAN Advanced network.
If there are two WiFi adapters connected to the machine,
naxalnet starts an ad-hoc on one of them and an ap on the other.
You can use the ap for connecting mobile phones and other devices
to the mesh network.

Read the code and the documentation in the code to learn the details.
See the directory [systemd-networkd](systemd-networkd) to see how
systemd-networkd configures the network.

## Use cases

### Online class

naxalnet can be used to share connections to join online classes.
You need at least one device with internet access.

<!--

### Malign democracies and well-established institutions

Withheld due to national security reasons.

-->

### Internet shutdown

You can communicate with neighbouring devices running naxalnet, using
services like [IPFS][], [Jami][], [Secure Scuttlebutt][ssb] and others
which can work on an intranet. They should be installed on your
machine _before_ your friendly democratic government announces an
[internet shutdown][], since you cannot download and install them
during a shutdown. When a shutdown occurs, [enable naxalnet][enablenx].

## Uninstalling

If you installed naxalnet manually, use make uninstall to remove
naxalnet and its data files. This requires python pip to be installed.

```sh
# Uninstall the program, keeping the config files
sudo make uninstall
# Or, to uninstall and remove config files
sudo make purge
```

## Contributing or reporting bugs

See [HACKING.md](HACKING.md)

## Similar projects

Many projects make setting up B.A.T.M.A.N. Advanced mesh networks with
WiFi routers easier. They are easier to setup and are more
configurable. But naxalnet is different from them. It simplifies
setting up mesh networks with _laptops or computers_, and was not
made to work with routers.

The following projects does something similar to naxalnet, but
requires special devices or routers to work. If you live in an area
where the materials are easily available, consider using them instead
of naxalnet.

- [LibreMesh][]: framework for OpenWrt-based firmwares
- [disaster.radio][]: solar-powered communications network

## License

naxalnet is [free/libre/swatantra][free-sw] and open source software;
you can redistribute it and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation,
eitherversion 3 of the License, or (at your option) any later version.

See [LICENSE](LICENSE) for the complete version of the license.

[batman-adv]: https://www.open-mesh.org/projects/batman-adv/wiki
[internet shutdown]: https://internetshutdowns.in
[ipfs]: https://ipfs.io "InterPlanetary File System"
[jami]: https://jami.net "Peer to peer video calls"
[ssb]: https://scuttlebutt.nz "Secure Scuttlebutt"
[dasbus]: https://github.com/rhinstaller/dasbus "A python D-Bus library"
[aur]: https://aur.archlinux.org/packages/naxalnet
[aur-devel]: https://aur.archlinux.org/packages/naxalnet-git
[arch-resolved]: https://wiki.archlinux.org/title/Systemd-resolved#DNS "systemd-resolved on ArchWiki"
[batman-systemd]: https://www.open-mesh.org/news/101 "systemd v248 brings support for batman advanced"
[libremesh]: https://libremesh.org
[disaster.radio]: https://disaster.radio
[startnx]: #start-naxalnet
[iwd]: https://iwd.wiki.kernel.org "WiFi daemon"
[free-sw]: https://gnu.org/philosophy/free-sw.html "What is free software?"
[enablenx]: #running-at-boot
[requirements]: #requirements
[install-manual]: #manually
[python-systemd]: https://github.com/systemd/python-systemd