Repository files navigation

Make your Raspberry Pi a vSIX access router with cloud-init.

NOTE: This cloud-config is for Raspberry Pi - might work on other Ubuntu machines as well but not guaranteed.

vSIX Pi is a Raspberry Pi-based broadband router officially maintained by vSIX Project. It supports the following features as of September 1, 2021, making it easy for anyone to experience Internet access via vSIX - AS4690.

• Connect to vSIX directly through NGN - no need to pay your ISP anymore. Connection through the WIDE-BB is also supported
• Living in a multi-prefix network - connect to two or more tunnel providers simultaneously and advertise multiple prefixes with RA
• Use with wireless - your Pi become a fast Wi-Fi access point supporting 11n/ac
• Use with wired - support Ethernet connection via additional USB NICs or tagged VLAN on the onboard NIC

You need to be a member of vSIX Working Group - readour website carefully and get the invitation from us.

Apply the Generic Tunneling Access Service fromvSIX Portal, and get the IPv6 prefixes delegated. The following information is needed to set up vSIX Pi; all of them are displayed on the Portal.

• Your global IPv6 address - customer endpoint (CE) address, also needed for the prior submission. Typically, this address is allocated from your ISP (VNE)
• IPv6 addresses of each tunnel provider - provider endpoint (PE) addresses
• Delegated IPv6 prefixes of each site -/60 of address space is allocated for every PE

Prepare a Raspberry Pi. The authors, the vSIX Access Service Team, tested using the series 4B with 2GB of RAM and 16GB of storage. It might also work with the series 3B, although Wi-Fi and Ethernet performance would be degraded - checkhardware specifications of your Pi. In summary, the minimum system requirements are as follows:

• Ubuntu Server 20.04 and later installed onseries 3B and later
• More than1GB of RAM
• More than8GB of SD card capacity

Thanks tocloud-init, installation and setup procedures are fully automated. All you have to do is1) edit a simple configuration file in YAML format and2) type a single command to generate cloud-config.

First, shallow clone this repository and install dependent libraries with:

% git clone --depth 1 https://github.com/wide-vsix/cloud-init-vsixpi% cd cloud-init-vsixpi% pipenv update

Next, override the example variables adjusting with your environment. Follow the instructions in the comments carefully.

% cp vsixpi.yml.example vsixpi.yml% vim vsixpi.yml

Finally, build the cloud-config templates - the outputs are in thecloud-config directory.

% pipenv run generate% bat cloud-config/user-data -l yaml

Download the latest Ubuntu Server fromhere - the LTS release is recommended, but totally up to you. Then extract.xz archive and burn your SD card.

For macOS users, this is like the following:

% diskutil list                         # Check where the SD card is mounted% sudo diskutil unmountDisk /dev/disk2  # Suppose /dev/disk2 is the SD card% # Specify target path as /dev/rdisk2 instead of /dev/disk2 - it will fasten the writing% sudo gdd bs=16M status=progress if=./ubuntu-20.04.2-preinstalled-server-arm64+raspi.img of=/dev/rdisk2

When the writing is completed, the SD card will be remounted assystem-boot. Copy all the files under thecloud-config directory to this area and overwrite the default cloud-config.

Connect LAN cable to the onboard NIC, insert the SD card, and turn on the power. cloud-init is called during the initial boot sequence, and this is why the first startup takes a relatively long time - it is about 30 minutes in the author's environment, though it depends mainly on your network bandwidth. Note that your Pi will automatically reboot once during the cloud-init setup. Hang tight until the console is entirely silent.

You will see a Wi-Fi named VSIX-FREE-WIFI by default. If you connect it withAdios,IPv4!, RDNSS will complete the address configuration and ready you to experience the vSIX access service - of course, you can change the SSID and password. Welcome to vSIX! Let's test your connectivity attest-ipv6.com.

FYI:iNonius Project provides the speed test service for both IPv4 and IPv6.

If you need further assistance, don't hesitate to ask questions at#helpme of our Slack. The vSIX developers will support you one by one for any kind of request.

Below are hints and tips for the advanced use of vSIX Pi.

Open your favorite browser and go tohttp://vsixpi.local:19999 to seeNetdata monitoring dashboard.

ATTENTION: If you would like to help us improve our service quality, please run the following command on your Pi. Netbox will send your Pi's metrics to our account, enabling us to detect the deterioration quickly.

% sudo docker exec -it netdata netdata-claim.sh \    -token=HMWaSQ0c3eTe_NE3qXW2RNi8uK5aWKRvY__pO8Z8rcIKsd90duT4zzeHqHGV8phaKzp-7QGK1-o9RIEPNL_nH1j_eD6xL_lubBBKoYYcXOqJThubqomLNwm4gE-1x56yFSNvJpk \    -rooms=0e12b8e6-bf96-4d10-aabd-a3f0976f43de,7a52dc34-6231-4dee-8fb2-fd7259b77e3f \    -url=https://app.netdata.cloud

The following updates can be applied by editing thevsixpi.yml:

• Change CE address and PE addresses - discarding or moving tunnels
• Change SSID, passphrase, and radio channel
• Change VLAN ID of the onboard NIC, install or uninstall USB Ethernet adapters
• Change RA related parameters as well as MTU and TCP MSS Clamping

Remember to reboot after the reconfiguration; otherwise, the system will be unstable, or some configuration will not be applied appropriately.

% cd /var/lib/vsixpi% sudo vim vsixpi.yml% sudo pipenv run reconfigure% sudo reboot

CAUTION: This operation is destructive - it overwrites each configuration file, and any manual changes made to them will be lost.

If you need to regenerate all configurations every before shutdown automatically, useauto_reconf: yes invsixpi.yml and type:

% sudo systemctl enable --now vsixpi-auto-reconf.service

This option is advantageous if you don't know much about Linux and don't want to touch anything butvsixpi.yml.

Checkissues andpull requests as well.

• Perform periodical health checks from vSIX Pis to automatically detect failures of the access service or backbone network - currently being undertaken and developed with the@SINDAN project
• Selective RA based on an automatic tunnel quality measurement for IPv6 multi-prefix environment

• Currently, the auto-reconfiguration feature doesn't work. We're trying to fix the bugs, and kindly follow the abovemanual reconfigure procedure for the time being Fixed byPull Request #11 and available inv21.09.06 and later releases

This repository is maintained by the vSIX Access Service Team and supported by many volunteers. Followings are responsible for reviewing pull requests:

• miya -Author of the initial release@mi2428
• hide -Co-author of the initial release@hdfln

See also the list ofcontributors who participated in this project.

This product is licensed underThe 2-Clause BSD License - see theLICENSE file for details.