<commit_before>![PIRANHA](https://i.imgur.com/kHWUNOu.png)

## Voucher and Captive Portal solution for community networks

This tool allows an administrator to manage a voucher system to get through the gateway.

It could be used in a community that wants to share an Internet connection and for that the user's pay a fraction each, but needs the payment from everyone. So the vouchers allows to control the payments via the control of the access to Internet.

## Features

This are the currently implemented features:
  * Runs directly from the OpenWRT/LEDE router: no need for extra hardware
  * Integrates it's administration with Ubus and LiMe App
  * Has a command-line interface for listing, creating and removing vouchers
  * Voucher database is shared among nodes in the network

## Prerequisites

This software assumes that will be running on a OpenWRT/LEDE distribution (because uses uci for config). Needs `ip6tables-mod-nat` and `ipset` packages installed.

## Install

  * add the libremesh software feed to opkg
  * opkg install pirania
  * opkg install pirania-app

## Command line

`epoc` is expressed in [Unix Timestamp](https://en.wikipedia.org/wiki/Unix_time) format. You can use a tool like [unixtimestamp.com](https://www.unixtimestamp.com/) to get a date in the correct format.

### `captive_portal status`

Prints the status of pirania: enabled or disabled.

### `captive_portal start`

Starts pirania. If you want pirania to automatically turn on use: `uci set pirania.base_config.enabled=1 && uci commit`

### `captive_portal stop`

Stops pirania. If you want pirania to stop automatically turning on use: `uci set pirania.base_config.enabled=0 && uci commit`

#### `voucher show`

Lists all the vouchers.

### `voucher show_active`

List all the vouchers that are currently active.

### `voucher add`

Create a new voucher. This voucher will start deactivated and not bonded to any device.

Params:
- `name`: a name used to identify the voucher
- `secret-code`: the voucher secret (password)
- `expiration-date`: date (unix time) that the voucher will expire

Ex.: `voucher add my-voucher-name voucher-secret 1619126965`

### `voucher activate`

Activates a voucher, asigning a mac address. After the activation, the device with this MAC
address will have internet access.

Params:
- `secret-code`: the password of the voucher.
- `mac`: the MAC address of the device that will have access.

Ex: `voucher activate mysecret 00:11:22:33:44:55`

### `voucher deactivate`

Deactivate a voucher of the specified `ID`.

Params:
- `ID`: a string used to identify the voucher.

Ex: `voucher deactivate Qzt3WF`


### `voucher remove_voucher`

Invalidates a voucher by changing it's expire date to 0.

Params:
- `voucher`: voucher secret

Ex.: `voucher remove_voucher voucher-secret`

### `voucher is_mac_authorized`

Check if a specific mac address is authorized.

Params:
- `mac`: a device's mac address

Ex.: `voucher is_mac_authorized d0:82:7a:49:e2:37`


### `voucher renew_voucher`

Check if a specific mac address is authorized.

Params:
- `id`: the voucher ID.
- `expiration-date`: the new date (unix time) that the voucher will expire

Ex.: `voucher renew_voucher Qzt3WF 1619126965`


# How it works

It uses iptables rules to filter inbound connections outside the mesh network.<commit_msg>pirania: fix renew_voucher readme doc<commit_after>![PIRANHA](https://i.imgur.com/kHWUNOu.png)

## Voucher and Captive Portal solution for community networks

This tool allows an administrator to manage a voucher system to get through the gateway.

It could be used in a community that wants to share an Internet connection and for that the user's pay a fraction each, but needs the payment from everyone. So the vouchers allows to control the payments via the control of the access to Internet.

## Features

This are the currently implemented features:
  * Runs directly from the OpenWRT/LEDE router: no need for extra hardware
  * Integrates it's administration with Ubus and LiMe App
  * Has a command-line interface for listing, creating and removing vouchers
  * Voucher database is shared among nodes in the network

## Prerequisites

This software assumes that will be running on a OpenWRT/LEDE distribution (because uses uci for config). Needs `ip6tables-mod-nat` and `ipset` packages installed.

## Install

  * add the libremesh software feed to opkg
  * opkg install pirania
  * opkg install pirania-app

## Command line

`epoc` is expressed in [Unix Timestamp](https://en.wikipedia.org/wiki/Unix_time) format. You can use a tool like [unixtimestamp.com](https://www.unixtimestamp.com/) to get a date in the correct format.

### `captive_portal status`

Prints the status of pirania: enabled or disabled.

### `captive_portal start`

Starts pirania. If you want pirania to automatically turn on use: `uci set pirania.base_config.enabled=1 && uci commit`

### `captive_portal stop`

Stops pirania. If you want pirania to stop automatically turning on use: `uci set pirania.base_config.enabled=0 && uci commit`

#### `voucher show`

Lists all the vouchers.

### `voucher show_active`

List all the vouchers that are currently active.

### `voucher add`

Create a new voucher. This voucher will start deactivated and not bonded to any device.

Params:
- `name`: a name used to identify the voucher
- `secret-code`: the voucher secret (password)
- `expiration-date`: date (unix time) that the voucher will expire

Ex.: `voucher add my-voucher-name voucher-secret 1619126965`

### `voucher activate`

Activates a voucher, asigning a mac address. After the activation, the device with this MAC
address will have internet access.

Params:
- `secret-code`: the password of the voucher.
- `mac`: the MAC address of the device that will have access.

Ex: `voucher activate mysecret 00:11:22:33:44:55`

### `voucher deactivate`

Deactivate a voucher of the specified `ID`.

Params:
- `ID`: a string used to identify the voucher.

Ex: `voucher deactivate Qzt3WF`


### `voucher remove_voucher`

Invalidates a voucher by changing it's expire date to 0.

Params:
- `voucher`: voucher secret

Ex.: `voucher remove_voucher voucher-secret`

### `voucher is_mac_authorized`

Check if a specific mac address is authorized.

Params:
- `mac`: a device's mac address

Ex.: `voucher is_mac_authorized d0:82:7a:49:e2:37`


### `voucher renew_voucher`

Change the expiration date of a voucher.

Params:
- `id`: the voucher ID.
- `expiration-date`: the new date (unix time) that the voucher will expire

Ex.: `voucher renew_voucher Qzt3WF 1619126965`


# How it works

It uses iptables rules to filter inbound connections outside the mesh network.
{'fraction_non_alphanumeric': 0.08167870036101083, 'fraction_numerical': 0.014139590854392299, 'mean_word_length': 4.423327895595432, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '784444', 'n_tokens_mistral': 2170, 'n_tokens_neox': 2028, 'n_words': 876}