FreedomBox: take your online privacy back

FreedomBox is a ready made personal server, designed with privacy and data ownership in mind. It is a subset of the Debian universal operating system and includes free software only. You can run it on a small, inexpensive and power-efficient computer box in your home that is dedicated for that use. It can also be installed on any computer running Debian or in a virtual machine.

In order to replace third-party communication services that are data mining your entire life, you will be able to host services yourself and use them at home or over the Internet through a browser or specialized apps. These services include chat and voice calls, webmail, file sharing and calendar, address book and news feed synchronization. For example, to start using a private chat service, activate the service from the administration interface and add your friends as authorized users of the service. They will be able to connect to the service hosted on your FreedomBox, using XMPP chat clients such as Conversations on Android, Pidgin on Windows and Linux, or Messages on Mac OS, for encrypted communications.

FreedomBox is a product you can just buy, set up and use. Once installed the interface is easy to use, similar to a smart phone.

User documentation:

• List of applications offered by FreedomBox.

• Manual

• Live Help from the community

FreedomBox can also host a Wi-Fi access point, ad blocking proxy and a virtual private network (VPN). More advanced users can replace their router with a FreedomBox.

Setting up FreedomBox on a specific hardware or on your computer running Debian may require a bit of technical expertise or help from the community.

Related technical documentation:

• Machines that support FreedomBox

• Download and Install

• FreedomBox Developer Manual

1. Typical usage: Private Cloud

FreedomBox provides services to the computers and mobile devices in your home, and to your friends. This includes secure instant messaging and low-bandwidth, high-quality voice conference calling. FreedomBox lets you publish your content in a blog and wiki to collaborate with the rest of the world. On the roadmap are a personal email server and federated social networking, to provide privacy-respecting alternatives to Gmail and Facebook.

2. Typical usage: Network-Attached Storage (NAS)

The storage space available to FreedomBox can be expanded by attaching an external disk drive. This allows FreedomBox to become a media library for your photos, music, and videos. The folders are shared to laptops and mobile phones on the local network, and the media can be streamed to local devices including smart TVs.

3. Advanced usage: Smart Home Router

FreedomBox runs in a physical computer and can route your traffic. It can sit between various devices at home such as mobiles, laptops and TVs and the Internet, replacing a home wireless router. By routing traffic, FreedomBox can remove tracking advertisements and malicious web bugs before they ever reach your devices. FreedomBox can cloak your location and protect your anonymity by "onion routing" your traffic over Tor. FreedomBox provides a VPN server that you can use while you are away from home to keep your traffic secret on untrusted public wireless networks and to securely access various devices at home.

It can also be carried along with your laptop and set up to offer its services on public networks at work, school or office. In the future, FreedomBox intends to deliver support for alternative ways of connecting to the Internet such as Mesh networking.

4. Advanced usage: For Communities

The primary design goal of FreedomBox is to be used as a personal server at home for use by a single family and their friends. However, at the core, it is a server software that can aid a non-technical user to setup services and maintain them with ease. Security is automatically managed and many of the technical choices in system administration are taken care by the software automatically thereby reducing complexity for a non-technical user. This nature of FreedomBox makes it well-suited for hosting services for small communities like villages or small firms. Communities can host their own services using FreedomBox with minimal effort. They can setup Wi-Fi networks that span the entire area of the community and draw Internet connections from long distances. Community members can enjoy previously unavailable Internet connectivity, ubiquitous Wi-Fi coverage, free VOIP services, offline education and entertainment content, etc. This will also boost privacy for individuals in the community, reduce dependence on centralized services provided by large companies and make them resistant to censorship.

The free e-book FreedomBox for Communities describes the motivation and provides detailed instructions to setup FreedomBox for this use case. Members of the FreedomBox project are involved in setting up Wi-Fi networks with free Internet connectivity in rural India. This e-book documents their knowledge and experiences.

5. FreedomBox Interface

5.1. Screenshot

5.3. Video resources

Eben Moglen's talk, Eben Moglen - Freedom in the cloud, delivered before the FreedomBox project was started gives insights into the philosophy behind FreedomBox.

First demonstration of FreedomBox at SFLC, University of Columbia by Sunil Mohan Adapa.

Quick Start

1. What you need to get started

The easy way is to buy a FreedomBox kit.

Alternatively you may choose to build it yourself, by gathering all the components:

• A supported device (including any device that can run Debian). We will call that the FreedomBox in the rest of this manual.

• A power cable for your device.
• An ethernet cable.

• A microSD card (or equivalent storage media for your device), prepared according to the instructions on the Download page.

2. How to get started

1. Plug one end of your ethernet cord into your FreedomBox's ethernet port, and plug the other end into your router.

2. Power on the FreedomBox.

   • Note: On most single board computers, don't expect any output on a monitor connected via HDMI as the support may not exist in the kernel. See below to access and control your FreedomBox via network.

3. On first boot, FreedomBox will perform its initial setup (older versions of FreedomBox reboot after this step). This process may take several minutes on some machines. After giving it about 10 minutes, proceed to the next step.

4. After the FreedomBox has finished its initial setup, you can access its web interface through your web browser.

   • If your computer is connected directly to the FreedomBox through a second (LAN) ethernet port, you can browse to: http://freedombox/ or http://10.42.0.1/.

   • If your computer supports mDNS (GNU/Linux, Mac OSX or Windows with mDNS software installed), you can browse to: http://freedombox.local/ (or http://the-hostname-you-entered-during-install.local/)

   • If you know your way around the router's web interface, you can look up the IP address of the FreedomBox there, and browse to that address.

   • If none of these methods are available, then you will need to figure out the IP address of your FreedomBox. You can use the "nmap" program from your computer to find its IP address:

          nmap -p 80 --open -sV 192.168.0.0/24 (replace the ip/netmask with the one the router uses)

     In most cases you can look at your current IP address, and change the last digits with zero to find your home network, like so: XXX.XXX.XXX.0/24

     Your FreedomBox will show up as an IP address with an open tcp port 80 using Apache httpd service on Debian, such as the example below which would make it accessible at http://192.168.0.165:

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

     If nmap does not find anything with the above command, you can try replacing 192.168.0.0/24 with 10.42.0.255/24.

          nmap -n -sP 10.42.0.255/24

     The scan report will show something similar to the following:

          Nmap scan report for 10.42.0.1
          Host is up (0.00027s latency).
          Nmap scan report for 10.42.0.50
          Host is up (0.00044s latency).

     In this example, the FreedomBox is accessible at http://10.42.0.50. (10.42.0.1 is my laptop.)

5. On accessing FreedomBox's web interface your browser will warn you that it communicates securely but that it regards the security certificate for doing so as invalid. This is a fact you need to accept because the certificate is auto generated on the box and therefore "self-signed" (the browser might also use words such as "untrusted", "not private", "privacy error" or "unknown issuer/authority"). Telling your browser that you are aware of this might involve pressing buttons such as "I understand the Risks", "proceed to ... (unsafe)" or "Add exception". After installation this certificate can be changed to a normal one using the Let's Encrypt option.

   • 

   • 

6. The first time you access the FreedomBox web interface, you will see a welcome page. Click the "Start Setup" button to continue.

   • 

     If you have installed FreedomBox using a Debian package, you will be asked for a secret key. This secret was generated during the installation of the Debian package. It can be read from the file /var/lib/plinth/firstboot-wizard-secret.

7. The next page asks you to provide a user name and password. Fill in the form, and then click "Create Account."

   • Note: The user that you create here has Admin privileges and can also log in using ssh. For additional security, you may want to use a separate account for administrative tasks and for your normal, daily use. You can add more users later.

   • 

8. After completing the form, you will be logged in to FreedomBox's web interface and able to access apps and configuration through the interface.

   • 

Now you can try any of the Apps that are available on FreedomBox.

3. Finding your way around

3.1. Front page

The front page is the page that you will see when accessing the web root of your FreedomBox. You can also access it by clicking the FreedomBox logo in the top-left corner of the FreedomBox's web interface.

The front page includes shortcuts to apps that have been installed and are enabled. For web apps, clicking the shortcut will take you directly to the app's web page. For other services, clicking the shortcut will show more information about the service.

3.2. Apps menu

The Apps menu can be accessed by clicking the grid icon, next to the FreedomBox logo. This page lists all of the apps that are available for installing on FreedomBox. Click the name of an app to visit its page, where you can install and configure it.

3.3. Help menu

The Help menu can be accessed by clicking the question mark icon in the top-right corner. It includes helpful links and the FreedomBox manual.

3.4. System menu

The System menu can be accessed by clicking the gear icon in the top-left corner. It includes a number of pages related to system configuration.

3.5. User menu

In the top-right corner, the name of the currently logged-in user is shown. A drop-down menu includes options for editing the current user or logging out of the user interface.

3.6. Burger menu

FreedomBox's web interface is responsive. When the display or browser window is very narrow, menu options may be hidden.

That is because the top menu options are collapsed into the burger icon shown at the top right corner of the window. Click on it to display a drop-down menu.

Getting Help

The FreedomBox community provides live help via forum, chat and email. Feel free to join and ask anything you like. If you receive help, please consider to report your solution to the Questions and Answers page, so others can benefit in the future.

1. Discussion Forum

The easiest way to get support is by using the discussion forum. You can browse solutions to known problems or request help from community contributors by asking a question. This is also the best way to provide community contributors with feedback about your FreedomBox experience.

To post new content, you will need to register for an account with name and email address (but you can provide pseudonym and non-primary email address). By watching topics and categories or by enabling 'mailing list mode' in your account preferences, you can interact with the forum by just sending and receiving emails similar to a mailing list.

2. Matrix

You can join our Matrix room #freedombox:matrix.org. The room is federated with the IRC channel and remembers the chat history. If you do not yet have a client installed, you can use your web browser to join. For more options, see this matrix client overview page.

3. IRC #freedombox

Providing you are familiar with Internet Relay Chat (IRC) and IRC client, you can get an instant online help from the community on irc.debian.org, channel #freedombox. Potentially it takes some time before some member is answering you, be patient, a reaction will come later.

4. Email

FreedomBox users and contributors can be reached by email via a discussion list. In order to ask a question and get an answer from the community, please register from the mailing list page providing your email adress and creating a password. You can also read discussions archives. This list gathers about 700 readers.

5. Help Back

Once you've got your solution, don't forget to add it to the Questions and Answers page and tell which features do you use from the box on Use Cases page. It could help others to use FreedomBox in a way they would have not imagined.

Download and Install

Welcome to the FreedomBox download page.

• Note: If you purchased a FreedomBox kit, this section is not meant for you, so you can just skip it entirely. (Unless you specifically want to build an alternative software image).

You may either install FreedomBox on one of the supported inexpensive hardware devices, on any Debian operating system, or deploy it on a virtual machine.

Installing on a machine running a Debian system is easy because FreedomBox is available as a package. We do recommend to install FreedomBox on a supported single board computer (SBC). The board will be dedicated for FreedomBox use from home, this will prevent a lot of risks, such as accidental misconfiguration by the user. In case of trouble deciding which hardware is best for you or during the installation, please use the support page or read the Questions and Answers page based on posts on the Freedombox-discuss mailing list archives.

1. Downloading on Debian

If you are installing on an existing Debian installation, you don't need to download these images. Instead, read the instructions on setting up FreedomBox on Debian.

2. Downloading for SBC or Virtual Machine

2.1. Prepare your device

Read the hardware specific instructions on how to prepare your device at the Hardware section. On the web, there is a lot of documentation about setting your device up and flashing USB or SD Cards to boot your hardware.

2.2. Downloading Images

Recent images for supported targets are available here:

• Official Images: https://freedombox.org/download/

• Official Images: https://ftp.freedombox.org/pub/freedombox/

2.3. Verifying the Downloaded Images

It is important to verify the images you have downloaded to ensure that the file has not been corrupted during the transmission and that it is indeed the image built by FreedomBox developers.

Note: Testing and nightly images are automatically signed by the FreedomBox CI server.

• First open a terminal and import the public keys of the FreedomBox developers who built the images:

  $ gpg --keyserver keyserver.ubuntu.com --recv-keys BCBEBD57A11F70B23782BC5736C361440C9BC971
  $ gpg --keyserver keyserver.ubuntu.com --recv-keys 7D6ADB750F91085589484BE677C0C75E7B650808
  # This is the FreedomBox CI server's key
  $ gpg --keyserver keyserver.ubuntu.com --recv-keys 013D86D8BA32EAB4A6691BF85D4153D6FE188FC8

• Next, verify the fingerprint of the public keys:

  $ gpg --fingerprint BCBEBD57A11F70B23782BC5736C361440C9BC971
  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
  
  $ gpg --fingerprint 7D6ADB750F91085589484BE677C0C75E7B650808
  pub   4096R/7B650808 2015-06-07 [expires: 2020-06-05]
        Key fingerprint = 7D6A DB75 0F91 0855 8948  4BE6 77C0 C75E 7B65 0808
  uid                  James Valleroy <jvalleroy@mailbox.org>
  uid                  James Valleroy <jvalleroy@freedombox.org>
  sub   4096R/25D22BF4 2015-06-07 [expires: 2020-06-05]
  sub   4096R/DDA11207 2015-07-03 [expires: 2020-07-01]
  sub   2048R/2A624357 2015-12-22
  
  $ gpg --fingerprint 013D86D8BA32EAB4A6691BF85D4153D6FE188FC8
  pub   rsa4096 2018-06-06 [SC]
        013D 86D8 BA32 EAB4 A669  1BF8 5D41 53D6 FE18 8FC8
  uid           [ unknown] FreedomBox CI (Continuous Integration server) <admin@freedombox.org>
  sub   rsa4096 2018-06-06 [E]

• Finally, verify your downloaded image with its signature file .sig. For example:

  $ gpg --verify freedombox-stable-free_buster_cubietruck-armhf.img.xz.sig 
  gpg: assuming signed data in 'freedombox-stable-free_buster_cubietruck-armhf.img.xz'
  gpg: Signature made Sat 09 May 2020 11:54:01 AM EDT
  gpg:                using RSA key 013D86D8BA32EAB4A6691BF85D4153D6FE188FC8
  gpg: Good signature from "FreedomBox CI (Continuous Integration server) <admin@freedombox.org>" [undefined]
  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: 013D 86D8 BA32 EAB4 A669  1BF8 5D41 53D6 FE18 8FC8

2.4. Installation

After the download you can use the image to boot your chosen hardware (including virtual machines). You'll need to copy the image to the memory card or USB stick as follows:

