Contents

  1. FreedomBox Einführung
    1. Smart Router
    2. Private Cloud
  2. Schnelleinstieg
  3. Getting Help
  4. Release Notes
    1. Plinth v0.15.3 (2017-10-20)
    2. Plinth v0.15.2 (2017-09-24)
    3. Plinth v0.15.0 (2017-07-01)
    4. Plinth v0.14.0 (2017-04)
    5. Plinth v0.13.1 (2017-01-22)
    6. Plinth v0.12.0 (2016-12-08)
    7. Plinth v0.11.0 (2016-09-29)
    8. Plinth v0.10.0 (2016-08-21)
    9. Version 0.9.4 (2016-06-24)
    10. Version 0.9 (2016-04-24)
    11. Version 0.8 (2016-02-20)
    12. Version 0.7 (2015-12-13)
    13. Version 0.6 (2015-10-31)
    14. Version 0.5 (2015-08-07)
    15. Version 0.3 (2015-01-20)
    16. Version 0.2 (2014-03-16)
    17. Version 0.1 (2013-02-26)
  5. Herunterladen und installieren
    1. Herunterladen für Debian
    2. Herunterladen für Hardware oder Virtualle Maschinen
  6. Apps
    1. Anonymity Network (Tor)
    2. BitTorrent (Deluge)
    3. BitTorrent (Transmission)
    4. Bookmarks (Shaarli)
    5. Chat Server (XMPP)
    6. Dynamic DNS Client
    7. Email Client (Roundcube)
    8. ownCloud
    9. Public Visibility (PageKite)
    10. Secure Shell
    11. Voice Chat (Mumble)
    12. Web Proxy (Privoxy)
    13. Wiki and Blog (Ikiwiki)
    14. Unhosted Storage
  7. System
    1. Configure
    2. Users and Groups
    3. Networks
    4. Software Upgrades
    5. Diagnostics
    6. Firewall
    7. Date & Time
  8. Hardware
    1. Unterstützte Hardware
    2. Ziel-Hardware
    3. Cubietruck
    4. Beagle Bone Black
    5. A20 OLinuXino Lime2
    6. A20 OLinuXino MICRO
    7. APU
    8. VirtualBox
    9. Debian
    10. DreamPlug
    11. Raspberry Pi Model B+
    12. Raspberry Pi 2 Model B
    13. USB Wi-Fi
  9. Advanced Topics
    1. Adding Additional Features
  10. Mitarbeiten
    1. Quick Links
    2. Welcome to newcomers
    3. Development priorities
    4. Contributions needed
  11. Für Entwickler
    1. Writing Applications - Tutorial
    2. Reference Guide
  12. Hacking
    1. Plinth
    2. FreedomBox Setup
    3. Freedom Maker
  13. Weiteres Material: Handbücher Älterer Versionen
  14. Weitersagen

FreedomBox Einführung

FreedomBox ist ein persönlicher Server, der Ihre Privatsphäre schützt. Es ist ein freier Software-Stack, ein Teil des Debian universellen Betriebssystems, das auf vielen Varianten von günstiger und energieeffizienter Hardware installiert werden kann. Die Einfachheit der Installation und des Betriebs einer FreedomBox ist ähnlich der von einem Smartphone.

1. Smart Router

FreedomBox läuft auf einem physischen Computer und kann Ihren Datenverkehr lenken. Es kann zwischen verschiedenen Geräten zu Hause sitzen, wie beispielsweise Mobiltelefone, Laptops, Fernseher und das Internet und ersetzt einen Wireless-Router. Durch das Routen des Datenverkehrs kann FreedomBox Tracking-Anzeigen und bösartige Web-Bugs entfernen, bevor sie überhaupt Ihre Geräte erreichen. FreedomBox kann Ihren Standort verbergen und schützt Ihre Anonymität durch "Onion Routing" Ihres Datenverkehrs über Tor. FreedomBox bietet einen VPN-Server, den Sie verwenden können wenn Sie unterwegs sind, um Ihren Datenverkehr auf nicht vertrauenswürdigen öffentlichen Funknetzen zu verschiedenen Geräten zuhause sicher und geheim zu halten. Es kann auch zusammen mit Ihrem Laptop mitgeführt und dazu verwendet werden, um sich an öffentliche Netze bei der Arbeit, in der Schule oder Büro zu verbinden, um deren Dienste in Anspruch zu nehmen. Es könnte in einem Dorf verwendet werden, um die Kommunikation im ganzen Dorf zu ermöglich. Zukünftig beabsichtigt FreedomBox Unterstützung für alternative Verbindungsmöglichkeiten mit dem Internet zu ermöglichen, wie beispielsweise Mesh Netze.

2. Private Cloud

FreedomBox bietet Dienstleistungen: für Ihren Computer und mobile Geräte in Ihrem Haus und zu Computern und mobilen Geräten von anderen Menschen, die Ihre Freunde sind. FreedomBox bietet Filesharing wie Dropbox, gemeinsame Kalander wie Google oder Yahoo und Foto-Sharing. FreedomBox bietet Instant Messaging und wirklich sichere Sprachkonferenzen, die auf niedriger Bandbreite mit hoher Qualität arbeiten. FreedomBox hat einen Blog und Wiki und lässt Sie so Ihre Informationen veröffentlichen und gemeinsam mit dem Rest der Welt zusammenarbeiten. In Kürze wird ein persönlicher E-Mail-Server und verteiltes Social-Networking mit GNU Social und Diaspora realisiert, die beide Ihre Privatsphäre respektieren als Alternative zu Google Mail und Facebook.

Schnelleinstieg

  1. Falls Sie es nicht bereits getan haben, laden Sie ein FreedomBox Image herunter und installieren Sie es indem Sie den Anweisungen auf Download folgen.

  2. Stecken Sie ein Ende des Ethernetkabels in den Ethernet-Port Ihrer FreedomBox und das andere Ende in Ihren Router.

    • Auf der Dreamplug sollte der eth0-Port (in der Mitte der Box) an den Router angeschlossen werden.
  3. Wenn Ihr Gerät einen zweiten Ethernet-Port hat, können Sie Ihren Computer mit einem weiteren Ethernetkabel direkt daran anschließen.
  4. Starten Sie Ihre FreedomBox.

  5. Beim ersten Booten wird die FreedomBox die Erstinstallation durchführen und dann neu zu starten. Dies kann mehrere Minuten dauern.

  6. Nachdem die FreedomBox neu gestartet wurde, können Sie auf dessen Web-Interface (genannt Plinth) über Ihren Webbrowser zugreifen.

    • Wenn der Computer direkt an die FreedomBox durch einen zweiten (LAN) Ethernet-Port angeschlossen ist, können Sie http://freedombox/ oder http://10.42.0.1/ verwenden.

    • Wenn Ihr Computer mDNS unterstützt (GNU/Linux, Mac OSX und Windows mit installierter mDNS-Software), können Sie http://freedombox.local/ (oder http://der-hostname-den-Sie-bei-der-Installation-verwendet-haben.local/) verwenden.

    • Wenn keine dieser Methoden zur Verfügung steht, müssen Sie die IP-Adresse Ihrer FreedomBox herausfinden. Sie können dazu das "nmap" Programm verwenden:

           nmap -p 80 --open -sV 192.168.0.0/24

      Ihre FreedomBox wird als eine IP-Adresse mit einer offenen TCP-Port 80 unter Verwendung vom Apache-Dienst http auf Debian erscheinen, wie das Beispiel hier zeigt, wo es über http://192.168.0.165 zugänglich ist:

           Nmap scan report for 192.168.0.165
           Host is up (0.00088s latency).
           PORT   STATE SERVICE VERSION
           80/tcp open  http    Apache httpd 2.4.17 ((Debian))
  7. Beim Zugriff auf Plinth wird Sie Ihr Browser warnen, dass er sicher kommuniziert aber dass er das Sicherheitszertifikat für ungültig hält. Dies ist eine Tatsache, die Sie zur Zeit akzeptieren müssen, weil das Zertifikat automatisch auf der Box erzeugt und daher "selbstsigniert" wird (der Browser könnte auch Worte wie "nicht vertrauenswürdig", "nicht privat", "Privatsphäre-Fehler" oder "unbekannter Emittent/Behörde" verwenden). Ihrem Browser mitzuteilen dass Sie dies wissen, wird durch Drücken der Tasten wie "Ich verstehe die Risiken" oder "Ausnahme hinzufügen" erreicht.
  8. Beim ersten Zugriff werden Sie eine Willkommensseite sehen die Sie bittet, einige grundlegende Informationen zum Einrichten der FreedomBox bereitzustellen.

  9. Nach dem Ausfüllen des Formulars werden Sie bei Plinth angemeldet und in der Lage sein, auf Anwendungen und Konfigurationen über diese Schnittstelle zuzugreifen.
  10. Wenn Ihr Computer direkt mit der FreedomBox verbunden ist kann Ihre FreedomBox als Router arbeiten, und Ihnen Zugriff auf das Internet ermöglichen.

Nun können Sie die Apps, die auf der FreedomBox verfügbar sind, ausprobieren.

Getting Help

This document is intended to give you the information you need to get started with your FreedomBox. However, if you have any questions after reading this document, you can get help by:

Release Notes

The following are the release notes for each FreedomBox version.

1. Plinth v0.15.3 (2017-10-20)

1.1. Changed

  • Rename Disks to Storage.
  • Rename Snapshot to Storage Snapshots.
  • tt-rss: Enable API access by default.
  • Allow access to Plinth from outside the LAN.
  • matrix-synapse: Disable public registration by default.
  • power: Merge actions into the user dropdown.

1.2. Added

  • Add locales for Kannada (kn) and for Bengali (bn).
  • ejabberd: Use Let's Encrypt certificate, also across renewals.
  • matrix-synapse: Add enable/disable public registrations.
  • Add captcha validation on 3 failed attempts.
  • matrix-synapse: Enable LDAP integration.
  • letsencrypt: Automatically obtain and revoke SSL certificates.

1.3. Fixed

  • Fix front page label names.
  • Fix vertical alignment of shortcut icons.
  • storage: Fix issue with locales that use other decimal separators.
  • Make tt-rss api accessible using Apache basic auth.
  • letsencrypt: Handle case where current domain is empty.
  • Handle both admin and non-admin user names in update user template.

2. Plinth v0.15.2 (2017-09-24)

2.1. Added

  • letsencrypt: Show more info on cert validity status.
  • letsencrypt: Add option to delete certificates.
  • letsencrypt: Add option to let Plinth manage certbot's renewal hooks.
  • power: Warn if a package manager is running before shutdown/restart.
  • security: Install and manage fail2ban.
  • names: Include domain and services from dynamicdns.
  • disks: Add low disk space warning to system and disks page.
  • ssh: New application to manage SSH server.
  • Add api module to get enabled services and access info.
  • Add Django password validators.
  • ejabberd, ikiwiki, ttrss: Add user login descriptions.

2.2. Removed

  • diaspora: Disable for this release due to issues affecting package.
  • Remove help from navbar before firstboot complete.

2.3. Fixed

  • i18n: Don't use backslash-newline for wrapping long lines.
  • radicale: Update link to documentation.
  • sso: Upgrade crypto to 4096-bit RSA and SHA-512.
  • Users: Allow non-admin users to log out.

2.4. Changed

  • letsencrypt: Make Let's Encrypt an essential module.
  • UI: Make apps and configure pages responsive on small screens.
  • Make help accessible for logged-in non-admin users.

3. Plinth v0.15.0 (2017-07-01)

  • Added Tahoe-LAFS module for distributed file storage.
  • Added Diaspora* module for federated social networking.
    • Currently only available in "contrib" repository.
  • New Locales for Czech (cs) and Tamil (ta).
  • Added SSO using auth_pubtkt for Syncthing, TT-RSS, and the Repro admin panel.
    • If you are logged in to Plinth, you will be automatically logged in to these web apps.
  • ejabberd: Added option to enable/disable Message Archive Management.
  • help: Added Debian release name to about page.
  • firstboot: De-bloat first welcome screen.
  • Pinned footer to the bottom of the viewport.
  • disks: Restrict precision of reported available space on root partition.
  • diagnostics: Disable button if app/service is not running.
  • help: Only show help pages if user is logged in.
  • navbar: Moved logout to user drop-down and added a new power drop-down.
  • disks: Show disabled partition resize option if no space is available.
  • Added line break to titles to fix frontpage layout.
  • syncthing: Fixed typos and clarity in description.
  • firewall: Fix 500 error when firewalld is not running.
  • setup: Disable install/upgrade when dpkg/apt is running.
  • disks: Use information from lsblk for more accuracy.
  • datetime: Show timezone properly when it not in expected list.

4. Plinth v0.14.0 (2017-04)

  • tor: Added option to use upstream bridges.
  • openvpn: Added shortcut to front page, shown only when logged-in.
  • openvpn: Non-admin users can download their own profiles.
  • Added new locales for Hindi (hi) and Gujarati (gu).
  • Added Syncthing module for file synchronization.
  • Added Matrix Synapse as chat server with groups, audio and video.
  • Require admin access for all system configuration pages.
  • Changed appearance of topbar and footer.
  • openvpn: Regenerate user key or certificate if empty.
  • disks: Workaround issue in parted during resize.

5. Plinth v0.13.1 (2017-01-22)

  • Two new apps were added:
    • Gobby Server (infinoted) for collaborative editing of text documents
    • Domain Name Server (BIND), in system menu
  • Added JavaScript license web labels to provide partial support for LibreJS.

  • Added basic configuration form for Minetest server.
  • Added indicator to Help->About page if new Plinth version is available.

  • Show app logos on front page instead of generic icons.
  • Prevent anonymous users from accessing setup pages.
  • Split Chat Server (XMPP) app into Chat Server (ejabberd) and Chat Client (jsxc).

