<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article
  PUBLIC '-//OASIS//DTD DocBook XML V4.4//EN'
  'http://www.docbook.org/xml/4.4/docbookx.dtd'>
<article><articleinfo><title>FreedomBox/Manual/Networks</title><revhistory><revision><revnumber>8</revnumber><date>2017-03-31 20:04:48</date><authorinitials>Drahtseil</authorinitials><revremark>Screenshot Network Single</revremark></revision><revision><revnumber>7</revnumber><date>2017-03-02 16:26:27</date><authorinitials>AaronFerrucci</authorinitials><revremark>Corrected a few typos</revremark></revision><revision><revnumber>6</revnumber><date>2016-09-02 05:31:28</date><authorinitials>SunilMohanAdapa</authorinitials><revremark>Add information about configuring BATMAN-Adv Mesh network</revremark></revision><revision><revnumber>5</revnumber><date>2016-03-06 20:43:34</date><authorinitials>PhilippeBaret</authorinitials><revremark>Text correction</revremark></revision><revision><revnumber>4</revnumber><date>2015-09-13 15:04:43</date><authorinitials>SunilMohanAdapa</authorinitials><revremark>Demote headings one level for inclusion into manual</revremark></revision><revision><revnumber>3</revnumber><date>2015-09-12 11:23:58</date><authorinitials>SunilMohanAdapa</authorinitials><revremark>Update link to renamed Firewall page</revremark></revision><revision><revnumber>2</revnumber><date>2015-09-12 10:04:19</date><authorinitials>SunilMohanAdapa</authorinitials><revremark>Add information about Internet connection sharing</revremark></revision><revision><revnumber>1</revnumber><date>2015-09-12 09:24:59</date><authorinitials>SunilMohanAdapa</authorinitials><revremark>New page for FreedomBox manual on networking</revremark></revision></revhistory></articleinfo><section><title>Networks</title><para>This section describes how networking is setup by default in FreedomBox and how you can customize it.  See also the <ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Manual/Firewall#">Firewall</ulink> section for more information on how firewall works. </para><section><title>Default setup</title><para>In a fresh image of FreedomBox, network is not configured at all. When the image is written to an SD card and the device boots, configuration is done.  During first boot, FreedomBox setup package detects the networks interfaces and tries to automatically configure them so that FreedomBox is available for further configuration via the web interface from another machine without the need to connect a monitor.  Automatic configuration also tries to make FreedomBox useful, out of the box, for the most important scenarios FreedomBox is used for. </para><para>There are two scenarios it handles: when is a single ethernet interface and when there are multiple ethernet interfaces. </para><section><title>Single ethernet interface</title><para>When there is only single ethernet interface available on the hardware device, there is not much scope for it to play the role of a router. In this case, the device is assumed to be just another machine in the network.  Accordingly, the only available interface is configured to be an <code>internal</code> interface in <code>automatic</code> configuration mode.  This means that it connects to the Internet using the configuration provided by a router in the network and also makes all (internal and external) of its services available to all the clients on this network. </para><para><inlinemediaobject><imageobject><imagedata fileref="https://wiki.debian.org/FreedomBox/Manual/Networks?action=AttachFile&amp;do=get&amp;target=network_single.png"/></imageobject><textobject><phrase>network_single.png</phrase></textobject></inlinemediaobject> </para></section><section><title>Multiple ethernet interface</title><para>When there are multiple ethernet interfaces available on the hardware device, the device can act as a router.  The interfaces are then configured to perform this function. </para><para>The first network interface is configured to be an WAN or <code>external</code> interface in automatic configuration mode.  This means that it connects to the Internet using network configuration provided by the Internet Service Provider (ISP).  Only services that are meant to be provided across the entire Internet (external services) will be exposed on this interface.  You must plug your Internet connection into the port of this ethernet interface.  If you wish to continue to have your existing router manage the Internet connection for you, then plug a connection from your router to the port on this interface. </para><para>The remaining network interfaces are configured for the clients of a router.  They are configured as LAN or <code>internal</code> interfaces in <code>shared</code> configuration mode.  This means that all the services (both external and internal) services are provided to who ever connects on this interface.  Further, the <code>shared</code> mode means that clients will be able to receive details of automatic network connection on this interface.  Specifically, DHCP configuration and DNS servers are provided on this interface.  The Internet connection available to the device using the first network interface will be <code>shared</code> with clients using this interface.  This all means that you can connect your computers to this network interface and they will get automatically configured and will be able to access the Internet via the FreedomBox. </para><para>Currently, it is not very clear which interface will be come the WAN interface (and the remaining being LAN interfaces) although the assignment process is deterministic.  So, it take a bit of trail and error to figure out which one is which.  In future, for each device, this will be well documented. </para></section><section><title>Wi-Fi configuration</title><para>All Wi-Fi interfaces are configured to be LAN or <code>internal</code> interfaces in <code>shared</code> configuration mode.  They are also configured to become Wi-Fi access points with following details. </para><itemizedlist><listitem><para>Name of the access point will be <code>FreedomBox</code> plus the name of the interface (to handle the case where there are multiple of them). </para></listitem><listitem><para>Password for connecting to the interface will be <code>freedombox123</code>. </para></listitem></itemizedlist></section></section><section><title>Internet Connection Sharing</title><para>Although the primary duty of FreedomBox is to provide decentralized services, it can also act like a home router.  Hence, in most cases, FreedomBox connects to the Internet and provides other machines in the network the ability to use that Internet connection.  FreedomBox can do this in two ways: using a <code>shared</code> mode connection or using an <code>internal</code> connection. </para><para>When an interface is set in <code>shared</code> mode, you may connect your machine directly to it.  This is either by plugging in an ethernet cable from this interface to your machine or by connecting to a Wi-Fi access point.  This case is the simplest to use, as FreedomBox automatically provides your machine with the necessary network configuration.  Your machine will automatically connect to FreedomBox provided network and will be able to connect to the Internet given that FreedomBox can itself connect to the Internet. </para><para>Sometimes the above setup may not be possible because the hardware device may have only one network interface or for other reasons.  Even in this case, your machine can still connect to the Internet via FreedomBox.  For this to work, make sure that the network interface that your machine is connecting to is in <code>internal</code> mode.  Then, connect your machine to network in which FreedomBox is present.  After this, in your machine's network configuration, set FreedomBox's IP address as the gateway.  FreedomBox will then accept your network traffic from your machine and send it over to the Internet.  This works because network interfaces in <code>internal</code> mode are configured to <code>masquerade</code> packets from local machines to the Internet and receive packets from Internet and forward them back to local machines. </para></section><section><title>Customization</title><para>The above default configuration may not be fit for your setup.  You can customize the configuration to suit your needs from the <code>Networks</code> area in the 'setup' section of the FreedomBox web interface. </para><section><title>PPPoE connections</title><para>If your ISP does not provide automatic network configuration via DHCP and requires you to connection via PPPoE.  To configure PPPoE, remove any network connection existing on an interface and add a PPPoE connection.  Here, optionally, provide the account username and password given by your ISP and activate the connection. </para></section><section><title>Connect to Internet via Wi-Fi</title><para>By default Wi-Fi devices attached during first boot will be configured as access points.  They can be configured as regular Wi-Fi devices instead to connection to a local network or an existing Wi-Fi router. To do this, click on the Wi-Fi connection to edit it.  Change the mode to <code>Infrastructure</code> instead of <code>Access Point</code> mode and <code>IPv4 Addressing Method</code> to <code>Automatic (DHCP)</code> instead of <code>Shared</code> mode. Then the SSID provided will mean the Wi-Fi network name you wish to connect to and passphrase will be the used to while making the connection. </para></section><section><title>Adding a new network device</title><para>When a new network device is added, network manager will automatically configure it.  In most cases this will not work to your liking. Delete the automatic configuration created on the interface and create a new network connection.  Select your newly added network interface in the add connection page. </para><itemizedlist><listitem><para>Then set firewall zone to <code>internal</code> and <code>external</code> appropriately. </para></listitem><listitem><para>You can configure the interface to connect to a network or provide network configuration to whatever machine connects to it. </para></listitem><listitem><para>Similarly, if it is a Wi-Fi interface, you can configure it to become a Wi-FI access point or to connect to an existing access points in the network. </para></listitem></itemizedlist></section><section><title>Configuring a mesh network</title><para>FreedomBox has rudimentary support for participating in BATMAN-Adv based mesh networks.  It is possible to either join an existing network in your area or create a new mesh network and share your Internet connection with the rest of the nodes that join the network.  Currently, two connections have to be created and activated manually to join or create a mesh network. </para><section><title>Joining a mesh network</title><para>To join an existing mesh network in your area, first consult the organizers and get information about the mesh network. </para><orderedlist numeration="arabic"><listitem><para>Create a new connection, then select the connection type as <emphasis>Wi-Fi</emphasis>.  In the following dialog, provide the following values: </para><informaltable><tgroup cols="3"><colspec colname="col_0"/><colspec colname="col_1"/><colspec colname="col_2"/><tbody><row rowsep="1"><entry colsep="1" rowsep="1"><para><emphasis role="strong">Field Name</emphasis></para></entry><entry colsep="1" rowsep="1"><para><emphasis role="strong">Example Value</emphasis></para></entry><entry colsep="1" rowsep="1"><para><emphasis role="strong">Explanation</emphasis></para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Connection Name</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> Mesh Join - BATMAN </para></entry><entry colsep="1" rowsep="1"><para> The name must end with 'BATMAN' (uppercase) </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Physical Interface</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> wlan0 </para></entry><entry colsep="1" rowsep="1"><para> The Wi-Fi device you wish to use for joining the mesh network </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Firewall Zone</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> External </para></entry><entry colsep="1" rowsep="1"><para> Since you don't wish that participants in mesh network to use internal services of FreedomBox </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>SSID</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> ch1.freifunk.net </para></entry><entry colsep="1" rowsep="1"><para> As provided to you by the operators of the mesh network.  You should see this as a network in <emphasis>Nearby Wi-Fi Networks</emphasis> </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Mode</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> Ad-hoc </para></entry><entry colsep="1" rowsep="1"><para> Because this is a peer-to-peer network </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Frequency Band</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> 2.4Ghz </para></entry><entry colsep="1" rowsep="1"><para> As provided to you by the operators of the mesh network </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Channel</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> 1 </para></entry><entry colsep="1" rowsep="1"><para> As provided to you by the operators of the mesh network </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>BSSID</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> 12:CA:FF:EE:BA:BE </para></entry><entry colsep="1" rowsep="1"><para> As provided to you by the operators of the mesh network </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Authentication</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> Open </para></entry><entry colsep="1" rowsep="1"><para> Leave this as open, unless you know your mesh network needs it be otherwise </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Passphrase</emphasis> </para></entry><entry colsep="1" rowsep="1"/><entry colsep="1" rowsep="1"><para> Leave empty unless you know your mesh network requires one </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>IPv4 Addressing Method</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> Disabled </para></entry><entry colsep="1" rowsep="1"><para> We don't want to request IP configuration information yet </para></entry></row></tbody></tgroup></informaltable><para>Save the connection.  Join the mesh network by activating this newly created connection. </para></listitem><listitem><para>Create a second new connection, then select the connection type as <emphasis>Generic</emphasis>.  In the following dialog, provide this following values: </para><informaltable><tgroup cols="3"><colspec colname="col_0"/><colspec colname="col_1"/><colspec colname="col_2"/><tbody><row rowsep="1"><entry colsep="1" rowsep="1"><para><emphasis role="strong">Field Name</emphasis></para></entry><entry colsep="1" rowsep="1"><para><emphasis role="strong">Example Value</emphasis></para></entry><entry colsep="1" rowsep="1"><para><emphasis role="strong">Explanation</emphasis></para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Connection Name</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> Mesh Connect </para></entry><entry colsep="1" rowsep="1"><para> Any name to identify this connection </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Physical Interface</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> bat0 </para></entry><entry colsep="1" rowsep="1"><para> This interface will only show up after you successfully activate the connection in first step </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>Firewall Zone</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> External </para></entry><entry colsep="1" rowsep="1"><para> Since you don't wish that participants in mesh network to use internal services of FreedomBox </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para> <emphasis>IPv4 Addressing Method</emphasis> </para></entry><entry colsep="1" rowsep="1"><para> Auto </para></entry><entry colsep="1" rowsep="1"><para> Mesh networks usually have a DHCP server somewhere that provide your machine with IP configuration. If not, consult the operator and configure IP address setting accordingly with <emphasis>Manual</emphasis> method </para></entry></row></tbody></tgroup></informaltable><para>Save the connection.  Configure your machine for participation in the network by activating this connection.  Currently, this connection has to be manually activated every time you need to join the network.  In future, FreedomBox will do this automatically. You will now be able reach other nodes in the network.  You will also be able to connect to the Internet via the mesh network if there is an Internet connection point somewhere in mesh as setup by the operators. </para></listitem></orderedlist></section><section><title>Creating a mesh network</title><para>To create your own mesh network and share your Internet connection with the rest of the nodes in the network: </para><orderedlist numeration="arabic"><listitem><para>Follow the instructions as provided above in step 1 of <emphasis>Joining a mesh network</emphasis> but choose and fix upon your own valid values for <emphasis>SSID</emphasis> (a name for you mesh network), <emphasis>Frequency Band</emphasis> (usually 2.4Ghz), <emphasis>Channel</emphasis> (1 to 11 in 2.4Ghz band) and <emphasis>BSSID</emphasis> (a hex value like 12:CA:DE:AD:BE:EF).  Create this connection and activate it. </para></listitem><listitem><para>Follow the instructions as provided above in step 2 of <emphasis>Joining a mesh network</emphasis> but select <emphasis>IPv4 Addressing Method</emphasis> as <emphasis>Shared</emphasis>.  This will provide automatic IP configuration to other nodes in the network as well as share the Internet connection on your machine (achieved using a second Wi-Fi interface, using Ethernet, etc.) with other nodes in the mesh network. </para></listitem></orderedlist><para>Spread the word about your mesh network to your neighbors and let them know the parameters you have provided when creating the network.  When other nodes connect to this mesh network, they have to follow steps in <emphasis>Joining a mesh network</emphasis> but use the values for <emphasis>SSID</emphasis>, <emphasis>Frequency Band</emphasis> and <emphasis>Channel</emphasis> that you have chosen when you created the mesh network. </para></section></section></section><section><title>Manual Network Operation</title><para>FreedomBox automatically configures networks by default and provides a simplified interface to customize the configuration to specific needs.  In most cases, manual operation is not necessary.  The following steps describe how to manually operate network configuration in the event that a user finds FreedomBox interface to insufficient for task at hand or to diagnose a problem that FreedomBox does not identify. </para><para>On the command line interface: </para><para>For text based user interface for configuring network connections: </para><screen><![CDATA[nmtui]]></screen><para>To see the list of available network devices: </para><screen><![CDATA[nmcli device]]></screen><para>To see the list of configured connections: </para><screen><![CDATA[nmcli connection]]></screen><para>To see the current status of a connection: </para><screen><![CDATA[nmcli connection show '<connection_name>']]></screen><para>To see the current firewall zone assigned to a network interface: </para><screen><![CDATA[nmcli connection show '<connection_name>' | grep zone]]></screen><para>or </para><screen><![CDATA[firewall-cmd --zone=internal --list-all
firewall-cmd --zone=external --list-all]]></screen><para>To create a new network connection: </para><screen><![CDATA[nmcli con add con-name "<connection_name>" ifname "<interface>" type ethernet
nmcli con modify "<connection_name>" connection.autoconnect TRUE
nmcli con modify "<connection_name>" connection.zone internal]]></screen><para>To change the firewall zone for a connection: </para><screen><![CDATA[nmcli con modify "<connection_name>" connection.zone "<internal|external>"]]></screen><para>For more information on how to use <code>nmcli</code> command, see its man page. Also for a full list of configuration settings and type of connections accepted by Network Manager see: </para><para><ulink url="https://developer.gnome.org/NetworkManager/stable/ref-settings.html"/> </para><para>To see the current status of the firewall and manually operate it, see the <ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Manual/Firewall#">Firewall</ulink> section. </para><!--rule (<hr>) is not applicable to DocBook--><informaltable><tgroup cols="8"><colspec colname="col_0"/><colspec colname="col_1"/><colspec colname="col_2"/><colspec colname="col_3"/><colspec colname="col_4"/><colspec colname="col_5"/><colspec colname="col_6"/><colspec colname="col_7"/><tbody><row rowsep="1"><entry colsep="1" rowsep="1"><para><emphasis role="strong">Information</emphasis></para></entry><entry colsep="1" rowsep="1"/><entry colsep="1" rowsep="1"/><entry colsep="1" rowsep="1"><para><emphasis role="strong">Support</emphasis></para></entry><entry colsep="1" rowsep="1"><para><emphasis role="strong">Contribute</emphasis></para></entry><entry colsep="1" rowsep="1"/><entry colsep="1" rowsep="1"><para><emphasis role="strong">Reports</emphasis></para></entry><entry colsep="1" rowsep="1"><para><emphasis role="strong">Promote</emphasis></para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Introduction#">Overview</ulink>      </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Hardware#">Hardware</ulink>      </para></entry><entry colsep="1" rowsep="1"><para><emphasis role="strong"> </emphasis></para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Support#">Live Help</ulink>     </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Contribute#">Where To Start</ulink>     </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Translate#">Translate</ulink>    </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/ProgressCalls#">Calls</ulink>      </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/TalksAndPresentations#">Talks</ulink>     </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Features#">Features</ulink>     </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Vision#">Vision</ulink>     </para></entry><entry colsep="1" rowsep="1"><para><emphasis role="strong"> </emphasis></para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/QuestionsAndAnswers#">Q&amp;A</ulink>      </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Design#">Design</ulink>      </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/TODO#">To Do</ulink>      </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/ReleaseNotes#">Releases</ulink>       </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Press#">Press</ulink>     </para></entry></row><row rowsep="1"><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Download#">Download</ulink>     </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Manual#">Manual</ulink>      </para></entry><entry colsep="1" rowsep="1"><para><emphasis role="strong"> </emphasis></para></entry><entry colsep="1" rowsep="1"/><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Contribute/Code#">Code</ulink>      </para></entry><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Contributors#">Contributors</ulink>      </para></entry><entry colsep="1" rowsep="1"/><entry colsep="1" rowsep="1"><para><ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/FreedomBox/Blog#">Blog</ulink>     </para></entry></row></tbody></tgroup></informaltable><para><!--"~-smaller-~" is not applicable to DocBook-->HELP &amp; DISCUSSIONS: <ulink url="https://discuss.freedombox.org">Discussion Forum</ulink> - <ulink url="https://lists.alioth.debian.org/mailman/listinfo/freedombox-discuss">Mailing List</ulink> - <ulink url="irc://irc.debian.org/freedombox">#freedombox irc.debian.org</ulink> | CONTACT <ulink url="https://freedomboxfoundation.org/">Foundation</ulink> | JOIN <ulink url="https://salsa.debian.org/freedombox-team/">Project</ulink>  </para><para><link linkend="">Next call</link>: Sunday, June 23rd at 17:00 UTC </para><para><link linkend="">Latest news</link>: Announcing Pioneer FreedomBox Kits - 2019-03-26 </para><para>This page is copyright its contributors and is licensed under the <ulink url="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)</ulink> license. </para><!--rule (<hr>) is not applicable to DocBook--><para> <ulink url="https://wiki.debian.org/FreedomBox/Manual/Networks/CategoryFreedomBox#">CategoryFreedomBox</ulink> </para></section></section></article>