1. Figure out which device your card actually is.
   1. Unplug your card.

   2. Run dmesg -w to show and follow the kernel messages.

   3. Plug your card in. You will see messages such as following:

      [33299.023096] usb 4-6: new high-speed USB device number 12 using ehci-pci
      [33299.157160] usb 4-6: New USB device found, idVendor=058f, idProduct=6361
      [33299.157162] usb 4-6: New USB device strings: Mfr=1, Product=2, SerialNumber=3
      [33299.157164] usb 4-6: Product: Mass Storage Device
      [33299.157165] usb 4-6: Manufacturer: Generic
      [33299.157167] usb 4-6: SerialNumber: XXXXXXXXXXXX
      [33299.157452] usb-storage 4-6:1.0: USB Mass Storage device detected
      [33299.157683] scsi host13: usb-storage 4-6:1.0
      [33300.155626] scsi 13:0:0:0: Direct-Access     Generic- Compact Flash    1.01 PQ: 0 ANSI: 0
      [33300.156223] scsi 13:0:0:1: Direct-Access     Multiple Flash Reader     1.05 PQ: 0 ANSI: 0
      [33300.157059] sd 13:0:0:0: Attached scsi generic sg4 type 0
      [33300.157462] sd 13:0:0:1: Attached scsi generic sg5 type 0
      [33300.462115] sd 13:0:0:1: [sdg] 30367744 512-byte logical blocks: (15.5 GB/14.4 GiB)
      [33300.464144] sd 13:0:0:1: [sdg] Write Protect is off
      [33300.464159] sd 13:0:0:1: [sdg] Mode Sense: 03 00 00 00
      [33300.465896] sd 13:0:0:1: [sdg] No Caching mode page found
      [33300.465912] sd 13:0:0:1: [sdg] Assuming drive cache: write through
      [33300.470489] sd 13:0:0:0: [sdf] Attached SCSI removable disk
      [33300.479493]  sdg: sdg1
      [33300.483566] sd 13:0:0:1: [sdg] Attached SCSI removable disk

   4. In the above case, the disk that is newly inserted is available as /dev/sdg. Very carefully note this and use it in the copying step below.

2. Decompress the downloaded image using tar:

   $ xz -d freedombox-stable-free_buster_cubietruck-armhf.img.xz

   The above command is an example for the cubietruck stable image. Your downloaded file name will be different.

3. Copy the image to your card. Double check to make sure you don't write to your computer's main storage (such as /dev/sda). Also make sure that you don't run this step as root to avoid potentially overriding data on your hard drive due to a mistake in identifying the device or errors while typing the command. USB disks and SD cards inserted into the system should typically be write accessible to normal users. If you don't have permission to write to your SD card as a user, you may need to run this command as root. In this case triple check everything before you run the command. Another safety precaution is to unplug all external disks except the SD card before running the command.

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

   $ dd bs=1M if=freedombox-stable-free_buster_cubietruck-armhf.img of=/dev/sdg conv=fdatasync status=progress

An alternative to copy to SD card command

• $ cat freedombox-stable-free_buster_cubietruck-armhf.img > /dev/sdg ; sync

On MS Windows you will need a tool like etcher. On MacOS (OSX) you can use programs like balenaetcher and rosaimagewriter.

• The above command is an example for the cubietruck stable image. Your image file name will be different.

  When picking a device, use the drive-letter destination, like /dev/sdg, not a numbered destination, like /dev/sdg1. The device without a number refers to the entire device, while the device with a number refers to a specific partition. We want to use the whole device. Downloaded images contain complete information about how many partitions there should be, their sizes and types. You don't have to format your SD card or create partitions. All the data on the SD card will be wiped off during the write process.

• Use the image by inserting the SD card or USB disk into the target device and booting from it. Your device should also be prepared (see the Hardware section).

• Read (the rest of) the Manual for instructions on how to use applications in FreedomBox.

2.5. Troubleshooting

• Can't boot off your MicroSD card (and/or disk utilities like GPartEd report a missing/corrupt partition table).

  • You likely forgot or failed to extract the .img file with xz -d before writing it to your device (e.g. /dev/sdg).

3. Obtaining Source Code

FreedomBox is fully free software and you can obtain the source code to study, modify and distribute improvements.

3.1. From within FreedomBox

FreedomBox is made up of several software programs and you can obtain the source code to any of them. These instructions are similar to obtaining and building source code for Debian since FreedomBox is a pure blend of Debian. Using this process you can obtain the source code to the exact version of the package you are currently using in FreedomBox.

1. To see the list of software packages installed on your FreedomBox, run the following in a terminal:

   dpkg -l

2. To obtain the source code for any of those programs, then run:

   apt source <package_name>

   This requires that the apt sources list contains information about the source code repositories. These are present by default on all FreedomBox images. If you have installed FreedomBox using a package from Debian, you need to ensure that source repositories are added in the file.

3. To build the package from source code, first install its dependencies

   apt build-dep <package_name>

   Switch to the source directory created by the apt source command:

   cd <source_directory>

   Then build the package

    dpkg-buildpackage -rfakeroot -uc

4. Install the package:

    dpkg -i ../<built_package>.deb

3.2. Other Ways to Obtain Source Code

1. Source code for any of the packages can be browsed and searched using the web interface at sources.debian.org. For example, see the plinth package.

2. Source code and pre-built binary package for any version of a package including historic versions can be obtained from snapshot.debian.org. For example, see the plinth package.

3. You can also obtain the links to upstream project homepage, upstream version control, Debian's version control, changelog, etc. from the Debian tracker page for a project at tracker.debian.org. For example, see the tracker page for plinth package.

4. You can build and install a package from its Debian's version control repository. For example,

    git clone https://salsa.debian.org/freedombox-team/freedombox.git
    cd freedombox
    apt build-dep .
    dpkg-buildpackage -rfakeroot -uc
    dpkg -i ../freedombox*.deb

3.3. Building Disk Images

You can also build FreedomBox disk images for various hardware platforms using the freedom-maker tool. This is also available as a Debian package and source code for it may be obtained using the above methods. Build instructions for creating disk images are available as part of the source code for freedom-maker package.

FreedomBox disk images are built and uploaded to official servers using automated Continuous Integration infrastructure. This infrastructure is available as source code too and provides accurate information on how FreedomBox images are built.

3.3.1. U-boot on Pioneer Edition Images

There is one minor exception to the u-boot package present on the hardware sold as FreedomBox Home Server Kits Pioneer Edition. It contains a small but important fix that is not part of Debian sources. The fork of the Debian u-boot source repository along with the minor change done by the FreedomBox is available as a separate repository. We expect this change to be available in upstream u-boot eventually and this repository will not be needed. This package can be built on a Debian armhf machine as follows (cross compiling is also possible, simply follow instructions for cross compiling Debian packages):

apt install git git-buildpackage
git clone https://salsa.debian.org/freedombox-team/u-boot.git
cd u-boot
pbuilder create --distribution=buster
gbp buildpackage --git-pbuilder

The u-boot Debian package will be available in u-boot-sunxi*.deb. This package will contain

mkdir temp
dpkg -x u-boot-suxi*.deb temp
unxz <lime2_image_built_with_freedom_maker>
dd if=temp/usr/lib/u-boot/A20-OLinuXino-Lime2/u-boot-sunxi-with-spl.bin of=<lime2.img> seek=8 bs=1k conv=notrunc

The resulting image will have the modified u-boot in it.

1. Bepasty (File & Snippet Sharing)

Available since: version 20.14

1.1. What is bepasty?

bepasty is a web application that allows large files to be uploaded and shared. Text and code snippets can also be pasted and shared. Text, image, audio, video and PDF documents can be previewed in the browser. Shared files can be set to expire after a time period.

1.2. Screenshot

1.3. Passwords and Permissions

bepasty uses only passwords (without usernames) to control access. Depending on which password is used to login to bepasty, the user will have different permissions. They can have any combination of the following permissions:

• read: Read a file, if they know the URL.

• list: List all files.

• create: Paste or upload a new file.

• delete: Delete a file.

• admin: Can lock and unlock files.

After bepasty is installed, it comes pre-configured for the following roles:

• Viewer: can view and list files
• Editor: can view, list, create, and delete files
• Administrator: has all permissions

These roles support a use-case of file sharing between known, authorized users. If needed, you can re-configure bepasty to support other roles and use-cases.

1.4. Distributing passwords

By default, the Public Access configuration is set to None, so a password is required for any use of bepasty. This means that you will need to distribute the passwords to the appropriate users, through any communication channels that you have.

Note that you may want to create multiple passwords with the same permissions. This allows you to distribute a unique password to each user (or to a group of users). Then if you want to revoke access to one user, you can simply delete their password. The other users with their own passwords will not be affected.

1.5. Using bepasty

After logging in to bepasty, if you have the Create permission, you will see a large text box where you can paste any text. Optionally, you can provide a filename or Content-Type for the data. After clicking Submit, the file is created.

You can also drag and drop files in the area at the bottom. They are uploaded immediate after dropping them in this area. You can also create a list to track a collection of uploaded files.

For either case, you can set a maximum lifetime value. After this time expires, the file will be deleted.

If you have the List permission, then you will see a link List all Items at the top of the page. This will show all files that have been created or uploaded.

If you have the Delete or Admin permission, you will see extra actions shown next to each file on the list page.

If you only have the Read permission, then to read files, you will need to have both a password and one or more URLs for existing files.

1.6. Managing passwords

The bepasty configuration page in FreedomBox interface allows you to create new passwords, or to remove a password. When you create a password, you can choose any combination of the permissions described above. Note that a typical Administrator should have all of the permissions (not just "Admin").

You can also set a Comment. This is recommended, and you should use the comment to help yourself remember the purpose of the password, or who will be using the password.

You can also configure Public Access, which sets the default permissions that are available even without logging in with a password. You can set this to allow reading files by their URL, or reading and listing all files.

1.7. External links

• Upstream project: https://github.com/bepasty

• User documentation: https://bepasty-server.readthedocs.io/en/latest/user.html

2. Calibre (e-Library)

Available since: version 20.15

calibre is an e-book management solution. You can organize your e-books into collections in calibre known as "libraries". calibre can do e-book format conversion between most of the popular e-book formats. It can also manage metadata of your e-books such as book covers, descriptions, author and publisher information etc.

Moving your calibre library from your desktop to your FreedomBox has the benefit of being able to access your e-books from any device on the local network or through the Internet.

Only users who are members of the calibre group have access to the libraries. You can assign users to this group via the system app users and groups.

You might be familiar with the e-book reader shipped with the calibre application on your desktop. The server version of calibre that's installed on your FreedomBox has a web-based e-book reader with similar look and feel. This allows you to read your e-books from any device with a web browser.

2.1. Managing Libraries

After installation of calibre, a default library called "Library" will be made available. The FreedomBox administrator can add or delete any of the libraries including the default one from the app settings in FreedomBox web interface.

2.2. Access

calibre can be accessed after installation through the web client at https://<my_freedombox_name>/calibre.

2.3. External links

• Official website: https://calibre-ebook.com

3. Coturn (VoIP Helper)

Available since: version 20.8

Coturn is a server to facilitate audio/video calls and conferences by providing an implementation of TURN and STUN protocols. WebRTC, SIP and other communication servers can use it to establish a call between parties who are otherwise unable connect to each other.

It is not meant to be used directly by users. Servers such as Matrix Synapse need to be configured with the details provided on the Coturn app page. Apart from Matrix Synapse, Jitsi, Ejabberd, Nextcloud Talk, etc. can use Coturn server for audio/video calls and conferences. There is no need for the servers to be running on the same machine as FreedomBox and external servers can use Coturn running on FreedomBox.

Coturn is configured in FreedomBox as an advanced app. This means that you need to check "Show advanced apps and features" in "General Configuration" to see Coturn icon in the "Apps" section.

3.1. How it works

When making an audio/video call, it is best to route the media streams between two peers directly. This will give the best possible latency (better signal quality) and avoid depending on a centralized server (privacy). It scales well because a simple chat server can host thousands of calls without involving the server in any way other than to setup the call. However, this approach does not work most of the time due to how networks are configured. Most peers on the network do not have a unique IP address allocated to them. They work hidden behind a network device that performs "Network Address Translation" (NAT) for them. This means that the two peers have no way of reaching each other.

To address this problem, a simple technique known as STUN was introduced. With the help of a third party STUN server, the peers can trick the NAT devices, to carry the traffic between the two peers. Unfortunately, this trick only works about 80% of the time. So, if STUN fails, peers have no choice but to route their traffic through an intermediary server called TURN server. All the mechanism of trying out STUN first and then falling back to TURN is described in a protocol known as ICE.

On FreedomBox, Coturn provides both STUN and TURN servers. Both services are provided over TCP as well as UDP. They are provided on unencrypted as well as encrypted channels (which have a higher chance of success). Since STUN servers are very inexpensive and don't consume a lot of server resources, there is no authentication needed to use them. TURN servers on the other hand need authentication. This authentication is highly simplified and does not require maintaining a database of users. A server such as matrix-synapse which is about to setup an audio/video call between two peers will generate a username and password using a shared secret. When the peers use the TURN server, they will be validated using these credentials because the TURN server also knows the same secret.

In summary, a communication server needs to know the URLs of the STUN/TURN servers along with a shared authentication secret for TURN. After that, during audio/video call setup, they will correctly guide the peers to use STUN/TURN servers. Coturn app in FreedomBox provides exactly this information. This information can be used to configure a communication server irrespective of whether it is running on the same FreedomBox or on another server.

3.2. Configuring Matrix Synapse

To configure Matrix Synapse to use Coturn TURN/STUN server, you need to check "Automatically manage audio/video call setup" in Matrix Synapse's configuration section, and then click on "Update seup".

3.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 Coturn:

• UDP 3478
• TCP 3478
• UDP 3479
• TCP 3479
• UDP 5349
• TCP 5349
• UDP 5350
• TCP 5350
• UDP 49152-50175
• TCP 49152-50175

3.4. External links

• Upstream project: https://github.com/coturn/coturn

4. Deluge (Distributed File Sharing via BitTorrent)

Available since: version 0.5

4.1. What is Deluge?

Deluge is a BitTorrent node (both, client and server at the same time).

BitTorrent is a communications protocol for peer-to-peer (P2P) file sharing.

• It is not anonymous; you should assume that others can see what files you are sharing.

• This technology works best for big, popular files.

There are two BitTorrent web nodes 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.

4.2. Screenshot

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

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.

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

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.

4.4. External links

• Upstream projects:

  • Deluge: https://www.deluge-torrent.org

  • BitTorrent: https://www.bittorrent.org

• Protocol description:

  • Upstream: https://www.bittorrent.org/introduction.html

  • At Wikipedia: https://en.wikipedia.org/wiki/BitTorrent

5. Ejabberd (Chat Server)

Available since: version 0.3

5.1. What is ejabberd?

Ejabberd is a chat server which uses the Extensible Messaging and Presence Protocol (XMPP).

5.2. What is XMPP?

XMPP is a federated server-client 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.

Currently FreedomBox offers both, a server (ejabberd) and a web client (JSXC) from its web interface.

5.3. Privacy

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.4. Setting the Domain Name

For XMPP to work, your FreedomBox needs to have a Domain Name that can be accessed over the network.

If you only need the local network (LAN) users to chat with each other you can invent your domain name, but if you want users from the internet to join your rooms you need a public domain name. 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.5. Registering FreedomBox users to use XMPP

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

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)

5.7. Compatible clients

• FreedomBox provides a web client: JSXC.

• XMPP clients are available for various desktop and mobile platforms. FreedomBox links to the download sources of some of them. Feel free to include more here (needs free registration). We'll notice and might list them in FreedomBox.

  

5.7.1. FreedomBox webclient

For maximum simplicity FreedomBox provides a web client: JSXC. No need for your users to install additional software on their side. They'll be able to just use their browser. This is usually the first choice for new and eventual users.

5.7.2. Mobile clients

You can download an XMPP client for your smartphone or tablet among the ones listed below.