6. Plinth v0.12.0 (2016-12-08)

  • Open up RTP ports in the firewall for repro (SIP server).
  • Front page shortcuts for services show a Configure button in the details box for logged-in users.
  • Add mods packages to be installed with Minetest server.
  • Fix issue with reading Dynamic DNS status as non-root user.
  • After the hostname is changed, ensure the domain name is still set correctly.
  • Allow the domain name to be cleared, and properly set the configuration in this case.
  • On the Certificates (Let's Encrypt) page, show a more informative message when no domains are configured.
  • On the Chat Server (XMPP) page, show more clearly if domain is not set.
  • Apps that require login will not be shown on the front page, unless the user is logged in.
  • Show status block for News Feed Reader (Tiny Tiny RSS).
  • Change appearance of front page with larger icons and repositioned text.
  • Firewall page only lists services that have been setup. The port lists are collapsible under each service.
  • Support configuring IPv6 networks.
  • Make it less likely to accidentally delete the only Plinth user.
  • Updated to work with JSXC 3.0.0 (XMPP web client).

7. Plinth v0.11.0 (2016-09-29)

  • Added loading icon for additional busy operations.
  • Added basic front page with shortcuts to web apps, and information about enabled services.
  • networks: Add batctl as dependency, required for batman-adv mesh networking.
  • users:
    • Fixed checking restricted usernames.
    • Display error message if unable to set SSH keys.
    • Flush nscd cache after user operations to avoid some types of errors.
  • monkeysphere:
    • Adopted to using SHA256 fingerprints.
    • Sort items for consistent display.
    • Handle new uid format of gpg2.
    • Fixed handling of unavailable imported domains.
  • minetest: Fixed showing status block and diagnostics.
  • Fixed stretched favicon.
  • Switched base template from container-fluid to container. This will narrow the content area for larger displays.
  • Plinth is now able to run as "plinth" user instead of root user.
  • xmpp: Replaced jwchat with jsxc.
  • ikiwiki: Allow only alphanumerics in wiki/blog name to avoid invalid paths.

8. Plinth v0.10.0 (2016-08-21)

  • Updated Plinth to support Django 1.10.
  • Added a page to display recent status log from Plinth. It is accessible from the 500 error page.
  • Tor: Added options to toggle relay and bridge relay modes.
  • Radicale: Added access rights control.
  • Ikiwiki: Updated suggested packages.
  • Users and Groups: Fixed editing users without SSH keys.
  • Networks: Added basic support for configuring batman-adv mesh networking.
  • Networks: Fixed incorrect access for retrieving DNS entries.
  • New languages:
    • Persian (50% translated)
    • Indonesian (not started, contributions needed)
  • New modules added to Plinth:
    • Disks: Shows free space of mounted partitions, and allows expanding the root partition.
    • Security: Controls login restrictions.
    • Snapshots: Manages Btrfs snapshots.

9. Version 0.9.4 (2016-06-24)

  • Added Polish translation.
  • Fixed issue preventing access to Plinth on a non-standard port.
  • Dealt with ownCloud removal from Debian. The ownCloud page in Plinth will be hidden if it has not been setup. Otherwise, a warning is shown.
  • Fixed issue in Privoxy configuration. Two overlapping listen-addresses were configured, which prevented privoxy service from starting.
  • Fixed issue that could allow someone to start a module setup process without being logged in to Plinth.
  • Fixed issues with some diagnostic tests that would show false positive results.
  • Added check to Diagnostics to skip tests for modules that have not been setup.
  • Fixed some username checks that could cause errors when editing the user.
  • Added sorting of menu items per locale.
  • Moved Dynamic DNS and Pagekite from Applications to System Configuration.
  • Allowed setting IP for shared network connections.
  • Switched Dreamplug image from "non-free" to "free". This means that we no longer include the non-free firmware for the built-in wifi on Dreamplug.
  • Added the "userdir" module for the Apache web server. This allows users in the "admin" group to create a folder called "public_html" under their home folder, and to publicly share files placed in this folder.
  • New wiki and manual content licence: Creative Commons Attribution-ShareAlike 4.0 International (from June 13rd 2016).

  • Switched to using apt-get for module setup in Plinth. This fixes several issues that were seen during package installs.

10. Version 0.9 (2016-04-24)

  • Fixed Wi-Fi AP setup.
  • Prevent lockout of users in 'sudo' group after setup is complete.
  • Improved setup mechanism for Plinth modules. Allows users to see what a module is useful for, before doing the setup and package install. Also allows essential modules to be setup by default during FreedomBox install.

  • Added HTTPS certificates to Monkeysphere page. Reorganized so that multiple domains can be added to a key.
  • Added Radicale, a CalDAV and CardDAV server.
  • Added Minetest Server, a multiplayer infinite-world block sandbox.
  • Added Tiny Tiny RSS, a news feed reader.

11. Version 0.8 (2016-02-20)

  • Added Quassel, an IRC client that stays connected to IRC networks and can synchronize multiple frontends.
  • Improved first boot user interface.
  • Fixed Transmission RPC whitelist issue.
  • Added translations for Turkish, Chinese, and Russian. Fixed and updated translations in other languages.
  • Added Monkeysphere, which uses PGP web of trust for SSH host key verification.
  • Added Let's Encrypt, to obtain certificates for domains, so that browser certificate warnings can be avoided.
  • Added repro, a SIP server for audio and video calls.
  • Allow users to set their SSH public keys, so they can login over SSH without a password.

12. Version 0.7 (2015-12-13)

  • Translations! Full translations of the interface in Danish, Dutch, French, German and Norwegian Bokmål, and partial Telugu.
  • Support for OLinuXino A20 MICRO and LIME2
  • New Plinth applications: OpenVPN, reStore
  • Improved first-boot experience
  • Many bugfixes and cleanups

13. Version 0.6 (2015-10-31)

  • New supported hardware target: Raspberry Pi 2
  • New modules in Plinth:
    • Shaarli: Web application to manage and share bookmarks
    • Date & Time: Configure time zone and NTP service

    • Service Discovery: Configure Avahi service
  • 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

14. 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.

15. 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.

16. Version 0.2 (2014-03-16)

  • Support for Raspberry Pi and VirtualBox (x86) in addition to the ?DreamPlug.

  • New Services:
    • 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.

17. 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".

Herunterladen und installieren

Sie können FreedomBox entweder auf einer der unterstützten Hardware, auf einem Debian System oder einer virtuellen Maschine verwenden.

1. Herunterladen für Debian

Wenn Sie auf Debian installieren, brauchen Sie diese Images nicht herunterladen. Stattdessen lesen Sie bitte die Anleitungen zum Einrichten der FreedomBox auf Debian.

2. Herunterladen für Hardware oder Virtualle Maschinen

2.1. Gerät vorbereiten

Siehe die Hardware-spezifischen Anweisungen, wie Sie Ihr Gerät vorbereiten. Lesen Sie so viele Dokumentationen wie möglich, die Sie im Internet über das ersten Booten und Flashen von USB oder SD-Karten auf Ihrer Hardware finden können.

2.2. Images Herunterladen

Neueste Images für unterstützte Geräte finden Sie hier:

2.3. Heruntergeladene Images Überprüfen

Es ist wichtig die Images die Sie heruntergeladen haben zu überprüfen, um sicherzustellen, dass die Datei nicht während der Übertragung beschädigt wurde und dass es sich in der Tat um die durch FreedomBox Entwickler erstellte Images handelt.

  • Öffnen Sie zunächst ein Terminal und importieren Sie den öffentlichen Schlüssel des FreedomBox Entwicklers, der das Image erstellt hat:

    $ gpg --keyserver x-hkp://pool.sks-keyservers.net --recv-keys 0x36C361440C9BC971
  • Als nächstes überprüfen Sie den Fingerabdruck des öffentlichen Schlüssels:
    $ 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
  • Schließlich verifizieren Sie Ihr heruntergeladenes Image mit seiner Signatur-Datei .sig. Beispielsweise:

    $ gpg --verify freedombox-unstable-free_2015-12-13_cubietruck-armhf.img.xz.sig freedombox-unstable-free_2015-12-13_cubietruck-armhf.img.xz
    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

2.4. Installation

Nach dem Download können Sie das Image verwenden um die unterstützte Hardware (einschließlich virtuelle Maschinen) zu booten. Sie müssen das Image wie folgt auf die Speicherkarte oder den USB-Stick kopieren:

  1. Finden Sie heraus, welches Gerät Ihre Karte tatsächlich ist.
    1. Entnehmen Sie Ihre Karte.
    2. Starten Sie dmesg -w um die Kernel-Meldungen anzuzeigen.

    3. Stecken Sie Ihre Karte ein. Sie sehen Nachrichten wie:
    • [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
    • Im obigen Fall ist die Platte, die neu eingefügten wurde als /dev/sdg verfügbar. Notieren Sie dies sorgfältig und verwenden Sie es in dem Kopierschritt unten.

  2. Entpacken Sie das heruntergeladene Image:
    $ xz -d freedombox-unstable-free_2015-12-13_cubietruck-armhf.img.xz

    Der oben stehende Befehl ist ein Beispiel für das cubietruck Image vom 2015.12.13. Ihre heruntergeladene Datei wird einen anderen Namen haben.

  3. Kopieren Sie das Image auf Ihre Karte. Überprüfen sie dabei alle Schritte sehr genau um sicherzustellen, dass Sie nicht aus Versehen auf den Speicher des Computers (wie /dev/sda) schreiben. Stellen Sie auch sicher, dass Sie diesen Schritt nicht als root durchführen, um zu vermeiden versehentlich Daten auf Ihrer Festplatte durch einen Fehler bei der Identifizierung des Geräts oder einem Fehler während der Eingabe des Befehls zu löschen. USB Sticks und SD-Karten sollten in der Regel für normale Benutzer beschreibbar sein. Wenn Sie nicht über die Berechtigung verfügen, auf die SD-Karte als Benutzer zu schreiben, müssen Sie diesen Befehl als root ausführen. In diesem Fall überprüfen Sie alles dreifach, bevor Sie den Befehl ausführen. Eine weitere Sicherheitsmaßnahme ist, alle externen Festplatten mit Ausnahme der SD-Karte abzuziehen, bevor Sie den Befehl ausführen.

    For example, if your SD card is /dev/sdf as noted in the first step above, then to copy the image, run:

    Zum Beispiel, wenn die SD-Karte /dev/sdf heißt, wie im ersten Schritt oben festgestellt wurde, dann führen Sie folgendes aus, um das Image zu kopieren:

    $ cd build
    $ dd bs=1M if=freedombox-unstable-free_2015-12-13_cubietruck-armhf.img of=/dev/sdf conv=fdatasync

Andere moglichkeit zum kopieren zum SD card, when dd ist nicht for hande.

$ cat freedombox-unstable-free_2015-12-13_cubietruck-armhf.img > /dev/sdf ; sync

Fur MS Windows gibt das programm etcher.

  • Der oben stehende Befehl ist ein Beispiel für das cubietruck Image vom 2015.12.13. Ihre heruntergeladenen Dateinamen wird anders sein.

    Bei der Auswahl des Geräts, verwenden Sie den Laufwerkbuchstaben, wie /dev/sdf, nicht ein nummerisches Ziel, wie /dev/sdf1. Das Gerät ohne Nummer bezieht sich auf die gesamte Vorrichtung, während der Name mit Zahl auf eine bestimmte Partition verweist. Wir wollen das ganze Gerät verwenden. Heruntergeladene Images enthalten alle Informationen über wie viele Partitionen benötigt werden, ihre Größen und Typen. Sie müssen nicht die SD-Karte formatieren oder Partitionen erstellen. Alle Daten auf der SD-Karte werden während des Schreibprozesses gelöscht werden.

    1. Verwenden Sie das Image, indem Sie die SD-Karte oder USB-Platte in das Gerät einsetzen und von ihm starten. Ihr Gerät sollte ebenfalls vorbereitet worden sein (siehe den entsprechenden Abschnitt).

    2. Lesen Sie (den Rest) des Handbuchs für Anweisungen, wie Sie Anwendungen in FreedomBox verwenden.

Apps

1. Anonymity Network (Tor)

1.1. What is Tor?

Tor is a network of servers operated by volunteers. It allows users of these servers to improve their privacy and security while surfing on the Internet. You and your friends are able to access to your FreedomBox via Tor network without revealing its IP address. Activating Tor application on your FreedomBox, you will be able to offer remote services (chat, wiki, file sharing, etc...) without showing your location. This application will give you a better protection than a public web server because you will be less exposed to intrusive people on the web.

1.2. Using Tor to browse anonymously

Tor Browser is the recommended way to browse the web using Tor. You can download the Tor Browser from https://www.torproject.org/projects/torbrowser.html and follow the instructions on that site to install and run it.

1.3. Using Tor Hidden Service to access your FreedomBox

Tor Hidden Service provides a way to access your FreedomBox, even if it's behind a router or firewall.

To enable Tor Hidden Service, first navigate to the Anonymity Network (Tor) page. (If you don't see it, click on the FreedomBox logo at the top-left of the page, to go to the main Apps page.) On the Anonymity Network (Tor) page, under Configuration, check "Enable Tor Hidden Service", then press the Update setup button. Tor will be reconfigured and restarted.

After a while, the page will refresh and under Status, you will see a table listing the Hidden Service .onion address. Copy the entire address (ending in .onion) and paste it into the Tor Browser's address field, and you should be able to access your FreedomBox. (You may see a certificate warning because FreedomBox has a self-signed certificate.)

Tor Browser - Plinth

Currently only HTTP (port 80), HTTPS (port 443), and SSH (port 22) are accessible through the Tor Hidden Service configured on the FreedomBox.

1.4. Running a Tor relay

When Tor is installed, it is configured by default to run as a bridge relay. The relay or bridge option can be disabled through the Tor configuration page in Plinth.

At the bottom of the Tor page in Plinth, there is a list of ports used by the Tor relay. If your FreedomBox is behind a router, you will need to configure port forwarding on your router so that these ports can be reached from the public Internet.

1.5. Using Tor SOCKS port (advanced)

FreedomBox provides a Tor SOCKS port that other applications can connect to, in order to route their traffic over the Tor network. This port is accessible on any interfaces configured in the internal firewall zone. To configure the application, set SOCKS Host to the internal network connection's IP address, and set the SOCKS Port to 9050.

2. BitTorrent (Deluge)

2.1. What is Deluge?

BitTorrent is a communications protocol using peer-to-peer (P2P) file sharing. It is not anonymous; you should assume that others can see what files you are sharing. There are two BitTorrent web clients available in FreedomBox: Transmission and Deluge. They have similar features, but you may prefer one over the other.

Deluge is a lightweight BitTorrent client that is highly configurable. Additional functionality can be added by installing plugins.

2.2. Screenshot

Deluge Web UI

2.3. Initial Setup

After installing Deluge, it can be accessed by pointing your browser to https://<your freedombox>/deluge. You will need to enter a password to login:

Deluge Login

The initial password is "deluge". The first time that you login, Deluge will ask if you wish to change the password. You should change it to something that is harder to guess.

Next you will be shown the connection manager. Click on the first entry (Offline - 127.0.0.1:58846). Then click "Start Daemon" to start the Deluge service that will run in the background.

Deluge Connection Manager (Offline)

Now it should say "Online". Click "Connect" to complete the setup.

Deluge Connection Manager (Online)

At this point, you are ready to begin using Deluge. You can make further changes in the Preferences, or add a torrent file or URL.

3. BitTorrent (Transmission)

3.1. What is Transmission ?

BitTorrent is a communications protocol using peer-to-peer (P2P) file sharing. It is not anonymous; you should assume that others can see what files you are sharing. There are two BitTorrent web clients available in FreedomBox: Transmission and Deluge. They have similar features, but you may prefer one over the other.

Transmission is a lightweight BitTorrent client that is well known for its simplicity and a default configuration that "Just Works".

3.2. Screenshot

Transmission Web Interface

3.3. Using Transmission

After installing Transmission, it can be accessed at https://<your freedombox>/transmission. When you try to access this page, you will be required to login with a username and password. The default for both is "transmission". You can change the username and password using the configuration form in Plinth.

3.4. Known Issues

  • The initial password is shown in the Plinth configuration form in a hashed format. This prevents it from being read or copied. However, after the password is changed, it is shown directly, without hashing.

4. Bookmarks (Shaarli)

Currently not functional

Shaarli is currently not available in Debian testing and the version in sid is said to be not functional. We are expecting this will soon be resolved and Shaarli will be again available in the FreedomBox.

ITP https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=864559

4.1. What is Shaarli?

Shaarli is personal (single-user) bookmarking application to install on your FreedomBox. It can also be used for micro-blogging, pastebin, online notepad and snippet archive. Shaarli is designed as a no-database delicious clone. As such, it provides very fast services, easy backup and import/export links as desktop or mobile browser bookmarks. Links stored can be public or private. Shaarli delivers ATOM and RSS feeds from its minimalist interface.

5. Chat Server (XMPP)

5.1. What is XMPP?

XMPP is a federated protocol for Instant Messaging. This means that users who have accounts on one server, can talk to users that are on another server. XMPP can also be used for voice and video calls, if supported by the clients.

With XMPP, there are two ways that conversations can be secured:

  1. TLS: This secures the connection between the client and server, or between two servers. This should be supported by all clients and is highly recommended.
  2. End-to-end: This secures the messages sent from one client to another, so that even the server cannot see the contents. The latest and most convenient protocol is called OMEMO, but it is only supported by a few clients. There is another protocol called OTR that may be supported by some clients that lack OMEMO support. Both clients must support the same protocol for it to work.

5.2. Setting the Domain Name

For XMPP to work, your FreedomBox needs to have a Domain Name that can be accessed over the public Internet. You can read more about obtaining a Domain Name in the Dynamic DNS section of this manual.

Once you have a Domain Name, you can tell your FreedomBox to use it by setting the Domain Name in the System Configuration.

  • Note: After changing your Domain Name, the Chat Server (XMPP) page may show that the service is not running. After a minute or so, it should be up and running again.

Please note that ?Pagekite does not support the XMPP protocol at this time.

5.3. Registering XMPP users through SSO

Currently, all users created through Plinth will be able to login to the XMPP server. You can add new users through the System Users and Groups module. It does not matter which Groups are selected for the new user.

5.4. Using the web client

After the XMPP module install completes, the JSXC web client for XMPP can be accessed at https://<your freedombox>/plinth/apps/xmpp/jsxc/. It will automatically check the BOSH server connection to the configured domain name.

5.5. Using a desktop or mobile client

XMPP clients are available for various desktop and mobile platforms.

5.6. Port Forwarding

If your FreedomBox is behind a router, you will need to set up port forwarding on your router. You should forward the following ports for XMPP:

  • TCP 5222 (client-to-server)
  • TCP 5269 (server-to-server)

6. Dynamic DNS Client

6.1. What is Dynamic DNS?

In order to reach a server on the Internet, the server needs to have permanent address also know as the static IP address. Many Internet service providers don't provide home users with a static IP address or they charge more providing a static IP address. Instead they provide the home user with an IP address that changes every time the user connects to the Internet. Clients wishing to contact the server will have difficulty reaching the server.

Dynamic DNS service providers assist in working around a problem. First they provide you with a domain name, such as 'myhost.example.org'. Then they associate your IP address, whenever it changes, with this domain name. Then anyone intending to reach the server will be to contact the server using the domain name 'myhost.example.org' which always points to the latest IP address of the server.

For this to work, every time you connect to the Internet, you will have to tell your Dynamic DNS provider what your current IP address is. Hence you need special software on your server to perform this operation. The Dynamic DNS function in FreedomBox will allow users without a static public IP address to push the current public IP address to a Dynamic DNS Server. This allows you to expose services on FreedomBox, such as ownCloud, to the Internet.

6.2. GnuDIP vs. Update URL

There are two main mechanism to notify the Dynamic DNS server of your new IP address; using the GnuDIP protocol and using the Update URL mechanism.

If a service provided using update URL is not properly secured using HTTPS, your credentials may be visible to an adversary. Once an adversary gains your credentials, they will be able to replay your request your server and hijack your domain.

On the other hand, the GnuDIP protocol will only transport a salted MD5 value of your password, in a way that is secure against replay attacks.

6.3. Using the GnuDIP protocol

  1. Register an account with any Dynamic DNS service provider. A free service provided by the FreedomBox community is available at https://gnudip.datasystems24.net .

  2. In FreedomBox UI, enable the Dynamic DNS Service.

  3. Select GnuDIP as Service type, enter your Dynamic DNS service provider address (for example, gnudip.datasystems24.net) into GnuDIP Server Address field.

    DynamicDNS-Settings.png

  4. Fill Domain Name, Username, Password information given by your provider into the corresponding fields.

6.4. Using an Update URL

This feature is implemented because the most popular Dynamic DNS providers are using Update URLs mechanism.

  1. Register an account with a Dynamic DNS service provider providing their service using Update URL mechanism. Some example providers are listed in the configuration page itself.
  2. In FreedomBox UI, enable the Dynamic DNS service.

  3. Select other Update URL as Service type, enter the update URL given by your provider into Update URL field.

  4. If you browse the update URL with your Internet browser and a warning message about untrusted certificate appears, then enable accept all SSL certificates. WARNING: your credentials may be readable here because man-in-the-middle attacks are possible! Consider choosing a better service provider instead.

  5. If you browse the update URL with your Internet browser and the username/password box appears, enable use HTTP basic authentication checkbox and provide the Username and Password.

  6. If the update URL contains your current IP address, replace the IP address with the string <Ip>.

6.5. Checking If It Works

  1. Make sure that external services you have enabled such as /jwchat, /roundcube and /ikiwiki are available on your domain address.
  2. Go to the Status page, make sure that the NAT type is detected correctly. If your FreedomBox is behind a NAT device, this should be detected over there (Text: Behind NAT). If your FreedomBox has a public IP address assigned, the text should be "Direct connection to the Internet".

  3. Check that the last update status is not failed.

6.6. Recap: How to create a DNS name with GnuDIP

  1. Access to GnuIP login page (answer Yes to all pop ups)

  2. Click on "Self Register"
  3. Fill the registration form (Username and domain will form the public IP address [username.domain])
  4. Take note of the username/hostname and password that will be used on the FreedomBox app.

  5. Save and return to the GnuDIP login page to verify your username, domain and password (enter the datas, click login).
  6. Login output should display your new domain name along with your current public IP address (this is a unique address provided by your router for all your local devices).
  7. Leave the GnuDIP interface and open the Dynamic DNS Client app page in your FreedomBox.

  8. Click on "Set Up" in the top menu.
  9. Activate Dynamic DNS
  10. Choose GnuDIP service.
  11. Add server address (gnudip.datasystems24.net)
  12. Add your fresh domain name (username.domain, ie [username].freedombox.rocks)
  13. Add your fresh username (the one used in your new IP address) and password
  14. Add your GnuDIP password
  15. Fill the option with http://myip.datasystems24.de (try this url in your browser, you will figure out immediatly)

7. Email Client (Roundcube)

7.1. What is Roundcube?

Roundcube is a browser-based multilingual email client with an application-like user interface. Roundcube is using the Internet Message Access Protocol (IMAP) to access e-mail on a remote mail server. It supports MIME to send files, and provides particularly address book, folder management, message searching and spell checking.

7.2. Using Roundcube

After Roundcube is installed, it can be accessed at https://<your freedombox>/roundcube.

8. ownCloud

ownCloud was removed from Debian

ownCloud was removed from Debian, so it is not available in the FreedomBox any more. Existing installations however are still working for time being. We are working on finding an adequate alternative.

Migrate to the official owncloud repository can be done in following this post

8.1. What is ownCloud?

ownCloud is a self-hosted file sync and share server. It provides access to your data through a platform to view, sync and share across devices. Calendars and Contacts feature will help you keeping google at a nice distance. ownCloud's functionalities are native or available via plugins (Collaborative Editing, Play Music, Watch Movies, Store Passwords, Dashboard, Mozilla Sync...) via https://apps.owncloud.com/

8.2. Installation

Clicking on the ownCloud application in Plinth will show an installation prompt. Proceed to install. After the installation, visit the /owncloud link provided in the ownCloud page. First time installation wizard will show up asking for administrator username and password to setup (no additional details such as database configuration are requested). After providing the details, you will be logged. You will be able to start using the ownCloud and create more users.

8.2.1. External Storage

ownCloud's external storage plugin allows you to expose the contents of a hard drive or those of an online storage account as a folder. Following are the steps required to setup such storage.

  1. Mount your hard drive or external storage to any fixed directory on the system.
  2. Install two packages needed via the 'apt-get' on the SSH command line shell (this step will not be needed in future):
    • $ sudo apt-get install php-google-api-php-client php-dropbox  
  3. Goto ownCloud Apps section and enable 'External Storage Support' plugin.
  4. Goto 'Admin' section and add your hard drive mount path in the external storage section. This folder will now show up in your folders list to access and sync across devices.

9. Public Visibility (PageKite)

9.1. What is PageKite?

PageKite makes local websites and services publicly accessible immediately without creating yourself a public IP address. It does this by tunneling protocols such as HTTPS or SSH through firewalls and NAT. Using PageKite requires an account on a PageKite relay service. One such service is https://pagekite.net.

A PageKite relay service will allow you to create kites. Kites are similar to domain names, but with different advantages and drawbacks. A kite can have a number of configured services. PageKite is known to work with HTTP, HTTPS, and SSH, and may work with some other services, but not all.

9.2. Using PageKite

  1. Create an account on a PageKite relay service.

  2. Add a kite to your account. Note your kite name and kite secret.
  3. In Plinth, go to the "Configure PageKite" tab on the Public Visibility (PageKite) page.

  4. Check the "Enable PageKite" box, then enter your kite name and kite secret. Click "Save settings".

  5. On the "Standard Services" tab, you can enable HTTP and HTTPS (recommended) and SSH (optional).
    • HTTP is needed to obtain the Let's Encrypt certificate. You can disable it later.
  6. On the Certificates (Let's Encrypt) page, you can obtain a Let's Encrypt certificate for your kite name.

10. Secure Shell

10.1. What is Secure Shell?

FreedomBox runs openssh-server server by default allowing remote logins from all interfaces. If your hardware device is connected to a monitor and a keyboard, you may login directly as well. Regular operation of FreedomBox does not require you to use the shell. However, some tasks or identifying a problem may require you to login to a shell.

10.2. Setting Up A User Account

10.2.1. Plinth First Log In: Admin Account

When creating an account in Plinth for the first time, this user will automatically have administrator capabilities. Admin users are able to log in using ssh (see Logging In below) and have superuser privileges via sudo.

10.2.2. Default User Account

  • Note: If you can access Plinth, then you don't need to do this. You can use the user account created in Plinth to connect to SSH.

The pre-built FreedomBox images have a default user account called "fbx". However the password is not set for this account, so it will not be possible to log in with this account by default.

There is a script included in the freedom-maker program, that will allow you to set the password for this account, if it is needed. To set a password for the "fbx" user:

1. Decompress the image file.

2. Get a copy of freedom-maker from https://github.com/freedombox/freedom-maker.

3. Run sudo ./bin/passwd-in-image <image-file> fbx.

4. Copy the image file to SD card and boot device as normal.

The "fbx" user also has superuser privileges via sudo.

10.3. Logging In

10.3.1. Local

To login via SSH, to your FreedomBox:

$ ssh fbx@freedombox

Replace fbx with the name of the user you wish to login as. freedombox should be replaced with the hostname or IP address of you FreedomBox device as found in the Quick Start process.

fbx is the default user present on FreedomBox with superuser privileges. Any other user created using Plinth and belonging to the group admin will be able to login. The root account has no password set and will not be able to login. Access will be denied to all other users.

fbx and users in admin group will also be able to login on the terminal directly. Other users will be denied access.

If you repeatedly try to login as a user and fail, you will be blocked from logging in for some time. This is due to libpam-abl package that FreedomBox installs by default. To control this behavior consult libpam-abl documentation.

10.3.2. SSH over Tor

If in Plinth you have enabled hidden services via Tor, you can access your FreedomBox using ssh over Tor. On a GNU/Linux computer, install netcat-openbsd.

$ sudo apt-get install netcat-openbsd

Edit ~/.ssh/config to enable connections over Tor.

$ nano ~/.ssh/config

Add the following:

Host *.onion
  user USERNAME
  port 22
  ProxyCommand nc -X 5 -x 127.0.0.1:9050 %h %p

Replace USERNAME with, e.g., an admin username (see above).

Note that in some cases you may need to replace 9050 with 9150.

Now to connect to the FreedomBox, open a terminal and type:

$ ssh USERNAME@ADDRESS.onion

Replace USERNAME with, e.g., an admin username, and ADDRESS with the hidden service address for your FreedomBox.

10.4. Becoming Superuser

After logging in, if you want to become the superuser for performing administrative activities:

$ sudo su

Make a habit of logging in as root only when you need to. If you aren't logged in as root, you can't accidentally break everything.

10.5. Changing Password

To change the password of a user managed by Plinth, use the change password page. However, the fbx default user is not managed by Plinth and its password cannot be changed in the web interface.

To change password on the terminal, log in to your FreedomBox as the user whose password you want to change. Then, run the following command:

$ passwd

This will ask you for your current password before giving you the opportunity to set a new one.

11. Voice Chat (Mumble)

11.1. What is Mumble?

Mumble is a voice chat software. Primarily intended for use while gaming, it is suitable for simple talking with high audio quality, noise suppression, encrypted communication, public/private-key authentication by default, and "wizards" to configure your microphone for instance. A user can be marked as a "priority speaker" within a channel.

11.2. Using Mumble

FreedomBox includes the Mumble server. Clients are available for desktop and mobile platforms. Users can download one of these clients and connect to the server.

11.3. Port Forwarding

If your FreedomBox is behind a router, you will need to set up port forwarding on your router. You should forward the following ports for Mumble:

  • TCP 64738
  • UDP 64738

12. Web Proxy (Privoxy)

A web proxy acts as a filter for incoming and outgoing internet traffic. Thus, you can instruct any computer in your network to pass internet traffic through the proxy to remove unwanted ads and tracking mechanisms.

Privoxy is a software for security, privacy, and accurate control over the web. It provides a much more powerful web proxy (and anonymity on the web) than what your browser can offer. Privoxy "is a proxy that is primarily focused on privacy enhancement, ad and junk elimination and freeing the user from restrictions placed on his activities" (source: Privoxy FAQ).

12.1. Screencast

Watch the screencast on how to setup and use Privoxy in FreedomBox.

12.2. Setting up

  1. In Plinth install Web Proxy (Privoxy)

    Privoxy-Installation.png

  2. Adapt your browser proxy settings to your FreedomBox hostname (or IP address) with port 8118. Please note that Privoxy can only proxy HTTP and HTTPS traffic. It will not work with FTP or other protocols.

    Privoxy-BrowserSettings.png

  3. Go to page http://config.privoxy.org/ or http://p.p. If Privoxy is installed properly, you will be able to configure it in detail; if not you will see an error message.

  4. If you are using a laptop that occasionally has to connect through other routers than yours with the FreedomBox and Privoxy, you may want to install a proxy switch add-on that allows you to easily turn the proxy on or off.

12.3. Advanced Users

  1. The default installation should provide a reasonable starting point for most. There will undoubtedly be occasions where you will want to adjust the configuration, that can be dealt with as the need arises.
  2. While using Privoxy, you can see its configuration details and documentation at http://config.privoxy.org/ or http://p.p.

  3. To enable changing these configurations, you first have to change the value of enable-edit-actions in /etc/privoxy/config to 1. Before doing so, read carefully the manual, especially:

    • Access to the editor can not be controlled separately by "ACLs" or HTTP authentication, so that everybody who can access Privoxy can modify its configuration for all users. This option is not recommended for environments with untrusted users. Note that malicious client side code (e.g Java) is also capable of using the actions editor and you shouldn't enable this options unless you understand the consequences and are sure your browser is configured correctly.

  4. Now you find an EDIT button on the configuration screen in http://config.privoxy.org/.

  5. The Quickstart is a good starting point to read on how to define own blocking and filtering rules.

13. Wiki and Blog (Ikiwiki)

13.1. What is Ikiwiki?

Ikiwiki converts wiki pages into HTML pages suitable for publishing on a website. It provides particularly blogging, podcasting, calendars and a large selection of plugins.

13.2. Quick Start

After the app installation on your box administration interface:

  • Go to "Create" section and create a wiki or a blog
  • Go back to "Configure" section and click on /ikiwiki link
  • Click on your new wiki or blog name under "Parent directory"
  • Enjoy your new publication page.

13.3. Creating a wiki or blog

You can create a wiki or blog to be hosted on your FreedomBox through the Wiki & Blog (Ikiwiki) page in Plinth. The first time you visit this page, it will ask to install packages required by Ikiwiki.

After the package install has completed, select the Create tab. You can select the type to be Wiki or Blog. Also type in a name for the wiki or blog, and the username and password for the wiki's/blog's admin account. Then click Update setup and you will see the wiki/blog added to your list. Note that each wiki/blog has its own admin account.

ikiwiki: Create

13.4. Accessing your wiki or blog

From the Wiki & Blog (Ikiwiki) page, select the Manage tab and you will see a list of your wikis and blogs. Click a name to navigate to that wiki or blog.

ikiwiki: Manage

From here, if you click Edit or Preferences, you will be taken to a login page. To log in with the admin account that you created before, select the Other tab, enter the username and password, and click Login.

13.5. User login through SSO

Besides the wiki/blog admin, other FreedomBox users can be given access to login and edit wikis and blogs. However, they will not have all the same permissions as the wiki admin. They can add or edit pages, but cannot change the wiki's configuration.

To add a wiki user, go to the Users and Groups page in Plinth (under System configuration, the gear icon at the top right corner of the page). Create or modify a user, and add them to the wiki group. (Users in the admin group will also have wiki access.)

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.

13.6. Adding FreedomBox users as wiki admins

  1. Login to the wiki, using the admin account that was specified when the wiki was created.
  2. Click "Preferences", then "Setup".
  3. Under "main", in the "users who are wiki admins", add the name of a user on the FreedomBox.

  4. (Optional) Under "auth plugin: passwordauth", uncheck the "enable passwordauth?" option. (Note: This will disable the old admin account login. Only SSO login using HTTP auth will be possible.)
  5. Click "Save Setup".
  6. Click "Preferences", then "Logout".
  7. Login as the new admin user using "Login with HTTP auth".

14. Unhosted Storage

14.1. What is Unhosted?

Unhosted is a way to uncouple web applications from data. No matter where a web application is served from, the data can be stored on an Unhosted storage server of user's choice. Unhosted web apps do not send your user data to their server and are hence known as "serverless", "client-side", or "static" web apps. Either you connect your own server at runtime, or your data stays within the browser. Your FreedomBox can become your Unhosted storage server using a remoteStorage server know as reStore.

This module is currently disabled in FreedomBox as the package required for reStore server is not available in Debian yet. The package is available for testing via http://debian-dev.freedombox.at/

14.2. Setup

Your FreedomBox contains a remoteStorage server called reStore, that can serve as your personal storage server for Unhosted web apps. To setup reStore, simply install and enable in FreedomBox web UI. After the setup, create an account by visiting the link provided on the Unhosted app page https://<yourdomain>/restore/.

User accounts are currently not integrated with Plinth user management, and public sign-up is enabled!

14.3. Try Unhosted apps

Once Unhosted is setup on FreedomBox and when FreedomBox is accessible by a domain name (such by using PageKite, Dynamic DNS or Tor Hidden Service), try one of the following Unhosted web apps (more are listed at http://unhosted.org/apps):

To connect the Unhosted app to your FreedomBox's Unhosted storage, click on the remoteStorage icon and type your address <user>@<yourdomain>, e.g.:

remotestorage.png

If this doesn't work, make sure that

  • FreedomBox has a domain name using PageKite, Dynamic DNS or Tor Hidden Service.

  • The reStore server is running.
  • You have created the account specified in the reStore server.
  • 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 be able to use it. All data of the Unhosted web app is now stored on your FreedomBox.

System

1. Configure

Configure covers a couple of general topics:

  1. Hostname
    • Hostname is the local name by which other devices on the local network can reach your FreedomBox. Default is freedombox.

  2. Domain Name
  3. Language
    • Language for the web administration interface Plinth

2. Users and Groups

You can grant access to your FreedomBox for other users. Provide the Username with a password and assign a group to it. Currently the groups

  • admin
  • wiki

are supported.

The user will be able to log in to services that support single sign-on through LDAP, if they are in the appropriate group.

Users in the admin group will be able to log in to all services. They can also log in to the system through SSH and have administrative privileges (sudo).

These characteristics can also be changed later-on.

It is also possible to set an SSH public key which will allow this user to securely log in to the system without using a password. You may enter multiple keys, one on each line. Blank lines and lines starting with # will be ignored.

A user's account can be deactivated, which will temporarily disable the account.

2.1. Known Issues

  • Currently, Plinth does not distinguish between users and administrators. Every user added through Plinth will have full access to the Plinth interface.

3. Networks

This section describes how networking is setup by default in FreedomBox and how you can customize it. See also the Firewall section for more information on how firewall works.

3.1. Default setup

In a fresh image of FreedomBox, network is not configured at all. When the image is written to an SD card and the device boots, configuration is done. During first boot, FreedomBox setup package detects the networks interfaces and tries to automatically configure them so that FreedomBox is available for further configuration via the web interface from another machine without the need to connect a monitor. Automatic configuration also tries to make FreedomBox useful, out of the box, for the most important scenarios FreedomBox is used for.

There are two scenarios it handles: when is a single ethernet interface and when there are multiple ethernet interfaces.

3.1.1. Single ethernet interface

When there is only single ethernet interface available on the hardware device, there is not much scope for it to play the role of a router. In this case, the device is assumed to be just another machine in the network. Accordingly, the only available interface is configured to be an internal interface in automatic configuration mode. This means that it connects to the Internet using the configuration provided by a router in the network and also makes all (internal and external) of its services available to all the clients on this network.

network_single.png

3.1.2. Multiple ethernet interface

When there are multiple ethernet interfaces available on the hardware device, the device can act as a router. The interfaces are then configured to perform this function.

The first network interface is configured to be an WAN or external interface in automatic configuration mode. This means that it connects to the Internet using network configuration provided by the Internet Service Provider (ISP). Only services that are meant to be provided across the entire Internet (external services) will be exposed on this interface. You must plug your Internet connection into the port of this ethernet interface. If you wish to continue to have your existing router manage the Internet connection for you, then plug a connection from your router to the port on this interface.

The remaining network interfaces are configured for the clients of a router. They are configured as LAN or internal interfaces in shared configuration mode. This means that all the services (both external and internal) services are provided to who ever connects on this interface. Further, the shared mode means that clients will be able to receive details of automatic network connection on this interface. Specifically, DHCP configuration and DNS servers are provided on this interface. The Internet connection available to the device using the first network interface will be shared with clients using this interface. This all means that you can connect your computers to this network interface and they will get automatically configured and will be able to access the Internet via the FreedomBox.

Currently, it is not very clear which interface will be come the WAN interface (and the remaining being LAN interfaces) although the assignment process is deterministic. So, it take a bit of trail and error to figure out which one is which. In future, for each device, this will be well documented.

3.1.3. Wi-Fi configuration

All Wi-Fi interfaces are configured to be LAN or internal interfaces in shared configuration mode. They are also configured to become Wi-Fi access points with following details.

  • Name of the access point will be FreedomBox plus the name of the interface (to handle the case where there are multiple of them).

  • Password for connecting to the interface will be freedombox123.

3.2. Internet Connection Sharing

Although the primary duty of FreedomBox is to provide decentralized services, it can also act like a home router. Hence, in most cases, FreedomBox connects to the Internet and provides other machines in the network the ability to use that Internet connection. FreedomBox can do this in two ways: using a shared mode connection or using an internal connection.

When an interface is set in shared mode, you may connect your machine directly to it. This is either by plugging in an ethernet cable from this interface to your machine or by connecting to a Wi-Fi access point. This case is the simplest to use, as FreedomBox automatically provides your machine with the necessary network configuration. Your machine will automatically connect to FreedomBox provided network and will be able to connect to the Internet given that FreedomBox can itself connect to the Internet.

Sometimes the above setup may not be possible because the hardware device may have only one network interface or for other reasons. Even in this case, your machine can still connect to the Internet via FreedomBox. For this to work, make sure that the network interface that your machine is connecting to is in internal mode. Then, connect your machine to network in which FreedomBox is present. After this, in your machine's network configuration, set FreedomBox's IP address as the gateway. FreedomBox will then accept your network traffic from your machine and send it over to the Internet. This works because network interfaces in internal mode are configured to masquerade packets from local machines to the Internet and receive packets from Internet and forward them back to local machines.

3.3. Customization

The above default configuration may not be fit for your setup. You can customize the configuration to suit your needs from the Networks area in the 'setup' section of the FreedomBox web interface.

3.3.1. PPPoE connections

If your ISP does not provide automatic network configuration via DHCP and requires you to connection via PPPoE. To configure PPPoE, remove any network connection existing on an interface and add a PPPoE connection. Here, optionally, provide the account username and password given by your ISP and activate the connection.

3.3.2. Connect to Internet via Wi-Fi

By default Wi-Fi devices attached during first boot will be configured as access points. They can be configured as regular Wi-Fi devices instead to connection to a local network or an existing Wi-Fi router. To do this, click on the Wi-Fi connection to edit it. Change the mode to Infrastructure instead of Access Point mode and IPv4 Addressing Method to Automatic (DHCP) instead of Shared mode. Then the SSID provided will mean the Wi-Fi network name you wish to connect to and passphrase will be the used to while making the connection.

3.3.3. Adding a new network device

When a new network device is added, network manager will automatically configure it. In most cases this will not work to your liking. Delete the automatic configuration created on the interface and create a new network connection. Select your newly added network interface in the add connection page.

  • Then set firewall zone to internal and external appropriately.

  • You can configure the interface to connect to a network or provide network configuration to whatever machine connects to it.
  • Similarly, if it is a Wi-Fi interface, you can configure it to become a Wi-FI access point or to connect to an existing access points in the network.

3.3.4. Configuring a mesh network

FreedomBox has rudimentary support for participating in BATMAN-Adv based mesh networks. It is possible to either join an existing network in your area or create a new mesh network and share your Internet connection with the rest of the nodes that join the network. Currently, two connections have to be created and activated manually to join or create a mesh network.

3.3.4.1. Joining a mesh network

To join an existing mesh network in your area, first consult the organizers and get information about the mesh network.

  1. Create a new connection, then select the connection type as Wi-Fi. In the following dialog, provide the following values:

    Field Name

    Example Value

    Explanation

    Connection Name

    Mesh Join - BATMAN

    The name must end with 'BATMAN' (uppercase)

    Physical Interface

    wlan0

    The Wi-Fi device you wish to use for joining the mesh network

    Firewall Zone

    External

    Since you don't wish that participants in mesh network to use internal services of FreedomBox

    SSID

    ch1.freifunk.net

    As provided to you by the operators of the mesh network. You should see this as a network in Nearby Wi-Fi Networks

    Mode

    Ad-hoc

    Because this is a peer-to-peer network

    Frequency Band

    2.4Ghz

    As provided to you by the operators of the mesh network

    Channel

    1

    As provided to you by the operators of the mesh network

    BSSID

    12:CA:FF:EE:BA:BE

    As provided to you by the operators of the mesh network

    Authentication

    Open

    Leave this as open, unless you know your mesh network needs it be otherwise

    Passphrase

    Leave empty unless you know your mesh network requires one

    IPv4 Addressing Method

    Disabled

    We don't want to request IP configuration information yet

    Save the connection. Join the mesh network by activating this newly created connection.
  2. Create a second new connection, then select the connection type as Generic. In the following dialog, provide this following values:

    Field Name

    Example Value

    Explanation

    Connection Name

    Mesh Connect

    Any name to identify this connection

    Physical Interface

    bat0

    This interface will only show up after you successfully activate the connection in first step

    Firewall Zone

    External

    Since you don't wish that participants in mesh network to use internal services of FreedomBox

    IPv4 Addressing Method

    Auto

    Mesh networks usually have a DHCP server somewhere that provide your machine with IP configuration. If not, consult the operator and configure IP address setting accordingly with Manual method

    Save the connection. Configure your machine for participation in the network by activating this connection. Currently, this connection has to be manually activated every time you need to join the network. In future, FreedomBox will do this automatically. You will now be able reach other nodes in the network. You will also be able to connect to the Internet via the mesh network if there is an Internet connection point somewhere in mesh as setup by the operators.

3.3.4.2. Creating a mesh network

To create your own mesh network and share your Internet connection with the rest of the nodes in the network:

  1. Follow the instructions as provided above in step 1 of Joining a mesh network but choose and fix upon your own valid values for SSID (a name for you mesh network), Frequency Band (usually 2.4Ghz), Channel (1 to 11 in 2.4Ghz band) and BSSID (a hex value like 12:CA:DE:AD:BE:EF). Create this connection and activate it.

  2. Follow the instructions as provided above in step 2 of Joining a mesh network but select IPv4 Addressing Method as Shared. This will provide automatic IP configuration to other nodes in the network as well as share the Internet connection on your machine (achieved using a second Wi-Fi interface, using Ethernet, etc.) with other nodes in the mesh network.

Spread the word about your mesh network to your neighbors and let them know the parameters you have provided when creating the network. When other nodes connect to this mesh network, they have to follow steps in Joining a mesh network but use the values for SSID, Frequency Band and Channel that you have chosen when you created the mesh network.

3.4. Manual Network Operation

FreedomBox automatically configures networks by default and provides a simplified interface to customize the configuration to specific needs. In most cases, manual operation is not necessary. The following steps describe how to manually operate network configuration in the event that a user finds FreedomBox interface to insufficient for task at hand or to diagnose a problem that FreedomBox does not identify.

On the command line interface:

For text based user interface for configuring network connections:

nmtui

To see the list of available network devices:

nmcli device

To see the list of configured connections:

nmcli connection

To see the current status of a connection:

nmcli connection show '<connection_name>'

To see the current firewall zone assigned to a network interface:

nmcli connection show '<connection_name>' | grep zone

or

firewall-cmd --zone=internal --list-all
firewall-cmd --zone=external --list-all

To create a new network connection:

nmcli con add con-name "<connection_name>" ifname "<interface>" type ethernet
nmcli con modify "<connection_name>" connection.autoconnect TRUE
nmcli con modify "<connection_name>" connection.zone internal

To change the firewall zone for a connection:

nmcli con modify "<connection_name>" connection.zone "<internal|external>"

For more information on how to use nmcli command, see its man page. Also for a full list of configuration settings and type of connections accepted by Network Manager see:

https://developer.gnome.org/NetworkManager/stable/ref-settings.html

To see the current status of the firewall and manually operate it, see the Firewall section.

4. Software Upgrades

FreedomBox can automatically install security upgrades. On the Upgrades page of the Settings section in Plinth you can turn on automatic upgrades. For FreedomBox versions above 0.5, this feature is enabled by default and there is no manual action necessary. It is strongly recommended that you have this option enabled to keep your FreedomBox secure.

Upgrades are performed every day at night. If you wish to shutdown FreedomBox every day after use, keep it running at night once a week or so to let the automatic upgrades happen. Alternatively, you can perform manual upgrades as described below.

upgrades.png

4.1. Manual Upgrades

In the Plinth web interface, you can initiate a manual upgrade process from Upgrades page of the Settings section. Note that once the upgrades start, it may take a long time to complete and Plinth may seem to wait for the page to load.

Under some circumstances, automatic upgrades may fail and require you perform a manual upgrade action. Even upgrades initiated from Plinth may not finish properly. This may be because the upgrade process requires you to make a decision. In these cases, manual upgrade on the terminal may be the only option.

In addition, while the upgrade task is running any application installations will wait until the upgrade task is finished. Depending on the hardware, the upgrade task may take a little time, therefore, giving the impression that the application installation stalled.

To perform manual upgrades on the terminal, login into FreedomBox on a terminal or using a remote secure shell (see Secure Shell section). Then run the following commands:

$ sudo su -
Password:
# apt-get update
# apt-get dist-upgrade

This will ask you if it is alright to install/upgrade (or remove) some packages and use (or release) some disk space. Say yes after review. In some cases, during the upgrades process you will be asked questions about modified configuration files, answering with a default Keep current configuration is usually safe.

5. Diagnostics

The system diagnostic test will run a number of checks on your system to confirm that applications and services are working as expected.

Just click Run Diagnostics. This may take some minutes.

6. 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 in Plinth web interface of FreedomBox is automatic. When you enable a service it is automatically permitted in the firewall and when you disable a service it is automatically disabled in the firewall. For services which are enabled by default on FreedomBox, firewall ports are also enabled by default during the first run process.

Firewall.png

Firewall management in FreedomBox is done using FirewallD.

6.1. Interfaces

Each interface is needs to be assigned to one (and only one) zone. Whatever rules are in effect for a zone, those rules start to apply for that interface. For example, if HTTP traffic is allowed in a particular zone, then web requests will be accepted on all the addresses configured for all the interfaces assigned to that zone.

There are primarily two firewall zones used. The internal zone is meant for services that are provided to all machines on the local network. This may include services such as streaming media and simple file sharing. The external zone is meant for services that are provided publicly on the Internet. This may include services such as blog, website, email web client etc.

For details on how network interfaces are configured by default, see the Networks section.

6.2. Ports/Services

The following table attempts to document the ports, services and their default statuses in FreedomBox. If you find this page outdated, see the Plinth source for lib/freedombox/first-run.d/90_firewall and Firewall status page in Plinth UI.

Service

Port

External

Enabled by default

Status shown in Plinth

Managed by Plinth

Minetest

30000/udp

{*}

{X}

(./)

(./)

XMPP Client

5222/tcp

{*}

{X}

(./)

(./)

XMPP Server

5269/tcp

{*}

{X}

(./)

(./)

XMPP Bosh

5280/tcp

{*}

{X}

(./)

(./)

NTP

123/udp

{o}

(./)

(./)

(./)

Plinth

443/tcp

{*}

(./)

(./)

{X}

Quassel

4242/tcp

{*}

{X}

(./)

(./)

SIP

5060/tcp

{*}

{X}

(./)

(./)

SIP

5060/udp

{*}

{X}

(./)

(./)

SIP-TLS

5061/tcp

{*}

{X}

(./)

(./)

SIP-TLS

5061/udp

{*}

{X}

(./)

(./)

RTP

1024-65535/udp

{*}

{X}

(./)

(./)

SSH

22/tcp

{*}

(./)

(./)

{X}

mDNS

5353/udp

{o}

(./)

(./)

(./)

Tor (Socks)

9050/tcp

{o}

{X}

(./)

(./)

Obfsproxy

<random>/tcp

{*}

{X}

(./)

(./)

OpenVPN

1194/udp

{*}

{X}

(./)

(./)

Mumble

64378/tcp

{*}

{X}

(./)

(./)

Mumble

64378/udp

{*}

{X}

(./)

(./)

Privoxy

8118/tcp

{o}

{X}

(./)

(./)

JSXC

80/tcp

{*}

{X}

{X}

{X}

JSXC

443/tcp

{*}

{X}

{X}

{X}

DNS

53/tcp

{o}

{X}

{X}

{X}

DNS

53/tdp

{o}

{X}

{X}

{X}

DHCP

67/udp

{o}

(./)

{X}

{X}

Bootp

67/tcp

{o}

{X}

{X}

{X}

Bootp

67/udp

{o}

{X}

{X}

{X}

Bootp

68/tcp

{o}

{X}

{X}

{X}

Bootp

68/udp

{o}

{X}

{X}

{X}

LDAP

389/tcp

{o}

{X}

{X}

{X}

LDAPS

636/tcp

{o}

{X}

{X}

{X}

6.3. Manual operation

See FirewallD documentation for more information on the basic concepts and comprehensive documentation.

6.3.1. Enable/disable firewall

To disable firewall

service firewalld stop

or with systemd

systemctl stop firewalld

To re-enable firewall

service firewalld start

or with systemd

systemctl start firewalld

6.3.2. Modifying services/ports

You can manually add or remove a service from a zone.

To see list of services enabled:

firewall-cmd --zone=<zone> --list-services

Example:

firewall-cmd --zone=internal --list-services

To see list of ports enabled:

firewall-cmd --zone=<zone> --list-ports

Example:

firewall-cmd --zone=internal --list-ports

To remove a service from a zone:

firewall-cmd --zone=<zone> --remove-service=<service>
firewall-cmd --permanent --zone=<zone> --remove-service=<interface>

Example:

firewall-cmd --zone=internal --remove-service=xmpp-bosh
firewall-cmd --permanent --zone=internal --remove-service=xmpp-bosh

To remove a port from a zone:

firewall-cmd --zone=internal --remove-port=<port>/<protocol>
firewall-cmd --permanent --zone=internal --remove-port=<port>/<protocol>

Example:

firewall-cmd --zone=internal --remove-port=5353/udp
firewall-cmd --permanent --zone=internal --remove-port=5353/udp

To add a service to a zone:

firewall-cmd --zone=<zone> --add-service=<service>
firewall-cmd --permanent --zone=<zone> --add-service=<interface>

Example:

firewall-cmd --zone=internal --add-service=xmpp-bosh
firewall-cmd --permanent --zone=internal --add-service=xmpp-bosh

To add a port to a zone:

firewall-cmd --zone=internal --add-port=<port>/<protocol>
firewall-cmd --permanent --zone=internal --add-port=<port>/<protocol>

Example:

firewall-cmd --zone=internal --add-port=5353/udp
firewall-cmd --permanent --zone=internal --add-port=5353/udp

6.3.3. Modifying the zone of interfaces

You can manually change the assignment of zones of each interfaces after they have been autuomatically assigned by the first boot process.

To see current assignment of interfaces to zones:

firewall-cmd --list-all-zones

To remove an interface from a zone:

firewall-cmd --zone=<zone> --remove-interface=<interface>
firewall-cmd --permanent --zone=<zone> --remove-interface=<interface>

Example:

firewall-cmd --zone=external --remove-interface=eth0
firewall-cmd --permanent --zone=external --remove-interface=eth0

To add an interface to a zone:

firewall-cmd --zone=<zone> --add-interface=<interface>
firewall-cmd --permanent --zone=<zone> --add-interface=<interface>

Example:

firewall-cmd --zone=internal --add-interface=eth0
firewall-cmd --permanent --zone=internal --add-interface=eth0

7. Date & Time

This network time server is a program that maintains the system time in synchronization with servers on the Internet.

You can select your time zone by picking a big city nearby (they are sorted by Continent/City) or select directly the zone with respect to GMT (Greenwich Mean Time).

DateTime.png

Hardware

FreedomBox zielt darauf ab, ein Unterhaltungselektronik-Gerät zu sein, das einfach zu installieren, zu unterhalten und zu verwenden ist. Das Projekt zielt nicht darauf ab, ein spezielles Gerät zu realisieren. Statt dessen planen wir existierende Hardware zu unterstützen/anzupassen.

Zusätzlich zur Unterstützung verschiedener Single-Board-Computer und anderer Geräte, unterstützt FreedomBox auch die Installation in einer virtuellen Maschine. Auch kann jede Debian-Maschine in eine FreedomBox durch die Installation des freedombox-setup Paket umgewandelt werden. Siehe das Handbuch für weitere Details.

1. Unterstützte Hardware

1.1. Empfohlene Hardware

FreedomBox Danube Edition
FreedomBox - Danube Edition
(basierend auf Cubietruck)

BeagleBone Black
BeagleBone Black

A20 OLinuXino Lime2
A20 OLinuXino Lime2

A20 OLinuXino MICRO
A20 OLinuXino MICRO

PC Engines APU
PC Engines APU

Debian
Debian

VirtualBox
VirtualBox

.

.

.

1.2. Auch Funktionierende Hardware

Diese Hardware funktioniert, ist aber nicht empfohlen aufgrund von Freiheits-, Kosten-Nutzen- oder anderer Bedenken:

DreamPlug
DreamPlug

Raspberry Pi
Raspberry Pi

Raspberry Pi 2
Raspberry Pi 2

Hinweis: Da FreedomBox noch in der Entwicklung ist, bedeutet Unterstützte Hardware, dass FreedomBox Images für die genannte Hardware realisiert werden und mindestens ein Entwickler berichtet hat, dass sie in ihren Grundfunktionen arbeitet.

2. Ziel-Hardware

2.1. Liste der Ziel-Hardware

Obwohl sich das Projekt auf die Unterstützung von bestimmten Geräten konzentriert, versuchen wir eine möglichst breite Vielzahl an Hardware zu unterstützen, die für die FreedomBox geeignet ist. Werfen Sie einen Blick auf die Liste der unterstützen Hardware für weitere Unterstützung.

2.2. Hardware Unterstützung hinzufügen

Wenn Sie Entwickler sind, sollten Sie erwägen, Hardware-Unterstützung für Ihr Gerät beizutragen, indem Sie Freedom Maker und FreedomBox Setup anpassen.

3. Cubietruck

3.1. FreedomBox Danube Edition

FreedomBox Danube Edition

FreedomBox Danube Edition is a custom casing around Cubietruck and an SSD-hard drive.

3.2. Cubietruck / Cubieboard3

Cubietruck (Cubieboard3) is a single board computer with very good performance compared to many other boards. FreedomBox images are built for this device. To use this board as FreedomBox, a separate USB WiFi device that does not require non-free firmware is recommended.

3.3. Download

FreedomBox SD card images are provided for this hardware. These SD card images are meant for use with the on-board SD card slot and do not work when used with a separate SD card reader connected via USB.

An alternative to downloading these images is to install Debian on the Cubietruck and then install FreedomBox on it.

3.4. Build Image

FreedomBox images for this hardware can be built using Freedom Maker.

3.5. Availability

FreedomBox Danube Edition

  • A limited number of units are planned to be shipped along with the release of FreedomBox 1.0. If you wish to get one, express your interest.

Cubietruck / Cubieboard3

3.6. Hardware

  • Open Hardware: No
  • CPU: Allwinner A20, ARM Cortex-A7 @ 1GHz dual-core
  • RAM: 2 GiB DDR3 @ 480 MHz
  • Storage: 8 GB NAND flash built-in, 1x microSD slot
  • Architecture: armhf
  • Ethernet: 10/100/1000, RJ45
  • WiFi: Broadcom BCM4329/BCM40181 (no free WiFi drivers + firmware available)

  • SATA: 1x 2.0 port

3.7. Non-Free Status

  • Non-free blobs required: ?
  • WiFi: no free WiFi drivers + firmware available

  • Works with stock Debian kernel: yes

3.8. Known Issues

  • The on-board WiFi does not work with free software. A separate USB WiFi device is recommended.

4. Beagle Bone Black

Beagle Bone Black

Beagle Bone Black (Revision C.1) is an Open Source Hardware (OSHW) single board computer. This means that the designer is actively helping people using the platform for their own designs, and supports them in adding hardware functionality and production advice. This is a part of freedom that is often overlooked, but very much aligned with the FreedomBox goals. FreedomBox images are built and tested for this device. To use this device as a FreedomBox, a separate USB WiFi device that does not require non-free firmware is recommended.

4.1. Download

FreedomBox SD card images are available for this device. Follow the instructions on the download page to create a FreedomBox SD card and boot the device.

Note: This image is for BeagleBone Black (Revision C.1) only. It will not work on the BeagleBone Green, and also not on the Revisions A&B. If you have such a device and would like to help getting FreedomBox to run on it, contact us!

An alternative to downloading these images is to install Debian on the BeagleBone and then install FreedomBox on it.

4.2. Build Image

FreedomBox images for this hardware can be built using Freedom Maker.

4.3. Availability

4.4. Hardware

  • Open Source Hardware (OSHW): Yes

  • CPU: AM335x 1GHz ARM Cortex-A8

  • RAM: 512MB DDR3L 800 Mhz
  • Storage: Onboard 4GB, 8bit Embedded MMC and microSD
  • Architecture: armhf
  • Ethernet: 10/100, RJ45
  • WiFi: None, use a USB WiFi device

  • SATA: None

4.5. Non-Free Status

  • Non-free blobs required: No
  • WiFi: Not available

  • Works with stock Debian kernel: Yes

4.6. Known Issues

None

5. A20 OLinuXino Lime2

A20 OLinuXino Lime2

Olimex's A20 OLinuXino Lime2 is a fully Open Source Hardware (OSHW) single board computer. This means that the designer is actively helping people using the platform for their own designs, and supports them in adding hardware functionality and production advice. This is a part of freedom that is often overlooked, but very much aligned with the FreedomBox goals. It uses the Allwinner A20 Dual Core ARM processor. FreedomBox images are built and tested for this device starting with version 0.7. To use this device as a FreedomBox, a separate USB WiFi device that does not require non-free firmware is recommended.

5.1. Similar Hardware

The following similar hardware will also work well with FreedomBox.

5.2. Download

FreedomBox SD card images are available for this device. Follow the instructions on the download page to create a FreedomBox SD card and boot the device. 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.

5.3. Build Image

FreedomBox images for this hardware can be built using Freedom Maker.

5.4. Availability

  • Price: 45 EUR (A20 OLinuXino Lime2)
  • Price: 55 EUR (A20 OLinuXino Lime2 4GB)
  • Olimex Store

5.5. 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

5.6. Non-Free Status

  • Non-free blobs required: No
  • WiFi: Not available

  • Works with stock Debian kernel: Yes
  • Boot Firmware: BROM (GPLV2+)

5.7. Known Issues

  • None

6. A20 OLinuXino MICRO

A20 OLinuXino MICRO

Olimex's A20 OLinuXino MICRO is a fully Open Source Hardware (OSHW) single board computer. This means that the designer is actively helping people using the platform for their own designs, and supports them in adding hardware functionality and production advice. This is a part of freedom that is often overlooked, but very much aligned with the FreedomBox goals. It uses the Allwinner A20 Dual Core ARM processor. FreedomBox images are built and tested for this device starting with version 0.7. To use this device as a FreedomBox, a separate USB WiFi device that does not require non-free firmware is recommended.

6.1. Similar Hardware

The following similar hardware will also work well with FreedomBox.

6.2. Download

FreedomBox SD card images are available for this device. Follow the instructions on the download page to create a FreedomBox SD card and boot the device. 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.

6.3. Build Image

FreedomBox images for this hardware can be built using Freedom Maker.

6.4. Availability

  • Price: 55 EUR (A20 OLinuXino MICRO)
  • Price: 65 EUR (A20 OLinuXino MICRO 4GB)
  • Olimex Store

6.5. 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

6.6. Non-Free Status

  • Non-free blobs required: No
  • WiFi: Not available

  • Works with stock Debian kernel: Yes
  • Boot Firmware: BROM (GPLV2+)

6.7. Known Issues

  • None

7. 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.

7.1. Similar Hardware

Although untested, the following similar hardware is also likely to work well with FreedomBox.

7.2. 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.

7.3. 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.

7.4. Build Image

FreedomBox images for this hardware, which is for all amd64 machines, can be built using Freedom Maker.

7.5. Availability

7.6. 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

7.7. Non-Free Status

  • Non-free blobs required: No
  • WiFi: Not available

  • Works with stock Debian kernel: Yes
  • Boot firmware: Coreboot

7.8. Known Issues

None

8. VirtualBox

VirtualBox

This page will help you get started with using FreedomBox on a virtual machine using VirtualBox. While VirtualBox images are primarily used for testing and development, they can also be used for regular use if you have spare resources on one of your machines. This setup is useful if:

  • You don't own one of the supported hardware devices.

  • You don't use Debian GNU/Linux as your operating system.
  • You don't want to disturb your Debian installation to try out FreedomBox.

Prebuilt FreedomBox images for VirtualBox are routinely made available in VirtualBox's own VDI image file format. They contain a Debian GNU/Linux operating system and an installation of FreedomBox with all dependencies ready to run on any OS supported by VirtualBox (Windows, Linux, Macintosh, and Solaris).

A more adventurous alternative to downloading one of these images is to install Debian on VirtualBox and then install FreedomBox on it.

VirtualBox itself is available from https://www.virtualbox.org/ (or your distribution's package manager).

8.1. Download

Follow the instructions on the download page to download and verify a VirtualBox image. As pr. 2016-03-26 the latest images are v0.7-amd64 and v0.7-i386.

8.2. Creating a Virtual Machine

  1. Decompress the downloaded VDI image (tool for Windows, Mac).

  2. Create a new VM in the VirtualBox UI with OS type Linux and Version Debian (32/64-bit according to the downloaded image).

VirtualBox Name and OS dialog

  1. In the Hard disk dialog choose Use an existing virtual hard disk file and select the .vdi file you extracted in step 1.

VirtualBox Hard disk dialog

  1. When created, go to the virtual machine's Settings -> [Network] -> [Adapter 1]->[Attached to:] and choose the network type your want the machine to use according to the explanation in Network Configuration below. The recommended type is the Bridged adapter option, but be aware that this exposes the FreedomBox's services to your entire local network.

VirtualBox recommended network setting

8.3. First Boot

When satisfied with the VM settings click the start button in the VirtualBox UI and your new FreedomBox will boot.

The console of the VM will show the textual screen below when finished booting, from here most interaction with FreedomBox will be through the web interface (aka. Plinth) in a browser.

FreedomBox console after booting successfully

To access the web interface you need to find out your FreedomBox's IP address as described in section: Finding out the IP address of the virtual machine. Then access this IP from a web browser which is on the same network as the VM (f.ex. the host). If all is well, you are now presented with a welcome message and invited to complete the first boot process.

FreedomBox welcomes you to the first boot

This mainly consist of creating an administrative user for the system.

8.4. Using

See the FreedomBox usage page for more details.

You can log in to the Debian GNU/Linux system as the user created during Plinth first boot on the VirtualBox console or remotely via ssh.

After logging in, you can become root with the command sudo su.

8.5. Build Image

If you wish to build your own images instead of downloading available images, it can be done using Freedom Maker.

8.6. Tips & Troubleshooting

8.6.1. Network Configuration

VirtualBox provides many types of networking options. Each has its advantages and disadvantages. For more information about how various networking types work in VirtualBox, see VirtualBox's networking documentation. https://www.virtualbox.org/manual/ch06.html

For a simple setup, it is recommended that you use a single network interface in your guest machine. This will make the first boot script automatically configure that interface as an internal network with automatic network configuration. Inside the guest machine, the networking is configured automatically and all the services are made available on this network interface. For more information on how networks are configured by default in FreedomBox, see Networks section.

What remains is to make those services available to the host machine or to other machines in the network. You must then choose one of the following types of networking for the network interface on your guest machine. To set a particular type of network for the guest's network adapter, go to the guest VM's settings then the network options and then select the adapter you wish to configure. There, set the network type from the available list of networks.

  1. First and the recommended option is to use the Bridged type of network. This option exposes the guest machine to the same network that host network is connected to. The guest obtains network configuration information from a router or DHCP server on the network. The guest will appear as just another machine in the network. A major advantage of this of setup is that the host and all other machines in the network will be able to access the services provided by guest without requiring any further setup. The only drawback of this approach is that if the host is not connected to any network, the guest's network will remain unconfigured making it inaccessible even from the host.

  2. Second method is Host only type of networking. With a guest's network interface configured in this manner, it will only be accessible from the host machine. The guest will not able access any other machine but the host, so you do not have internet access on the guest. All services on the guest are available to the host machine without any configuration such as port forwarding.

  3. The third option is to use the NAT type of network. This the networking type that VirtualBox assigns to a freshly created virtual machine. This option works even when host is not connected to any network. The guest is automatically configured and is able to access the internet and local networks that host is able to connect to. However, the services provided by the guest require port forwarding configuration setup to be available outside.

    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 2222 fbx@localhost

    Map 4443 on host to 443 on the guest. This make FreedomBox HTTPS service available on host using the URL https://localhost:4443/ You will need to add a mapping for each such services from host to guest.

  4. The final option is to create two network interfaces, one host only and one NAT type. This way you can access the guest without any additional configuration, and you have internet access on the guest. The guest will be invisible to any other machines on the network.

Summary of various network types:

-

Guest accessible from other machines

Guest accessible from host

Works without port forwarding

Works without host connected to network

Guest has internet access

Bridged

(./)

(./)

(./)

{X}

(./)

Host only

{X}

(./)

(./)

(./)

{X}

NAT

(./)

(./)

{X}

(./)

(./)

NAT and Host

{X}

(./)

(./)

(./)

(./)

8.6.2. Finding out the IP address of the virtual machine

This depends on the network configuration you chose. With a bridged adapter, your virtual machine gets its IP address from the DHCP server of your network, most likely of your Router. You can try the first couple of IP addresses or check your router web interface for a list of connected devices.

If you chose host-only adapter, the IP address is assigned by the DHCP server of your VirtualBox network. In the VirtualBox Manager, go to File -> Preferences -> Network -> Host-only Networks. You can see and edit the DHCP address range there, typically you get assigned addresses close to the Lower Address Bound.

Another possibility of finding the IP address is to login via the Virtualbox Manager (or similar software). The FreedomBox images do not have any default user accounts, so you need to set an initial user and password using the passwd-in-image script.

See also QuickStart for instructions on how to scan your network to discover the IP of the VM.

8.6.3. Networking Problems with macchanger

The package macchanger can cause network problems with VirtualBox. If you have a valid IP address on your guest's host network adapter (like 192.168.56.101) but are not able to ping or access the host (like 192.168.56.1), try uninstalling macchanger:

$ dpkg --ignore-depends=freedombox-setup --remove macchanger 

You might have to manually remove the script /etc/network/if-prep-up/macchanger. If Debian complains about unmet dependencies when you use a package manager (apt-get, aptitude, dpkg), try to remove 'macchanger' from the dependencies of 'freedombox-setup' in the file /var/lib/dpkg/status.

8.6.4. Mounting Images Locally

If you want to mount images locally, use the following to copy built images off the VirtualBox:

$ mkdir /tmp/vbox-img1 /tmp/vbox-root1
$ vdfuse -f freedombox-unstable_2013.0519_virtualbox-i386-hdd.vdi /tmp/vbox-img1/
$ sudo mount -o loop /tmp/vbox-img1/Partition1 /tmp/vbox-root1
$ cp /tmp/vbox-root1/home/fbx/freedom-maker/build/freedom*vdi ~/
$ sudo umount /tmp/vbox-root1
# $ sudo umount /tmp/vbox-img1 # corruption here.

8.6.5. 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.

Übersetzungen: Deutsch - English

9. Debian

FreedomBox ist ein "pure blend" von Debian. Dies bedeutet dass alles von FreedomBox in den Debian Paketen zur Verfügung steht. Es bedeutet auch, dass jedes Gerät das mit Debian läuft in eine FreedomBox umgewandelt werden kann.

Diese Seite beschreibt den Prozess wie man FreedomBox auf einem Debian-System installiert. Aktuell arbeitet FreedomBox auf Debian Testing (Stretch) und Unstable (Sid).

Setzen Sie eine frische Debian Installation ein

Die Installation der FreedomBox verändert Ihr Debian System in umfangreicher und wichtiger Weise. Dies beinhaltet die Installing einer Firewall und die Neuerstellung von Server Zertifikaten. Es ist deshalb empfohlen dass Sie FreedomBox auf einem frischen/neuen Debian System installieren anstatt auf einem existierenden Setup.

nutzen Sie "fbx" als Login-Nname

Wenn Sie eine erstes Benutzerkonto erstellen, nutzen Sie "fbx" als Login-Name. (Sobald der FreedomBox Setup abgeschlossen ist werden alle Benutzerkonten außer "fbx" durch pam_access ausgesperrt werden. Dies beeinflusst auch den sudo Zugriff.)

9.1. Auf Debian installieren

  1. Beachten Sie den Abschnitt zur Fehlerbehebung weiter unten; er enthält Tips und Work-arounds die bei der Installation hilfreich sein können.
  2. Installieren Sie Debian Testing (Stretch) oder Unstable (Sid) auf Ihre Hardware.

  3. Aktualisieren Sie Ihre Paketliste.
    $ sudo apt-get update
  4. Installieren Sie das freedombox-setup Package.

    $ sudo apt-get install freedombox-setup
    • Wenn Sie gefragt werden, ob MacChanger automatisch laufen soll, wählen Sie "No".

  5. Starten Sie das FreedomBox Setup-Program. Dies installiert weitere Pakete und definiert grundlegende Konfigurationen.

    $ sudo /usr/lib/freedombox/setup | tee freedombox-setup.log
    Eventuell müssen Sie ihre bereits vorhandene Netzwerk-Konfiguration löschen. Siehe Fehlerbehebungen Notiz Nr. 2 unten.
  6. Starten Sie das System neu. Dies ist notwendig um die Scripte für den ersten Durchlauf zu aktivieren.
    $ sudo reboot
  7. Nach dem Systemstart warten Sie bis das System ein zweites Mal neu startet. Die Scripte setzen das Grundsystem auf und initiieren einen Neustart.
  8. Nach dem zweiten Neustart können Sie beginnen Ihre FreedomBox zu benutzen.

9.2. Fehlerbehebungen

  1. Es gibt ein Problem im policykit-1 Paket welches Fehlermeldungen und Systemstillstand während der Installation vom freedombox-setup Paket verursachen kann. Das Problem kann umgangen werden, wenn policykit-1 zuerst installiert wird und danach das System neu gestartet wird. Anschließend könnnen Sie die oben beschriebene Prozedur problemlos abarbeiten.

    $ sudo apt-get update
    $ sudo apt-get install policykit-1
    $ sudo reboot
  2. FreedomBox unterstützt keine Netzwerkkonfiguration über /etc/network/interfaces und sie wird keine non-loopback Interfaces die dort definiert sind unterstützen. (Siehe Fehler #797614.) Zukünftige Versionen von freedombox-setup werden diese Datei automatisch leeren; für den Moment editieren Sie sie per Hand und stellen sicher dass sie nur folgendes enthält:

    auto lo
    iface lo inet loopback

    Wenn Sie den Installationsprozess bereits abgeschlossen haben ohne diesen Schritt durchzuführen, müssen Sie jetzt die Datei /etc/network/interfaces entsprechend anpassen und den Rechner neustarten. Anschließend werden die Netzwerke die durch den setup Schritt oben definiert worden sind konfiguriert werden. Netzwerk-Schnittstellen werden dann in der Firewall-Zone internal oder external stehen. Dies ist wesentlich damit das FreedomBox Web-Interface von anderen Geräten im Netzwerk erreichbar ist. Man kann die Netzwerkverbindungen über das nmtui Kommando, falls nötig, bearbeiten.

10. DreamPlug

DreamPlug

DreamPlug is the hardware for which FreedomBox has been originally targeted. FreedomBox images are built and tested for it. For using this device as FreedomBox, a USB WiFi device that does not require non-free firmware is recommended.

You can find more support and discussion for DreamPlug on the official forum.

10.1. 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. See also instructions for using an internal micro-SD with DreamPlug.

An alternative to downloading these images is to install Debian on DreamPlug and then install FreedomBox on it.

10.2. Networking

The network port towards the middle of the box, is configured by FreedomBox to be an upstream Internet link. The remaining port is configured for a local computer to connect to.

10.3. Firmware

Note that the factory firmware configurations may vary between revisions of the hardware, and render some images incompatible. See the DreamPlug firmware page for information on what images are compatible and how to update your DreamPlug firmware.

10.4. Build Image

FreedomBox images for this hardware can be built using Freedom Maker.

10.5. Testing

Instructions on how to test this hardware are available.

10.6. Availability

10.7. Hardware

  • Open Hardware: No
  • CPU: Marvell Kirkwood 88F6281 @ 1.2GHz
  • RAM: 512MB 16bit DDR2-800 MHz
  • Storage: 4 GB on board micro-SD
  • Architecture: armel
  • Ethernet: 2x 10/100/1000, RJ45
  • WiFi: SD8787, 802.11 b/g/n

  • SATA: eSATA 2.0 port

10.8. Non-Free Status

  • Non-free blobs required: built-in WiFi

  • WiFi: no free WiFi drivers + firmware available

  • Works with stock Debian kernel: yes

10.9. Known Issues

  • WiFi does not work with free software. A separate USB WiFi device is recommended.

11. Raspberry Pi Model B+

Raspberry Pi (Model B+)

Raspberry Pi (Model B+) is a popular single board computer developed with the intention of promoting teaching of basic computer science in schools. FreedomBox images are built and tested for it. For using this board as FreedomBox, a USB WiFi device that does not require non-free firmware is recommended.

Note: The Debian architecture used for this device is armel. This means floating point computations are done in software and most operations are slower than what Raspberry Pi is capable of.

11.1. 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.

11.2. Build Image

FreedomBox images for this hardware can be built using Freedom Maker.

11.3. Availability

11.4. Hardware

  • Open Hardware: No
  • CPU: ARM1176JZF-S (ARMv6k) 700 MHz
  • RAM: 512 MB
  • Storage: MicroSD card slot
  • Architecture: armel
  • Ethernet: 10/100, RJ45
  • WiFi: None, use a USB WiFi device

  • SATA: None

11.5. Non-Free Status

  • Non-free blobs required: boot firmware
  • WiFi: Not available

  • Works with stock Debian kernel: No

11.6. Known Issues

  • The Debian architecture used for this device is armel. This means floating point computations are done in software and generally most operations are slower than what Raspberry Pi is capable of.

12. Raspberry Pi 2 Model B

Raspberry Pi 2

Raspberry Pi 2 (Model B ) is a popular single board computer developed with the intention of promoting teaching of basic computer science in schools. It is a successor to Raspberry Pi Model B+ with much faster processor and more RAM. FreedomBox images are built and tested for it. For using this board as FreedomBox, a USB WiFi device that does not require non-free firmware is recommended.

Note: For FreedomBox release 0.5, the Debian architecture used for this device is armel. This means floating point computations are done in software and most operations are slower than what Raspberry Pi 2 is capable of. Starting with FreedomBox release 0.6 separate armhf images with full hardware floating point support are available.

12.1. 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.

12.2. Build Image

FreedomBox images for this hardware can be built using Freedom Maker.

12.3. Availability

12.4. Hardware

  • Open Hardware: No
  • CPU: 900 MHz quad-core ARM Cortex-A7
  • RAM: 1 GB
  • Storage: MicroSD card slot
  • Architecture: armhf
  • Ethernet: 10/100, RJ45
  • WiFi: None, use a USB WiFi device

  • SATA: None

12.5. Non-Free Status

  • Non-free blobs required: boot firmware
  • WiFi: Not available

  • Works with stock Debian kernel: No

12.6. Known Issues

  • The Debian architecture used for this device is armel. This means floating point computations are done in software and generally most operations are slower than what Raspberry Pi 2 is capable of. However, starting with FreedomBox 0.6 separate images for Raspberry Pi 2 with armhf architecture will be built.

13. USB Wi-Fi

FreedomBox works on many single board computers. However, many of these boards do not have built-in Wi-Fi capabilities. Even when Wi-Fi capability is available, non-free proprietary firmware is required to make them work.

A solution to the problem is to plug-in a USB Wi-Fi device into one of the available USB ports. There are many such devices available which do not require non-free firmware to work. The following is a list of such devices that work with FreedomBox devices. Some devices based on these chips have tested to work well with FreedomBox including functions such as access point mode.

13.1. 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

13.2. Resources

Advanced Topics

1. Adding Additional Features

There are a number of incomplete projects that you might find useful, for setting up a wiki, an IM server, and so forth. To check these out, download the repository:

$ hg clone https://bitbucket.org/nickdaly/plugserver ~/plugserver

Then, read the README. It's pretty detailed. Also, if you can, it may be best to wait until these tools are fully integrated into the FreedomBox image. Otherwise, migrating from these custom tools to the officially supported FreedomBox tools may be difficult. Ultimately, that decision is up to you.

Mitarbeiten

From code, design and translation to spreading the world and donation, here is a list of possible contributions to develop FreedomBox.

Progess calls
TODO page
Donation page

2. 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.

3. Development priorities

Upcoming priorities are discussed on an regular basis. You find the progress of the web interface Plinth with its priorities here:Project Progress. We want to enjoy soon a version 1.0.

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.

4. Contributions needed

4.1. 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.

4.2. Bugs

List of bugs listed on Debian universal system. Also see the Packages overview for FreedomBox packaging team for status of various packages that we use.

4.3. 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.

  • FreedomBox Setup: a Debian package for setting up the FreedomBox.

  • Plinth: a web interface to administer the functions of FreedomBox.

  • Freedom Maker: a script to build FreedomBox disk images for use on various hardware devices or virtual machines.

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.

4.4. Design

4.4.1. User Experience Design

If you are a user experience designer, you can help FreedomBox with the following items:

4.4.2. Technical Design

FreedomBox is still under development any many components are yet to be worked on. You can contribute to the discussion on various technical design and implementation aspects of FreedomBox. See:

4.5. 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.

4.6. 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.

4.7. 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.

4.8. 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.

The primary user interface (Plinth) was internationalized in the 0.7 release. You can contribute to the localization effort using the web-based tool at Weblate or directly to the source tree via 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.

4.9. 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.

Für Entwickler

This manual is meant for developers intending to develop applications for FreedomBox. It provides a step by step tutorial and an API reference.

1. Writing Applications - Tutorial

This tutorial covers writing an application for FreedomBox. FreedomBox is a pure blend of Debian with a web interface, known as Plinth, that configures its applications. We shall discuss various aspects of building an application for FreedomBox, by creating an example application.

There are two parts to writing a FreedomBox application. First is to make sure that the application is available as a Debian package uploaded to the repositories. This is the majority of the work involved. However, if an application is already available in Debian repositories, it is trivial to build a FreedomBox UI for it. The second part of writing an application for FreedomBox is to provide a thin web interface layer for configuring the application. This is done by extending Plinth's user interface to provide visibility to the application and to let the user control its operations in a highly simplified way. This layer is referred to as 'Plinth application'.

Plinth applications can either be distributed as part of Plinth source code by submitting the applications to the Plinth project or they can distributed independently. This tutorial covers writing an application that is meant to be distributed as part of Plinth. However, writing independent Plinth applications is also very similar and most of this tutorial is applicable.

Note

The term application, in this tutorial, is used to mean multiple concepts. FreedomBox application is a combination of Debian package and a web interface layer. The web interface layer is also called a Plinth application which is very similar to and built upon a Django application.

1.1. Before we begin

Plinth is a web interface built using Python3 and Django. FreedomBox applications are simply Django applications within the Plinth project. Hence, for the most part, writing a FreedomBox application is all about writing a Django application.

You should start by reading the Django tutorial. All the concepts described there are applicable for how plinth and its applications are be built.

1.2. Picking an application

We must first, of course, pick an application to add to FreedomBox. For the purpose of this tutorial, let us pick Tiny Tiny RSS. The project description reads as, Tiny Tiny RSS is an open source web-based news feed (RSS/Atom) reader and aggregator, designed to allow you to read news from any location, while feeling as close to a real desktop application as possible.

Choosing an application

When choosing an application we must make sure that the application respects users' freedom and privacy. By choosing to use FreedomBox, users have explicitly made a choice to keep the data with themselves, to not provide privacy compromising data to centralized entities and to use Free Software that respects their Software Freedom. These are not properties of some of the applications in FreedomBox but all applications must adhere to these principles. Applications should not even ask the users questions to this effect, because users have already made a choice.

1.3. Packaging the application

Majority of the effort in creating an application for FreedomBox is to package it for Debian and get it uploaded to Debian repositories. Going through the process of packaging itself is outside the scope of this tutorial. It is, however, well documented elsewhere. You should start here.

Debian packaging might seem like an unnecessary process that takes time with its adherence to standards, review process, legal checks, etc. However, upon close examination, one will find that without these steps the goals of the FreedomBox project cannot be met. Some of the advantages of Debian packaging are listed below:

  • Legal check ensures that proprietary licensed code or code with bad licenses does not inadvertently creep in.
  • Libraries have to be packaged separately easing security handling. When a security vulnerability is identified in a library, just the library will have to be updated and not all the applications that depend on it.
  • Upgrades become smoother. The dependency handling of the packaging system, configuration handling tools, tools to deal with various types of well known files help with ensuring a proper upgrade.
  • Collaborative maintenance teams ensure that the package is well cared for even if you get busy with other work and can't spend time on your package. Following standards and using common infrastructure is critical to enable this development methodology.

1.4. Creating the project structure

Create a directory structure as follows with empty files. We will fill them up in a step-by-step manner.

+- <plinth_root>/
  |
  +- plinth/
  | |
  | +- modules/
  |   |
  |   +- ttrss/
  |     |
  |     +- __init__.py
  |     |
  |     +- forms.py
  |     |
  |     +- urls.py
  |     |
  |     +- views.py
  |     |
  |     +- templates/
  |     | |
  |     | +- ttrss.html
  |     |
  |     +- tests
  |       |
  |       +- __init__.py
  |
  +- actions/
  | |
  | +- ttrss
  |
  +- data/
    |
    +- etc/
      |
      +- plinth/
        |
        +- modules-enabled/
          |
          +- ttrss

The __init__.py indicates that the directory in which it is present is a Python module. For now, it is an empty file.

Plinth's setup script setup.py will automatically install the plinth/modules/ttrss directory (along with other files described later) to an appropriate location. If you are creating an application that stays independent and outside of Plinth source tree, then your setup.py script will need to install it a proper location on the system. The plinth/modules/ directory is a Python3 namespace package. So, you can install it with the plinth/modules/ directory structure into any Python path and still be discovered as plinth.modules.*.

1.5. Tell Plinth that we exist

The first thing to do is tell Plinth that our application exists. This is done by writing a small file with the Python import path to our application and placing it in data/etc/plinth/modules-enabled/. Let us create this file ttrss:

plinth.modules.ttrss

This file is automatically installed to /etc/plinth/modules-enabled/ by Plinth's installation script setup.py. If we are writing a module that resides independently outside the Plinth's source code, the setup script will need to copy it to the target location. Further, it is not necessary for the application to be part of the plinth.modules namespace. It can, for example, be plinth_ttrss.

1.6. Writing the URLs

For a user to visit our application in Plinth, we need to provide a URL. When the user visits this URL, a view is executed and a page is displayed. In urls.py write the following:

from django.conf.urls import url

from . import views

urlpatterns = [
    url(r'^apps/ttrss/$', views.index, name='index'),
]

This routes the /apps/ttrss/ URL to a view called index defined in plinth/modules/ttrss/views.py. This is no different than how routing URLs are written in Django. See Django URL dispatcher for more information.

1.7. Adding a menu item

We have added a URL to be handled by our application but this does not yet show up to be a link in Plinth web interface. Let us add a link in the applications list. In __init__.py add the following:

from plinth import cfg

def init():
    """Intialize the module."""
    menu = cfg.main_menu.get('apps:index')
    menu.add_urlname('News Feed Reader (Tiny Tiny RSS)', 'glyphicon-bullhorn',
                     'ttrss:index', 850)

As soon as Plinth starts, it will load all the enabled modules into memory. After this, it gives a chance to each of the modules to initialize itself by calling the init() method if there is such a method available as <app>.init(). Here we have implemented this method and added our menu item to the applications menu as part of the initialization process.

We wish to add our menu item to the list of applications which is why we have retrieved the applications menu which is available under the main menu. After this we add our own menu item to this menu. There are several parameters during this process that are important:

  • In the first parameter we are providing the display name to use for our application when showing the menu item.
  • In the second parameter we are providing the icon to show for this menu item. This is an icon from the Twitter Bootstrap library. See

    the Twitter Bootstrap library documentation for a list of available icons. We can pick an icon from the available list of icons and just mention its glyphicon class as name here.

  • The third parameter is the name of the URL we have created for our application. Note that when including this application's URLs, Plinth will automatically set the name of the module as the Django

    URL namespace. Hence it is ttrss:index and not just index.

  • The final parameter specifies where in the menu this application shows up. This is weightage number with which Plinth sorts the menu items. Higher the weightage, the lower the menu item appears (as it sinks). Since Plinth menu items are alphabetically sorted, for our

    application we wish for it to appear between Public Visibility and Voice Chat. Their weights are 800 and 900 respectively. So we selected 850.

We have used the application menu item to insert our own menu item as a child. To be able to use the application menu item, we need to make sure that the module providing the application menu is loaded before our application is loaded. We will do that in the next step.

1.8. Specifying module dependencies

Specifying a simple list of applications to be loaded before our application provided to Plinth is sufficient. Add this in __init__.py.

depends = ['plinth.modules.apps']

Plinth will now make sure that the apps module is loaded before our module is loaded. Application initialization is also ensured to happen in this order. We can safely use any features of this module knowing that they have been initialized.

Circular dependencies

Circular dependencies are not possible among Plinth applications. Attempting to add them will result in error during startup.

1.9. Writing the enable/disable form

We wish to provide a user interface to the user to enable and disable the application. Complex modules may require more options but this is sufficient for our application. Add the following forms.py.

from django import forms

class TtrssForm(forms.Form):
    """Tiny Tiny RSS configuration form."""
    enabled = forms.BooleanField(
        label='Enable Tiny Tiny RSS',
        required=False)

This creates a Django form that shows a single option to enable/disable the application. It also shows its current state. This is how a regular Django form is built. See Django Forms documentation for more information.

Too many options

Resist the temptation to create a lot of configuration options. Although this will put more control in the hands of the users, it will make FreedomBox less usable. FreedomBox is a consumer product. Our target users are not technically savvy and we have make most of the decisions on behalf of the user to make the interface as simple and easy to use as possible.

1.10. Writing a view

In views.py, let us add a view that can handle the URL we have provided above.

from .forms import TtrssForm

def index(request):
    """Serve configuration page."""
    status = get_status()

    form = None

    if request.method == 'POST':
        form = TtrssForm(request.POST, prefix='ttrss')
        if form.is_valid():
            _apply_changes(request, status, form.cleaned_data)
            status = get_status()
            form = TtrssForm(initial=status, prefix='ttrss')
    else:
        form = TtrssForm(initial=status, prefix='ttrss')

    return TemplateResponse(request, 'ttrss.html',
                            {'title': 'News Feed Reader (Tiny Tiny RSS)',
                             'status': status,
                             'form': form})

This view works with the form we created in the previous step. It shows the current status of the service in form. This status is retrieved with the help of get_status() helper method. When the form is posted, again this view is called and it verifies whether the form's input values are correct. If so, it will apply the actions necessary for changed form values using the _apply_changes() method.

1.11. Getting the current status of the application

The view in the previous setup requires the status of the application to be retrieved using the get_status() method. Let us implement that method in views.py.

from plinth.modules import ttrss

def get_status():
    """Get the current status."""
    return {'enabled': ttrss.is_enabled()}

This method retrieves the various statuses of the application for display in the view. Currently, we only need to show whether the application is enabled or disabled. So, we retrieve that using a helper method defined in __init__.py.

from plinth import action_utils

def is_enabled():
    """Return whether the module is enabled."""
    return action_utils.webserver_is_enabled('50-tt-rss')

This method uses one of the several action utilities provided by Plinth. This method checks whether a webserver configuration named 50-tt-rss is enabled.

1.12. Displaying the application page

The view that we have written above requires a template file known as ttrss.html to work. This template file controls how the web page for our application is displayed. Let us create this template file in templates/ttrss.html.

{% extends "base.html" %}

{% load bootstrap %}

{% block content %}

<h2>News Feed Reader (Tiny Tiny RSS)</h2>

<p>Tiny Tiny RSS is a news feed (RSS/Atom) reader and aggregator,
  designed to allow you to read news from any location, while feeling
  as close to a real desktop application as possible.</p>

<h3>Configuration</h3>

<form class="form" method="post">
  {% csrf_token %}

  {{ form|bootstrap }}

  <input type="submit" class="btn btn-primary" value="Update setup"/>
</form>

{% endblock %}

This template extends an existing template known as base.html. This template is available in Plinth core to provide all the basic layout, styling, menus, JavaScript and CSS libraries. We will override the content area of the base template and keep the rest.

Yet again, there is nothing special about the way this template is written. This is a regular Django template. See Django Template documentation.

For styling and UI components, Plinth uses the Twitter Bootstrap project. See Bootstrap documentation for reference.

1.13. Applying the changes from the form

The view we have created displays the form and processes the form after the user submits it. It used a helper method called _apply_changes() to actually get the work done. Let us implement that method in views.py.

from django.contrib import messages

from plinth import actions

def _apply_changes(request, old_status, new_status):
    """Apply the changes."""
    modified = False

    if old_status['enabled'] != new_status['enabled']:
        sub_command = 'enable' if new_status['enabled'] else 'disable'
        actions.superuser_run('ttrss', [sub_command])
        modified = True

    if modified:
        messages.success(request, 'Configuration updated')
    else:
        messages.info(request, 'Setting unchanged')

We check to make sure that we don't try to disable the application when it is already disabled or try to enable the application when it is already enabled. Although Plinth's operations are idempotent, meaning that running them twice will not be problematic, we still wish avoid unnecessary operations for the sake of speed.

We are actually perform the operation using Plinth actions. We will implement the action to be performed a bit later.

After we perform the operation, we will show a message on the response page showing that the action was successful or that nothing happened. We use the Django messaging framework to accomplish this. See Django messaging framework for more information.

1.14. Installing packages required for the application

Plinth takes care of installing all the Debian packages required for our application to work. All we need to do is specify the list of the Debian packages required using a decorator on our view as follows:

from plinth import package

@package.required(['tt-rss'])
def index(request):
    """Serve configuration page."""
    ...

The first time this application's view is accessed, Plinth shows a package installation page and allows the user to install the required packages. After the package installation is completed, the user is shown the application's configuration page.

If there are configuration tasks to be performed immediately before or after the package installation, Plinth provides hooks for it. The before_install= and on_install= parameters to the @package.required decorator take a callback methods that are called before installation of packages and after installation of packages respectively. See the reference section of this manual or the plinth.package module for details. Other modules in Plinth that use this feature provided example usage.

1.15. Writing actions

The actual work of performing the configuration change is carried out by a Plinth action. Actions are independent scripts that run with higher privileges required to perform a task. They are placed in a separate directory and invoked as scripts via sudo. For our application we need to write an action that can enable and disable the web configuration. We will do this by creating a file actions/ttrss.

import argparse

from plinth import action_utils


def parse_arguments():
    """Return parsed command line arguments as dictionary."""
    parser = argparse.ArgumentParser()
    subparsers = parser.add_subparsers(dest='subcommand', help='Sub command')

    subparsers.add_parser('enable', help='Enable Tiny Tiny RSS')
    subparsers.add_parser('disable', help='Disable Tiny Tiny RSS')

    return parser.parse_args()


def subcommand_enable(_):
    """Enable web configuration and reload."""
    action_utils.webserver_enable('50-tt-rss')


def subcommand_disable(_):
    """Disable web configuration and reload."""
    action_utils.webserver_disable('50-tt-rss')


def main():
    """Parse arguments and perform all duties."""
    arguments = parse_arguments()

    subcommand = arguments.subcommand.replace('-', '_')
    subcommand_method = globals()['subcommand_' + subcommand]
    subcommand_method(arguments)


if __name__ == '__main__':
    main()

This is a simple Python3 program that parses command line arguments. While Python3 is preferred, it can be written in other languages also. It uses a helper utility provided by Plinth to actually enable and disable Apache2 web server configuration.

This script is automatically installed to /usr/share/plinth/actions by Plinth's installation script setup.py. Only from here will there is a possibility of running the script under sudo. If you are writing an application that resides indenpendently of Plinth's source code, your setup.py script will need to take care of copying the file to the target location.

1.16. Creating diagnostics

Plinth provides a simple API for showing diagnostics results. The application has to implement a method for actually running the diagnostics and return the results as a list. Plinth then takes care of calling the diagnostics method and displaying the list in a formatted manner.

To implement the diagnostics method, method called diagnose() has to be available as <app>.diagnose(). It must return a list in which each item is the result of a test performed. The item itself is a two-tuple containing the display name of the test followed by the result as passed, failed or error.

def diagnose():
    """Run diagnostics and return the results."""
    results = []

    results.extend(action_utils.diagnose_url_on_all(
        'https://{host}/ttrss', extra_options=['--no-check-certificate']))

    return results

There are several helpers available to implement some of the common diagnostic tests. For our application we wish to implement a test to check whether the /ttrss URL is accessible. Since this is a commonly performed test, there is a helper method available and we have used it in the above code. The {host} tag replaced with various IP addresses, hostnames and domain names by the helper to produce different kinds of URLs and they are all tested. Results for all tests are returned which we then pass on to Plinth.

The user can trigger the diagnostics test by going to System -> Diagnostics page. This runs diagnostics for all the applications. If we want users to be able to run diagnostics specifically for this application, we can include a button for it in our template immediately after the application description.

{% include "diagnostics_button.html" with module="ttrss" enabled=True %}

1.17. Logging

Sometimes we may feel the need to write some debug messages to the console and Plinth log file. Doing this in Plinth is just like doing this any other Python application.

import logging

logger = logging.getLogger(__name__)

def example_method():
    logger.debug('A debug level message')

    logger.info('Showing application page - %s', request.method)

    try:
        something()
    except Exception as exception:
        # Print stack trace
        logger.exception('Encountered an exception - %s', exception)

For more information see Python logging framework documentation.

1.18. Adding a License

Plinth is licensed under the GNU Affero General Public License Version 3 or later. FreedomBox UI applications, which run as modules under Plinth, also need to be under the same license or under a compatible license. The license of our application needs to clear for our application to be accepted by users and other developers. Let us add license headers to our application.

#
# This file is part of Plinth.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#

The above header needs to be present in every file of the application. It is suitable for Python files. However, in template files, we need to modify it slightly.

{% extends "base.html" %}
{% comment %}
#
# This file is part of Plinth.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#
{% endcomment %}

...

1.19. Internationalization

Every string message that is visible to the user must be localized to user's native language. For this to happen, our application needs to be internationalized. This requires marking the user visible messages for translation. Plinth applications use the Django's localization methods to make that happen.

from django.utils.translation import ugettext as _

def index(request):
    ...
    return TemplateResponse(request, 'ttrss.html',
                            {'title': _('News Feed Reader (Tiny Tiny RSS)'),
                             'status': status,
                             'form': form})

Notice that the page's title is wrapped in the _() method call. Let us do that for the menu item of the application too.

from django.utils.translation import ugettext_lazy as _

def init():
    """Intialize the module."""
    menu = cfg.main_menu.get('apps:index')
    menu.add_urlname(_('News Feed Reader (Tiny Tiny RSS)'), 'glyphicon-envelope',
                     'ttrss:index', 600)

Notice that in this case, we have used the ugettext_lazy and in the first case we have used the regular ugettext. This is because in the second case the gettext lookup is made once and reused for every user looking at the interface. These users may each have a different language set for their interface. Lookup made for one language should not be used for other users. The _lazy method provided by Django makes sure that the return value is an object that will actually be converted to string at the final moment when the string is being displayed. In the first case, the looked is made and string is returned immediately.

All of this is the usual way internationalization is done in Django. See Django internationalization and localization documentation for more information.

1.20. Coding standards

For readability and easy collaboration it is important to follow common coding standards. Plinth uses the Python coding standards and uses the pylint and flake8 tools to check if the there are any violations. Run these tools on our application and fix any errors and warnings. Better yet, integrate these tools into your favorite IDE for on-the-fly checking.

For the most part, the code we have written so far, is already compliant with the coding standards. This includes variable/method naming, indentation, document strings, comments, etc. One thing we have to add are the module documentation strings. Let us add those. In __init__.py add the top:

"""
Plinth module to configure Tiny Tiny RSS.
"""

2. Reference Guide

This section describes Plinth API that is most frequently used by application. Note that since Plinth is under development and has not yet reached 1.0, this API is subject to change. This is not usually a problem because all the Plinth applications currently reside in Plinth source repository itself and are updated when the API is updated.

2.1. Applications

These methods are optionally provided by the application and Plinth calls/uses them if they are present.

2.1.1. <application>.init()

Optional. This method is called by Plinth soon after all the applications are loaded. The init() call order guarantees that other applications that this application depends on will be initialized before this application is initialized.

2.1.2. <application>.diagnose()

Optional. Called when the user invokes system-wide diagnostics by visiting System -> Diagnositcs. This method must return an array of diagnostic results. Each diagnostic result must be a two-tuple with first element as a string that is shown to the user as name of the test and second element is the result of the test. It must be one of passed, failed, error. Example return value:

[('Check http://localhost/app is reachable', 'passed'),
 ('Check configuration is sane', 'passed')]

2.1.3. <appliation>.depends

Optional. This module property must contain a list of all applications that this application depends on. The application is specified as string containing the full module load path. For example, plinth.modules.apps.

2.1.4. plinth.package.required(package_list, before_install=None, on_install=on_install)

Make sure that a set of Debian packages are installed before a view can be accessed. If the packages are not currently installed on the system, a special installation view is displayed showing the list of packages to be installed. If the user chooses to proceed, package installation will start and an installation progress screen will be shown. After completion of the installation process, the original view is shown.

The package_list must be an iterable containing the Debian package names as strings. If provided, the before_install callable is called just before the installation process starts. Similarly, on_install callable is called just after the package installation completes.

2.2. Actions

Plinth's web front does not directly change any aspect of the underlying operating system. Instead, it calls upon Actions, as shell commands. Actions live in /usr/share/plinth/actions directory. They require no interaction beyond passing command line arguments or taking sensitive arguments via stdin. They change the operation of the services and applications of the FreedomBox and nothing else. These actions are also directly usable by a skilled administrator.

The following methods are provided by Plinth to run actions and to implement them easily by reusing code for common tasks.

2.2.1. plinth.actions.run(action, options=None, input=None, async=False)

Run an action command present under the actions/ directory. This runs subprocess.Popen() after some checks. The action must be present in the actions/ directory.

options are a list of additional arguments to pass to the command. If input is given it must be bytearray containing the input to pass on to the executed action. If async is set to True, the method will return without waiting for the command to finish.

2.2.2. plinth.actions.superuser_run(action, options=None, input=None, async=False)

This is same as plinth.actions.run() except the command is run with superuser privelages.

2.2.3. plinth.action_utils

Several utlities to help with the implementation of actions and diagnotic tests are implemented in this module. Refer to the module source code for a list of these methods and their documentation.

2.3. Menus

2.3.1. plinth.cfg.main_menu

This is a reference to the global main menu. All menu entries in Plinth are decendents of this menu item. See Menu.add_item() and Menu.add_urlname() for adding items to this menu or its children.

2.3.2. plinth.menu.Menu.get(self, urlname, url_args=None, url_kwargs=None)

Return a child of this menu item. urlname must be the name of a URL as configured in Django. django.core.urlresolvers.reverse() is called before the lookup for child menu item is performed. url_args and url_kwargs are passed on to reverse().

2.3.3. plinth.menu.Menu.add_item(self, label, icon, url, order=50)

Add a menu item as a child to the current menu item. label is the user visible string shown for the menu item. icon must be a glyphicon class from the Twitter Bootstrap library. url is the relative URL to which this menu item will take the user to.

2.3.4. plinth.menu.Menu.add_urlname(self, label, icon, urlname, order=50, url_args=None, url_kwargs=None)

Same as plinth.menu.Menu.add_item() but instead of URL as input it is the name of a URL as configured in Django. django.core.urlresolvers.reverse() is called before it is added to the parent menu item. url_args and url_kwargs are passed on to reverse().

2.4. Services

2.4.1. plinth.service.Service.__init__(self, service_id, name, ports=None, is_external=False, enabled=True)

Create a new Service object to notify all applications about the existence and status of a given application. service_id is a unique identifier for this application. name is a display name of this application that is shown by other applications such as on the firewall status page. ports is a list of names recognized by firewalld when enabling or disabling firewalld services. If is_external is true, the ports for this service are accessible from external interfaces, that is, from the Internet. Otherwise, the service is only available for client connected via LAN. enabled is the current state of the application.

2.4.2. plinth.service.Service.is_enabled(self)

Return whether the service is currently enabled.

2.4.3. plinth.service.Service.notify_enabled(self, sender, enabled)

Notify other applications about the change of status of this application. sender object should identify which application made the change. enabled is a boolean that signifies whether the application is enabled (= True) or disabled (= False).

This is typically caught by the firewall application to enable or disable the ports corresponding to an application.

Hacking

FreedomBox consists of three main projects:

1. Plinth

Plinth is a web interface to administer the functions of the FreedomBox.

Plinth is Free Software under GNU Affero General Public License version 3 or (at your option) a later version.

1.1. Using

  • 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 http://freedombox/plinth.

  • 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

1.2. Screenshots

About Page Enabling Tor Hidden Services Setting up Email Client Newsfeed from anywhere

1.3. Support

You may ask for support on

1.4. Contributing

We are looking for help to improve Plinth. You can contribute to Plinth by not just by coding but also by translating, documenting, designing, packaging and providing support.

1.4.1. Debian Package

2. FreedomBox Setup

FreedomBox Setup is a Debian package for setting up the FreedomBox. If you download and use pre-built images you don't have to worry about this package.

FreedomBox Setup is responsible for setting up basic networking, web server, user accounts, installing essential packages etc. It performs first part of the setup during the image build process. Later, when the image is booted for the first time on actual hardware (or on a virtual machine), it does the remaining setup and then reboots the machine. It also comes with a diagnostic script to check if the FreedomBox Setup is running as expected.

FreedomBox Setup is Free Software licensed under GNU General Public License version 3 or (at your option) a later version.

2.1. Using

  • FreedomBox Setup comes installed with all FreedomBox images. You can download FreedomBox images and run on any of the supported hardware.

  • 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.

2.2. Support

You may ask for support on

2.3. Contributing

We are looking for help to improve FreedomBox Setup.

3. Freedom Maker

Freedom Maker is a script to build FreedomBox disk images for use on various hardware devices or virtual machines.

Freedom Maker can currently build FreedomBox disk images for the following:

It relies on the vmdebootstrap project actually create images. If a hardware platform is capable of running Debian, it should not be too much effort adopt Freedom Maker to create FreedomBox images for the platform.

Freedom Maker is Free Software licensed under GNU General Public License version 3 or (at your option) a later version.

3.1. Building FreedomBox Images

3.2. Support

You may ask for support on

3.3. Contributing

We are looking for help to improve Freedom Maker.

  • Instructions on how to contribute code are available.

  • Freedom Maker is hosted on FreedomBox Alioth Portal. The primary Git repository is hosted there.

  • Freedom Maker is also hosted on FreedomBox GitHub Page. Pull requests are accepted there.

  • You can contribute to FreedomBox by adding support for more hardware platforms. Freedom Maker can be easily adopted to newer platforms if they already support running Debian.

  • You can create and test images with Freedom Maker regularly to test for new features and check for regressions.
  • List of bugs, TODO items and feature requests are available on the issue tracker.

  • You can request for development assistance on the mailing list or the #freedombox IRC channel.

Weiteres Material: Handbücher Älterer Versionen

Weitersagen