@ -53,6 +53,10 @@ Of course, people should modify the system, add own scripts, etc ... but if you
*BTW there is a beneficial side effect when updating with a new SD card: You also get rid of any malware or system bloat that happened in the past. You start with a fresh system :)*
## How can I avoid using a prepared blockchain and validate myself?
The torrent and FTP download use a prepared blockchain to kick start the RaspiBlitz. If you want to selft validate you could do this on another more powerful computer and then transfere your own validated blockchain over to the RaspiBlitz. Check the options `Copying from another Computer`&`Cloning from a 2nd HDD` described in the [README](README.md) for more details.
## I have the full blockchain on another computer. How do I copy it to the RaspiBlitz?
Copying a already synced blockchain from another computer (for example your Laptop) can be a quick way to get the RaspiBlitz started. Also that way you synced and verified the blockchain yourself and not trusting the RaspiBlitz FTP/Torrent downloads (dont trust, verify).
@ -85,9 +89,21 @@ You can simply use the HDD of another RaspiBlitz or you prepare a HDD yourself b
* copy an indexed Blockchain into the root folder "bitcoin"
* when your HDD is ready the content of your folder bitcoin should look like this:
```
/bitcoin/blocks
/bitcoin/chainstate
/bitcoin/indexes
```
optional you can add also the testnet data:
To connect the 2nd HDD to the RaspiBlitz, the use of a Y cable to provide extra power is recommended (see optional shopping list). Because the RaspiBlitz cannot run 2 HDDs without extra power. For extra power you can use a battery pack, like in this picture:
```
/bitcoin/testnet3/blocks
/bitcoin/testnet3/chainstate
/bitcoin/testnet3/indexes
```
To connect the 2nd HDD to the RaspiBlitz, the use of a Y cable to provide extra power is recommended (see optional shopping list). Because the RaspiBlitz cannot run 2 HDDs without extra power. For extra power you can use a battery pack (like in picture below) or choose a external HDD with its own power supply.
Also there are first free 3D open source files in this repo in the directory `case.3dprint` that you can selfprint. Those are much simpler then the 'Lightning Shell' and are not finished yet. But feel free to try out and improve - PullRequests welcome.
Also there are first free 3D open source files in this repo in the directory `case.3dprint` that you can selfprint. Those are much simpler then the 'Lightning Shell' and are not finished yet. But feel free to try out and improve - PullRequests welcome.
## Are those "Under-Voltage detected" warnings a problem?
When your USB power adapter for the RaspiBlitz delivers to low power those messages with "Under-Voltage detected" (undervoltage) are shortly seen on the display. If you see those just one or two times thats not OK, but can be in a tolerant window. Nevertheless make sure your USB power adapter can deliver at least 3A. If you still see those warnings maybe get a second USB Power adapter just for the HDD and power the HDD thru a Y-Cable - see https://en.wikipedia.org/wiki/Y-cable#USB
## Why do we need to download the blockchain and not syncing it?
The RaspiBlitz is powered by the RaspberryPi. The processing power of this SingleBoardComputer is too low to make a fast sync of the blockchain from the bitcoin peer to peer network during setup process (validation). To sync and index the complete blockchain could take weeks or even longer. Thats why the RaspiBlitz needs to download a prepared blockchain from another source.
## Is using the perpared SD card image secure?
Using pre-build software almost always shifts trust to the one how build made the binary. But at least you can check with the SHA checksum after download if the image downloaded is really the one offered by the GitHub Repo. To do so make a quick check if your browser is really in the correct GiutHub page and that your HTTPS of the GitHub page is signed by 'DigiCert'. Then compare the SHA-256 string (always next to the download link of the image on the README) with the result of the command `shasum -a 256 [DOWNLOADED-FILE-TO-CHECK]` (Mac/Linux). Still this is not optimal and if at least some people from the community request it, I will consider signing the download as an author for the future.
The best way would be to build the sd card yourself. You use the script `build_sdcard.sh` for it. Take some minutes to check if you see any suspicious in that build script and then follow the [README](README.md#build-the-sd-card-image) on this.
## Is downloading the blockchain from a third party secure?
To download a blockchain from a third party (torrent/ftp) is not optimal and for the future with more cheap & powerfull SingleBoardComputers we could get rid of this 'patch'.
The downloaded Blockchain is pre-indexed and pre-validated. That should be practical secure enough, because if the user gets a "manipulated" blockchain it would not work after setup. The beginning of the downloaded blockchain needs to fit the genesis block (in bitcoind software) and the end of the downloaded blockchain needs not match with the rest of the bitcoin network state - hashes of new block distrubuted within the peer-2-peer network need to match the downloaded blockchain head. So if you downloaded a manipulated blockchain it would simply just dont work in practice. As long as you are not in a total hostile environment where someone would be able to fake a whole network of peers and miners around you - this is secure enough for running a small funded full node to try out the lightning network.
If you dont trust the download or you want to run the RaspiBlitz in a more production like setup (on your own risk) then dont use the torrent/ftp download and choose the option to COPY the blockchain data from a more powerful computer (laptop or desktop) where you synced, veryfied and indexed the blockchain all by your yourself - see [README](README.md#4-copying-from-another-computer) for more details.
## What is the "Base Torrent File"?
Inspired by the website getbitcoinblockchain.com we use one of their base torrent files to have a basic set of blocks - that will not change for the future. This torrent contains most of the data (the big file) and we dont need to change the torrent for a long time. This way the torrent can get establish a wide spread seeding and the torrent network can take the heavy load.
At the moment (Baseiteration=1) this is just the bitcoin blk and rev files up to the number:
- /blocks : 01390
- /testnet3/blocks: 00152
For litecoin (Baseiteration=1) its blk and rev files up to the number:
- /blocks : 00124
The base torrent file should always have the following naming scheme:
So for example the second version of the base torrent for litecoin created on 2018-10-31 would have this name: raspiblitz-litecoin2-2018-10-31-base.torrent
## What is the "Update Torrent File" and how to create it?
All the rest of the files get packaged into a second torrent file. This file will be updated much more often. The seeding is expected to be not that good and download may be slower, but thats OK because its a much smaller file.
This way a good balance between good seeding and up-to-date blockchain can be reached.
To create the Update Torrent file, follow the following step ...
Have a almost 100% synced bitcoind MAINNET with txindex=1 on a RaspiBlitz
(remove all funds from this node - because blockchain get messed with)
Now change to your computer where you package the torrent files and transfere the three directories into your torrent base directory (should be your current working directory):
Now change again to your computer where you package the torrent files and transfere the three directories into your torrent base directory (should be your current working directory):
(Re-)name the "torrent base directory" to the same name as the torrent UPDATE file itself later (without the .torrent ending). The update torrentfile should always have the following naming schema:
*So for exmaple an update torrent created on 2018-12-24 for litecoin that is an update to the second base torrent version would have this name: raspiblitz-litecoin2-2018-12-24-update.torrent*
Now open your torrent client (e.g. qTorrent for OSX) and create a new torrent-file with the freshly renamed "torrent base directory" as source directory.
Add this list of trackers to your torrent and start seeding (keep a free/empty line between the three single trackers):
```
udp://tracker.justseed.it:1337
udp://tracker.coppersurfer.tk:6969/announce
udp://open.demonii.si:1337/announce
udp://denis.stalker.upeer.me:6969/announce
```
After successful crreation of the torrent file:
* copy to `/home.admin/assets`
* push to master
* change in `50torrentHDD.sh script`
* add to Torrent-[RSS](https://github.com/rootzoll/raspiblitz/issues/285#issuecomment-457796120)
* seed at home and at services like justseed.it
* update [issue](https://github.com/rootzoll/raspiblitz/issues/285#issuecomment-457796120) and ask on twitter for help on seeding
## What is the process of creating a new sd card image release?
Work Nodes for the process of producing a new sd card image release:
* Start `Ubuntu LIVE` from USB stick on Build Computer (press F12 on startup)
* Connect secure WIFI (hardware switch on)
* Download latest Raspbian Desktop (without recommended software) from [raspberrypi.org](https://www.raspberrypi.org/downloads/raspbian/) to the NTFS formatted data USB stick
* Open terminal and compare checksum `shasum -a 256 /media/ubuntu/...[DOWNLOADED-RASPBIAN]`
* Use in file manager context on NTFS USB stick `extract here` to unzip
* Connect sd card reader with 8GB sd card
* Use in file manager context on img-file `write image` write to sd card
* Use in file manager context on `boot` drive free space `open in terminal`
* Run command `touch ssh`
* Close terminal and eject `boot`
* Connect a RaspiBlitz (without HDD) to network, insert sd card and power up
* Login new with `ssh admin@[IP-OF-RASPIBLITZ]` (pw:raspiblitz) and run `./XXprepareRelease.sh`
* Deconnect Wifi on build laptop (hardware switch off) and shutdown
* Remove `Ubuntu LIVE` USB stick and replace with `Ubuntu AIRGAP`
* PowerOn Build Laptop (press F12 for boot menu)
* Cut Power of RaspiBlitz, remove sd card and connect with sd card reader to build laptop
* Open `Disks` manager, select sd card and choose `Create Disk Image` (right upper corner window)
* Store image to NTFS USB stick (click to start can take a while - enter password)
* Open in File Manager the NTFS USB Stick, context menu the created IMG file `compress`
* Name it: `raspiblitz-vX.X-YEAR-MONTH-DAY.img.zip`
* Delete all IMG files from NTFS (just keep zips)
* Context on white space, `Open in Terminal`, run `shasum -a 256 [NEW-ZIP] > sha256.txt`
* [Do future author signing here with tools from airgap build machine]
* Shutdown build computer
* Connect NTFS USB stick to MacOS (its just readonly)
* Run tests with new image
* Upload new image to Download Server
* Copy SHA256-String into GutHub README and update downloadlink
## Can I run RaspiBlitz on other computers than RaspberryPi?
There is an experimental section in this GitHub that tries to build for other SingleBoardComputers. Feel free to try it out and share your experience: [dietpi/README.md](dietpi/README.md)
## Is it possible to connect over Wifi instead of using a LAN cable?
A LAN cable is recommended because it reduces a possible source of error on the network connection side. But how to setup WLAN when you dont have a LAN-Router/Switch available see here:
## How to setup fresh/clean/reset and not getting into recovery mode?
When you put in a sd card with a new/clean RaspiBlitz image the RaspiBlitz will get into recovery mode because it detects the old data on your HDD and assumes you just want to continue to work with this data.
But there might be cases where you want to start a totally fresh/clean RaspiBlitz from the beginning. To do so you need to delete the old data from the HDD. You can do so by formating it on another computer (for example with FAT and name it "NEW"). Or when you can run the script "/home/admin/XXcleanHD.sh -all" on the terminal.
When the HDD is clean, then flash a new RaspiBlitz sd card and your setup should start fresh.
*Build your own Lightning Node on a RaspberryPi with a nice Display.*
`Version 1.0 with lnd 0.5.1-beta and bitcoin 0.17.0.1 or litecoin 0.16.3.`
`Version 1.0 with lnd 0.5.2-beta and bitcoin 0.17.0.1 or litecoin 0.16.3.`
*The RaspiBlitz is a all-switches-on Lightning Node based on LND running together with a Bitcoin- or Litecoin-Fullnode running on a RaspberryPi3 with a 1TB HDD and an nice Display for easy setup and monitoring. Its mainly targeted for learning how to run your own decntralized Node from home. Discover & develop the growing ecosystem of the Lightning Network by becoming a part of it.*
**The RaspiBlitz is a all-switches-on Lightning Node based on LND running together with a Bitcoin- or Litecoin-Fullnode on a RaspberryPi3 - with a 1TB HDD and an nice Display for easy setup & monitoring.**
Its mainly targeted for learning how to run your own node decentralized from home. Discover & develop the growing ecosystem of the Lightning Network by becoming a part of it.
## Feature Overview
This is a quick look at the SSH main menu (once RaspiBlitz is SetUp):
There are additional services that can be switched on:
As an parallel alternative to the SSH menu there is also the RTL WebUI available (LND API Coverage at 57%):
See more details in the [Feature Documentation](#feature-documentation) & of course you have all the [Fullnode APIs](#interface--apis).
## Time Estimate to Setup a RaspiBlitz
The RaspiBlitz is optimized for being Setup during a workshop at hackdays or conference. When it comes ready assembled together with a up-to-date synced HDD containing the blockchain its possible to have it ready in about 2 to 3 hours.
The RaspiBlitz is optimized for being setup during a workshop at a hackday or conference. When it comes ready assembled together with a up-to-date synced blockchain its possible to have it ready in about 2 to 3 hours - most is waiting time.
If you start at home ordering the parts from Amazon (see shopping list below) then its a weekend project with a lot of download and syncing time where you can do other stuff while checking on the progress from time to time.
@ -24,13 +42,11 @@ The RaspiBlitz is build from the following parts:
* Cheap Casing
* LCD-Display
**Total Price: Under 150 USD / 130 EUR (depending on country & shop)**
* [What other case options do I have?](FAQ.md#what-other-case-options-do-i-have)
**All together under 150 USD / 130 EUR (depending on country & shop)**
## Amazon Shopping Lists
These are the community currated shopping lists based in country:
These are the community currated shopping lists based on country:
@ -43,6 +59,8 @@ These are the community currated shopping lists based in country:
*You can even pay your RaspiBlitz Amazon Shopping with Bitcoin & Lightning thru [Bitrefill](https://blog.bitrefill.com/its-here-buy-amazon-vouchers-with-bitcoin-on-bitrefill-bb2a4449724a).*
* [What other case options do I have?](FAQ.md#what-other-case-options-do-i-have)
## Assemble your RaspiBlitz
If your RaspiBlitz is not assembled yet, put the RaspberryPi board into the case and add the display like in picture below:
@ -85,23 +103,21 @@ So open up a [terminal](https://www.youtube.com/watch?v=5XgBd6rjuDQ) and connect
## Support
Fore more details on the setup process see the documentation below. If you run into a problem or you have still a question, follow these steps to get support:
If you run into a problem or you have still a question, follow the steps below to get support. Also check the [setup documentation](#setup-process-detailed-documentation) for details.
1. Check the [FAQ](FAQ.md) if you can find an answere to this question/problem.
1. Lookup the [FAQ](FAQ.md) if you can find an answere to this question/problem.
2. Please determine if your problem/question is about RaspiBlitz or for example with LND. For example if you cant route a payment or get an error when opening a channel that is an LND question/problem an is best answered by the LND dev community: https://dev.lightning.community
3. Go to the GitHub issues of the RaspiBlitz: https://github.com/rootzoll/raspiblitz/issues Do a search there. Also check closed issues by removing 'is:open' from the filter/search-box.
4. If you havent found an answere yet, open a new issue on the RaspiBlitz GitHub. You may have to register an account with GitHub for this. If its a bug with the RaspiBlitz, please add (copy+paste) a Debug Report to your issue (see [FAQ](FAQ.md) how to generate) and/or add some screenshots/photios so the community gets more insight into your problem.
4. If you havent found an answere yet, open a new issue on the RaspiBlitz GitHub. You may have to register an account with GitHub for this. If its a bug with the RaspiBlitz, please add (copy+paste) a Debug Report to your issue (see [FAQ](FAQ.md) how to generate) and/or add some screenshots/photos so the community gets more insight into your problem.
## Documentation
### Setup Process
## Setup Process (Detailed Documentation)
*The goal is, that all information needed is provided from the interaction with the RaspiBlitz itself during the setup. Documentation in this chapter is for background, comments for educators and to mention edge cases.*
#### Init
### Init
Automatically after login per SSH as admin to the RaspiBlitz, the user can choose if the RaspiBlitz should run Bitcoin or Litecoin with Lightning:
@ -143,123 +159,346 @@ After this the setup process will need some time and the user will see a lot of
*Background: After the user interaction the following scripts are started to automatically setup the RaspiBlitz:*
#### Getting the Blockchain
### Getting the Blockchain
The following screen is just shown if the HDD was not prepared with a copy of the Bitcoin blockchain (as part of a ready-2-go set).
*If you have a HDD with a prepared blockchain (e.g. a ready2go-set or you are at a workshop) you can skip to the [next chapter](#setup-lightning). If you started with an empty HDD - you will see the following screen:*
To get a copy of the blockchain, the RaspiBlitz offers the following options:
The options - and when to choose which - will be explained here shortly:
#### 1. Torrent
This is the default way to download the blockchain data for the RaspiBlitz. If you choose it will show you the following screen:
The options - and when to choose - will be explained here shortly:
##### Torrent
*This can take a while - normally it should be done if you keep it running over night, but some users reported that it took up to 3 days. If it takes longer than that or you cannot see any progress (downloading starting) for over an hour after you started thsi option consider to cancel the download and choose the FTP download option.*
TODO
It is safe to close the terminal window (shutdown your laptop) while the RaspiBlitz is doing the torrent download. To check on progress and to continue the setup you need to ssh back in again.
##### FTP-Download
You can cancel the torrent download by keeping the key `x` pressed. Then the download will stop and you will be asked if you want to keep the progress so far. This makes sense if you need to shutdown the RaspiBlitz and you want to continue later or when you want to try another download option but want to keep the option to continue on torrent if the other option is slower or not working.
TODO
* [How can I avoid using a prepared blockchain and validate myself?](FAQ.md#how-can-i-avoid-using-a-prepared-blockchain-and-validate-myself)
##### Copying from another Computer
#### 2. FTP-Download
TODO
You should try the FTP download if the torrent option is not working for you. Please be aware that the files are hosted on a central server by us and up-time and bandwidth is not guaranteed. If you start it, you should see the following screen:
##### Cloning from a 2nd HDD
TODO
It is safe to close the terminal window (shutdown your laptop) while the RaspiBlitz is doing the FTP download. To check on progress and to continue the setup you need to ssh back in again.
##### Sync from Bitcoin-Network
You can cancel the FTP download by keeping the key `x` pressed. Then the download will stop and you will be asked if you want to keep the progress so far. This makes sense if you need to shutdown the RaspiBlitz and you want to continue later or when you want to try another download option but want to keep the option to continue on FTP download if the other option is slower or not working.
TODO
#### 4. Copying from another Computer
#### Setup Lightning
If you have another computer available (laptop, desktop or another raspiblitz) that already runs a working blockchain (with txindex=1) you can use this option to copy it over to the RaspiBlitz. This will be done over the local network by SCP (SSH file transfere). Choose this option and follow the given instructions.
Before the lighting service can be started, the Bitcoin service needs to make sure that the blockchain is up to date. The downloaded blockchain data could be several weeks old - this could take some minutes. Then the Lightning Service gets started and a wallet can be created:
This is also the best option if you dont like to run your RaspiBlitz with a prepared blockchain by a third party. Then install bitcoin-core in a more powerful computer, sync+validate the blockchain (with txindex=1) there by yourself and copy it over after that thru the local network.
More details: [I have the full blockchain on another computer. How do I copy it to the RaspiBlitz?](FAQ.md#i-have-the-full-blockchain-on-another-computer-how-do-i-copy-it-to-the-raspiblitz)
#### 5. Cloning from a 2nd HDD
If is a backup way to transfere a blockchain from another computer if copying over the network is not working. More details on the setup can be found [here](FAQ.md#how-do-i-clone-the-blockchain-from-a-2nd-hdd).
#### 6. Sync from Bitcoin-Network
This is the fallback of last resort. A RaspberryPi has a very low power CPU and syncing+validating the blockchain directly with the peer2peer network can take multiple weeks - thats why the other options above where invented.
### Setup Lightning
Lightning is installed and waiting for your setup if you see this screen.
The creation of the Lightning Bitcoin Wallet gets done with the command: `lncli create` the RaspiBlitz is calling in the background.
The RaspiBlitz calling the LND wallet creation command for you:
After the wallet was created the Lightning service needs to scan the Blockchain ... this can take some time. If needed the user can close the SSH session with the RaspiBlitz during that time (progress is displayed on the LCD as status). On SSH back in just continue with the setup process.
First it will ask you to set your wallet unlock password - use your choosen PASSWORD C here and confirm it by inputting it a second time.
Second it will ask you if you have an existing "cipher seed mnemonic" - if this is your first RaspiBlitz/LND just ansere `n`.
*The "cipher seed mnemonic" is the word list that contains the backup of your private key. If you dont have one from a former RaspiBlitz setup it will be created for you. If you want to recovcer on old LND wallet, thats the point in the setup to enter it.*
*Background: Blockchain synup, LND wallet creation and LND scanning is all done within the script `70initLND.sh`*
Third it will ask you if you want to protect your backup word list with an additional password. You can simple keep this empty and just press ENTER to continue. If you want to go for this extra protection use your chossen PASSWORD D here.
Now the setup process is almost done and the RaspiBlitz needs a reboot:
LND will now generate a fresh cipher seed (word list) for you. WRITE THIS DOWN before you continue - without you limit your chances to recover funds in case of failing hardware etc. If you just want to try/experiment with the RaspiBlitz at least take a photo with your smartphone just in case. If you might plan to keep your RaspiBlitz running after trying it out store this word list offline or in a password safe. Hit ENTER once your done.
It will now make sure your wallet is initialized correctly and may ask you to unlock it with your just set PASSWORD C.
*The LND wallet needs to get unlocked on every new start/reboot of the RaspiBlitz.*
The RaspiBlitz will now do final setup configuration like installing tools, moving the SWAP file to the HDD or activating the firewall. You will see some text moving across the screen until this screen:
After reboot the RaspiBlitz is showing that the Wallet needs to be unlocked on the LCD and its ready to SSH back in:
The basic setup is done - hooray ... but still prepare for some long waiting time after this before you can play around with your new RaspiBlitz. Press OK to make a reboot. Your terminal session will get disconnected and the raspberry pi restarts.
### First Start: Syncing & Scanning
After the reboot is done it takes a while for all services to start up - wait until you see on the LCD/display that LND wallet needs to get unlocked. Then SSH in again with the same command like in the beginning (check LCD/display) but this time (and every following login) use your PASSWORD A.
After terminal login LND will ask you (like on every start/reboot) to unlock the wallet again - use PASSWORD C:
*Background: The LND wallet needs to get unlocked on every new start of the RaspiBlitz. The status information loop on the LCD is done by the script '00infoBlitz.sh'*
Now on first start you will habe a longer waiting time (between 1 hour and 2-3 days, depending on your initial setup) ... but thats OK, just leave the RaspiBlitz running until its done. You can even close your terminal now and shutdown your laptop and ssh back in later on. You will see on the Blitz LCD/display that it is ready, when the blue backgound screen is gone and you see the status screen like further below.
After SSH back in as admin the main menu shows the unlock option:
To understand what is taking so long .. its two things:
1. Blockchain Sync
Once the wallet is unlocked the setup is finally over and the main menu shows the option and features of the RaspiBlitz:
The blockchain on you HDD is not absolutly up-to-date. Depending how you got it transferred to your RaspiBlitz it will be some hours, days or even weeks behind. Now the RaspiBlitz needs to catch-up the rest by directly syncing with the peer-2-peer network until it reaches almost 100%. But even if you see in the beginning a 99.8% this can take time - gaining 1% can be up to 4 hours (depending on network speed). So be patient here.
And if you scroll down .. you see even more feature options:
2. LND Scanning
*Background: The script `00mainMenu.sh` is now the place to offer further features und extend the possibilities of the RaspiBlitz. Feel free to come up with ideas. Check out the developer section at the end of this page.*
Automatically if the Blockchain Sync is done LND will start to scan the blockchain and collect information. If you reached this point it should normally just take around 1 hour until the waiting time is over.
### Features
Once all is done you should see this status screen on the RaspiBlitz LCD/display:
You can manually extend your RaspiBlitz with features listed in the RaspiBolt Guide: https://github.com/Stadicus/guides/blob/master/raspibolt/raspibolt_60_bonus.md
Already integrated features of the RaspiBlitz are/will be listed as part of the main menu after connecting via ssh as admin user.
### Main Menu
*Background: The script `91addBonus.sh` is the place to put your setup of features you want to add to RaspiBlitz. Its run at the end of the automated setup process before final reboot. To make the feature executable for the user, add a new option to the `00mainMenu.sh`*
If you now login by SSH in your RaspiBlitz (or you are still logged in) you will the the Main Menu:
#### Status Infoscreen
And if you scroll down .. you see even more options. All options of the main menu will be explained below in the feature documentation.
#### Detailed Balances and Channel Info
*OK .. so from here on your RaspiBlitz is ready to play with.*
If you like to do this all from a webbrowser with a dashboard UI instead from an SSH terminal, go to `SERVICES`, activate the `RTL Webinterface` and after the reboot open in your webbrowser: http://[LOCAL-IP-OF-YOU-NODE]:3000 (PASSWORD B is your RPC password).
You can use the Switch to TOR option from the main menu to make the node reachable thru TOR. This way you can get thru a NAT without needed to open/forward ports on your router. Bitcoin and LND will have a seperate onion-address displayed on LCD and the Status Info Screen option in menu.
Have fun and riding the lightning :D
*BTW always love seeing photos of new RaspBlitzes added to the network on twitter @rootzoll*
The TOR integration is experimental and at the moment there is no way to switch off TOR again.
* [How can I get further help/support?](#support)
### Feature Documentation
These are the features available thru the RaspiBlitz SSH main menu and services. They have the goal to offer some basic/fallback functionality & configurations to you. More complex or user-friendly tasks are best to be done with wallets, apps and scripts you connect to your Lightning Node via [APIs](#interface--apis) - because you have a full Bitcoin- and Lightning-Node on the RaspiBlitz.
So lets take a look at the SSH main menu (3 pages to scroll down):
#### INFO: Raspiblitz Status Screen
This is the screen that gets displayed on the LCD/display. Its useful to call in a remote situation from SSH if you dont have your RaspiBlitz next to you or to make a screenshot.
*Its not automatically updating. Its just for one-time info.*
#### FUNDING: Fund your on-chain Wallet
Before you can open channels with other nodes you need to put some coins onto your LND on-chain wallet. Use this option to generate an address to send funds to.
*Reminder: RaspiBlitz & LND is still experimental software. With funding your LND node you accept the risk of loosing funds. So just play with small amounts - something in then area of 20 EUR/USD should be enough to make your first experiences.*
#### CONNECT: Connect to a Peer
Before you can open a channel with another node on the network you need to connect this node as a peer to your node.
Opening a channel with a peer is just optional. Having another node a peer helps your node to receive information about the network thru the gossip protocol. It will help your node to find better routes thru the network.
#### CHANNEL: Open a Channel with Peer
To open a payment channel with another node you can use this option.
Find interessting nodes to open channels with on online directories like [1ML.com](https://1ml.com/).
*This is just a very basic shell script. For more usability try the RTL Webinterface (under Services) or connect a (mobile) wallet with your RaspiBlitz.*
#### SEND: Pay an Invoice/PaymentRequest
Pay an invoice thru lightning.
*This is just a very basic shell script. For more usability try the RTL Webinterface (under Services) or connect a (mobile) wallet with your RaspiBlitz.*
#### RECEIVE: Create Invoice/PaymentRequest
Create an invoice to send to someone or a service to be payed thru lightnig.
*This is just a very basic shell script. For more usability try the RTL Webinterface (under Services) or connect a (mobile) wallet with your RaspiBlitz.*
The autopilot is a feature of LND that you can switch on. It automatically uses around half of your your on-chain funds (if available) to open channels with other lightning nodes the autopilot thinks can be useful to improve your payment routes.
There is now the option to connect and control your LND node with the mobile app called "Shango" - choose option in the main menu.
##### Testnet
You can switch from mainnet to testnet of your blockchain if you want to try things out and play with free test coins.
#### Public Domain with DynamicDNS
Please beware that to might take some time to sync the test blockchain and you need to setup a new lnd testnet wallet during the process.
This is a way to make your RaspiBlitz publicly reachable from the internet so that other nodes can open channels with you and you can connect with the
##### DynamicDNS
To do so you can register at an DynamicDomain service like freedns.afraid.org, forward the TCP ports 8333 (Bitcoin/mainnet),9735 (LND Node) & 10009 (LND RPC) from your internet router to the local IP of your RaspiBlitz and then activate unter "Services" the "DynamicDNS" option.
This is a way to make your RaspiBlitz publicly reachable from the internet so that other nodes can open channels with you and you can connect with your mobile wallet from outside your local network.
To do so you can register at an DynamicDomain service like freedns.afraid.org and forward the TCP ports ...
* 8333 (Bitcoin/mainnet)
* 9735 (LND Node)
* 10009 (LND RPC)
... from your internet router to the local IP of your RaspiBlitz and then activate unter "Services" the "DynamicDNS" option.
You will be asked for your dynamic domain name such like "mynode.crabdance.org" and you can also optionally set an URL that will be called regularly to update your routers IP with the dynnamic domain service. At freedns.afraid.org this URL is called "Direct URL" under the menu "Dynamic DNS" once you added one.
## Auto-unlock LND on startup
##### Run behind TOR
You can run your Bitcoin- and Lightning-Node as a TOR hidden service - replacing your IP with an .onion-address
This has some benefits:
* You dont publish your IP running a node so its much harder to resolve your real name and location.
* You tunnel thru the NAT of your router and make Bitcoin and Lightning reachable to all other TOR nodes
But this also comes with the following side effects:
* Mobile wallets dont support connecting over TOR yet
* Lightning nodes that dont run TOR cannot reach you (like behind NAT)
To try it out just switch on the service - you can deactivate later on if its not working for you.
The TOR integration is experimental and at the moment there is no way to switch off TOR again.
##### RTL Webinterface
The RTL Webinterface is a LND Control Dashboard you can run in your browser with a nice GUI - it offers much more control over your Lightning node than the RaspiBlitu SSH menus. Its recommended to give it a try.
Feedback is welcome by the RTL programmer: https://github.com/ShahanaFarooqui/RTL
##### LND Auto-Unlock
This feature is based on https://github.com/Stadicus/guides/blob/master/raspibolt/raspibolt_6A_auto-unlock.md
It can be activated under "Services" -> "Auto-unlock LND". Its recommended to be turned on, when DynamicDNS is used. Because on a public IP change of your router, LND gets restarted automatically and without Auto-Unlock it will stay inactive/unreachbale until you manually unlock it.
But keep in mind that when activated, your Password C will be stored on the RaspiBlitz SD card. That lowers your security in (physical) attack scenarios. On an update you would need to re-enter your password C.
*But keep in mind that when activated, your Password C will be stored on the RaspiBlitz SD card. That lowers your security in (physical) attack scenarios. On an update you would need to re-enter your password C.*
#### MOBILE: Connect Mobile Wallet
This feature should support you in connecting your RaspiBlitz to a mobile wallet on your smartphone.
[mobile](pictures/mainmenu-mobile.png)
At the moment [ZAP (iOS)](https://github.com/LN-Zap/zap-iOS) and [Shango (iOS/Android)](https://github.com/neogeno/shango-lightning-wallet) are available.
Please keep in mind that if you also want to connect to your smartphone also from the outside (thru LTE, 3G, ..) with your RaspiBlitz you might need to open/forward ports on your router and should look into the DynamicDNS features to handle changeing IP of our Home-DSL.
#### EXPORT: Macaroons and TLS.cert
Offers the following options to get the Macaroon and TLS files to be used in other apps and wallets.
*Macaroons: Access Tokens that allow certain command executions on the LND node.*
*TLS: Certificate to secure/encrypt the communication with the LND node.*
[export](pictures/mainmenu-export.png)
##### Hex-String
The Macaroons and TLS.cert files can be copy+pasted as Hex-Strings from RaspiBlitz to any other app that supports that. If you choose this option RaspiBlitz will all files print for you as Hex-String to do so.
SCP is a SSH like command to transfer files. If were able to SSH into the RaspiBlitz also the SCP to transfere the files should work. If you choose these option, RaspiBlitz will print prepared SCP commands you can copy+paste to run in a second terminal.
Opens an ad-hoc webserver so that you can download the files in your local network thru the browser.
*This is a least secure way to transfere those file - everybody in your local network has access to those file during download. Remember with the Admin-Macaroon somebody could takeover your node and spend all your funds. Just use as last fallback.*
##### Renew Macaroons & TLS
Use if you want to invalidate earlier exported Macaroons & TLS files - e.g. lost mobile wallet.
#### NAME: Change Name/Alias of Node
Change the name of your node.
#### PASSWORD: Change Passwords
Change you passwords for security.
#### CHASHOUT: Remove Funds fro, on-chain Wallet
Use if the want to remove all funds from the RaspiBlitz.
A saf way to shutdown the RaspiBlitz. If then a reboot/restart is needed - un/replug the power.
#### X: Console Terminal
Closes the SSH main menu and exits tothe terminal - where the user can make use of the CLI clients `bitcoin-cli`&`lncli` directly to make use of the Bitcoin- and Lightningnode.
With the command `raspiblitz` its possible to return to the main menu.
## Interface / APIs
To develop your own scripts/apps and to connect other servcies/apps to your RaspiBlitz you have multiple interfaces/APIs available:
### Bitcoin
* `bitcoin-cli` command line interface on the terminal
* `bitcoind` running on port 8333 (public)
* `JSON-RPC` running on port 8332 (local) [DOC](https://en.bitcoin.it/wiki/API_reference_%28JSON-RPC%29)
### LND-Lightning
* `lncli` command line interface on the terminal [DOC](https://api.lightning.community/)
* `lnd` running on port 9735 (public)
* `gRPC` running on port 10009 (public) [DOC](https://api.lightning.community/)
* `REST` running on port 8080 (public) [DOC](https://api.lightning.community/rest/index.html)
## Updating to new Version
@ -271,7 +510,7 @@ If you have a RaspiBlitz version 0.98 or newer do the following:
* Remove power
* Remove SD card
Now download the new RaspiBlitz SD card image and write it to your SD card .. yes you simply overwrite the old one, it's OK, the RaspiBlitz stores all your personal data on the HDD. See details about latest SD card image [here](README.md#installing-the-software).
Now download the new RaspiBlitz SD card image and write it to your SD card .. yes you simply overwrite the old one, it's OK, the RaspiBlitz stores all your personal data on the HDD. See details about latest SD card image [here](#installing-the-software).
*If you have done manual changes to the system (installed packages, added scripts, etc) you might need to do some preparations before overwriting your sd card - see [FAQ](FAQ.md#why-do-i-need-to-re-burn-my-sd-card-for-an-update).*
@ -298,13 +537,16 @@ The whole build process takes a while. At the end the LCD drivers get installed
*Note: If you plan to use your self build sd card as a MASTER copy to backup image and distribute it. Use a smaller 8GB card for that. This way its ensured that it will fit on every 16 GB card recommended for RaspiBlitz later on.*
* [Can I run RaspiBlitz on other computers than RaspberryPi?](FAQ.md#can-i-run-raspiblitz-on-other-computers-than-raspberrypi)
* [How can I build an SD card other then the master branch?](FAQ.md#how-can-i-build-an-sd-card-other-then-the-master-branch)
* [How can I build an SD card from my forked GitHub Repo?](FAQ.md#how-can-i-build-an-sd-card-from-my-forked-github-repo)
## Community Development
Everybody is welcome to join, improve and extend the RaspiBlitz - its a work in progress. Check the issues if you wanna help out or add new ideas. You find the scripts used for RaspiBlitz interactions on the device at `/home/admin` or in this git repo in the subfolder `home.admin`.
Everybody is welcome to join, improve and extend the RaspiBlitz - its a work in progress. [Check the issues](https://github.com/rootzoll/raspiblitz/issues) if you wanna help out or add new ideas. You find the scripts used for RaspiBlitz interactions on the device at `/home/admin` or in this git repo in the subfolder `home.admin`.
Join me on twitter [@rootzoll](https://twitter.com/rootzoll), visit us at a upcomming [#lightninghackday](https://twitter.com/hashtag/LightningHackday?src=hash) or check by on of our bitcoin meetups in Berlin ... every 1st Thursday evening a month at the room77 bar - feel free to buy me a beer with lightning there :)
Join me on twitter [@rootzoll](https://twitter.com/rootzoll), visit us at a upcomming [#lightninghackday](https://twitter.com/hashtag/LightningHackday?src=hash)
* [How can I get further help/support?](#support)
IRC channel on Freenode `irc://irc.freenode.net/raspiblitz` (unmoderated)
IRC channel on Freenode `irc://irc.freenode.net/raspiblitz` (unmoderated)
## Why do we need to download the blockchain and not syncing it?
The RaspiBlitz is powered by the RaspberryPi. The processing power of this SingleBoardComputer is too low to make a fast sync of the blockchain from the bitcoin peer to peer network during setup process (validation). To sync and index the complete blockchain could take weeks or even longer. Thats why the RaspiBlitz needs to download a prepared blockchain from another source.
## Is downloading the blockchain secure?
The downloaded Blockchain is pre-indexed and pre-validated. That is secure enough because if the user gets a "manipulated" blockchain it would not work after setup. The beginning of the downloaded blockchain needs to fit the genesis block (in bitcoind software) and the end of the downloaded blockchain needs not match with the rest of the bitcoin network state - hashes of new block distrubuted within the peer-2-peer network need to match the downloaded blockchain head. So if you downloaded a manipulated blockchain it would simply just dont work in practice.
There might be theoretical scenarios why it would be bad for the whole network if anybody is downloading a prepared blockchain and not syncing and self-validating every block, but with a lot of self-validating full nodes already out there, just putting some RaspiBlitz with a downloaded blockchain into the mix and runnig as a self-valifating full node from that point on, is practically just strengthening the the overall network. And dont forget, the most important part of running a full node is to validate the new blocks summited by the miners - to balance out there power and to keep the Bitcoin network running by our rules.
If you have any link to a more detailed discussion of this topic, please add it here for people to do their own research.
## Blockchain Data
The RaspiBlitz needs the following files from a bitcoind (>=0.17.0) that is fully sync and has indexing switched on (has line txindex=1 in bitcoin.conf file) - all files from the directories:
```
/blocks
/chainstate
/indexes
```
Notice: If you had your node fully sync but not indexed, once you switch it on you need to start your client and wait for it to verify the chain and index before copying the folders above to your external HDD. This can take a couple of hours.
Make sure not to add other files like wallet data or lock files to a prepared download.
You might want to include the testnet data also - then add the testnet3 folder that just contains the same three folders from the testnet blockchain.
On download all those files need to be placed finally in the /mnt/hdd/bitcoin folder of the RaspiBlitz.
## Download Process
At the moment the RaspiBlitz offers two technical ways to download the blockchain:
### FTP Download (fallback)
The easiest way is to put the blockchain data on a FTP server and let people download it. FTP is able to download complete directories - HTTP can just handle single file. FTP clients and server hosting is widly available.
The downside that this is a central point solution and is hard to scale up (without spending a lot of money). But it is available as a backup, if other solutions do not work.
### Torrent Download (default)
The preferred way is to to download the blockchain data thru the peer2peer torrent network. This way the community can help to seed the torrents (at least while downloading). Supporters of the project can setup constant seeding. There is no single point of failure within the download structure.
In the beginning we used just on torrent file - containing all the directories and data like mentioned above. But this had the downside, that everytime when we update the torrent the seeding is bad in the beginning and downloads are slow. Good seeding needs time to build up.
Thats why there are two torrent files now:
#### Base Torrent File
Inspired by the website getbitcoinblockchain.com we use one of their base torrent files to have a basic set of blocks - that will not change for the future. This torrent contains most of the data (the big file) and we dont need to change the torrent for a long time. This way the torrent can get establish a wide spread seeding and the torrent network can take the heavy load.
At the moment this is just the bitcoin blk and rev files up to the number:
- /blocks : 01390
- /testnet3/blocks: 00152
For litecoin its blk and rev files up to the number:
- /blocks : 00124
#### Update Torrent File (Description)
All the rest of the files get packaged into a second torrent file. This file will be updated much more often. The seeding is expected to be not that good and download may be slower, but thats OK because its a much smaller file.
This way a good balance between good seeding and up-to-date blockchain can be reached.
#### Update Torrent File (Creation)
To create the Update Torrent file, follow the following step ...
Have a almost 100% synced bitcoind MAINNET with txindex=1 on a RaspiBlitz
(remove all funds from this node - because blockchain get messed with)
Now change to your computer where you package the torrent files and transfere the three directories into your torrent base directory (should be your current working directory):
Now change again to your computer where you package the torrent files and transfere the three directories into your torrent base directory (should be your current working directory):
(Re-)name the "torrent base directory" to the same name as the torrent UPDATE file itself later (without the .torrent ending). For the correct naming see the chapter "Torrent Files Naming Schema" below.
Now open your torrent client (e.g. qTorrent for OSX) and create a new torrent-file with the freshly renamed "torrent base directory" as source directory.
Add this list of trackers to your torrent and start seeding (keep a free/empty line between the three single trackers):
```
udp://tracker.justseed.it:1337
udp://tracker.coppersurfer.tk:6969/announce
udp://open.demonii.si:1337/announce
udp://denis.stalker.upeer.me:6969/announce
```
Name the new torrent file
To create the torrent file can take some time. Finally add the generated torrent file to the /home.admin/assets/ of the github and change the name of the updateTorrent varibale file in the script 50torrentHDD.bitcoin.sh
#### Torrent Files Naming Schema
The base torrent file should always have the following naming scheme:
So for example the second version of the base torrent for litecoin created on 2018-10-31 would have this name: raspiblitz-litecoin2-2018-10-31-base.torrent
The update torrentfile should always have the following naming schema:
So for exmaple an update torrent created on 2018-12-24 for litecoin that is an update to the second base torrent version would have this name: raspiblitz-litecoin2-2018-12-24-update.torrent
The RaspiBlitz started as small collection of shell scripts to setup a bitcoin+lightning node. At this time it was not needed to have settings file. The idea was that the scripts analyse the system state and make the changes required - automatically trying to catch up. That was OK as long RaspiBlitz was just a helper to setup your Lightning node and the rest was up to you.
Over time users that are running a RaspiBlitz expected that it can handle more complex setup and customization. Also it should be easy to update the system (exchange sd card with a newer image) and should be able to have the same configuration afterwards - keeping its state. Thats why starting from version 1.0 there will be a raspiblitz config file stored on the HDD that stores stores the config state.
## The Config File
The RaspiBlitz config file is stored on the HDD root:
`/mnt/hdd/raspiblitz.conf`
Its simple structure is: one key-value pair per line. In the end its bash-script syntax to define varibales. The RaspiBlitz shell scripts can import this file with:
`source /mnt/hdd/raspiblitz.conf`
After this line all the config values are available and can be worked with. I prefer to call this line in scripts explicitly and not setting this values as environment variables, because when you read as a newbie such a script, you get an idea where the config file is stored.
## The Config Values
So see what config parameters are available check the comments in the following script:
`/home/admin/_bootstrap.sh`
## Adding new Config Values
If you extend the RaspiBlitz scripts and you have the need to add a new config key-value add it to the `/home/admin/00enforceConfig.sh` script. There is a section for default values and setting them in the config file, if they dont exist there yet. Because this script runs on every startup, you can be sure that the default value is then available to your extended script - especially if people update their system.
## Bootstrap Service: Enforcing the Config
On every start of the RaspiBlitz take the config file and check if the system is running as stated in the config file and when needed make changes to the system. This is done by calling this script on startup with systemd:
`/home/admin/_bootstrap.sh`
So if you change the config by hand or you write a script that changes the config, then simply trigger a restart the RaspiBliz.
Having this script checking the system on every startup, the user can easily update the SD card with a fresh image and the system will automatically establish the old state.
## What to put into the config file and what not
All values users put into setup or setting dialogs and that is not stored on the HDD (for example in the config files of lnd or bitcoin) is a hot cadidate to put into the raspi config file. Some values make sense to get stored as a duplicate (for performance or easy of access) - but dont get to wild.
bluecell296
6 years ago
GitHub