5.7.2.1. Conversations (Android)

Conversations is an Android XMPP client with videochat support available on F-Droid or the Play Store. In addition to text messaging, you can use Conversations to send images and have group chats.

From left to right: (1) First screen - (2) Login screen - (3) Add contacts.

When first starting the Conversations app, you will be asked whether you want to create a new account or if you want to use an existing account. Choose "I already have an account" (1)

With ejabberd installed, the FreedomBox provides an XMPP account for every FreedomBox user. Additional (non-admin) FreedomBox user accounts can be created under System > Users and Groups.

Once logged into a FreedomBox/XMPP account (2), the Conversation app provides a + button that brings up a few choices to contact other people (3).

5.7.2.2. Movim (Android)

Movim is a free software XMPP client with videochat support for Android available on F-Droid.

5.7.2.3. ChatSecure (iOS)

ChatSecure is a free software XMPP client with videochat support available from the App Store.

5.7.2.4. Monal (iOS)

Monal is a free software XMPP client with videochat support available from the App Store.

5.7.2.5. Siskin (iOS)

Siskin is a free software XMPP client with videochat support available from the App Store.

5.7.3. Desktop clients

5.7.3.1. Gajim (Windows, MacOS, Linux)

Gajim is a XMPP open-source client for the desktop, available for Windows, MacOS and Linux. This application is available in Debian, and for other operating systems you can download it from this page and find instructions about installation.

From left to right: (1) First screen - (2) Login screen - (3) Main window

A popup shows up right after you start Gajim for the first time (1), asking you to either login to your XMPP (FreedomBox) account or to register for a new account. When you choose to login, after clicking "Forward", you will be asked a Jabber ID and a password (2): you have to enter your FreedomBox account and password here.

Finally, after logging in successfully, you will see the main Gajim screen (3). From there, you can add a contact (Account > Add contact...) then you can start a conversation (Gajim > Start chat).

5.7.3.2. Dino (Linux)

Dino is another XMPP free software client for the desktop. It is available for https://github.com/dino/dino/wiki/Distribution-Packages.

From left to right: (1) First screen - (2) Login screen - (3) Start conversation

When first starting Dino after installation, click on the Setup account button. You will be then asked your JID: this is your FreedomBox account. Enter it then click Next (2). Alternatively, you can click on Create account if you don't have a FreedomBox account.

Once you have logged in, you will be able to either start a conversation with one of your XMPP contacts or to join a channel (3).

5.7.3.3. Movim (Linux)

Movim is a free software XMPP client with videochat support for Linux. The project provides an unofficial Debian package.

5.7.3.4. Monal (MacOS)

Monal is a free software XMPP client with videochat support available from the Mac App Store.

5.8. External links

5.8.1. Ejabberd

• Website: https://www.ejabberd.im

• User documentation: https://docs.ejabberd.im

5.8.2. Clients' sites

• Conversations: https://conversations.im

• Gajim: https://gajim.org

• Dino: https://github.com/dino/dino

• Movim: https://movim.eu

• ChatSecure: https://chatsecure.org

• Monal: https://monal.im

• Siskin: https://siskin.im

5.8.3. XMPP Protocol

• Website: https://xmpp.org

• Summary at Wikipedia: https://en.wikipedia.org/wiki/XMPP

6. Postfix/Dovecot/Rspamd (Email Server)

Available since: 22.6

6.1. About the Email Server

FreedomBox provides a complete email server solution using Postfix, Dovecot, and Rspamd. Postfix sends and receives emails. Dovecot allows email clients to access your mailbox using IMAP and POP3. Rspamd deals with spam. The following features are available:

• Send and receive email
  • Interoperate with other mail servers
  • Prevent others from spoofing your email addresses using SPF
  • Sign all outgoing email using DKIM
  • Receive reports of spoofing attempts using DMARC
• Access mails easily

  • Access mail from any device using Roundcube webmail

  • Configure email clients by just typing in email address and password
  • Auto-configuration works with clients using autoconf scheme such as Thunderbird
  • Auto-configuration works with clients using DNS scheme
  • Keep mails on server and access them with multiple clients using IMAP
  • Fetch mails to local machine using POP3
• Email address for all your users

  • Each user on your FreedomBox automatically gets an email address such as user@mydomain.example

  • Each user gets unlimited automatic aliases. user+purpose@mydomain.example points to user@mydomain.example

  • Users may themselves add more aliases. foo@mydomain.example can point to user@mydomain.example

  • Many common aliases such as info@mydomain.example and postmaster@mydomain.example point to administrator's email address.

• Filter messages on the server using sieve filters
  • Setup vacation auto-responders that work even when you are not using your email client
  • Forward to external/internal addresses, file in folders, delete, etc.
  • Manage filters on the server using email client (for example, Thunderbird with sieve add-on)
• Automatically setup and configure TLS certificates obtained by Let's Encrypt

  • All services (SMTP, IMAP, POP3 and manageseive) are configured to use TLS/STARTTLS

  • Certificates are renewed every 3 months or so
  • Upon renewal, certificates are installed and services are restarted
• Backup and restore emails, aliases and configuration
  • Set a schedule for periodic backups
• Scan incoming email for spam
  • Check the message against various block lists
  • Automatically move spam to the Junk folder
  • Sets a flag on the message when spam score reaches a threshold
  • Rejects the message during receiving when spam score reaches a high threshold
  • Understand spam decisions using extended spam headers added to a message
  • View details of spam processing and manage settings using Rspamd web interface

  • Admins can login to spam web interface using FreedomBox single-sign-on

  • Teach spam vs. not-spam using example messages

6.2. Prerequisites

• You must own a domain on which you can configure advanced DNS records (MX, TXT and SRV). Such a domain can be obtained by buying one from a registrar or by obtaining a paid service from one of the Dynamic DNS providers (such as freedns.afraid.org). Currently, free subdomains provided by FreedomBox Foundation's free Dynamic DNS service at ddns.freedombox.org are not suitable. Support is planned in future.

• Your ISP or cloud provider, on your Internet connection, must not be blocking traffic to external mail servers. Quite a few of them block outgoing traffic on port 25. This will render the email server unable to send mails to external addresses. Many such providers allow you to request removing this restriction. To test whether this is a problem for your Internet connection, run the following command (you should see some text like this):

user@myserver:~$ nc freedombox.org 25
220 mx.sflc.info ESMTP Postfix (Debian/GNU)
^C

6.3. Installing

Go to the Apps menu.

If already installed, the Email Server will be shown above the Disabled line. This is likely not your case, but if it is, that means that the Email Server is already installed, so skip this step and jump to the next one.

If the Email Server is shown among the icons below the Disabled line, it is either not yet installed or it is currently disabled. This is the usual starting status.

Select the Postfix/Dovecot app. You are presented with the Postfix/Dovecot app page. If not installed yet you'll be shown the Install button. Click on it!

This will trigger the installation process.

After installing all needed software packages and configuring them, FreedomBox will tell you that the installation is successful and the app page will show additional content such as port information, configuration form and DNS settings.

Next time you go to the Apps Menu it will show the app enabled (above the disabled line).

6.4. Configuring the Email Server

1. If you wish to send email to and receive mails from users on other email servers on the Internet, you need a proper domain. As explained in the Prerequisites section, either buy a domain from a registrar or obtain one from a Dynamic DNS provider. If you purchased a domain from a registrar add it in the System, Configuration page. If it is a Dynamic DNS, configured it in System, Dynamic DNS Client page.

2. When a domain is added to FreedomBox, a TLS certificate is automatically obtained for the domain. This certificate is then used for encrypted communication with all the services that are configured with the domain. Go to System section, Let's Encrypt app page and verify that certificate has been successfully obtained for the domain. If not, click on the Obtain button and resolve any problems that show up. For successfully obtaining the certificate, your FreedomBox must be reachable from the Internet and your router, if any, must be configured to do port forwarding for the web ports (80, 443).

3. After adding a domain to FreedomBox, visit the Email app page. In the Configuration section, select the configured domain as the primary domain for the purposes of sending and receiving email.

4. After setting the primary domain, information will become available in the DNS Records section of the page. These are the records that must be manually configured on the domain. Login to your DNS provider's web interface for managing DNS records on your domain. There enter all the entries shown in the DNS records table.

   • The length of the value of DNS record for DKIM exceeds 255 characters in length. Typically, it must be broken into multiple values enclosed in the double quotes and separated by spaces. This is what FreedomBox does. If your DNS provider has a different way to enter these multiple values, consult their documentation.

   • All the records are assumed "under" the domain you are configuring but a full value can also be provided. For example, "Domain" value of "dkim._domainkey" means "dkim._domainkey.mydomain.example.". Use the latter form if necessary.

5. Install Roundcube app if you want to access emails using a web interface. In Roundcube configuration, be sure enable option to "Use only the local mail server". This removes the server field in the login page and makes the app work without any further configuration.

6.5. Using the Email Server

As a user you can:

• Start sending and getting emails using most email clients.

• Create and/or manage your email aliases in the Aliases tab of the Email Server app page in FreedomBox web interface.

• Manage filters on the server using sieve

Once an admin has set up RoundCube configuration for it to work with the FreedomBox Email server you can log into RoundCube and start sending emails without the need for other email clients. Use the same login credentials to RoundCube that you use to log into the FreedomBox web interface.

6.5.1. With FreedomBox Webmail Client (RoundCube)

RoundCube email client is provided by FreedomBox as an optional app. If RoundCube has been installed before the email server, there is an option to make it work with FreedomBox's email server. Once both apps are installed, you have a complete webmail setup ready.

6.5.2. With Thunderbird

Open Thunderbird. Go to hamburger menu → New → Existing Mail Account. Enter a display name, your FreedomBox email address, and your FreedomBox password. Click continue.

FreedomBox implements the Automatic Account Configuration endpoint which Thunderbird will make use of.

6.5.3. Manual Configuration

Tell your email client to use these parameters:

• Username: your FreedomBox email address or just the username part

• Incoming mail: IMAPS, port 993, forced SSL, normal password authentication

• Outgoing mail: SMTPS, port 465, forced SSL, normal password authentication

STARTTLS on the SMTP submission port is also supported.

6.5.4. Email Aliases

