FreedomBox/Manual/Jessie +-----------------------------------------------------------------------------+ |Revision History | |-----------------------------------------------------------------------------| |Revision 19 |2014-03-28 08:33:04 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Mention where the authorative source for the document is. | |-----------------------------------------------------------------------------| |Revision 18 |2014-03-28 01:50:47 |NickDaly | |-----------------------------------------------------------------------------| |split lines correctly in "Building your own" code examples | |-----------------------------------------------------------------------------| |Revision 17 |2014-03-28 01:49:16 |NickDaly | |-----------------------------------------------------------------------------| |MoinWiki doesn't support non-sequential ordered lists, worked around | |non-sequential numbering. | |-----------------------------------------------------------------------------| |Revision 16 |2014-03-28 01:39:30 |NickDaly | |-----------------------------------------------------------------------------| |Fixed diagram numbering. | |-----------------------------------------------------------------------------| |Revision 15 |2014-03-26 22:57:42 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Visit freedombox/plinth/ to get startet. | |-----------------------------------------------------------------------------| |Revision 14 |2014-03-26 22:50:11 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Plinth got a new upstream now. | |-----------------------------------------------------------------------------| |Revision 13 |2014-03-26 22:04:20 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Correct typos. | |-----------------------------------------------------------------------------| |Revision 12 |2014-03-26 22:00:10 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Correct more formatting. | |-----------------------------------------------------------------------------| |Revision 11 |2014-03-26 21:26:14 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |More formatting fixes. | |-----------------------------------------------------------------------------| |Revision 10 |2014-03-26 21:15:40 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Fix more links. | |-----------------------------------------------------------------------------| |Revision 9 |2014-03-26 13:11:12 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Avoid some unwanted links. | |-----------------------------------------------------------------------------| |Revision 8 |2014-03-26 13:06:20 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Correct heading levels. | |-----------------------------------------------------------------------------| |Revision 7 |2014-03-26 12:19:50 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Fix formatting. | |-----------------------------------------------------------------------------| |Revision 6 |2014-03-24 14:04:11 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Fix some links. | |-----------------------------------------------------------------------------| |Revision 5 |2014-03-24 14:01:01 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Mistake. | |-----------------------------------------------------------------------------| |Revision 4 |2014-03-24 13:59:53 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Typo. | |-----------------------------------------------------------------------------| |Revision 3 |2014-03-24 13:51:07 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Second translformation try, using pandoc to html, and then "html2wiki | |--dialect=MoinMoin" to convert from HTML to moinmoin. | |-----------------------------------------------------------------------------| |Revision 2 |2014-03-24 13:41:46 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Transform some mediawiki notation to moinmoin. | |-----------------------------------------------------------------------------| |Revision 1 |2014-03-24 13:35:03 |PetterReinholdtsen | |-----------------------------------------------------------------------------| |Converted freedombox-setup/doc/README.fbx-home to wiki format using "pandoc | |doc/README.fbx-home -f rst -t mediawiki". | +-----------------------------------------------------------------------------+ ------------------------------------------------------------------------------- Table of Contents Welcome to your FreedomBox! Getting Help Using your FreedomBox Hacking on your FreedomBox Updating the documentation Welcome to your FreedomBox! Getting Help This document is intended to give you all the information you need to get started with your FreedomBox. However, if you have any questions after reading this document, you can get help by: * Emailing freedombox-discuss@lists.alioth.debian.org. You can also sign up to receive copies of every discussion that happens on the mailing list and read the archives. * Chatting at #freedombox@irc.oftc.net. * Reading the wiki. * Reading the FreedomBox Foundation's website. * Reading the FreedomBox Project Page. Using your FreedomBox This section describes the basic information you need to know to successfully use your FreedomBox. Quick Start 1. Plug one end of your ethernet cord into your FreedomBox's eth0 port (the one toward the middle of the box), and plug the other end into your router. 2. Plug your computer into the eth1 port (the one toward the end of the box) on the FreedomBox. 3. Plug your FreedomBox into a power outlet. 4. Wait a few minutes while it starts itself for the first time. 5. Start enjoying the Internet. 6. Navigate to your FreedomBox by browsing to: http://freedombox/plinth 7. Bask in your own awesomeness :) Now, you can try: * Browsing the Internet * Hosting a Wiki * Publishing with your FreedomBox Other tools are also planned, such as an IM (chat) server, a blog, and more. Browsing the Internet To browse the Internet through your FreedomBox: 1. Plug one end of your ethernet cord into your FreedomBox's eth0 port (the one toward the middle of the box), and plug the other end into your router. 2. Plug your computer into the eth1 port (the one toward the end of the box) on the FreedomBox. 3. Start enjoying the Internet. Hosting a Wiki 1. Connect to your FreedomBox, as root, because we're going to modify the system by installing some new packages. 2. Install the ikiwiki package: $ apt-get install ikiwiki Say "yes" when it asks you about installing new packages. 3. Follow the ikiwiki setup instructions, or use the additional projects to automatically configure ikiwiki. Publishing with your FreedomBox Now that you've put a wiki together, you might as well publish it to the Internet. To publish material to the Internet, you need two things: 1. A place to host it. 2. A name, so you can be found. You already have the place to host data, it's this FreedomBox. Now, you just need a name. While it's possible to buy your own domain name, it's a rather tedious and complicated process. Many folks have had good luck with "reverse proxies," things like PageKite. Other reverse proxy services are also available. Publishing with PageKite Getting started with PageKite is pretty straightforward. After you've connected to your FreedomBox you'll need to download and start PageKite. 1. Download PageKite: $ curl -s https://pagekite.net/pk/ |sudo bash 2. Start PageKite, replacing yourname with your site's name: $ pagekite.py 80 yourname.pagekite.me Now, you can access http://yourname.pagekite.me/ from anywhere! Common Tasks Some tasks require a bit of command line magic. We've reproduced that magic here, so it's easy to refer to, when you need it. Logging in to your FreedomBox When your FreedomBox first starts, it has two accounts: a root account for system maintenance, and a normal user who doesn't have the power to mess with how the system works. The default passwords for each of those users are: +-------------+ |root|freedom | |----+--------| |fbx |frdm | +-------------+ You'll need this information if you want to log in, as explained in the next section. Also, after you log in, you should probably change the default passwords. Otherwise, anybody else who reads this document could log into your box, too. Connecting to your FreedomBox These instructions will teach you how to log in, via ssh, to your FreedomBox. 1. Run an ethernet cord from your computer to your FreedomBox's eth0 port (the one toward the middle). 2. Wait a bit, or until your computer says that it's successfully connected. 3. Run the following command to log in as the administrative, everyday, user: $ ssh fbx@freedombox To log in as the root user instead, in case you want to perform some serious system maintenance: $ ssh root@freedombox Make a habit of logging in as root only when you need to. If you aren't logged in as root, you can't accidentally break everything. Even if everything does break though, don't worry, it can still be fixed, it'll just take a couple hours. See the Getting Help section for more details. Changing your Password To change your password, log in to your FreedomBox as the user whose password you want to change. Then, run the following command: $ passwd That'll ask you for your current password before giving you the opportunity to put in a new one. Updating your FreedomBox These instructions will teach you how to keep your FreedomBox up to date with the latest software releases. 1. Ask the box to update itself: $ apt-get update; apt-get upgrade Chances are good the "upgrade" command will ask you if it's alright to install some packages and use some disk space. Say "yes", because that's what you want it to do. If those commands complete successfully, then congratulations, you've just updated your FreedomBox! If they don't complete successfully ask for help, as described in the Getting Help section. Diagram Ever wonder what all those holes and fiddly bits were called? 1 2 3 4 5 : : : : : ________________________ | | || . |__| | ----\____|___||___O___O__O___/ ` ` : : : : : 6 7 8 9 10 * 1. Power Cord * 2. AC Adapter * 3. UART * 4. Reset Hole * 5. JTAG * 6. Foot * 7. USB * 8. Optical Out * 9. eth0 * 10. eth1 11 12 13 2 1 :: : : : ________________________ | .. |___| | | \______------__||__|_____/---- ` ` : : : 6 14 7 * 1. Power Cord * 2. AC Adapter * 6. Foot * 7. USB * 11. Microphone In * 12. Headphone Out * 13. eSATA * 14. SD Warnings * If you need to open the box, open it from the side that's not the AC Adapter side. Be very careful here: the box's two halves are held together, on the adapter side, by a couple of fragile wires. Hacking on your FreedomBox Your FreedomBox includes several projects you can check out: * Freedom Maker * Plinth * Privoxy To start using these projects, navigate to the relevant folder in the /home/fbx directory and examine their README files. Projects Freedom Maker Freedom Maker is the tool used to create a running FreedomBox system. It creates the bootable system image that lives on the DreamPlug's microSD card. http://anonscm.debian.org/gitweb/?p=freedombox/freedom-maker.git;a=summary Plinth Plinth is the FreedomBox's administration UI. It's not done yet, but it will be included in future FreedomBox updates when it's finished. https://github.com/NickDaly/Plinth Privoxy Privoxy is the FreedomBox's privacy-preserving web-proxy. https://github.com/jvasile/freedombox-privoxy Building your own FreedomBox Updating DreamPlug's U-Boot You can also review these instructions online: http://wiki.debian.org/FreedomBox/Firmware These instructions are from Ian Campbell, using uboot version 2012.04.01-2, which is the current version in Debian's Wheezy release. Prepare your system: # wget http://http.debian.net/debian/pool/main/u/u-boot/u-boot_2012.04.01-2_armel.deb # dpkg-deb -x u-boot_2012.04.01-2_armel.deb u-boot_2012.04.01-2_armel # cp -r u-boot_2012.04.01-2_armel/usr/lib/u-boot/dreamplug /mnt Move the USB drive to your DreamPlug, and connect to your system via JTAG. Connect the UART DreamPlug port to the JTAG Board's UART port or connect the JTAG DreamPlug port to the JTAG Board's JTAG port. Next, plug the USB cord into your main system and access the serial port with: # screen /dev/ttyUSB0 115200 Now, interrupt the boot process so you can flash it from within the bootloader, before the GNU/Linux system takes over: > usb start > fatload usb 2 0x6400000 dreamplug/u-boot.kwb > sf probe 0 > sf erase 0x0 0x80000 > sf write 0x6400000 0x0 0x${filesize} You must, of course, fill in the size of the file you're loading in hex. At this point, you should be able to reset the DreamPlug and have it boot to a serial console prompt. If that fails, you'll need real JTAG magic to try again. Note that freedom-maker now includes DreamPlug firmware in the FAT partition on USB stick targets. To use a freedom-maker USB stick to update your u-boot, ignore the instructions above about how to wget and extract the firmware, and just connect to the DreamPlug and follow the bootloader instructions. Building your own File-system Image On another system, download the Freedom-Maker repoistory and follow the README to build your own image that you can plug into your DreamPlug: $ git clone git://anonscm.debian.org/freedombox/freedom-maker.git ~/freedom-maker Adding Additional Projects There are a number of incomplete projects that you might find useful, for setting up a wiki, an IM server, and so forth. To check these out, download the repository: $ hg clone https://bitbucket.org/nickdaly/plugserver ~/plugserver Then, read the README. It's pretty detailed. A word of warning, though: the FreedomBox Foundation folks think that using PHP-based services, like the blog service included in that plugserver repository, is a generally poor idea. Just use the wiki instead. Also, if you can, it may be best to wait until these tools are fully integrated into the FreedomBox image. Otherwise, migrating from these custom tools to the officially supported FreedomBox tools may be difficult. Ultimately, that decision is up to you. Updating the documentation This manual is maintained on a Wiki, allowing every registered user to update it. If you find something that could be written better, please update it on https://wiki.debian.org/FreedomBox/Manual/Jessie .