freedombone-image(1)

NAME
freedombone-image - Creates a debian image suitable for installing onto systems

SYNOPSIS
freedombone-image -t [target] -u [username] -p [password] --ip [box static IP address] --iprouter [IP address of internet router] --ns1 [First DNS server IP] --ns2 [Second DNS server IP] -c [configuration file] -s [image size] --generic [yes|no] --minimal [yes|no] --ssh [port number] -v [variant] --repo [project git repo url] -m [debian mirror url] -o [yes|no] --debianonly [yes|no] --interface [wlan0/etc] --ssid [network] --wifitype [] --wifipass [passphrase]

DESCRIPTION
This creates a debian image suitable for writing to a microSD card.

INSTALLATION
Dependencies can be installed with:
    sudo apt-get -y install build-essential git python-docutils mktorrent vmdebootstrap xz-utils
    sudo apt-get -y install dosfstools btrfs-tools extlinux python-distro-info mbr
    sudo apt-get -y install qemu-user-static binfmt-support u-boot-tools qemu If you wish to create virtualbox images then on Debian you'll need to enable the contrib repo within /etc/apt/sources.list and then install the virtualbox package.

TYPICAL USAGE
An example of creating a minimal image which can be uploaded to the internet and potentially obtained by many users is:
    freedombone-image -t beaglebone -s 8G It will take some time to create the image, and you should do this on a laptop or desktop machine (i.e. not the beaglebone itself). Once it's completed you can copy it to a microSD card using the dd command and then log into the box.
    sudo dd bs=1M if=myimagefile of=/dev/sdX conv=fdatasync Possible targets are: beaglebone, cubieboard2, cubietruck, a20-olinuxino-lime, a20-olinuxino-lime2, a20-olinuxino-micro, i386, amd64, virtualbox-i386, virtualbox-amd64, qemu-i386, qemu-x86_64 If the image build fails with an error such as Error reading from server. Remote end closed connection then you can specify a debian package mirror repository manually with:
    freedombone-image -t beaglebone -s 8G -m http://ftp.de.debian.org/debian The minimal generic image does not have any services installed. The first time you ssh into it you will be prompted to change your password and then the rest of the installation will continue. For example:
    ssh fbone@freedombone.local -p 2222 With the password 'freedombone'. The --ssh option can be used to change the default ssh port number to be used. Optionally you can also interactively configure the image to build a complete system in one go. This is intended for a custom build specific to your needs - not a generic image usable by anyone. Note that if you make such builds publicly available then they become a security hazard, because all downloads will have the same ssh host keys and passwords.
    freedombone-image -t beaglebone -u myusername -p mypassword -s 8G --interactive yes --generic no Or if you don't want any manual interaction then specify a configuration file. You can easily create a configuration file with:
    sudo apt-get install dialog
    freedombone-config This will generate a configuration file called freedombone.cfg containing your settings. It could be included in the image creation as follows:
    freedombone-image -t beaglebone -u myusername -p mypassword -s 8G -c freedombone.cfg --generic no After image creation if you subsequently need to increase the size you can do that with gparted, or a similar disk utility.

CREATING AN 'ONION-ONLY' IMAGE
In some cases you may want to run a system behind a hostile firewall, or you may not have control of the internet router to be able to forward ports, or perhaps running a server at home is strictly prohibited in your area. In this case you can create an image which only runs through Tor, and this means that the various services are only available via onion addresses and not via the more conventional ICANN domain names. To create an onion-only image just add the --onion option, such as:
    freedombone-image -t beaglebone -s 8G --onion yes

INTERACTIVE INSTALL
For advanced users you can set the option --minimal no in order to show more decisions during the interactive install of the system. By default the number of options will be kept to a minimum level.

SECURITY
For images which you intend to be made public and potentially downloaded by many people use the --generic yes option. The generic option ensures that the user changes their login password and does not install any services so that the user can select which variant they want. The biggest potential problem when distributing images is the use of fixed default passwords. Adversaries will bet upon users being lazy or uninformed and not changing their passwords from the defaults. To increase the level of security you can optionally specify an ssh public key during image creation. This will ensure that nobody other than the holder of those keys can log into the resulting system. For example:
    freedombone-image -t beaglebone -u myusername -p mypassword -s 8G --interactive yes --pubkey "ssh-ed25519 C1Flz..." --generic no

VIRTUAL MACHINES
To make a qemu image:
    freedombone-image -t qemu-x86_64 -s 8G Then to run it:
    qemu-system-x86_64 -m 1G myimage.qcow2 You can also use i386 in place of x86_64 to create 32bit images. To make a virtualbox image:
    sudo apt-get install virtualbox
    freedombone-image -t virtualbox-amd64 -s 8G The resulting vdi image can then be run within virtualbox. At the time of writing virtualbox is an almost-but-not-quite open source system and so qemu is the preferred virtual machine environment.

WIFI
If you know that images are always going to be deployed within a particular wifi network then you can pre-configure them with wifi settings. To do that use the options:
    --interface wlan0 --ssid [yourSSID] --wifitype [wpa2-psk|none] --wifipass [passphrase] The option is only required if you are using a wifi security type other than "none".

MESH ROUTERS
To create an image suitable for installing onto a mesh router using Beaglebone Black hardware:
    freedombone-image -t beaglebone -v mesh You can change the target type depending upon your hardware. It is expected that you will have a wifi adaptor plugged in.

MESH CLIENTS / USB DRIVES
A mesh client is typically the mesh network variant of Freedombone installed onto a USB stick. Unlike a router which just moves mesh traffic around, a mesh client has a user interface and communications software installed. It's the end point which a user would interact with. To create an image for a mesh client:
    freedombone-image -t i386 -v meshclient One important point to consider is that it's likely that if you then boot from this on any available laptop the wifi may not work, due to the absence of proprietary drivers. Mesh networks may sometimes be deployed in emergency situations where the ability to communicate at all is more important than network security, so it is also possible to create an image which includes proprietary wifi drivers by setting the --insecure option. This is not advised, so use at your own risk.
    freedombone-image -t i386 -v meshclient --insecure yes Once the image is created you can then use the dd command to copy it to any number of USB drives.

BASIC IMAGE / DEBIAN ONLY
If you only want to install debian onto your target hardware, maybe as a test system, and don't want any additional Freedombone setup then you can set the --debianonly option to yes.

BUGS
Report bugs at https://github.com/bashrc/freedombone/issues

AUTHOR
Bob Mottram <bob@robotics.uk.to>
PGP/GPG: EA982E38
Bitmessage: BM-2cWuhmBvVdfrHhLoZTdspCkKeiTorUesSL
Web: http://robotics.uk.to