Email aliases are useful for privacy. Now as FreedomBox email user (you don't need to be an administrator) you can have temporary throw-away and specific email addresses under your control. You can list, create and delete email aliases from the My Email Aliases shortcut in FreedomBox home page.

Mails to non-existent users, non-existent aliases, or system users will be rejected at the SMTP connection level.

6.5.5. Automatic Email Aliases

In addition to allowing users to create their own aliases, FreedomBox also sets up automatic aliases by appending a string to your user name with a '+' sign. If your mail address is myname@mydomain.example, then all myname+anystring@mydomain.example is an automatic alias to your email address. For example, when subscribing to a mailing list call foolist, you can provide your email address as myname+foolist@mydomain.example. When mail is sent to that address, it ends up in your mailbox of myname@mydomain.example. This is primarily useful for mail sorting and spam control.

6.6. Advanced: Troubleshooting

6.6.1. How to debug an action script failure? How to access the system log?

Open a secure shell connection to your FreedomBox. Type sudo journalctl -b -o short-monotonic --no-pager

• -b show journal entries since boot

• -o short-monotonic use short timestamp format

• --no-pager make it easier to copy and paste

6.6.2. Why does the server say "relay access denied"?

This is because Postfix was not aware of the email domain. To fix that,

1. Ensure FreedomBox is aware of your internet domain name. If you don't have a domain name, skip to step 2.

   • Log into the FreedomBox web interface as an admin.

   • Go to System → Name Services

   • Add a domain name if you haven't done so.

6.6.3. Cannot send anything from Roundcube. It says "SMTP Error (250): Authentication failed".

Root cause: Roundcube tried to submit your email from an unencrypted connection, but ports 465 and 587 required SSL and STARTTLS encryption, respectively.

Solutions:

For RoundCube, edit the /etc/roundcube/config.inc.php file to make it use port 25 (unencrypted). Fix these settings:

$config['smtp_server'] = 'smtp://localhost';
$config['smtp_port'] = 25;

Notes:

• Access your FreedomBox via SSH.

• You can edit the file with nano text editor. The file is restricted, so you need to access it as superuser: sudo nano /etc/roundcube/config.inc.php.

If using another email client like Thunderbird, enforce SSL or STARTTLS usage by the email client.

6.7. Providing user feedback

Please provide your feedback on usage on this forum thread.

6.8. Technical info and discussion

FreedomBox email server was presented at Debconf21. Slides and video recording are available courtesy of the Debian Outreach team.

This salsa issue is driving the implementation. Feel free to join discussions and provide technical ideas.

6.9. External links

• Upstream websites:

  • http://www.postfix.org

  • https://www.dovecot.org

  • https://www.rspamd.com

7. GitWeb (Simple Git Hosting)

Available since: version 19.19

7.1. What is Git

Git is a distributed version-control system for tracking changes in source code during software development. GitWeb provides a web interface to Git repositories. You can browse history and content of source code, use search to find relevant commits and code. You can also clone repositories and upload code changes with a command-line Git client or with multiple available graphical clients. And you can share your code with people around the world.

To learn more on how to use Git visit Git tutorial.

7.2. Managing the repositories

After installation of GitWeb, a new repository can be created. It can be marked as private to limit access.

7.3. Access

GitWeb can be accessed after installation e.g. by the web client through https://<my_freedombox_name>/gitweb.

7.4. HTTP basic auth

GitWeb on FreedomBox currently supports HTTP(S) remotes only (i.e. not SSH). To avoid having to enter the password each time you pull/push to the repository, you can edit your remote to include the credentials.

Example: https://username:password@my.freedombox.rocks/gitweb/myrepo

Your username and password will be encrypted. Someone monitoring the network traffic will notice the domain name only.

Note: If using this method, your password will be stored in plain text in the local repository's .git/config file. For this reason, you should create a FreedomBox user who has only access to the gitweb and never use an admin account.

For GNOME users (Advanced)

GNOME "Passwords and Keys" utility can be used to store the username and password. See this StackOverflow Answer for details on how to do it.

7.5. Mirroring

Though your repositories are primarily hosted on your own FreedomBox, you can configure a repository on another Git hosting system like GitLab as a mirror.

7.6. Enabling/Disabling Features

In FreedomBox, some of the default features of gitweb have been changed:

• Enabled: Blame feature to show what revision and author last modified each line of a file
• Enabled: Pickaxe feature to list the commits that introduced or removed a given string
• Enabled: Highlight feature to perform syntax highlighting on blobs
• Disabled: Snapshot feature that provides a download of a compressed tar file for a given revision (due to high resource usage).

These features can be changed on a per-repository bases by an administrator by editing the git configuration file for the repository on FreedomBox. See manual page for gitweb.conf(5) for more details on syntax and features. For example, to re-enable the snapshot feature on myrepo repository, login to a FreedomBox terminal via SSH or web console as administrator and edit the file /var/lib/git/myrepo/config to contain the following section:

[gitweb]
snapshot = tgz

7.7. External links

• User documentation: https://git-scm.com/docs/gitweb

8. I2P (Anonymity Network)

8.1. About I2P

The Invisible Internet Project is an anonymous network layer intended to protect communication from censorship and surveillance. I2P provides anonymity by sending encrypted traffic through a volunteer-run network distributed around the world.

8.2. Services Offered

The following services are offered via I2P in FreedomBox by default. Additional services may be available when enabled from I2P router console that can be launched from FreedomBox web interface.

• Anonymous Internet browsing: I2P can be used to browse Internet anonymously. For this, configure your browser (preferable a Tor Browser) to connect to I2P proxy. This can be done by setting HTTP proxy and HTTPS proxy to freedombox.local (or your FreedomBox's local IP address) and ports to 4444 and 4445 respectively. This service is available only when you are reaching FreedomBox using local network (networks in internal zone) and not available when connecting to FreedomBox from the Internet. One exception to this is when you connect to FreedomBox's VPN service from Internet you can still use this service.

• Reaching eepsites: I2P network can host websites that can remain anonymous. These are called eepsites and end with .i2p in their domain name. For example, http://i2p-projekt.i2p/ is the website for I2P project in the I2P network. eepsites are not reachable using a regular browser via regular Internet connection. To browse eepsites, your browser needs to be configured to use HTTP, HTTPS proxies as described above. This service is available only when you are reaching FreedomBox using local network (networks in internal zone) and not available when connecting to FreedomBox from the Internet. One exception to this is when you connect to FreedomBox's VPN service from Internet you can still use this service.

• Anonymous torrent downloads: I2PSnark, an application for anonymously downloading and sharing files over the BitTorrent network is available in I2P and enabled by default in FreedomBox. This application is controlled via a web interface that can be launched from 'Anonymous torrents' section of I2P app in FreedomBox web interface or from the I2P router console interface. Only logged-in users belonging to 'Manage I2P application' group can use this service.

• IRC network: I2P network contains an IRC network called Irc2P. This network hosts the I2P project's official IRC channel among other channels. This service is enabled by default in FreedomBox. To use it, open your favourite IRC client. Then configure it to connect to host freedombox.local (or your FreedomBox's local IP address) with port number 6668. This service is available only when you are reaching FreedomBox using local network (networks in internal zone) and not available when connecting to FreedomBox from the Internet. One exception to this is when you connect to FreedomBox's VPN service from Internet you can still use this service.

• I2P router console: This is the central management interface for I2P. It shows the current status of I2P, bandwidth statistics and allows modifying various configuration settings. You can tune your participation in the I2P network and use/edit a list of your favourite I2P sites (eepsites). Only logged-in users belonging to 'Manage I2P application' group can use this service.

8.3. External links

• Upstream website: https://geti2p.net/en/

• User documentation: https://i2pd.readthedocs.io/en/latest/

9. Ikiwiki (Wiki and Blog)

Avaiable since: version 0.5

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

9.2. 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 FreedomBox. 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 Wiki or Blog" button.

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.

9.3. Accessing your wiki or blog

Your wikis and blogs are listed in the Ikiwiki app. Clicking on your site's name will bring you to its start page.

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.

9.4. 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 FreedomBox (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.

9.5. Adding FreedomBox users as wiki admins

1. Login to the site, using the admin account that was specified when the site 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. At the bottom of the page click "Save Setup".
6. Click "Preferences", then "Logout".
7. Login as the new admin user using "Login with HTTP auth".

9.6. Avoiding Spam

By default, every wiki page also has a "Discussion" page, which can be edited anonymously, without logging in. To avoid spam, you may want to disable the Discussion feature all together, by unchecking the "enable Discussion pages?" option in the setup.

9.7. Theming

1. Login to the site, using the admin account that was specified when the site was created.
2. Click "Preferences", then "Setup".
3. Under "web plugin: theme", check "enable theme?"
4. Right under the checkbox, type in the name of the desired theme. You can choose from the following officially supported themes:
   • actiontabs - mobile friendly
   • blueview - non-mobile friendly
   • goldtype - non-mobile friendly
   • monochrome - mobile friendly
5. At the bottom of the page click "Save Setup".

For your changes to become visible, you might have to delete your browser's cache or wait a few minutes and refresh your ikiwiki's page.

It is also possible to install user-contributed themes from ikiwiki's Theme Market. Please note, that this requires additional technical knowledge.

9.8. External links

• Website: https://ikiwiki.info

  • Theme Market https://ikiwiki.info/theme_market/

10. Infinoted (Collaborative text edition with Gobby)

Available since: version 0.5

infinoted is a server for Gobby, a collaborative text editor.

To use it, download Gobby, desktop client and install it. Then start Gobby and select "Connect to Server" and enter your FreedomBox's domain name.

10.1. 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 infinoted:

• TCP 6523

10.2. Extenal links

• Website: https://gobby.github.io/libinfinity

11. Janus (WebRTC server)

Available since version: 22.13

Janus is a lightweight, general purpose WebRTC server. It can support different kinds of real-time communication apps, such as video chat and streaming.

Currently, in FreedomBox, a simple video conference room is included with Janus. This video room can be accessed by anyone who visits your FreedomBox; it does not require logging in with a user account.

In the future, the simple video room app will be replaced by Jangouts, a fully-featured video conference app.

Coturn is required to use Janus, so it also needs to be installed and running on your FreedomBox.

11.1. Screenshot

11.2. Using Janus

The Janus shortcut will take you to the Janus Video Room page. From here, press the Start button at the top of the page.

Next, you will need to provide a display name. Any name can be used here. Press the "Join the room" button to enter the room.

The first time you enter the video room, your web browser will ask if this page has permission to access your camera and microphone. Press "Allow" to proceed.

Your own video will be displayed in the "Local Video" window. From here you can mute your audio, or use unpublish to stop sharing your video and audio. If other people join the video room, they will appear in the "Remote Video" windows.

11.3. External links

• Upstream project: https://janus.conf.meetecho.com

• Upstream end user documentation: https://janus.conf.meetecho.com/docs

12. JSXC (Web Chat Client)

Available since: version 0.11.0

JSXC is a web chat client. It can be used to join compatible chat servers.

FreedomBox offers both parties, a server (ejabberd) and a web client (JSXC), from its web interface.

12.1. Technical Specifications

JSXC features the XMPP over BOSH protocol and is implemented in HTML5.

XMPP is a federated server-client 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.

12.2. Installation

You can install JSXC through its icon in the Apps section of FreedomBox web interface. The ejabberd (XMPP server) icon also offers to launch the web client (and installs JSXC if not yet installed).

12.3. Usage

After the JSXC module install completes, the JSXC can be accessed through its icon in the Apps section of FreedomBox web interface. The ejabberd (XMPP server) icon also offers to launch the web client. Both will redirect you to https://<your freedombox>/plinth/apps/xmpp/jsxc/.

To use it, you need to input the domain name of the server to connect to. It will automatically check the BOSH server connection to the given domain name as you type it.

Videoconferencing and file transfer features are offered by JSXC but don't seem to work in FreedomBox yet.

12.4. Port Forwarding

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

• TCP 5222 (client-to-server)

12.5. External links

• Website: https://www.jsxc.org

• User documentation: https://www.jsxc.org/manual.html

13. Matrix Synapse (Chat Server)

Available since: version 0.14.0

13.1. What is Matrix?

Matrix is an open protocol for interoperable, decentralized, real-time communication over IP. Synapse is the reference implementation of a Matrix server. It can be used to setup instant messaging on FreedomBox to host chat rooms with end-to-end encrypted communication and audio/video calls. Matrix Synapse is a federated application where chat rooms can exist on any server and users from any server in the federated network can join them. Learn more about Matrix.

13.2. How to access your Matrix Synapse server?

We recommend the Element client to access the Matrix Synapse server. You can download Element for desktops. Mobile applications for Android and iOS are available from their respective app stores.

13.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 Matrix:

• TCP 8448

13.4. Setting up Matrix Synapse on your FreedomBox

To enable Matrix Synapse, first navigate to the Chat Server (Matrix Synapse) page and install it. Matrix needs a valid domain name to be configured. After installation, you will be asked to configure it. You will be able to select a domain from a drop down menu of available domains. Domains are configured using System -> Configure page. After configuring a domain, you will see that the service is running. The service will be accessible on the configured FreedomBox domain. Currently, you will not be able to change the domain once is it configured.

Your router has to be configured to forward port 8448.

All the registered users of your FreedomBox will have their Matrix IDs as @username:domain. If public registration is enabled, also your chosen client can be used to register a user account.

13.5. Setting up Audio/Video calls

The Matrix Synapse server is only responsible for establishing calls between participants in rooms. Matrix clients such as Element are actually responsible for the transfer of the audio/video traffic. Element supports calling in both one-to-one conversations and in groups.

For one-to-one conversations, Element tries to make a peer-to-peer connection between the two participants. This works when both the participants are using Element on computers with a public IP address or if they're on the same network. If both the participants are behind different NAT devices, establishing a direct peer-to-peer connection between them will not be possible. This problem can be solved by configuring Matrix Synapse with a STUN/TURN server. FreedomBox provides an app called Coturn for this purpose. FreedomBox doesn't automatically install Coturn on installing Matrix Synapse. However, as soon as Coturn app is installed, FreedomBox automatically configures Matrix Synapse to use it for audio/video calls. It is possible to override this configuration with a different STUN/TURN server in the web interface.

For calling groups with more than two participants (i.e. not one-on-one conversations), Element uses an external Jitsi Meet instance. Element uses jitsi.riot.im as its default Jitsi Meet instance. If the Matrix Synapse server is configured to use a different Jitsi Meet instance as the default, Element will use it instead for all users on that server.

13.6. Federating with other Matrix instances

You will be able to interact with any other person running another Matrix instance. This is done by simply starting a conversation with them using their matrix ID which is of the format @their-username:their-domain. You can also join rooms which are in another server and have audio/video calls with contacts on other server.

13.7. Memory usage

The Synapse reference server implemented in Python is known to be quite RAM hungry, especially when loading large rooms with thousands of members like #matrix:matrix.org. It is recommended to avoid joining such rooms if your FreedomBox device only has 1 GiB RAM or less. Rooms with up to a hundred members should be safe to join. The Matrix team is working on a new implementation of the Matrix server written in Go called Dendrite which might perform better in low-memory environments.

Some large public rooms in the Matrix network are also available as IRC channels (e.g. #freedombox:matrix.org is also available as #freedombox on irc.debian.org). It is better to use IRC instead of Matrix for such large rooms. You can join the IRC channels using Quassel.

13.8. Advanced usage

1. If you wish to create a large number of users on your Matrix Synapse server, use the following commands on a remote shell as root user:

   • cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1 | sed "s+^+registration_shared_secret: +" > /etc/matrix-synapse/conf.d/registration_shared_secret.yaml
     chmod 600 /etc/matrix-synapse/conf.d/registration_shared_secret.yaml
     chown matrix-synapse:nogroup /etc/matrix-synapse/conf.d/registration_shared_secret.yaml
     systemctl restart matrix-synapse
     register_new_matrix_user -c /etc/matrix-synapse/conf.d/registration_shared_secret.yaml

2. If you wish to see the list of users registered in Matrix Synapse, the following as root user:

   • apt install sqlite3
     echo 'select name from users' | sqlite3 /var/lib/matrix-synapse/homeserver.db  

3. If you wish to create a community in Matrix Synapse, a Matrix user with server admin privileges is needed. In order to grant such privileges to username run the following commands as root user:

   • sudo apt install sqlite3
     echo "UPDATE users SET admin=1 WHERE name='@username:domainname'" | sudo sqlite3 /var/lib/matrix-synapse/homeserver.db  

13.9. External links

• Matrix Website: https://matrix.org

• Synapse section:https://matrix.org/docs/projects/server/synapse

• User documentation: https://matrix.org/docs/guides

• Video tutorial for setting up Matrix Synapse on a Cloud instance: https://youtu.be/8snpMHHbymI

14. MediaWiki (Wiki)

Available since: version 0.20.0

14.1. About MediaWiki

MediaWiki is the software that powers the Wikimedia suite of wikis.

Read more about MediaWiki on Wikipedia

14.2. MediaWiki on FreedomBox

MediaWiki on FreedomBox is configured to be publicly readable and privately editable. Only logged in users can make edits to the wiki. This configuration prevents spam and vandalism on the wiki.

14.2.1. User management

Users can be created by the MediaWiki administrator (user "admin") only. The "admin" user can also be used to reset passwords of MediaWiki users. The administrator password, if forgotten can be reset anytime from the MediaWiki app page in web interface.

14.2.2. Use cases

MediaWiki is quite versatile and can be put to many creative uses. It also comes with a lot of plugins and themes and is highly customizable.

14.2.2.1. Personal Knowledge Repository

• MediaWiki on FreedomBox can be your own personal knowledge repository. Since MediaWiki has good multimedia support, you can write notes, store images, create checklists, store references and bookmarks etc. in an organized manner. You can store the knowledge of a lifetime in your MediaWiki instance.

14.2.2.2. Community Wiki

• A community of users can use MediaWiki as their common repository of knowledge and reference material. It can used as a college notice board, documentation server for a small company, common notebook for study groups or as a fan wiki like wikia.

14.2.2.3. Personal Wiki-based Website

• Several websites on the internet are simply MediaWiki instances. MediaWiki on FreedomBox is read-only to visitors. Hence, it can be adapted to serve as your personal website and/or blog. MediaWiki content is easy to export and can be later moved to use another blog engine.

14.2.3. Editing Wiki Content

The MediaWiki installation on FreedomBox ships with two kinds of editors - WikiText editor and !Visual editor.

14.2.3.1. WikiText Editor

• This editor is for editing the wiki directly in MediaWiki's markup language. It has a toolbar for common options like Bold, Italics etc. Click on the Advanced section for more options like Headings, bullet lists etc.

14.2.3.2. Visual Editor

• MediaWiki's VisualEditor extension provides a WYSIWYG interface to editing wiki pages. This extension is bundled with MediaWiki from 1.35 and is enabled by default from FreedomBox 21.9.

  Since this is essentially a rich-text editor, knowledge of MediaWiki's markup language is not required. To use advanced features not available in the VisualEditor (yet), switch back to source editing.

14.2.3.3. Other Formats

• You don't have to necessarily learn the MediaWiki formatting language. You can write in your favorite format (Markdown, Org-mode, LaTeX etc.) and convert it to the MediaWiki format using Pandoc.

14.2.3.4. Image Uploads

• Image uploads have been enabled since FreedomBox version 0.36.0. You can also directly use images from Wikimedia Commons using a feature called Instant Commons.

14.2.4. Customization

14.2.4.1. Skins

MediaWiki's default skin is usually Vector. The default skin set by FreedomBox is Timeless.

Vector is a skin best-suited for viewing on desktop browsers. It is not suitable for mobile screen sizes. Wikimedia sites host a separate mobile site. It is not worth hosting a separate mobile site for small MediaWiki installations like those on FreedomBox. Using a mobile-friendly skin like Timeless is a cheaper way of solving the problem.

Administrators can choose a default skin from the app configuration. Users of the site also have the choice of viewing it with a different skin.

14.3. External links

• Website: https://www.mediawiki.org/wiki/MediaWiki

15. Minetest (Block Sandbox)

Available since: version 0.9

Minetest is a multiplayer infinite-world block sandbox. This module enables the Minetest server to be run on this FreedomBox, on the default port (30000). To connect to the server, a Minetest client is needed.

15.1. 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 Minetest:

• UDP 30000

15.2. Install and enable mods

After SSHing into your FreedomBox server, install (unzip or git clone) mods in /var/games/minetest-server/.minetest/mods (for example, for the mobs_animal mod, you'd have the new /var/games/minetest-server/.minetest/mods/mobs_animal/ directory).

To enable a mod, first restart minetest:

sudo systemctl restart minetest-server.service

This will update the world config file, located in /var/games/minetest-server/.minetest/worlds/world/world.mt, with a line related to the added mod. Set that line from false to true in order to enable the new mod in your minetest instance. For example:

load_mod_mobs_animal = true

After that, save your changes, restart minetest one more time, then you should be all set.

15.3. External links

• Website: https://www.minetest.net

• Wiki: https://wiki.minetest.net

16. MiniDLNA (Simple Media Server)

Available since: version 19.23

MiniDLNA is a media server with the aim to be compliant with DLNA/UPnP clients.

Note: This service is available only on networks configured as "internal" zone. It is not available when connected via OpenVPN.

16.1. What is UPnP/DLNA?

Universal plug & play is a set of networking protocols that allow devices within a network such as PCs, TVs, printers etc. to seamlessly discover each other and establish communication for data sharing. It is zero configuration protocol and requires only a media server and a media player that are compliant with the protocol.

DLNA is derived from UPnP as a form of standardizing media interoperability. It forms a standard/certification which many consumer electronics conform to.

16.2. Setting up MiniDLNA on your FreedomBox

To install/enable the media server you need to navigate at MiniDLNA page and enable it. The application is intended to be available in the internal (home) network and therefore it requires a network interface configured for internal traffic.

After installation a web page becomes available on https://<your-freedombox>/_minidlna. It includes information for how many files the server is detecting, how many connections exist etc. This is very useful if plugging external disks with media to check if the new media files are detected properly. If that is not happening, disabling and enabling the server will fix it.

16.3. Using MiniDLNA to play media on your devices

Any DLNA compliant device or media player should be able to automatically detect, browse and play media from MiniDLNA on FreedomBox. The following devices and media players have been tested:

• GNOME Videos: Videos is the default media player on the popular GNU/Linux desktop environment GNOME. Open Videos, switch to 'Channels'. You should see a channel named 'freedombox: minidlna'. You will be able to browse and play media from it.

• VLC media player: VLC is a very popular media player for GNU/Linux, Android, Windows and macOS. Open VLC and click on 'View -> Playlist'. In the playlist sidebar that appears, select 'Universal Plug'n'Play'. You should see an item named 'freedombox: minidlna'. You should be able to browse and play media from it.

• Kodi: Kodi is a popular media centre software with user interface designed for Televisions. Open Kodi, goto 'System -> Service settings -> UPnP/DLNA' and 'Enable UPnP support'. Then visit 'Home -> Videos -> Files -> Add videos... -> Browse -> UPnP devices'. You should see 'freedombox: minidlna'. Select it and choose 'OK'. Then choose 'OK in the 'Add video source' dialog. From now on, you should see 'freedombox: minidlna' in 'Videos -> Files' section. You should be able to browse and play media from it. See Kodi documentation for more information.

• Roku: Roku is an appliance connected to a TV for playing Internet streaming services. Many TVs also have Roku built into them. In Roku interface, find a channel called 'Roku Media Player' and open it. You should see an item called 'freedombox: minidlna'. You should be able to browse and play media from it.

• Rhythmbox: Rhythmbox is the default audio player on the popular GNU/Linux desktop environment GNOME. Open Rhythmbox and ensure that the side pane is open by clicking on 'Application menu -> View -> Side Pane'. In the side pane you should see 'freedombox:minidlna' under the 'Shared' section. You should be able to browse and play audio files from it. Video files will not show up.

16.4. Supported media formats

MiniDLNA supports a wide variety of video and audio file formats.

• Video: Files ending with .avi, .mp4, .mkv, .mpg, .mpeg, .wmv, .m4v, .flv, .mov, .3gp, etc.

• Audio: Files ending with .mp3, .ogg, .flac, .wav, .pcm, .wma, .fla, .aac, etc.

• Image: Files ending with .jpg, .jpeg

• Playlist: Files ending with .m3u, .pls

• Captions: Files ending with .srt, .smi

Notably, it does not support the following file extensions. Renaming the file to a known extension seems to work in most cases.

• Video: Files ending with .webm

In addition to file format support from MiniDLNA, your media player or device needs to support the audio/video codecs with which the media has been encoded. MiniDLNA does not have the ability to translate files into a codec understood by the player. If you face problems with media playback, use the VLC player to find the codecs used in the media and the check your device or media player documentation on whether the codecs are supported.

16.5. File systems for external drives

If using an external drive that is used also from a Windows system the preferred filesystem should be NTFS. NTFS will keep Linux file permissions and UTF8 encoding for file names. This is useful if file names are in your language.

16.6. External links

• Upstream project site: http://minidlna.sourceforge.net

• About DLNA: https://en.wikipedia.org/wiki/Digital_Living_Network_Alliance

17. Mumble (Voice Chat) Server

Available since: version 0.5

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

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

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

17.4. Managing Permissions

A super user in Mumble has the ability to create administrator accounts who can in turn manage groups and channel permissions. This can be done after logging in with the username "SuperUser" using the super user password. See Mumble Guide for information on how to do this. The SuperUser password can be set through the FreedomBox interface.

17.5. External links

• Website: https://www.mumble.info

• User documentation: https://www.mumble.info/documentation

18. OpenVPN (Virtual Private Network)

Available since: version 0.7

18.1. What is OpenVPN?

OpenVPN provides to your FreedomBox a virtual private network service. You can use this software for remote access, site-to-site VPNs and Wi-Fi security. OpenVPN includes support for dynamic IP addresses and NAT.

18.2. 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 OpenVPN:

• UDP 1194

18.3. Setting up

1. In FreedomBox apps menu, select Virtual Private Network (OpenVPN) and click Install.

2. After the module is installed, there is an additional setup step that may take a long time to complete. Click "Start setup" to begin.

   

3. Wait for the setup to finish. This could take a while.

4. Once the setup of the OpenVPN server is complete, you can download your profile. This will download a file called <USER>.ovpn, where <USER> is the name of a FreedomBox user. Each FreedomBox user will be able to download a different profile. Users who are not administrators can download the profile from home page after login.

5. The ovpn file contains all the information a vpn client needs to connect to the server.

6. The downloaded profile contains the domain name of the FreedomBox that the client should connect to. This is picked up from the domain configured in 'Config' section of 'System' page. In case your domain is not configured properly, you may need to change this value after downloading the profile. If your OpenVPN client allows it, you can do this after importing the OpenVPN profile. Otherwise, you can edit the .ovpn profile file in a text editor and change the 'remote' line to contain the WAN IP address or hostname of your FreedomBox as follows.

   client
   remote mybox.freedombox.rocks 1194
   proto udp

18.4. Troubleshooting

If your network doesn't support IPv6, you might have to remove the following line from your OpenVPN client configuration. This is especially in cases where your server supports IPv6 but client does not thus confusing the OpenVPN client on which protocol to use.

proto udp6

To connect via IPv4, ensure that the following line is present.

proto udp

18.5. Browsing Internet after connecting to VPN

After connecting to the VPN, the client device will be able to browse the Internet without any further configuration. However, a pre-condition for this to work is that you need to have at least one Internet connected network interface which is part of the 'External' firewall zone. Use the networks configuration page to edit the firewall zone for the device's network interfaces.

18.6. Usage

18.6.1. On Android/LineageOS

1. Visit FreedomBox home page. Login with your user account. From home page, download the OpenVPN profile. The file will be named username.ovpn.

   • 

2. Download an OpenVPN client such as OpenVPN for Android. F-Droid repository is recommended. In the app, select import profile.

   • 

3. In the select profile dialog, choose the username.opvn file you have just downloaded. Provide a name for the connection and save the profile.

   • 

4. Newly created profile will show up. If necessary, edit the profile and set the domain name of your FreedomBox as the server address.

   • 

     

5. Connect by tapping on the profile.

   • 

     

6. When done, disconnect by tapping on the profile.

   • 

18.6.2. On Debian

Install an OpenVPN client for your system

$ sudo apt install openvpn

Open the ovpn file with the OpenVPN client.

$ sudo openvpn --config /path/to/<USER>.ovpn

If you use Network Manager, you can create a new connection by importing the file:

$ sudo apt install network-manager-openvpn-gnome
$ sudo nmcli connection import type openvpn file /path/to/<USER>.ovpn

If you get an error such as configuration error: invalid 1th argument to “proto” (line 5) then edit the .ovpn file and remove the line proto udp6.

18.7. Checking if you are connected

18.7.1. On Debian

1. Try to ping the FreedomBox or other devices on the local network.

2. Running the command ip addr should show a tun0 connection.

3. The command traceroute freedombox.org should show you the ip address of the VPN server as the first hop.

18.8. Accessing internal services

After connecting to OpenVPN, you will be able to access FreedomBox services that are only meant to be accessed on internal networks. This is in addition to being able to access external services. This can be done by using the IP address 10.91.0.1 as the host name for these services (for example, use smb://10.91.0.1 instead of smb://freedombox.local to access Samba shares).

The following services are known to work:

• Privoxy,

• Tor Socks,

• Shadowsocks,

• I2P Proxy and

• Samba.

Some services are known not to work at this time:

• Avahi,

• bind and

• MiniDLNA.

18.9. External Links

• Wiki / Tracker: https://community.openvpn.net/openvpn

19. Privoxy (Web Proxy)

Available since: version 0.1

A web proxy acts as a filter for incoming and outgoing web 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).

19.1. Screencast

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

19.2. Setting up

1. In FreedomBox, install Web Proxy (Privoxy)

   

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.

   

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.

19.3. Advanced Users

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.

1. Plan first:

   • While using Privoxy, you can see its configuration details and documentation at http://config.privoxy.org/ or http://p.p.

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

   • Read carefully the manual, especially this security warning:

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

2. Only when you are ready, perform the changes:

   1. To enable changing these configurations, you first have to change the value of enable-edit-actions in /etc/privoxy/config to 1.

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

19.4. External links

• Website: https://www.privoxy.org

• User manual: https://www.privoxy.org/user-manual/index.html

20. Quassel (Text Chat Client via IRC)

Available since: version 0.8

Quassel is an IRC application that is split into two parts, a "core" and a "client". This allows the core to remain connected to IRC servers, and to continue receiving messages, even when the client is disconnected. FreedomBox can run the Quassel core service keeping you always online and one or more Quassel clients from a desktop or a mobile device can be used to connect and disconnect from it.

20.1. Why run Quassel?

Many discussions about FreedomBox are being done on the IRC-Channel irc://irc.debian.org/freedombox. If your FreedomBox is running Quassel, it will collect all discussions while you are away, such as responses to your questions. Remember, the FreedomBox project is a worldwide project with people from nearly every time zone. You use your client to connect to the Quassel core to read and respond whenever you have time and are available.

20.2. How to setup Quassel?

• Within FreedomBox's web interface

  1. select Applications

  2. go to IRC Client (Quassel) and

  3. install the application and make sure it is enabled

     

  4. now your Quassel core is running

20.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 Quassel:

• TCP 4242
• Example configuration in router:

  • 

20.4. Clients

Clients to connect to Quassel from your desktop and mobile devices are available.

20.4.1. Desktop

In a Debian system, you can e.g. use quassel-client. The following steps describe how to connect Quassel Client with Quassel Core running on a FreedomBox. The first time you do this connection, Quassel Core will be initialized too.

1. Launch Quassel Client. You will be greeted with a wizard to Connect to Core.

   • 

2. Click the Add button to launch Add Core Account dialog.

   • 

3. Fill any value in the Account Name field. Fill proper DNS hostname of your FreedomBox in Hostname filed. Port field must have the value 4242. Provide the username and password of the account you wish to create to connect to the Quassel Core in the User and Password fields. Choose Remember if don't wish to be prompted for a password every time you launch Quassel client.

4. After pressing OK in the Add Core Account dialog, you should see the core account in the Connect to Core dialog.

   • 

5. Select the newly created core account and select OK to connect to it.

6. If this is the first time you are connecting to this core. You will see an Untrusted Security Certificate warning and need to accept the server certificate.

   • 

7. Select Continue. Then you will be asked if you wish to accept the certificate permanently. Select Forever.

   • 

8. If this Quassel Core has not been connected to before, you will then see a Core Configuration Wizard. Select Next.

   • 

9. In the Create Admin User page, enter the username and password you have used earlier to create the core connection. Select Remember password to remember this password for future sessions. Click Next.

   • 

10. In the Select Storage Backend page, select SQLite and click Commit.

    • 

11. The core configuration is then complete and you will see a Quassel IRC wizard to configure your IRC connections. Click Next.

    • 

12. In Setup Identity page next, provide a name and multiple nicknames. This is how you present yourself to other users on IRC. It is not necessary to give your real world name. Multiple nicknames are useful as fallback nicknames when the first nickname can't be used for some reason. After providing the information click Next.

    • 

13. In Setup Network Connection page next, provide a network name of your choice. Next provide a list of servers to which Quassel Core should connect to in order to join this IRC network (such as irc.debian.org:6667).

    • 

14. Select the server in the servers list and click Edit. In the Server Info dialog, set the port 6697 (consult your network's documentation for actual list of servers and their secure ports) and click Use SSL. Click OK. This is to ensure that communication between your FreedomBox and the IRC network server is encrypted.

    • 

15. Back in the Setup Network Connection dialog, provide a list of IRC channels (such as #freedombox) to join upon connecting to the network. Click Save & Connect.

    • 

16. You should connect to the network and see the list of channels you have joined on the All Chats pane on the left of the Quassel Client main window.

    • 

17. Select a channel and start seeing messages from others in the channel and send your own messages.

20.4.2. Android

For Android devices you may use e.g. Quasseldroid from F-Droid

• enter core, username etc. as above

  • 

By the way, the German verb quasseln means talking a lot, to jabber.

20.5. External links

• Website: https://quassel-irc.org

• Wiki: https://bugs.quassel-irc.org/projects/quassel-irc/wiki

21. Radicale (Calendar and Addressbook)

Available since: version 0.9

With Radicale, you can synchronize your personal calendars, ToDo lists, and addressbooks with your various computers, tablets, and smartphones, and share them with friends, without letting third parties know your personal schedule or contacts.

21.1. Why should I run Radicale?

Using Radicale, you can get rid of centralized services like Google Calendar or Apple Calendar (iCloud) data mining your events and social connections.

21.2. How to setup Radicale?

First, the Radicale server needs to be activated on your box.

• Within FreedomBox Service:

  1. select Apps

  2. go to Radicale (Calendar and Addressbook) and

  3. install the application. After the installation is complete, make sure the application is marked "enabled" in the FreedomBox interface. Enabling the application launches the Radicale CalDAV/CardDAV server.

  4. define the access rights:
     • Only the owner of a calendar/addressbook can view or make changes
     • Any user can view any calendar/addressbook, but only the owner can make changes
     • Any user can view or make changes to any calendar/addressbook

Note, that only users with a FreedomBox login can access Radicale.

If you want to share a calendar with only some users, the simplest approach is to create an additional user-name for these users and to share that user-name and password with them.

Radicale provides a basic web interface, which only supports creating new calendars and addressbooks. To add events or contacts, an external supported client application is needed.

• Creating addressbook/calendar using the web interface

  • Visit https://IP-address-or-domain-for-your-server/radicale/

  • Log in with your FreedomBox account

  • Select "Create new addressbook or calendar"
  • Provide a title and select the type
  • Optionally, provide a description or select a color
  • Click "Create"
  • The page will show the URL for your newly created addressbook or calendar

Now open your client application to create new calendar and address books that will use your FreedomBox and Radicale server. The Radicale website provides an overview of supported clients, but do not use the URLs described there; FreedomBox uses another setup, follow this manual. Below are the steps for two examples:

• Example of setup with Evolution client:
  • Calendar
    1. Create a new calendar
    2. For "Type," select "CalDAV"
    3. When "CalDAV" is selected, additional options will appear in the dialogue window.

    4. URL: https://IP-address-or-domain-for-your-server. Items in italics need to be changed to match your settings.

    5. Enable "Use a secure connection."

    6. User: USERNAME. Your Freedombox user-name.

    7. Click on "Find Calendars"
    8. Enter your password and select a calendar

       

  • TODO/Tasks list: Adding a TODO/Tasks list is basically the same as a calendar.
  • Contacts
    • Follow the same steps described above and replace CalDAV with WebDAV.

21.3. Synchronizing over Tor

In FreedomBox, setting up a calendar with Radicale over Tor is the same as over the clear net. Here is a short summary:

1. When logged in to FreedomBox interface over Tor, click on Radicale, and at the prompt provide your FreedomBox user name and password.

2. In the Radicale web interface, log in using your FreedomBox user name and password.

3. Click on "Create new address book or calendar", provide a title, select a type, and click "Create".

4. Save the URL, e.g., https://ONION-ADDRESS-FOR-YOUR-SERVER.onion/radicale/USERNAME/CALENDAR-CODE/. Items in italics need to be changed to match your settings.

These instructions are for Thunderbird/Lightning. Note that you will need to be connected to Tor with the Tor Browser Bundle.

1. Open Thunderbird, install the Torbirdy add-on, and restart Thunderbird. (This may not be necessary.)
2. In the Lightning interface, under Calendar/Home in the left panel right click with the mouse and select "New calendar".
3. Select the location of your calendar as "On the Network".

4. Select CalDAV and for the location copy the URL, e.g., https://ONION-ADDRESS-FOR-YOUR-SERVER.onion/radicale/USERNAME/CALENDAR-CODE/. Items in italics need to be changed to match your settings.

5. Provide a name, etc. Click "Next". Your calendar is now syncing with your FreedomBox over Tor.

6. If you have not generated a certificate for your FreedomBox with "Let's Encrypt", you may need to select "Confirm Security Exception" when prompted.

21.4. Synchronizing with your Android phone

There are various Apps that allow integration with the Radicale server. This example uses DAVx5, which is available e.g. on F-Droid. If you intend to use ToDo-Lists as well, the compatible app OpenTasks has to be installed first.

Follow these steps for setting up your account with the Radicale server running on your FreedomBox.

1. Install DAVx5
2. Create a new account on DAVx5 by clicking on the floating + button.

3. Select the second option as shown in the first figure below and enter the base url as https://<your.freedombox.address>/radicale/username/ (don't miss the / at the end). DAVx5 will be able to discover both CalDAV and WebDAV accounts for the user.

4. Follow this video from DAVx5 FAQ to learn how to migrate your existing contacts to Radicale.

Synchronizing contacts

1. Click on the hamburger menus of CalDAV and CardDAV and select either "Refresh ..." in case of existing accounts or "Create ..." in case of new accounts (see the second screenshot below).
2. Check the checkboxes for the address books and calendars you want to synchronize and click on the sync button in the header. (see the third screenshot below)

21.5. Advanced Users

21.5.1. Sharing resources

Above was shown an easy way to create a resource for a group of people by creating a dedicated account for all. Here will be described an alternative method where two users User1 and User2 are granted access to a calendar. This requires SSH-access to the FreedomBox.

1. create a file /etc/radicale/rights

   • [friends_calendar]
     user: ^(User1|User2)$
     collection: ^.*/calendar_of_my_friends.ics$
     permission: rw
     
     # Give write access to owners
     [owner-write]
     user: .+
     collection: ^%(login)s/.+$
     permission: rw

   • [friends_calendar] is just an identifier, can be any name.

   • The [owner-write] section makes sure that owners have access to their own files

2. edit file /etc/radicale/config and make the following changes in section [rights]

   • [rights]
     type = from_file
     file = /etc/radicale/rights

3. Restart the radicale server or the FreedomBox

21.5.2. Importing files

If you are using a contacts file exported from another service or application, it should be copied to: /var/lib/radicale/collections/user/contact file name.vcf.

21.6. External links

• Website: https://radicale.org/3.0.html

22. Roundcube (Email Client)

Available since: version 0.5

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

22.2. Using Roundcube

After Roundcube is installed, it can be accessed at https://<your freedombox>/roundcube. Enter your username and password. The username for many mail services will be the full email address such as exampleuser@example.org and not just the username like exampleuser. Enter the address of your email service's IMAP server address in the Server field. You can try providing your domain name here such as example.org for email address exampleuser@example.org and if this does not work, consult your email provider's documentation for the address of the IMAP server. Using encrypted connection to your IMAP server is strongly recommended. To do this, prepend 'imaps://' at the beginning of your IMAP server address. For example, imaps://imap.example.org.

22.3. Using Gmail with Roundcube

If you wish to use Roundcube with your Gmail account, you need to first enable support for password based login in your Google account preferences. This is because Gmail won't allow applications to login with a password by default. To do this, visit Google Account preferences and enable Less Secure Apps. After this, login to Roundcube by providing your Gmail address as Username, your password and in the server field use imaps://imap.gmail.com.

22.4. External links

• Website: https://roundcube.net

23. RSS Bridge (RSS Feed Generator)

Available since: version 22.16

23.1. What is RSS Bridge?

RSS-Bridge is a web application capable of generating RSS and Atom feeds for websites that don't have one. For example, with the help of RSS Bridge you can subscribe to YouTube channels without having to have a YouTube account.

23.2. Usage Example

23.2.1. Subscribing to a YouTube account

In this example, we will see one of the ways to subscribe to a given YouTube channel.

1. Visit the YouTube channel and copy its name to the clipboard

2. Find "YouTube Bridge" and click on show more

3. Paste the previously copied channel name in the Custom name section and click on Generate Feed

4. From the available feed types select Atom. If you're using a Chromium based browser, this will open the Atom feed in a new tab, which you can easily copy into your feed Reader, such as Tiny Tiny RSS

23.2.2. Subscribing to feed with Tiny Tiny RSS

1. Copy the URL that RSS Bridge generated

2. In Tiny Tiny RSS select Subscribe to feed from the drop-down menu on the right side.

3. Paste the generated link from step one into the textbox and select This feed requires authentication.

4. Submit your FreedomBox username and password and click on Subscribe

For a more detailed description of Tiny Tiny RSS, see its manual page

23.3. External links

• Website: https://rss-bridge.github.io/rss-bridge/

• User documentation: https://rss-bridge.github.io/rss-bridge/General/Project_goals.html

24. Samba (Network File Storage)

Available since: version 19.22

Samba lets you have shared folders over the local network that can be used from multiple computers running different operating systems. We refer to these shared folders as "shares".

You can have a personal folder shared between your own devices (Home share), a folder shared with a trusted group (Group share) or one that is shared with every device on the network (Open share).

Samba lets you to treat a share as if it's a local folder on your computer. However, shares are available only on the local network.

To learn more about Samba, please refer to the user documentation on their wiki.

24.1. Using Samba

After installation, you can choose which disks to use for sharing. Enabled shares are accessible in the file manager on your computer at location \\freedombox (on Windows) or smb://freedombox.local (on Linux and Mac). There are three types of shares you can choose from:

Open share - accessible to everyone in your local network.
Group share - accessible only to FreedomBox users who are in the freedombox-share group.
Home share - every user in the freedombox-share group can have their own private space.

24.1.1. Connecting from an Android device

To access Samba shares on an Android device, install "Android Samba Client" from F-Droid or Google Play. Enter smb://freedombox.local/<disk> as the share path in the app. Your shared folders should then be visible in the file manager app. Samba shares can also be used by VLC for Android which automatically discovers them.

24.1.2. Connecting from a macOS device

• Open a Finder window on your Mac.

• Use Go -> Connect to Server... from the file menu or press the shortcut Cmd+K to open the Connect To Server dialog.

• Enter the address of your Samba share, e.g. smb://192.168.0.105/disk and click Connect.

24.2. Integration with other apps

Transmission app on FreedomBox provides a setting to allow downloads to be saved directly to a Samba share.

If you want to make available files synchronized with Syncthing through Samba you need to make sure you synchronize in a Samba share folder. Additionally in order to make Syncthing shares available in Samba Open share or Group share you will need to ensure you click "Permissions > Ignore" button under the "Advanced" tab in folder you wish in the Syncthing web UI. This will ensure that the files will be writable through Samba.

24.3. Comparison with other apps

24.3.1. Syncthing

Syncthing maintains a copy of the shared folder on each device that it is shared with. Samba maintains only one copy on your FreedomBox device.

Syncthing can synchronize your shared folders between devices over the Internet. Samba shares are only available on the local network.

Since Syncthing is primarily a synchronization solution, it has features like conflict resolution and versioning. Samba has only copy of the file, so it doesn't need such features. For example, if two people are editing a spreadsheet stored on a Samba share, the last one to save the file wins.

24.4. External links

• Website: https://www.samba.org

• User documentation: https://www.samba.org/samba/docs

25. Searx (Web Search)

Available since: version 0.24.0

25.1. About Searx

Searx is a metasearch engine. A metasearch engine aggregates the results from various search engines and presents them in a unified interface.

Read more about Searx on their official website.

25.2. Screenshot

25.3. Screencast

Searx installation and first steps (14 MB)

25.4. Why use Searx?

25.4.1. Personalization and Filter Bubbles

Search engines have the ability to profile users and serve results most relevant to them, putting people into filter bubbles, thus distorting people's view of the world. Search engines have a financial incentive to serve interesting advertisements to their users, increasing their chances of clicking on the advertisements.

A metasearch engine is a possible solution to this problem, as it aggregates results from multiple search engines thus bypassing personalization attempts by search engines.

Searx avoids storing cookies from search engines as a means of preventing tracking and profiling by search engines.

25.4.2. Advertisement filtering

Searx filters out advertisements from the search results before serving the results, thus increasing relevance the of your search results and saving you from distractions.

25.4.3. Privacy

Searx uses HTTP POST instead of GET by default to send your search queries to the search engines, so that anyone snooping your traffic wouldn't be able to read your queries. The search queries wouldn't stored in browser history either.

Note: Searx used from Chrome browser's omnibar would make GET requests instead of POST.

25.5. Searx on FreedomBox

• Searx on FreedomBox uses Single Sign On. This means that you should be logged in into your FreedomBox in the browser that you're using Searx.

• SearX is easily accessible via Tor.

• Searx can be added as a search engine to the Firefox browser's search bar. See Firefox Help on this topic. Once Searx is added, you can also set it as your default search engine.

• Searx also offers search results in csv, json and rss formats, which can be used with scripts to automate some tasks.

25.6. External links

• Website: https://searx.me

• User documentation: https://searx.github.io/searx/user/index.html

26. Shaarli (Bookmarks)

Available since: version 21.15

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

26.2. External links

• Usage documentation: https://shaarli.readthedocs.io/en/master/Usage/

27. Shadowsocks (Bypass Censorship)

Available since: version 0.18.0

27.1. What is Shadowsocks?

Shadowsocks is a tool for securely forwarding network requests to a remote server. It consists of two parts: (1) a Shadowsocks server, and (2) a Shadowsocks client with a SOCKS5 proxy.

Shadowsocks can be used to bypass Internet filtering and censorship. This requires that the Shadowsocks server is in a location where it can freely access the Internet, without filtering.

Your FreedomBox can run a Shadowsocks client which can connect to a Shadowsocks server. It will also run a SOCKS5 proxy. Local devices can connect to this proxy, and their data will be encrypted and proxied through the Shadowsocks server.

Alternatively, your FreedomBox can run a Shadowsocks server, that allows Shadowsocks clients to connect to it. Clients' data will be encrypted and proxied through this server.

27.2. Using Shadowsocks?

Shadowsocks can be used as follows:

• Shadowsocks Client (a FreedomBox) is in a region where some parts of the Internet are blocked or censored.

• Shadowsocks Server (a different FreedomBox, or another server) is in a different region, which doesn't have these blocks.

• The FreedomBox running Shadowsocks Client provides SOCKS proxy service on the local network for other devices to make use of its Shadowsocks connection to the server.

27.3. Configuring your FreedomBox for Shadowsocks Client

To enable Shadowsocks Client, first navigate to the Shadowsocks Client (Bypass Censorship) page, and install it.

Server: the Shadowsocks server is not this FreedomBox's IP or URL; rather, it will be another server or VPS that has been configured as a Shadowsocks server. There are also some public Shadowsocks servers listed on the web, but be aware that whoever operates the server can see where requests are going, and any non-encrypted data will be visible to them.

To use Shadowsocks Client after setup, set the SOCKS5 proxy URL in your device, browser or application to http://freedombox_address:1080/

27.4. Configuring your FreedomBox for Shadowsocks Server

To enable Shadowsocks Server, first navigate to the Shadowsocks Server (Help Others Bypass Censorship) page, and install it.

Note: In general, a FreedomBox should be set up as either a Shadowsocks Server, or a Shadowsocks Client, but not both!

For Shadowsocks Clients to connect to your server, they will need to know your domain name, the password, and the encryption method.

27.4.1. 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 Shadowsocks Server:

• TCP 8388
• UDP 8388

27.5. External links

• Website: https://shadowsocks.org/

28. Sharing (File Publishing)

Available since: version 0.25

28.1. What Is Sharing App?

Sharing app allows you to share content over the web. Shared content can be individual files or whole directories.

The content can be shared publicly or restricted to the users of listed allowed groups. Allowed users will be able to access the shared content from their web browser at https://your_freedombox/share/content_name. Users not belonging to any of the allowed groups won't see or access the content through this mechanism.

28.2. Setting Up Shares

For the users to access the content through their browser it must exist and have a share. A share is an entry in the Sharing app relating:

• the Name (an thereby the URL) with which the users will ask for the content,
• the Disk Path of the content to be served and
• the sharing mode. On restricted mode, it also has the list of allowed groups.

Many shares can coexist in the same server.

Only admins can create, edit or remove shares. They'll find the Sharing app in the Apps section of FreedomBox web interface. Sharing app is an easy to use web application with an evident interface.

Each share has its own sharing mode (public or restricted) setting. Only groups recognized by FreedomBox service can be combined in the list of allowed groups. Groups created in the CLI won't be offered by the Sharing app.

28.3. Providing/Updating Content

The content can be created before or after the share is created and they can be updated independently.

The content doesn't need to be provided by an admin either. Any user with write access to the share's disk path can create or update it.

Multiple shares might point to the same content.

If you are user of FreedomBox and your admin refuses to create shares for you, and you don't need to restrict the access to your content, you still can fall back to the User Websites mechanism or the P2P networks (Deluge or Transmission for Torrent) to publish your files.

28.4. Technicalities

Sharing will share the content using the built-in Apache web server.

29. Syncthing (File Synchronization)

Available since: version 0.14

With Syncthing installed on your FreedomBox, you can synchronize content from other devices to your FreedomBox and vice-versa. For example, you can keep the photos taken on your mobile phone synchronized to your FreedomBox.

Users should keep in mind that Syncthing is a peer-to-peer synchronization solution, not a client-server one. This means that the FreedomBox isn't really the server and your other devices clients. They're all devices from Syncthing's perspective. You can use Syncthing to synchronize your files between any of your devices. The advantage that FreedomBox provides is that it is a server that's always running. Suppose you want your photos on your phone to be synchronized to your laptop, if you simply sync the photos to the FreedomBox, the laptop can get them from the FreedomBox whenever it comes online the next time. You don't have to be worried about your other devices being online for synchronization. If your FreedomBox is one of the devices set up with your Syncthing shared folder, you can rest assured that your other devices will eventually get the latest files once they come online.

After installation follow the instructions in the getting started of the Syncthing project. Syncthing allows individual folders to be selectively shared with other devices. Devices must be paired up before sharing by scanning QR codes or entering the device ids manually. Syncthing has a discovery service for easily identifying the other devices on the same network having Syncthing installed.

In order to access to the web client of the Syncthing instance running on your FreedomBox, use the path /syncthing. This web client is currently only accessible to the users of the FreedomBox that have administrator privileges, though it might be accessible to all FreedomBox users in a future release.

Syncthing has android apps available on the F-Droid and Google Play app stores. Cross-platform desktop apps are also available.

To learn more about Syncthing, please visit their official website and documentation.

29.1. Synchronizing over Tor

Syncthing should automatically sync with your FreedomBox even if it is only accessible as a Tor Onion Service.

If you would like to proxy your Syncthing client over Tor, set the all_proxy environment variable:

$ all_proxy=socks5://localhost:9050 syncthing

For more information, see the Syncthing documentation on using proxies.

29.2. Avoiding Syncthing Relays

Syncthing uses dynamic connections by default to connect with other peers. This means that if you are synchronizing over the Internet, the data might have to go through public Syncthing relays to reach your devices. This doesn't take advantage of the fact that your FreedomBox has a public IP address.

When adding your FreedomBox as a device in other Syncthing clients, set the address like "tcp://<my.freedombox.domain>" instead of "dynamic". This allows your Syncthing peers to directly connect to your FreedomBox avoiding the need for relays. It also allows for fast on-demand syncing if you don't want to keep Syncthing running all the time on your mobile devices.

29.3. Using Syncthing with other applications

29.3.1. Password Manager

Password managers that store their databases in files are suitable for synchronization using Syncthing. The following example describes using a free password manager called KeePassXC in combination with Syncthing to serve as a replacement for proprietary password managers that store your passwords in the cloud.

KeePassXC stores usernames, passwords etc. in files have the .kdbx extension. These kdbx files can be stored in a Syncthing shared folder to keep them synchronized on multiple machines. Free software applications which can read this file format are available for both desktop and mobile. You typically have to just point the application at the .kdbx file and enter the master password to access your stored credentials. For example, the same kdbx file can be accessed by using KeePassXC on desktop and KeePassDX on Android. KeePassXC can also be used to fill credentials into login fields in the browser by installing a browser extension.

29.4. External links

• Website: https://syncthing.net

• User documentation: https://docs.syncthing.net

30. Tiny Tiny RSS (News Feed Reader)

Available since: version 0.9

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

Any user created through FreedomBox web interface will be able to login and use this app. Each user has their own feeds, state and preferences.

30.1. Using the Web Interface

When enabled, Tiny Tiny RSS will be available from /tt-rss path on the web server. Any user created through FreedomBox will be able to login and use this app.

30.1.1. Adding a new feed

1. Go to the website you want the RSS feed for and copy the RSS/Atom feed link from it.

2. Select "Subscribe to feed.." from the Actions dropdown.

3. In the dialog box that appears, paste the URL for copied in step 1 and click the Subscribe button.

Give the application a minute to fetch the feeds after clicking Subscribe.

In some websites, the RSS feeds button isn't clearly visible. In that case, you can simply paste the website URL into the Subscribe dialog (step 3) and let TT-RSS automatically detect the RSS feeds on the page.

You can try this now with the homepage of WikiNews

As you can see in the image below, TT-RSS detected and added the Atom feed of WikiNews to our list of feeds.

If you don't want to keep this feed, right click on the feed shown in the above image, select Edit feed and click Unsubscribe in the dialog box that appears.

30.1.2. Importing your feeds from another feed reader

In your existing feed reader, find an option to Export your feeds to a file. Prefer the OPML file format if you have to choose between multiple formats. Let's say your exported feeds file is called Subscriptions.opml

Click on the Actions menu at the top left corner and select Preferences. You will be taken to another page.

Select the second tab called Feeds in the top header. Feeds has several sections. The second one is called OPML. Select it.

To import your Subscriptions.opml file into TT-RSS,

1. Click Browse and select the file from your file system

2. Click Import my OPML

After importing, you'll be taken to the Feeds section that's above the OPML section in the page. You can see that the feeds from your earlier feed reader are now imported into Tiny Tiny RSS. You can now start using Tiny Tiny RSS as your primary feed reader.

In the next section, we will discuss setting up the mobile app, which can let you read your feeds on the go.

30.2. Using the Mobile App

The official Android app from the Tiny Tiny RSS project works with FreedomBox's Tiny Tiny RSS Server. The older TTRSS-Reader application is known not to work.

To configure, first install the application, then in the setting page, set URL as https://<your.freedombox.address>/tt-rss-app/. Set your user name and password in the Login details as well as HTTP Authentication details. If your FreedomBox does not have a valid HTTPS certificate, then in settings request allowing any SSL certificate and any host.

30.3. RSS Bridge

RSS Bridge can be used with Tiny Tiny RSS to generate Atom/RSS links for websites that don't provide one.

30.4. External links

• Website: https://tt-rss.org

31. Tor (Anonymity Network)

Available since: version 0.3

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

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

31.3. Using Tor Onion Service to access your FreedomBox

Tor Onion Service provides a way to access your FreedomBox, even if it's behind a router, firewall, or carrier-grade NAT (i.e., your Internet Service Provider does not provide a public IPv4 address for your router).

To enable Tor Onion 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 Onion 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 Onion 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.)

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

31.4. Apps accessible via Tor

The following apps can be accessed over Tor. Note that this list is not exhaustive.

• Calendar and Addressbook (Radicale)

• File Synchronization (Syncthing)

• Feed reader (TinyTinyRSS)

• Web Search (Searx)

• Wiki (MediaWiki)

• Wiki and Blog (Ikiwiki)

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

At the bottom of the Tor page in FreedomBox, 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.

The requirements to run a relay are listed in the Tor Relay Guide. In short, it is

• recommended that a relay has at least 16 Mbit/s (Mbps) upload and download bandwidth available for Tor. More is better.
• required that a Tor relay be allowed to use a minimum of 100 GByte of outbound and of incoming traffic per month.

• recommended that a <40 Mbit/s non-exit relay should have at least 512 MB of RAM available; A relay faster than 40 Mbit/s should have at least 1 GB of RAM.

31.6. (Advanced) Usage as a SOCKS proxy

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.

31.6.1. Example with Firefox

Your web browser can be configured to use the Tor network for all of your browsing activity. This allows for censorship circumvention and also hides your IP address from websites during regular browsing. For anonymity, using tor browser is recommended.

Configure your local FreedomBox IP address and port 9050 as a SOCKS v5 proxy in Firefox. There are extensions to allow for easily turning the proxy on and off.

With the SOCKS proxy configured, you can now access any onion URL directly from Firefox. FreedomBox itself has an onion v3 address that you can connect to over the Tor network (bookmark this for use in emergency situations).

31.7. Circumventing Tor censorship

If your ISP is trying to block Tor traffic, you can use tor bridge relays to connect to the tor network.

1. Get the bridge configuration from the Tor BridgeDB

2. Add the lines to your FreedomBox Tor configuration as show below.

31.8. External links

• Website: https://www.torproject.org

• User documentation: https://2019.www.torproject.org/docs/documentation.html.en

32. Transmission (Distributed File Sharing via BitTorrent)

Available since: version 0.5

32.1. What is Transmission ?

Transmission is a BitTorrent node (both, client and server at the same time).

BitTorrent is a communications protocol for peer-to-peer (P2P) file sharing.

• It is not anonymous; you should assume that others can see what files you are sharing.

• This technology works best for big, popular files.

There are two BitTorrent web nodes 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".

32.2. Screenshot

32.3. Using Transmission

After installing Transmission, it can be accessed at https://<your freedombox>/transmission. Transmission uses single sign-on from FreedomBox, which means that if you are logged in on your FreedomBox, you can directly access Transmission without having to enter the credentials again. Otherwise, you will be prompted to login first and then redirected to the Transmission app.

32.4. Tips

32.4.1. Transferring Downloads from the FreedomBox

1. Transmission's downloads directory can be added as a shared folder in the Sharing app. You can then access your downloads from this shared folder using a web browser.

2. (Advanced) If you have the ssh access to your FreedomBox, you can use sftp or scp to browse the downloads directory using a suitable file manager or web browser:

   • Dolphin or Konqueror, if you access from a KDE desktop

   • The Other locations option in the default file manager, if you're on Gnome

   • WinSCP or FileZilla, if you're on Windows

   • Ghost Commander or Spider, if you're on Android.

32.5. Port Forwarding

If your FreedomBox is behind a router you optionally might want to set up port forwarding on your router in order to improve communication with other peers. You should forward the following ports for Transmission:

• TCP 51413 (or your configured peer listening port)

32.6. Using Remote Apps

In addition to using the web interface to control Transmission on FreedomBox, desktop and mobile apps may also be used. List of tested clients and their platforms are listed on the app page in FreedomBox web interface. When configuring these clients the URL to connect must be /transmission-remote/rpc and the port must be 443.

32.7. External Links

• Upstream projects:

  • Transmission: https://transmissionbt.com

  • BitTorrent: https://www.bittorrent.org

• Protocol description:

  • Upstream: https://www.bittorrent.org/introduction.html

  • At Wikipedia: https://en.wikipedia.org/wiki/BitTorrent

33. User Websites

Available since: version 0.9.4

33.1. What is User Websites?

User websites is a standard location for webservers to allow host users to expose static files on the filesystem as a website to the local network and/or the internet according to the network and firewall setup.

The standard webserver in FreedomBox is Apache and this is implemented by means of a specific Apache module.

33.2. Screenshot

Add when/if an interface is made for FreedomBox

33.3. Using User Websites

The module is always enabled and offers no configuration from the FreedomBox web interface. There is no configuration or status page shown for this module in the FreedomBox web interface.

To serve documents, place the files in the designated directory in a FreedomBox user's home directory in the filesystem.

This directory is: public_html

Thus the absolute path for the directory of a user named fbx with home directory in /home/fbx will be /home/fbx/public_html. User websites will serve documents placed in this directory when requests for documents with the URI path "~fbx" are received. For the the example.org domain thus a request for the document example.org/~fbx/index.html will transfer the file in /home/fbx/public_html/index.html.

33.4. Creating public_html folder and uploading documents

33.4.1. Visually from Linux

Linux standard desktop file managers use to support remote filesystem access through SFTP out of the box. Among others, Gnome's Nautilus, KDE/Plasma's Dolphin and XFCE's Thunar do so. This standarization allows for very easy, similar and straightforward procedures:

1. Connect with the file manager to your FreedomBox:

   • Gnome's Nautilus:
     1. To lauch Nautilus you can seek its archive icon, or search ether its name or the word "file".
     2. At the bottom of the left pane you'll find an option "+ Other locations".

     3. It leads you to a list of locations. Find "freedombox SFTP server" (english literal for all desktop languages). Click on it.

     4. The first time you'll be asked for your user and password. Enter your FreedomBox user and its password. The dialog will also offer you some options to remember it for some time.

   • Plasma file manager AKA Dolphin:
     1. Click on the location bar at the top of the window.

     2. Input ftp://freedombox.local

     3. The first time you'll be asked for your user and password. Enter your FreedomBox user and its password. The dialog will also offer you some option to remember it.

   • XFCE's Thunar:

     1. Type this into the browser bar: sftp://username@freedombox.local, replacing the 'username' placeholder with your actual FreedomBox username.

     2. I guess the first time you'll be asked for your password. Enter your FreedomBox user's password.

2. You should be shown FreedomBox filesystem. Enter the home folder and then enter you user's subfolder.

3. If there's no public_html folder, create it: right mouse button click, etc.

4. Drag your file(s) and drop it/'em into the public_html folder.

5. You should now be able to navigate your browser to the corresponding url and see the files.

33.4.2. Visually from Other Plattforms

If you want to use graphical free software clients, install:

• FileZilla or WinSCP for Windows.

• FileZilla for Mac.

• Spider or Ghost Commander, available in F-Droid application repository for Android.

Their usage will be similar to that described for Linux desktops.

Describe how to use privative plattfor-native remote location connectivity?

33.4.3. With a Command Line Interface (CLI)

Usually any Unix system, including Linux in all (most) of its flavours and Mac, provide the standard utilities ssh, scp and sftp. FreeDOS provides SSH2DOS. No need to install anything. It's already there!

Examples:

Connect to FreedomBox via SSH:

1. (replacing username with a valid FreedomBox user name and freedombox.local with your FreedomBox's domain name or IP):

   $ ssh username@freedombox.local

2. If your data is ok and your FreedomBox reachable, the first time you'll be asked to confirm its signature.

3. Then you'll be asked for the password of your FreedomBox user.

4. Then you'll be shown the welcome banner with the FreedomBox's buttefly logo in ASCII art (painted with characters).

5. The prompt changes to username@freedombox:~$.

Once connected create your website folder with:

• username@freedombox:~$ mkdir ~/public_html

...or one for another user:

1. use the sudo prefix like

   username@freedombox:~$ sudo mkdir /home/<the_other_user>/public_html

   , and introduce your password.

2. When you create a folder, by default it belongs to you no matter where it is created. Thus you'll then need to set its ownership to the other user:

   username@freedombox:~$ sudo chown <the_other_user>:<the_other_user> /home/<the_other_user>/public_htm

3. Better check it before you disconnect that `public_html' is listed among the contents of the other user's home folder.

   username@freedombox:~$ ls -l /home/<the_other_user>
   ...
   drwxr-xr-x  2 <the_other_user> <the_other_user>   4096 jan 29 17:39  public_html
   ...

   . The name of the other user must appear twice in the public_html line and its permissions should be drwxr-xr-x.

Then any user can upload their files to their respective folders with any of the graphical clients. Ask them to check it.

It is a good security practice to exit instead of to just wait for the connection to time out:

• username@freedombox:~$ exit

If then you want to also upload the web content through the command line you can

$ scp path/to/files username@freedombox.local:public_html/

. It will ask your password in FreedomBox. You should then be able to navigate your browser to the corresponding url and see the files.

Learn more about ssh, scp and sftp with $ man ssh, $ man scp and $ man sftp.

33.5. External Links

• Upstream project website: https://httpd.apache.org/docs/2.4/mod/mod_userdir.html

• User documentation: https://httpd.apache.org/docs/2.4/howto/public_html.html

34. WireGuard (Virtual Private Network)

34.1. About WireGuard

WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It can be a useful replacement for IPSec or OpenVPN.

34.2. Installation

You can install wireguard from the Apps section of the FreedomBox web interface.

34.3. Usage

• Point-to-point tunnel
• VPN client with default route

34.4. Configuration - Debian Peers

Note: These steps are handled automatically on FreedomBox. So you only need to follow these steps on any Debian clients that will connect to FreedomBox, or Debian servers that FreedomBox will connect to.

• Step 1 - Generating Keypairs

• Step 2 - Alternative A - Manual Configuration

34.5. Configuration - Mobile Clients

WireGuard has a user space implementation for mobile devices available via the WireGuard app - available for Android and iOS (a full list of supported operating systems is available here).

The client can be configured in several ways:

34.5.1. Alternative A - Create configuration manually

This is self-explanatory, you actually create the config on the mobile device then transfer the relevant keys to the server's config.

34.5.2. Alternative B - Create configuration from archive

Here you have to create a .zip archive of the client configuration file, transfer it to the device then import it into the app.

34.5.3. Alternative C - Import by reading a QR code (most secure method)

The mobile client as of version 0.0.20180724 supports QR code based input.

qrencode can be used to generate qr codes, even in a terminal/console using UTF8 characters.

The syntax is:

# qrencode -t ansiutf8 < client.conf

This will generate a QR code that is readable by the mobile client.

The advantage of this approach is that there is no need to transfer sensitive information via data channels that can potentially be compromised and there is no need for any additional software.

34.6. External Links

• Website: https://www.wireguard.com

35. WordPress (Website and Blog)

Available since: version 21.7

35.1. What is WordPress?

WordPress is a popular way to create and manage websites and blogs. It is a content management system that allows editing content using a visual web-based interface. No knowledge of HTML or other markup is needed to create websites. Complete layout and functionality of the web pages can be customized. Appearance can be chosen using themes. Administration interface and produced web pages are suitable for mobile devices.

35.2. Setting up WordPress on FreedomBox

To setup WordPress, navigate to the WordPress (Website and Blog) page and install it. WordPress needs a valid domain name to be configured. Before proceeding further, setup a proper domain name. Domains are configured using System -> Configure page. Access your FreedomBox web interface using the domain you have configured. After this, visit the WordPress web interface. This will show a setup page asking for the name of the site and details for a new administrator account. After this step, WordPress is fully configured and ready. You can then return to the FreedomBox's WordPress app page and optionally make the WordPress installation available to public.

35.3. Public Access

In the WordPress app page in FreedomBox, the app can be made publicly available. It is, by default, not publicly available. It is only available to users who login as administrators in FreedomBox interface. This is to protect the initial setup process from becoming publicly available. If the setup process is publicly available, any visitor will be able to create themselves an administrator account which is undesirable. Administrators must take care not to enable public access until WordPress' setup process has been completed.

35.4. Users

At the moment, WordPress has its own user accounts that are unrelated to FreedomBox accounts. The first account created during the setup process is an administrator account. After logging in with the administrator account, separate accounts for viewing, publishing, or administering may be created from within WordPress interface.

Changes to content and configuration of WordPress can only be done after logging into WordPress. However, by default, there is no link from the website or blog to reach the login page. Bookmark or directly type into the browser https://<mydomainname>/wordpress/wp-admin/ to reach administration interface.

35.5. WordPress as Home Page

A beautiful, well customized WordPress website can be set as the home page for your FreedomBox. This can be done in System -> Configure page of the FreedomBox web interface. For example, if your FreedomBox's domain name is myfreedombox.rocks and you set WordPress as the home page, visiting https://myfreedombox.rocks will take you to https://myfreedombox.rocks/wordpress/ instead of the FreedomBox interface.

35.6. Domain Name

When WordPress is setup for the first time, the domain name through which you access it is noted and WordPress gets configured with that domain name. Be sure to setup your domain name properly and access the WordPress setup process using the domain name and not a local IP address or domain name. Currently, FreedomBox does not provide an easy way to change the domain name once the app is installed.

35.7. Permalinks

By default, web addresses for newly created blog posts and pages look like /wordpress/?p=1. They can be made to look prettier like /wordpress/2021/08/06/sample-post/ instead. This can be done from the Settings -> Permalinks configuration page in WordPress interface. The necessary web server configuration changes are handled by FreedomBox during app installation.

35.8. Automatic Upgrades

Similar to all other apps, feature and security upgrades for WordPress are automatically handled by FreedomBox (when not disabled). After a minor version upgrade, changes to the database structure are automatically done by WordPress. However, after a major version upgrade, such as during major distribution upgrade every two years, database changes are not done automatically. For this, you need to login to WordPress and trigger the changes manually.

35.9. Plugins and Themes

WordPress in itself is quite powerful and sufficient to create and manage a simple website or blog. It's true power, however, lies in the thousands of plugins and themes. Plugins extend the functionality of WordPress. For example, a contact form can be added to WordPress by installing the appropriate plugin. Themes change the appearance and layout of the site. Installing a new theme will provide an extra administration option for how your site will appear to your visitors. Care must be taken to choose trustworthy plugins and themes that respect software freedom and privacy of users and visitors of the site.

From FreedomBox version 22.13, you can install plugins and themes directly from the WordPress GUI.

35.9.1. Google Fonts Privacy Issue

Please be aware that many of the third-party themes use Google Fonts which will violate your visitors' privacy.

One way to remove Google Fonts from your WordPress site is to remove the respective code lines from your theme's source code under Appearance >> Theme Editor. Please note these changes may be overwritten by the theme's next update.

35.9.2. Failing Updates

Manual update of the default theme and plugin, namely Twenty Twenty-One and Akismet Anti-Spam will fail, since these updates are managed separately by Debian. You do not have to worry about their updating.

35.9.3. Note for FreedomBox between version 21.7 and 22.12

Since there are few plugins/themes packaged for Debian, FreedomBox does not provide a simple way to install and manage them. You need to install them manually. This can be done as follows:

1. Note the URL of the plugin or theme to download by browsing them from WordPress administration interface or the official website. Be sure to select trustworthy ones with a free software license.

2. Log in via SSH using a FreedomBox administrator account.

3. Download the plugin or theme and unpack into a directory using the command line.

4. Move the directory under /var/lib/wordpress/wp-content/plugins/ or /var/lib/wordpress/wp-content/themes/ as appropriate.

5. Watch for upgrades to these plugins from WordPress and repeat the process for installing newer versions.

35.10. External links

• WordPress website: https://wordpress.org

• Discover WordPress plugins: https://wordpress.org/plugins/

• Explore WordPress themes: https://wordpress.org/themes/

• WordPress documentation: https://wordpress.org/support/

• Google Fonts: https://en.wikipedia.org/wiki/Google_Fonts

36. Zoph (Photo manager)

Available since: version 21.3 (and Debian 11, Bullseye)

36.1. What is Zoph?

Zoph is a web based photo manager, allowing uploads of photos to the FreedomBox server, where they can be organised into Albums, and associated with Locations, People and Categories. An individual photo can be in multiple albums, and Albums, Categories and Locations are hierarchical.

Zoph supports multiple users, and has a permissions system to control which Albums users can see, or create, whether they can see or create People etc.

For FreedomBox the username within Zoph must match the FreedomBox username so Single Sign On will work.

36.2. Using Zoph

After Zoph is installed, you'll need to click "Setup". Then you can launch the web client. It can also be accessed at https://<your freedombox>/zoph.

Only the very first time you'll be asked for user and password. The next times you'll be taken straight to a welcome screen.

The tab menu will be shown on top of every page. From there you can import photos from any computer, administer Zoph to add other users etc.

You can now go to the 'prefs' tab and set your preferences, for numbers of rows and columns in results displays, how much information you wish displayed about the camera used to take the photo and so on.

You can add information about People who are in your Photos.

36.2.1. Choosing a storage location for your photos

Your photos will need a lot of storage space compared to the other uses of your FreedomBox. You may want to put them onto an external disk. You can (not yet) specify in the initial install screen where your photos should be stored. The database which holds information about albums, people etc is held in your normal FreedomBox storage.

36.3. External links

• Website: http://www.zoph.org

1. Backups

FreedomBox includes the ability to backup and restore data, preferences, configuration and secrets from most of the applications. The Backups feature is built using Borg backup software. Borg is a deduplicating and compressing backup program. It is designed for efficient and secure backups. This backups feature can be used to selectively backup and restore data on an app-by-app basis. Backed up data can be stored on the FreedomBox machine itself or on a remote server. Any remote server providing SSH access can be used as a backup storage repository for FreedomBox backups. Data stored remotely may be encrypted and in such cases remote server cannot access your decrypted data.

1.1. Notes for Specific App Backups

Unless otherwise noted here, backup of an app's data will include its configuration, secrets and other data.

1.2. How to install and use Backups

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

Step 7

1.3. External links

• Upstream project: https://www.borgbackup.org

• User documentation: https://borgbackup.readthedocs.io/en/stable/

2. BIND (Domain Name Server)

BIND enables you to publish your Domain Name System (DNS) information on the Internet, and to resolve DNS queries for your user devices on your network.

Currently, on FreedomBox, BIND is only used to resolve DNS queries for other machines on local network. It is also incompatible with sharing Internet connection from FreedomBox.

Note: This service is available only on networks configured as "internal" zone. It is not available when connected via OpenVPN.

2.1. Using BIND

When BIND is enabled, that does not automatically mean that anything is using it. The following can be configured:

• FreedomBox can be configured to use the local BIND service for its own DNS lookups.

• Clients on the Local Area Network can be configured to use the FreedomBox's BIND service for their DNS lookups.

The FreedomBox can be set to use its own BIND service for DNS lookups through Networks:

1. Go to System page, and then select Networks.

2. Select the "FreedomBox WAN" connection and press Edit.

3. Under "IPv4 Addressing Method", there is a field "DNS Server". Set it to 127.0.0.1.

   • TODO: Add IPv6 instructions.

4. Press "Edit Connection" at the bottom to save the changes.

5. Restart the FreedomBox from the user drop-down menu.

TODO: Add instructions for serving clients on LAN.

2.2. External links

• Upstream project: https://www.isc.org/bind/

3. Cockpit (Server Administration)

Cockpit is a server manager that makes it easy to administer GNU/Linux servers via a web browser. On a FreedomBox, controls are available for many advanced functions that are not usually required. A web based terminal for console operations is also available.

It can be accessed by any user on your FreedomBox belonging to the admin group. Cockpit is only usable when you have proper domain name setup for your FreedomBox and you use that domain name to access Cockpit. See the Troubleshooting section for more information.

3.1. Using Cockpit

Install Cockpit like any other application on FreedomBox. Make sure that Cockpit is enabled after that.

Ensure that the user account on FreedomBox that will used for Cockpit is part of the administrators group.

Launch the Cockpit web interface. Login using the configured user account. Be sure to check the box to "reuse my password for privileged tasks", otherwise you will not be able to perform various tasks such as configuring raid, or editing users, once logged in.

Start using cockpit.

Cockpit is usable on mobile interfaces too.

3.2. Features

The following features of Cockpit may be useful for advanced FreedomBox users.

3.2.1. System Dashboard

Cockpit has a system dashboard that

• Shows detailed hardware information
• Shows basic performance metrics of a system
• Allows changing system time and timezone

• Allows changing hostname. Please use FreedomBox UI to do this

• Shows SSH server fingerprints

3.2.2. Viewing System Logs

Cockpit allows querying system logs and examining them in full detail.

3.2.3. Managing Storage

Cockpit allows following advanced storage functions:

• View full disk information
• Editing disk partitions
• RAID management

3.2.4. Networking

Cockpit and FreedomBox both rely on NetworkManager to configure the network. However, Cockpit offers some advanced configuration not available on FreedomBox:

• Route configuration
• Configure Bonds, Bridges, VLANs

3.2.5. Services

Cockpit allows management of services and periodic jobs (similar to cron).

3.2.6. Web Terminal

Cockpit offers a web based terminal that can be used perform manual system administration tasks.

3.3. Troubleshooting

Cockpit requires a domain name to be properly setup on your FreedomBox and will only work when you access it using a URL with that domain name. Cockpit will not work when using IP address in the URL. Using freedombox.local as the domain name also does not work. For example, the following URLs will not work:

https://192.168.0.10/_cockpit/
https://freedombox.local/_cockpit/

Starting with FreedomBox version 19.15, using .local domain works. You can access Cockpit using the URL https://freedombox.local/_cockpit/. The .local domain is based on your hostname. If your hostname is mybox, your .local domain name will be mybox.local and the Cockpit URL will be https://mybox.local/_cockpit/.

To properly access Cockpit, use the domain name configured for your FreedomBox.Cockpit will also work well when using a Tor Onion Service. The following URLs will work:

https://mybox.freedombox.rocks/_cockpit/
https://exampletorhs.onion/_cockpit/

The reason for this behaviour is that Cockpit uses WebSockets to connect to the backend server. Cross site requests for WebSockets must be prevented for security reasons. To implement this, Cockpit maintains a list of all domains from which requests are allowed. FreedomBox automatically configures this list whenever you add or remove a domain. However, since we can't rely on IP addresses, they are not added by FreedomBox to this domain list. You can see the current list of allowed domains, as managed by FreedomBox, in /etc/cockpit/cockpit.conf. You may edit this, but do so only if you understand web security consequences of this.

3.4. External links

• Upstream project: https://cockpit-project.org

• User documentation: https://cockpit-project.org/guide/latest/

4. Configure

Configure has some general configuration options:

4.1. Hostname

• Hostname is the local name by which other devices on the local network can reach your FreedomBox. The default hostname is freedombox.

4.2. Domain Name

• Domain name is the global name by which other devices on the Internet can reach your FreedomBox. The value set here is used by the Chat Server (XMPP), Matrix Synapse, and Certificates (Let's Encrypt).

4.3. Webserver Home Page

• This is an advanced option that allows you to set something other than FreedomBox Service as the home page to be served on the domain name of the FreedomBox. For example, if your FreedomBox's domain name is https://myfreedombox.rocks and you set MediaWiki as the home page, visiting https://myfreedombox.rocks will take you to https://myfreedombox.rocks/mediawiki/ instead of the usual https://myfreedombox.rocks/plinth/.

• You can set any web application, Ikiwiki wikis and blogs or Apache's default index.html page as the web server home page. Since release 20.20 you can also select a user's website among those users who have created their public_html directory.

• Tip: Bookmark the URL of FreedomBox Service before setting the home page to some other app.

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

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

7. Dynamic DNS Client

7.1. What is Dynamic DNS?

In order to reach a server on the Internet, the server needs to have permanent address also known 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.

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

7.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://ddns.freedombox.org .

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

3. Select GnuDIP as Service type, enter your Dynamic DNS service provider address (for example, ddns.freedombox.org) into GnuDIP Server Address field.

   

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

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

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

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