diff --git a/doc/freedombox-manual.xml b/doc/freedombox-manual.xml index 356882571..b9cbaa24c 100644 --- a/doc/freedombox-manual.xml +++ b/doc/freedombox-manual.xml @@ -5,6 +5,18 @@ FreedomBox Manual +
+ FreedomBox Introduction + FreedomBox is a personal server that protects your privacy. It is a free software stack, a subset of the Debian universal operating system, that can be installed in many flavors of cheap and power-efficient hardware. The simplicity of setting up and operating a FreedomBox is similar to that of a smart phone. +
+ Smart Router + FreedomBox runs in a physical computer and can route your traffic. It can sit between various devices at home such as mobiles, laptops and TVs and the Internet replacing a home wireless router. By routing traffic, FreedomBox can remove tracking advertisements and malicious web bugs before they ever reach your devices. FreedomBox can cloak your location and protect your anonymity by "onion routing" your traffic over Tor. FreedomBox provides a VPN server that you can use while you are away from home to keep your traffic secret on untrusted public wireless networks and to securely access various devices at home. It can also be carried along with your laptop and used to connect to public networks at work, school, or office to avail its services. It could be used in a village to provide communications throughout the village. In future, FreedomBox intends to provide support for alternative ways of connecting to the Internet such as Mesh networks. +
+
+ Private Cloud + FreedomBox provides services: to your computers and mobile devices in your home and to computers and mobile devices of other people who are your friends. FreedomBox provides file sharing like Dropbox, shared calendering like Google or Yahoo and photo sharing. FreedomBox provides instant messaging and truly secure voice conference calling that works on low bandwidth providing high quality. FreedomBox has a blog and wiki to let you publish your content and collaborate with the rest of the world. Coming soon, a personal email server and federated social networking using GNU Social and Diaspora, providing privacy-respecting alternatives to Gmail and Facebook. +
+
Quick Start @@ -20,7 +32,7 @@ - (Dreamplug only) Plug your computer into the eth1 port (the one toward the end of the box) on the FreedomBox. + If your device has a 2nd ethernet port, you can connect your computer to it directly, using an ethernet cable. Power on your your FreedomBox. @@ -32,10 +44,10 @@ After the FreedomBox has rebooted, you can access Plinth through your web browser. - If your computer is connected directly to the FreedomBox through a second ethernet port, you can browse to: or . + If your computer is connected directly to the FreedomBox through a second (LAN) ethernet port, you can browse to: or . - If your computer supports mDNS, you can browse to: . + If your computer supports mDNS (GNU/Linux, Mac OSX and Windows with mDNS software installed), you can browse to: . If neither of these methods are available, then you will need to figure out the IP address of your FreedomBox. You can use the "nmap" program to find its IP address: @@ -53,7 +65,7 @@ If your computer is connected directly to the FreedomBox, your FreedomBox can act as a router, allowing you to access the Internet. - Now, you can try any of the Apps that are available on FreedomBox. + Now, you can try any of the Apps that are available on FreedomBox.
Getting Help @@ -81,629 +93,323 @@
Release Notes - The following are the release notes for each FreedomBox version. + The following are the release notes for each FreedomBox version.
- Version 0.5 (2015-08-07) -
- Notable Features - - - New targets: CubieTruck, i386, amd64 - - - New apps in Plinth: Transmission, Dynamic DNS, Mumble, ikiwiki, Deluge, Roundcube, Privoxy - - - NetworkManager handles network configuration and can be manipulated through Plinth. - - - Software Upgrades (unattended-upgrades) module can upgrade the system, and enable automatic upgrades. - - - Plinth is now capable of installing ejabberd, jwchat, and privoxy, so they are not included in image but can be installed when needed. - - - User authentication through LDAP for SSH, XMPP (ejabberd), and ikiwiki. - - - Unit test suite is automatically run on Plinth upstream. This helps us catch at least some code errors before they are discovered by users! - - - New, simpler look for Plinth. - - - Performance improvements for Plinth. - - -
- freedom-maker - - - Add ability to set build and image mirrors separately - - - Updated installation instructions - - - Ability to set specific components based on targets - - - Add support for CubieTruck - - - Fix build failure during date change boundary - - - Disable btrfs for Raspberry Pi - - - Add support for building i386/amd64 images - - - Update documentation about the new targets - - - Corrected the git url for freedom-maker build - - - Use vmdebootstrap-0.8 - - - Remove unneeded DHCP config option to vmdebootstrap - - -
-
- freedombox-setup - - - Setup uap0 interface on dreamplug, using hostapd to configure wifi AP. - - - Set HOME in first-run initscript so etckeeper can find the git config. - - - Beaglebone: Don't need to copy u-boot files to boot partition. freedom-maker will install it in front of boot partition. - - - Add initial support for cubietruck. - - - Remove pagekite recommendation as Plinth now takes care of its installation and setup - - - Redirect to Plinth from home page instead of showing jwchat - - - Migrate to dh_python3 from python-support - - - Use nmcli to setup network connections - - - Remove jwchat/ejabber setup as it is handle by Plinth - - - Remove LDAP root password and create ou=groups - - - Remove renaming of network interfaces as it does not work. Start using systemd's new predictable naming. Don't alter /etc/network/interface anymore. - - - Use network manager for configuring DNS and DHCP servers - - - Fix hang issue when building Raspberry Pi images - - - Remove privoxy setup as it happens in Plinth now - - - Configure PAM for LDAP user logins - - -
-
- Plinth 0.4.5 - - - New app modules: - - - BitTorrent (Transmission) - - - Dynamic DNS - - - Voice Chat (Mumble) - - - Wiki & Blog (ikiwiki) - - - - - New system modules: - - - Networks - - - Software Upgrades - - - - - Add unit tests with coverage report and Travis-CI integration - - - Add systemd service file for Plinth - - - Use augeas to configure Pagekite - - - Use domainname as ejabberd host - - - Bugfixes for ownCloud and packagekit - - - Fixes for user dropdown menu when javascript is disabled - - - Simpler look - - -
-
- Plinth 0.5 - - - New app modules: - - - BitTorrent (Deluge) - - - Email Client (Roundcube) - - - Web Proxy (Privoxy) - - - - - Use libnm for Networks module - - - Add support for testing Django-dependent modules - - - Plinth can now setup ejabberd and jwchat - - - Setup firewall zones for network-manager connections - - - Manage LDAP users and groups with ldapscripts package - - - LDAP user authentication is now used for XMPP, ikiwiki, and SSH - - - Fixes to cherrypy autoreload and remove unneeded extra server. Plinth now uses much less CPU. - - - Use django-stronghold for authentication handling - - - Bundle tests with applications; add Travis-CI status image to README - - - Move to using python3-augeas for Pagekite - - - Extend and use action utilities for enabling/disabling services and Apache confs - - - Fixed timezone list issue - - - Bind a Network connection to an interface - - - Many small cleanups - - -
-
-
-
- Version 0.3 (2015-01-20) -
- Notable Features - - - Tor Bridges: All boxes now act as non-exit Tor bridges, routing traffic for the Tor network. - - - Firewall: firewall is on by default and is automatically managed. - - - Add BeagleBone support. We now have images for BeagleBone, RaspberryPi, VirtualBox i386/amd64, and DreamPlug. - - - Ability to enable and use Tor Hidden Services. Works with Ejabberd/JWChat and ownCloud services. - - - Enable Tor obfsproxy with scramblesuit. - - - Drop well-known root password (an account with sudo capabilities still exists for now but will be removed soon). - - - Switch to unstable as suite of choice for easier development. - - - Newer images are built with systemd by default (due to Debian change). - - - Install and operate firewall automatically (uses firewalld). - - - Major restructuring of Plinth UI using Python3, Django web development framework and Bootstrap3. Code quality is much better and UI is more polished. - - - Introduced packaging framework in Plinth UI for on-demand application installation. - - -
- freedom-maker - - - Newer images use systemd by default - - - VirtualBox images for amd64 architecture also - - - Default to btrfs filesytem where supported - - - Images for BeagleBone - - - Use Grub for virtualbox images - - - Use eatmydata to speed up build process - - - Switch to Debian Unstable as suite of choice - - - Drop well-known root password (an account with sudo capabilities still exists for now) - - -
-
- freedombox-setup - - - Add BeagleBone support - - - Enable scramblesuite for obfsproxy - - - Enable obfsproxy - - - Updates to testsuite - - - Pull documentation from Wiki and build it - - - Enable Tor transparent proxy - - - Update tests in testsuite - - -
-
- Plinth 0.4.1 - - - Ability to enable and see status of Tor Hidden Services. - - - Fully migrated to Django and removed all code that was re-inventing web frameworks. - - - Migrated to Python 3. - - - Ability to write and distribute Plinth modules outside of Plinth repository: FreedomBox Apps. - - - Improved security using Django authentication and forms. - - - Reorganized source code to look more like a Python application. - - - Use Python setup.py instead of custom Makefiles. - - - Setting up Plinth for development is easier. - - - Removed dependency on withsqlite package with help from Django models. - - - Removed duplicated code in Twitter bootstrap JS/CSS by depending on proper Debian packages. - - - Removed stubs and TODOish messages in UI in preparation of proper public (developer) release. - - - Code quality clean-ups. - - - Updated documentation on setting up and using Plinth from source. - - -
-
- Plinth 0.4.4 - - - Update to Bootstrap3 and improve styling in general - - - Fix issue with Apache configuration - - - Improvements to working behind a proxy server - - - Introduce package management framework - - - Show progress bar while installing ownCloud - - - Tested JWChat/ownCloud on .onion addresses - - - Test coverage measurement - - - Rewamped first boot wizard - - - Proper user management with editing and setting passwords - - - Remove expert mode - - - Seperate out domain name vs. hostname configuration - - - Fix issues with ejabberd configuration update on hostname change - - - Fix issue with hostname changes - - - Debian packaging related fixes - - - Many bug fixes and code cleanups - - -
-
- Firewall - Firewall is a network security system that controls the incoming and outgoing network traffic. Keeping a firewall enabled and properly configured reduces risk of security threat from the Internet. - The operation of the firewall is automatic. When you enable a service it is automatically permitted in the firewall and you disable a service is automatically disabled in the firewall. - Automatic management of firewall in FreedomBox is handled by Plinth web user interface using FirewallD. -
-
-
-
- Version 0.2 (2014-03-16) -
- New Architectures - In addition to the DreamPlug, Raspberry Pi and VirtualBox (x86) images are now provided. -
-
- New Services - These services are new as of this release: - - - Configuration Management UI - - - Instant Messaging - - - OwnCloud - - - dnsmasq - - - Low-Level Configuration Management - - - Service Announcement - - - LDAP Server - - - LXC Support - - - Source Packages - - - See the user documentation for instruction on how to use them. -
- Configuration Management UI - The FreedomBox now has an administrative interface, Plinth. - To use it: - - - Start your FreedomBox. - - - After Plinth is configured, log in. - - - To configure it: - - - Start your FreedomBox. - - - Plug your Ethernet cable in to your computer and eth1 on your DreamPlug. - - - Connect to Plinth. - - - Set up the user name and password you'll use to log into Plinth. - - -
-
- Instant Messaging - The FreedomBox now supports instant messaging via XMPP, using JWChat. - To use it: - - - Start your FreedomBox. - - - Register a new Jabber account. - - - Log in to your Jabber account. - - -
-
- OwnCloud - - - (with 4GB images) - - - (What is this? What is it for? How do we use it?) -
-
- dnsmasq - (What is this? What is it for? How do we use it?) -
-
- Low-Level Configuration Management - Etckeeper is now used for configuration management: after every major system operation, the system automatically takes a configuration snapshot so configuration changes can be reversed, as necessary. -
-
- Service Announcement - Avahi Service Announcement and mDNS Name Resolution. - (What is this? What is it for? How do we use it?) -
-
- LDAP server - (What is this? What is it for? How do we use it?) -
-
- LXC support - (What is this? What is it for? How do we use it?) -
-
- Source Packages - Source Packages for each installed package are now stored in the /usr/src/packages/ directory. -
-
-
- Changes since 0.1 release - - - The privoxy setup is now the default from Debian. - - -
-
-
- Version 0.1 (2013-02-26) - I am pleased to announce our first FreedomBox software release. The FreedomBox 0.1 image is available here (.torrent) (sha512sum: 867f5bf462102daef82a34165017b9e67ed8e09116fe46edd67730541bbfb731083850ab5e28ee40bdbc5054cb64e4d0e46a201797f27e0b8f0d2881ef083b40). - This 0.1 version is primarily a developer release, which means that it focuses on architecture and infrastructure rather than finish work. The exception to this is privoxy-freedombox, the web proxy discussed in previous updates, which people can begin using right now to make their web browsing more secure and private and which will very soon be available on non-FreedomBox systems. More information on that tool at the end of this post. + Version 0.7 (unreleased) - What have we accomplished? - - - This first release completes a number of important milestones for the project. - - - Full hardware support in Debian - - - A big part of the vision for the FreedomBox project revolves around the "Boxs", tiny plug servers that are capable of running full size computing loads cheaply and with little use of electricity. In many respects these are wireless routers given the brains of a smart phone. If you want to change the software on a router or smart phone today you normally need to worry about bootloader images, custom roms, and a whole collection of specialized build and install tools. We wanted to the FreedomBox to move beyond this fragmented environment and, with the help of some embedded device experts, we have managed to make our development hardware into a fully supported Debian platform. That means that anyone with a device can install Debian on it just like a laptop or desktop computer. This support is very important for ensuring that the work we do on the FreedomBox is as portable and reusable as possible. - - - - + Translations! + + + Support for OLinuXino A20 MICRO and LIME2 + + + New Plinth applications: OpenVPN, reStore + + + Improved first-boot experience + + + Many bugfixes and cleanups + + +
+
+ Version 0.6 (2015-10-31) + + + New supported hardware target: Raspberry Pi 2 + + + New modules in Plinth: - Basic software tools selected - - - There is a lot of great free software out there to choose from and we put a lot of thought into which elements would be included in our basic tool kit. This includes the user interface system - "plinth" that I outlined in a recent kickstarter update as well as basic cryptography tools like gpg and a one named "monkeysphere" that leverages gpg as an authentication tool. All of these are now bundled together and installed on the release image. This common working environment will simplify development going forward. - - + Shaarli: Web application to manage and share bookmarks - Box-to-box communication design - - - Some goals of the FreedomBox can be accomplished with one user and one FreedomBox but many, like helping someone route around repressive government firewalls, will require groups of people and groups of boxes working together. One of our greatest architectural challenges has been finding a way for boxes to communicate securely without so slowing down or breaking network access as to make the system unpleasant to use. We have now outlined and built the first version of our proposed solution: Freedom-buddy. Freedom-buddy uses the world class TOR network so that boxes can find each other regardless of location or restrictive firewall and then allows the boxes to negotiate secure direct connections to each other for actually sending large or time sensitive data. We believe this blended approach will be most effective at improving the security and usability of personal-server communications and all the services we plan to build into those servers. - - + Date & Time: Configure time zone and NTP service - Web cleaning - - - Our first service, a piece of software you can use today to start making your web browsing more secure and private, is called "privoxy-freedombox". This software combines the functionality of - the Adblock Plus ad blocker, the Easy Privacy filtering list, and the (HTTPS Everywhere) website redirection plugin into a single piece of software to run on your FreedomBox. Combining these different plugins into software for your FreedomBox means that you can use them with almost any browser or mobile device using a standard web proxy connection. Because of our focus on building the FreedomBox as part of Debian this software will soon be available to anyone running a Debian system regardless of whether you are using our target DreamPlug hardware, a laptop, or a large rack server somewhere. - As you read this packages should already be available in the Raspbian repositories, which is the optimized version of Debian used on the Raspberry Pi hardware. Hopefully we will get that onto the main Debian mirrors over the next month; if you are interested in building it for yourself in the meantime, the source is available from gitorious. As we build additional components for the FreedomBox we will continue to work on making them widely available. - - + Service Discovery: Configure Avahi service - What is next? + Documentation revamp including new user manual and developer guide + + + Improved diagnostic tests, available in Plinth + + + Avoid unnecessary changes when installing on existing Debian system + + + Network configuration supports PPPoE connections + + + Debian packages can be download over Tor + + +
+
+ Version 0.5 (2015-08-07) + + + New targets: CubieTruck, i386, amd64 + + + New apps in Plinth: Transmission, Dynamic DNS, Mumble, ikiwiki, Deluge, Roundcube, Privoxy + + + NetworkManager handles network configuration and can be manipulated through Plinth. + + + Software Upgrades (unattended-upgrades) module can upgrade the system, and enable automatic upgrades. + + + Plinth is now capable of installing ejabberd, jwchat, and privoxy, so they are not included in image but can be installed when needed. + + + User authentication through LDAP for SSH, XMPP (ejabberd), and ikiwiki. + + + Unit test suite is automatically run on Plinth upstream. This helps us catch at least some code errors before they are discovered by users! + + + New, simpler look for Plinth. + + + Performance improvements for Plinth. + + +
+
+ Version 0.3 (2015-01-20) + + + Tor Bridges: All boxes now act as non-exit Tor bridges, routing traffic for the Tor network. + + + Firewall: firewall is on by default and is automatically managed. + + + Add BeagleBone support. We now have images for BeagleBone, RaspberryPi, VirtualBox i386/amd64, and DreamPlug. + + + Ability to enable and use Tor Hidden Services. Works with Ejabberd/JWChat and ownCloud services. + + + Enable Tor obfsproxy with scramblesuit. + + + Drop well-known root password (an account with sudo capabilities still exists for now but will be removed soon). + + + Switch to unstable as suite of choice for easier development. + + + Newer images are built with systemd by default (due to Debian change). + + + Install and operate firewall automatically (uses firewalld). + + + Major restructuring of Plinth UI using Python3, Django web development framework and Bootstrap3. Code quality is much better and UI is more polished. + + + Introduced packaging framework in Plinth UI for on-demand application installation. + + +
+
+ Version 0.2 (2014-03-16) + + + Support for Raspberry Pi and VirtualBox (x86) in addition to the DreamPlug. + + + New Services: - - As you may have seen, our Project Lead, Bdale Garbee, is about to begin a well earned early retirement from his long time role as Open Source & Linux Chief Technologist at Hewlett-Packard. Over the coming month Bdale and the rest of the Foundation team will be putting together plans for the next stage of FreedomBox development and the road to a 1.0 release. News and updates will follow at freedomboxfoundation.org (rss). + + Configuration Management UI. + + + Instant Messaging. + + + OwnCloud. + + + dnsmasq. + + + Low-Level Configuration Management. + + + Service Announcement. + + + LDAP Server. + + + LXC Support. + + + Source Packages. + + + + + The privoxy setup is now the default from Debian. + + +
+
+ Version 0.1 (2013-02-26) + + + First FreedomBox software release (0.1 image, developer release). + + + Full hardware support in Debian + + + Support for DreamPlug. + + + Basic software tools selected as common working environment: + + + User interface system "plinth" + + + Cryptography tools: gpg or "monkeysphere" + + + Box-to-box communication design: Freedom-buddy (uses TOR network) + + + Web cleaning: "privoxy-freedombox".
+
+ Download and Install + You may either use FreedomBox on one of the supported hardware, install it on a Debian machine, or deploy on a virtual machine. +
+ Downloading on Debian + If you are installing on Debian, you don't need to download these images. Instead read instructions on setting up FreedomBox on Debian. +
+
+ Downloading on Hardware or Virtual Machine +
+ Prepare your device + See hardware specific instructions on how to prepare your device at the Hardware section. Gather and read a lot of documentation on the web about first boot and flashing USB or SD Card on your hardware. +
+
+ Downloading Images + Recent images for supported targets are available here: + + + Official Images: + + +
+
+ Verifying the Downloaded Images + It is important to verify the images you have downloaded to ensure that the file has not be corrupted during the transmission and that it is indeed the image built by FreedomBox developers. + + + First open a terminal and import the public key of the FreedomBox developer who built the images: + $ gpg --keyserver x-hkp://pool.sks-keyservers.net --recv-keys 0x36C361440C9BC971 + + + Next, verify the fingerprint of the public key: + $ gpg --fingerprint 0x36C361440C9BC971 +pub 4096R/0C9BC971 2011-11-12 + Key fingerprint = BCBE BD57 A11F 70B2 3782 BC57 36C3 6144 0C9B C971 +uid Sunil Mohan Adapa <sunil@medhas.org> +sub 4096R/4C1D4B57 2011-11-12 + + + Finally, verify your downloaded image with its signature file .sig. For example: + $ gpg --verify freedombox-unstable_2015-01-15_beaglebone-armhf-card.tar.bz2.sig freedombox-unstable_2015-01-15_beaglebone-armhf-card.tar.bz2 +gpg: Signature made Thursday 15 January 2015 09:27:50 AM IST using RSA key ID 0C9BC971 +gpg: Good signature from "Sunil Mohan Adapa <sunil@medhas.org>" +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: BCBE BD57 A11F 70B2 3782 BC57 36C3 6144 0C9B C971 + + +
+
+ Installation + After the download you can use the image to boot supported hardware (including virtual machines). You'll need to copy the image to the memory card or USB stick as follows: + + + Figure out which device your card actually is. + + + Unplug your card. + + + Run dmesg -w to show and follow the kernel messages. + + + Plug your card in. You will see messages such as following: + [33299.023096] usb 4-6: new high-speed USB device number 12 using ehci-pci +[33299.157160] usb 4-6: New USB device found, idVendor=058f, idProduct=6361 +[33299.157162] usb 4-6: New USB device strings: Mfr=1, Product=2, SerialNumber=3 +[33299.157164] usb 4-6: Product: Mass Storage Device +[33299.157165] usb 4-6: Manufacturer: Generic +[33299.157167] usb 4-6: SerialNumber: XXXXXXXXXXXX +[33299.157452] usb-storage 4-6:1.0: USB Mass Storage device detected +[33299.157683] scsi host13: usb-storage 4-6:1.0 +[33300.155626] scsi 13:0:0:0: Direct-Access Generic- Compact Flash 1.01 PQ: 0 ANSI: 0 +[33300.156223] scsi 13:0:0:1: Direct-Access Multiple Flash Reader 1.05 PQ: 0 ANSI: 0 +[33300.157059] sd 13:0:0:0: Attached scsi generic sg4 type 0 +[33300.157462] sd 13:0:0:1: Attached scsi generic sg5 type 0 +[33300.462115] sd 13:0:0:1: [sdg] 30367744 512-byte logical blocks: (15.5 GB/14.4 GiB) +[33300.464144] sd 13:0:0:1: [sdg] Write Protect is off +[33300.464159] sd 13:0:0:1: [sdg] Mode Sense: 03 00 00 00 +[33300.465896] sd 13:0:0:1: [sdg] No Caching mode page found +[33300.465912] sd 13:0:0:1: [sdg] Assuming drive cache: write through +[33300.470489] sd 13:0:0:0: [sdf] Attached SCSI removable disk +[33300.479493] sdg: sdg1 +[33300.483566] sd 13:0:0:1: [sdg] Attached SCSI removable disk + + + In the above case, the disk that is newly inserted is available as /dev/sdg. Very carefully note this and use it in the copying step below. + + + + + Decompress the downloaded image using tar: + $ tar -xjvf freedombox-unstable_2015-08-06_beaglebone-armhf-card.tar.bz2 + The above command is an example for the beaglebone image built on 2015-08-06. Your downloaded file name will be different. + + + Copy the image to your card. Double check and make sure you don't write to your computer's main storage (such as /dev/sda). Also make sure that you don't run this step as root to avoid potentially overriding data on your hard drive due to a mistake in identifying the device or errors while typing the command. USB disks and SD cards inserted into the system should typically be write accessible to normal users. If you don't have permission to write to your SD card as a user, you may need to run this command as root. In this case triple check everything before you run the command. Another safety precaution is to unplug all external disks except the SD card before running the command. + For example, if your SD card is /dev/sdf as noted in the first step above, then to copy the image, run: + $ cd build +$ dd bs=1M if=freedombox-unstable_2015-08-06_beaglebone-armhf-card.img of=/dev/sdf conv=fdatasync + The above command is an example for the beaglebone image built on 2015-08-06. Your image file name will be different. + When picking a device, use the drive-letter destination, like /dev/sdf, not a numbered destination, like /dev/sdf1. The device without a number refers to the entire device, while the device with a number refers to a specific partition. We want to use the whole device. Downloaded images contain complete information about how many partitions there should be, their sizes and types. You don't have to format your SD card or create partitions. All the data on the SD card will be wiped off during the write process. + + + Use the image by inserting the SD card or USB disk into the target + device and booting from it. Your device should also be prepared (see the Hardware section). + + + Read (the rest of) the Manual for instructions on how to use applications in FreedomBox. + + +
+
+
Apps
@@ -895,6 +601,48 @@ To login as a FreedomBox user, go to the wiki/blog's login page and select the Other tab. Then click the "Login with HTTP auth" button. The browser will show a popup dialog where you can enter the username and password of the FreedomBox user.
+
+ Unhosted + From : + + Also known as "serverless", "client-side", or "static" web apps, unhosted web apps do not send your user data to their server. Either you connect your own server at runtime, or your data stays within the browser. + + Note: This module is not yet part of mainline FreedomBox, but available for testing via . +
+ Set up remoteStorage + Your FreedomBox contains the restore remoteStorage server, which means that it can serve as your personal backend for Unhosted apps. Make sure the package is installed in your Plinth. + Then create a remoteStorage account at https://<yourdomain>/restore/. + Warning: These user accounts are currently not integrated with Plinth user management, and public sign-up is enabled! +
+
+ Try Unhosted apps + Once your FreedomBox is set up, and both PageKite and remoteStorage are running, try one of the following Unhosted apps (more are listed at ): + + + (a notepad) + + + (list your favorite drinks) + + + (a simple todo list) + + + To connect the Unhosted app to your remoteStorage, click on the remoteStorage icon and type your address <user>@<yourdomain>, e.g.: + + + + + + + remotestorage.png + + + + If this doesn't work, make sure that both PageKite and remoteStorage are running, and that your FreedomBox SSL certificate is trusted in your current browser session (important when using private browsing). + Finish the OAuth flow by authenticating with your password and authorizing access, then you should get redirected back to the Unhosted app, and you should be able to use it. All data of the Unhosted app is stored on your FreedomBox. +
+
System @@ -2483,15 +2231,18 @@ firewall-cmd --permanent --zone=internal --remove-interface=eth0
Hardware FreedomBox is aimed as a consumer electronics device that is easy to setup, maintain and use. The project does not aim to create a custom hardware device. Instead we plan to support/customize exiting hardware. - In addition to supporting various single board computers and other devices, FreedomBox also supports being installed in a virtual machine. Also, any Debian machine can be turned into a FreedomBox by installing the freedombox-setup package. See usage instructions for more details. + In addition to supporting various single board computers and other devices, FreedomBox also supports being installed in a virtual machine. Also, any Debian machine can be turned into a FreedomBox by installing the freedombox-setup package. See the manual for more details.
Supported Hardware
Recommended Hardware - + + + + @@ -2529,6 +2280,57 @@ firewall-cmd --permanent --zone=internal --remove-interface=eth0 BeagleBone Black + + + + + + + + + A20 OLinuXino Lime2 + + + + + + A20 OLinuXino Lime2 + + + + + + + + + + + A20 OLinuXino MICRO + + + + + + A20 OLinuXino MICRO + + + + + + + + + + + PC Engines APU + + + + + + PC Engines APU + + @@ -2640,7 +2442,14 @@ firewall-cmd --permanent --zone=internal --remove-interface=eth0
Targeted Hardware - Although the project may focus on supporting specific devices, we are looking to support as wider a variety of hardware as possible that is suitable for FreedomBox needs. Take a look at the list of hardware targeted for support. If you are a developer, consider adding hardware support for your device by modifying Freedom Maker and FreedomBox Setup. +
+ List of Hardware Targeted + Although the project may focus on supporting specific devices, we are looking to support as wider a variety of hardware as possible that is suitable for FreedomBox needs. Take a look at the list of hardware targeted for support. +
+
+ Adding Hardware Support + If you are a developer, consider adding hardware support for your device by modifying Freedom Maker and FreedomBox Setup. +
Cubietruck @@ -2664,12 +2473,12 @@ firewall-cmd --permanent --zone=internal --remove-interface=eth0
Download - FreedomBox SD card images for this hardware are being built. + FreedomBox SD card images for this hardware are being built. These SD card images are meant for use with the on-board SD card slot and won't work when used with a separate SD card reader connected via USB. An alternative to downloading these images is to install Debian on Cubietruck and then install FreedomBox on it.
Build Image - FreedomBox images for this hardware can be built using Freedom Maker once the support for it is added. + FreedomBox images for this hardware can be built using Freedom Maker.
Availability @@ -2759,6 +2568,7 @@ firewall-cmd --permanent --zone=internal --remove-interface=eth0
Download FreedomBox SD card images for this hardware are available. Follow the instructions on the download page to create a FreedomBox SD card and boot into FreedomBox. + Note: This image is for BeagleBone Black. It won't work on BeagleBone Green. An alternative to downloading these images is to install Debian on BeagleBone and then install FreedomBox on it.
@@ -2831,6 +2641,376 @@ firewall-cmd --permanent --zone=internal --remove-interface=eth0 None
+
+ A20 OLinuXino Lime2 + + + + + + + A20 OLinuXino Lime2 + + + + Olimex's A20 OLinuXino Lime2 is fully open source hardware single board computer using the Allwinner A20 Dual Core ARM processor. FreedomBox images are being built for it starting with version 0.7. For using this board as FreedomBox, a separate USB WiFi device that does not require non-free firmware is recommended. +
+ Similar Hardware + The following similar hardware will also work well with FreedomBox. + + + Olimex's A20 OLinuXino Lime2 4GB. This hardware merely has extra 4GB NAND storage that is not used by FreedomBox. + + +
+
+ Download + FreedomBox SD card images for this hardware are being built. These SD card images are meant for use with the on-board SD card slot and won't work when used with a separate SD card reader connected via USB. + An alternative to downloading these images is to install Debian on the device and then install FreedomBox on it. +
+
+ Build Image + FreedomBox images for this hardware can be built using Freedom Maker once the support for it is added. +
+
+ Availability + + + Price: 45 EUR (A20 OLinuXino Lime2) + + + Price: 55 EUR (A20 OLinuXino Lime2 4GB) + + + + Olimex Store + + + +
+
+ Hardware + + + Open Source Hardware (OSHW): Yes + + + CPU: Allwinner A20, ARM Cortex-A7 @ 1GHz dual-core + + + RAM: 1 GiB DDR3 + + + Storage: 4 GB NAND flash built-in (only on 4GB model), 1x microSD slot + + + Architecture: armhf + + + Ethernet: 10/100/1000, RJ45 + + + WiFi: None, use a USB WiFi device + + + SATA: 1x port + + +
+
+ Non-Free Status + + + Non-free blobs required: No + + + WiFi: Not available + + + Works with stock Debian kernel: Yes + + + Boot Firmware: BROM (GPLV2+) + + +
+
+ Known Issues + + + WiFi is not available. A separate USB WiFi device is recommended. + + +
+
+
+ A20 OLinuXino MICRO + + + + + + + A20 OLinuXino MICRO + + + + Olimex's A20 OLinuXino MICRO is fully open source hardware single board computer using the Allwinner A20 Dual Core ARM processor. FreedomBox images are being built for it starting with version 0.7. For using this board as FreedomBox, a separate USB WiFi device that does not require non-free firmware is recommended. +
+ Similar Hardware + The following similar hardware will also work well with FreedomBox. + + + Olimex's A20 OLinuXino MICRO 4GB. This hardware merely has extra 4GB NAND storage that is not used by FreedomBox. + + +
+
+ Download + FreedomBox SD card images for this hardware are being built. These SD card images are meant for use with the on-board SD card slot and won't work when used with a separate SD card reader connected via USB. + An alternative to downloading these images is to install Debian on the device and then install FreedomBox on it. +
+
+ Build Image + FreedomBox images for this hardware can be built using Freedom Maker once the support for it is added. +
+
+ Availability + + + Price: 55 EUR (A20 OLinuXino MICRO) + + + Price: 65 EUR (A20 OLinuXino MICRO 4GB) + + + + Olimex Store + + + +
+
+ Hardware + + + Open Source Hardware (OSHW): Yes + + + CPU: Allwinner A20, ARM Cortex-A7 @ 1GHz dual-core + + + RAM: 1 GiB DDR3 + + + Storage: 4 GB NAND flash built-in (only on 4GB model), 1x microSD slot + + + Architecture: armhf + + + Ethernet: 10/100, RJ45 + + + WiFi: None, use a USB WiFi device + + + SATA: 1x port + + +
+
+ Non-Free Status + + + Non-free blobs required: No + + + WiFi: Not available + + + Works with stock Debian kernel: Yes + + + Boot Firmware: BROM (GPLV2+) + + +
+
+ Known Issues + + + WiFi is not available. A separate USB WiFi device is recommended. + + +
+
+
+ APU + + + + + + + PC Engines APU 1D + + + + PC Engines APU 1D is a single board computer with 3 Gigabit ethernet ports, a powerful AMD APU and Coreboot firmware. FreedomBox images built for AMD64 machines are tested to work well for it. For using this board as FreedomBox, a USB WiFi device that does not require non-free firmware is recommended. +
+ Similar Hardware + Although untested, the following similar hardware is also likely to work well with FreedomBox. + + + Using amd64 image: + + + + apu1c + + + + + apu1c4 + + + + + apu1d4 + + + + + + Using i386 image: + + + + alix1d + + + + + alix1e + + + + + alix2d2 + + + + + alix2d3 + + + + + alix2d13 + + + + + alix3d2 + + + + + alix3d3 + + + + + alix6f2 + + + + + +
+
+ Download + FreedomBox disk images for this hardware are available. Follow the instructions on the download page to create a FreedomBox SD card, USB disk, SSD or hard drive and boot into FreedomBox. Pick the image meant for all amd64 machines. + An alternative to downloading these images is to install Debian on the APU and then install FreedomBox on it. +
+
+ Networking + The first network port, the left most one in the above picture, is configured by FreedomBox to be an upstream Internet link and the remaining 2 ports are configured for local computers to connect to. +
+
+ Build Image + FreedomBox images for this hardware, which is for all amd64 machines, can be built using Freedom Maker. +
+
+ Availability + + + Price: 110 - 170 USD (depending on the board and supplier) + + + + PC Engines + + + + + Full list of suppliers + + + +
+
+ Hardware + + + Open Hardware: No + + + CPU: AMD G series T40E + + + RAM: 2 GB DDR3-1066 DRAM + + + Storage: SD card, External USB + + + Architecture: amd64 + + + Ethernet: 3 Gigabit Ethernet ports + + + WiFi: None, use a USB WiFi device + + + SATA: 1 m-SATA and 1 SATA + + +
+
+ Non-Free Status + + + Non-free blobs required: No + + + WiFi: Not available + + + Works with stock Debian kernel: Yes + + + Boot firmware: Coreboot + + +
+
+ Known Issues + None +
+
VirtualBox @@ -2894,7 +3074,7 @@ firewall-cmd --permanent --zone=internal --remove-interface=eth0 To configure this go to VM settings -> [Network] -> [Adapter] -> [Port Forwarding]. Map a port such as 2222 from host to guest port 22 and you will be able to ssh into FreedomBox from host machine as follows: - ssh -p 4443 fbx@localhost + ssh -p 2222 fbx@localhost Map 4443 on host to 443 on the guest. This make FreedomBox HTTPS service available on host using the URL You will need to add a mapping for each such services from host to guest. @@ -3136,22 +3316,18 @@ $ cp /tmp/vbox-root1/home/fbx/freedom-maker/build/freedom*vdi ~/ $ sudo umount /tmp/vbox-root1 # $ sudo umount /tmp/vbox-img1 # corruption here.
+
+ Fixing the time after suspend and resume + The virtual machine loses the correct time/date after suspending and resuming. One way to fix this is to create a cron-job that restarts the time service ntp. You can add a crontab entry as root to restart ntp every 15 minutes by typing 'crontab -e' and adding this line: + */15 * * * * /etc/init.d/ntp restart + Do not restart this service too often as this increases the load of publicly and freely available NTP servers. +
Debian - - - - - - - Debian - - - FreedomBox is a pure blend of Debian. This means that all the work on FreedomBox is available in Debian as packages. It also means that any machine running Debian can be turned into a FreedomBox. - This page describes the process of installing FreedomBox on a Debian system. Currently, FreedomBox currently runs Debian Unstable (Sid) and Debian Testing (Strech). + This page describes the process of installing FreedomBox on a Debian system. Currently, FreedomBox works in Debian Testing (Stretch) and Unstable (Sid). Use a fresh Debian installation @@ -3162,7 +3338,10 @@ $ sudo umount /tmp/vbox-root1 Installing on Debian - Install Debian Unstable (Sid) on your hardware. + Check the Troubleshooting section below, for any tips or work-arounds that might help during the install. + + + Install Debian Testing (Stretch) or Unstable (Sid) on your hardware. If you choose to create an initial user account, use "fbx" as the login name. (Once the FreedomBox setup program completes, all user accounts except for the "fbx" account will be locked out via pam_access. This also affects sudo access.) @@ -3180,6 +3359,7 @@ $ sudo umount /tmp/vbox-root1 Run FreedomBox setup program. This installs further packages and sets up basic configuration. $ sudo /usr/lib/freedombox/setup | tee freedombox-setup.log + You may have to clear your existing network configuration. See Troubleshooting note #2 below. Reboot the system. This is necessary to trigger the first-run script. @@ -3203,9 +3383,10 @@ $ sudo apt-get install policykit-1 $ sudo reboot - Freedombox does not support network device configuration via /etc/network/interfaces, and it may misbehave if any non-loopback interfaces are mentioned there. (See bug #797614.) Future versions of freedombox-setup will clear this file automatically; for now, edit it manually and ensure that it contains only the following: + Freedombox does not support network device configuration via /etc/network/interfaces, and it will not manage any non-loopback interfaces mentioned there. (See bug #797614.) Future versions of freedombox-setup will clear this file automatically; for now, edit it manually and ensure that it contains only the following: auto lo iface lo inet loopback + If you have already completed the setup process without doing this step, you will need to clear out the /etc/network/interfaces file keeping only the above lines. Then perform a reboot. After this network connections configured by the setup step above will configure your network. Network interfaces will then be in the internal or external firwall zone. This is essential for the FreedomBox's web interface to be reachable from other machines in the network. You can tweak network manager connections with the nmtui command if you wish.
@@ -3499,6 +3680,14 @@ iface lo inet loopback +
+ Firmware Installation + The free firmware for these devices is not packaged in Debian yet. You can manually download and install the firmware as follows: + sudo su [enter password] +cd /lib/firmware +wget https://www.thinkpenguin.com/files/ath9k-htc/version-1.4-beta/htc_9271.fw +wget https://www.thinkpenguin.com/files/ath9k_firmware_free-version/htc_7010.fw +
Resources @@ -3535,6 +3724,20 @@ iface lo inet loopback
Contributing + From code, design and translation to spreading the world and donation, here is a list of possible contributions to develop FreedomBox. +
+ Welcome to newcomers + As a newcomer, you are more than welcome to introduce yourself to all users and doers on the "FreedomBox-discuss" mailing list or on the #freedombox IRC channel. + In addition to make useful contacts, you can start reporting bugs and translate (see below) the wiki website and the FreedomBox web interface. +
+
+ Development priorities + Upcoming priorities have been discussed end of October 2015 by several core developers and the Freedombox Foundation. You'll find on the mailing list archives a Medium Term Roadmap for 2015 and 2016. Please check next progess calls to keep yourself on track and meet members of the release team. A TODO page aggregates the complete list of the items to work on for FreedomBox. +
+
+ Add an Application + If you are a developer and wish to see an application available in FreedomBox, you can contribute by adding the application to FreedomBox. See the FreedomBox Developer Manual. +
Code If you are a developer, you can contribute code to one of the sub-projects of FreedomBox. Step-by-step process of contributing code to FreedomBox is available. @@ -3551,51 +3754,6 @@ iface lo inet loopback You can pickup a task from one of the TODO lists. The individual page project pages contain information availabily of the code, how to build and TODO lists.
-
- Add an Application - If you are a developer and wish to see an application available in FreedomBox, you can contribute by adding the application to FreedomBox. See the FreedomBox Developer Manual. -
-
- Donate - The FreedomBox Foundation is a Delaware non-profit corporation in the process of applying for 501(c)(3) federal nonprofit recognition from the IRS. FreedomBox project is run by volunteers. You can help the project financially by donating via PayPal, Bitcoin or by mailing a check. Please see the donation page for details on how to donate. -
-
- Document: User Manual, Website and Wiki - FreedomBox needs better documentation for users and contributors. FreedomBox manual is prepared by aggregating various pages on the wiki and exporting to various formats. The manual is then used in Plinth and elsewhere. - If you wish to contribute to the FreedomBox wiki (and consequently the FreedomBox manual), you can create a wiki account and start editing. - For contributing to the website please start a discussion on the FreedomBox mailing list. -
-
- Quality Assurance - - - FreedomBox already runs on many platforms and it is not possible for developers to test all possible platforms. If you have one of the supported hardware you can help with testing FreedomBox on the platform. - - - When an application is made available on FreedomBox, not all of its functionality is tested in the real world by developer doing the work. Deploying the application and testing it will help ensure high quality applications in FreedomBox. - - - See the quality assurance page for a basic list of test cases to check for and information on reporting bugs. -
-
- Translate - All text visible to users of FreedomBox needs to be localized to various languages. This includes: - - - Plinth web interface for FreedomBox - - - FreedomBox documentation - - - FreedomBox website and wiki - - - Individual applications that FreedomBox exposes to users such as ownCloud, JWChat etc. - - - If you wish to see FreedomBox available for one of your languages, please start a discussion on the FreedomBox discuss mailing list. -
Design
@@ -3633,6 +3791,48 @@ iface lo inet loopback
+
+ Donate + The FreedomBox Foundation is a Delaware non-profit corporation in the process of applying for 501(c)(3) federal nonprofit recognition from the IRS. FreedomBox project is run by volunteers. You can help the project financially by donating via PayPal, Bitcoin or by mailing a check. Please see the donation page for details on how to donate. +
+
+ Document: User Manual, Website and Wiki + FreedomBox needs better documentation for users and contributors. FreedomBox manual is prepared by aggregating various pages on the wiki and exporting to various formats. The manual is then used in Plinth and elsewhere. + If you wish to contribute to the FreedomBox wiki (and consequently the FreedomBox manual), you can create a wiki account and start editing. + For contributing to the website please start a discussion on the FreedomBox mailing list. +
+
+ Quality Assurance + + + FreedomBox already runs on many platforms and it is not possible for developers to test all possible platforms. If you have one of the supported hardware you can help with testing FreedomBox on the platform. + + + When an application is made available on FreedomBox, not all of its functionality is tested in the real world by developer doing the work. Deploying the application and testing it will help ensure high quality applications in FreedomBox. + + + See the quality assurance page for a basic list of test cases to check for and information on reporting bugs. +
+
+ Localization + All text visible to users of FreedomBox needs to be localized to various languages. This translation work includes: + + + Plinth web interface for FreedomBox + + + FreedomBox documentation + + + FreedomBox website and wiki + + + Individual applications that FreedomBox exposes to users such as ownCloud, JWChat etc. + + + Some of the translation work are implemented in user interface (Plinth) since the 0.7 release. Documents for user interface translation are currently available on Transifex localization platform and GitHub. If you wish to see FreedomBox available for one of your languages, please start a discussion on the FreedomBox discuss mailing list or on the #freedombox IRC channel to avoid double translations. + For more information, please visit the FreedomBox translation landing page. +
Spread the Word Speak to your family, friends, local community or at global conferences about the importance of FreedomBox. To be a successful project we need many more participants, be it users or contributors. Write about your efforts at the talks page and on the wiki. @@ -3701,7 +3901,7 @@ iface lo inet loopback | | | +- forms.py | | - | +- views.py + | +- urls.py | | | +- views.py | | @@ -4170,7 +4370,7 @@ Plinth module to configure Tiny Tiny RSS. Plinth comes installed with all FreedomBox images. You can download FreedomBox images and run on any of the supported hardware. Then, you can access Plinth by visiting the URL . - If you are on a Debian box, you may install Plinth from Debian package archive. Currently, only Sid (unstable) is supported. To install Plinth run: + If you are on a Debian box, you may install Plinth from Debian package archive. Currently, only Stretch (testing) and Sid (unstable) are supported. To install Plinth run: $ sudo apt-get install plinth @@ -4295,7 +4495,7 @@ Plinth module to configure Tiny Tiny RSS. If you are on a Debian box, you may install FreedomBox Setup from Debian package archive. This essentially turns your Debian installation into a FreedomBox! Currently, only Sid (unstable) is supported. To install FreedomBox Setup, see instructions on setting up FreedomBox on a Debian machine. - You can also get FreedomBox Setup from its Git repository and build Debian package from source. + You can also get FreedomBox Setup from its Git repository and build Debian package from source.
@@ -4323,10 +4523,7 @@ Plinth module to configure Tiny Tiny RSS. Instructions on how to contribute code are available. - FreedomBox Setup is hosted on FreedomBox Alioth Portal. The primary Git repository is hosted there. - - - Instructions to build Debian package from source are available. + FreedomBox Setup is part of the FreedomBox Alioth Project. List of bugs, TODO items, packages issues and feature requests are available on the issue tracker. @@ -4427,4 +4624,64 @@ Plinth module to configure Tiny Tiny RSS.
+
+ Other Resources: Manual Older Versions + + + + 0.3 Manual + + + + + 0.2 Manual + + + + + Jessie Manual + + + +
+
+ Tell people around you + + + + FreedomBox in the Press + + + + + Conferences + + + + + Talks and presentations + + + + Available Material Slides and other raw material + + + + + + Facebook + + + + + Twitter + + + + + Debconf11 Videos + + + +
diff --git a/doc/images/a20-olinuxino-lime2.jpg b/doc/images/a20-olinuxino-lime2.jpg new file mode 100644 index 000000000..887cb5970 Binary files /dev/null and b/doc/images/a20-olinuxino-lime2.jpg differ diff --git a/doc/images/a20-olinuxino-lime2_thumb.jpg b/doc/images/a20-olinuxino-lime2_thumb.jpg new file mode 100644 index 000000000..e2186b3c3 Binary files /dev/null and b/doc/images/a20-olinuxino-lime2_thumb.jpg differ diff --git a/doc/images/a20-olinuxino-micro.jpg b/doc/images/a20-olinuxino-micro.jpg new file mode 100644 index 000000000..5c6e4feb0 Binary files /dev/null and b/doc/images/a20-olinuxino-micro.jpg differ diff --git a/doc/images/a20-olinuxino-micro_thumb.jpg b/doc/images/a20-olinuxino-micro_thumb.jpg new file mode 100644 index 000000000..b1ecec4ad Binary files /dev/null and b/doc/images/a20-olinuxino-micro_thumb.jpg differ diff --git a/doc/images/apu1d.jpg b/doc/images/apu1d.jpg new file mode 100644 index 000000000..4e0fe59be Binary files /dev/null and b/doc/images/apu1d.jpg differ diff --git a/doc/images/apu1d_thumb.jpg b/doc/images/apu1d_thumb.jpg new file mode 100644 index 000000000..5a16039ad Binary files /dev/null and b/doc/images/apu1d_thumb.jpg differ diff --git a/doc/images/remotestorage.png b/doc/images/remotestorage.png new file mode 100644 index 000000000..f8444593f Binary files /dev/null and b/doc/images/remotestorage.png differ