Welcome to Etherbox!

This pad text is synchronized as you type, so that everyone viewing this page sees the same text. Add __NOPUBLISH__ to prevent this pad from being archived.## Guide to using your Etherbox

### Make sure you are connected to the network of the Etherbox
Look at the wireless networks listing, and select `etherbox`.

### Surf to etherbox.local
You should see this interface:

You find 4 folders:
    
* *etherdump*: a raw listing of all the pads you made
* *images*: a drag & drop folder to share images
* *include*: content related to the graphical design of your etherbox
* *pages*: this folder can have any name, books/videos/sound; you can delete and add as many folders via ftp (see below)

Some browsers don't like to connect via the local address etherbox.local or etherbox.lan.
A solution is to connect to the box typing its IP-address in a browser.

### Find out the IP address of the box
Open a terminal
    
    ping etherbox.local

Note that the ".local" domain works using a protocol called zero-configuration networking (aka Rendez-vous). On a Linux system you can install a package called *avahi* if it isn't installed already. On a Mac, this should already be installed. On Windows, installing software such as CyberDuck includes a separate installed for zero-configuration networking / Rendezvous which you can install.

### Create a writing pad and start working!

In the tabs upper left of the interface, you click on 'Etherpad'.
This brings you to the following page:

Type a name for your new pad, please don't use spaces or strange characters.
Those might complicate the backup and compression of your pages:

### Access to existing pads
In the tabs upper left of the interface, you click on 'Etherdump'.
This brings you to the index of all the pads:

You have different formats you can use: 
 
* *pad*: the actual pad, to continue editing
* *text*: a plain text file generated from your pad
* *diffhtml*: html-page generated from your pad, showing all the different changes


Once your Etherbox is set up in a place for collective work and exchanges, there are a few practical issues that you will have to deal with as a host.
This is a non-exhaustive list, written in a somehow chronogical order.

You need the IP-address to ssh into the box (see above).

### ssh to the box

Many of the operations described here require that you use the *ssh* program to gain access to the server via what is called the *shell* (ssh stands for secure shell). You do this by using a *Terminal* software. Most Linux users will be familiar with the Terminal. Mac users can find a Terminal in the "Utilities" folder of their applications. On Windows, you can use a dedicated ssh program such as PuTTY.
    
    ssh pi@ip-address-of-the-box

    login: pi
    pass: raspberry

You need to ssh in the Etherbox in order to shutdown or reboot it, or reboot parts of the software installed.
These are the default login/pass of any Raspberry.
You can of course change that, but the idea has been to create a low-threshold to participation, following as many "defaults" as possible, as the Etherbox has typically been used with a group of people physically together with respect for each other and the infrastructure they share, and not made available publically.

### Make it easier to login, with an ssh key

Starting from your laptop (open a new Terminal session if you are
connected to the pi):

    ssh-keygen

Choose the defaults. This generates an "ssh key" pair.

Use the ssh-copy-id utility to send it to the pi.

    ssh-copy-id pi@etherbox.local

### Shutdown the Etherbox

It is recommended to shutdown the etherbox rather than just unplugging it. There is a (small) chance that the filesystem could get messed up if you don't.

    sudo shutdown -h now

Wait a few moments still for the system to come to a halt before unplugging. You should see some blinking lights near the power connection of the pi finally stop changing.

### Reboot the Etherbox

    sudo reboot

### Restart Etherpad (this can help when people start having connection problems to the pads)
    
    sudo service etherpad restart

### Move to the home folder

All of these commands have the same effect, that the "current working folder" gets set to the pi user's home. 

    cd

    cd ~

    cd /home/pi

### Make dump (make static copies of the contents of the etherpads)

From the folder ~/www/etherpad you can use the make command to do many useful things. First you need to get to the right place:
    
    cd
    cd www/etherpad
    
or

    cd ~/www/etherpad

And then:
    
    make dump

For more recipes, have a look at the makefile

### Compile the contents of several pads with an .index pad

The default makefile has rules to create a single publication from any pad whose name ends ".index". This pad may then contain special "include" lines that cause the contents of other pads to be copy/pasted into the master document at that point. In this way many pads can be compiled into a single publication. Each pad should use *markdown* encoding. For example, an excerpt of the .index pad used to create this publication:

```    
    <!--  ## Introduction to series ('why networks of ones own'). What could be following threads/releases. -->
    #include http://etherbox.local:9001/p/seriesintroduction

    <!--  ## Introduction to first issue ('why etherbox'). FS -->
    #include http://etherbox.local:9001/p/issueintroduction

    ## Makefile
    ```makefile
    #include http://etherbox.local:9001/p/Makefile
    ```
```

Note that HTML comments are used ( &lt;!--  --&gt; ) to include reminders that are not processed / visible in the output. Note how markdown "code fencing" is used around the makefile to add syntax coloring to the contents of this pad.

If the pad is named HELLO.index, then (following the rules of the default Makefile), after each dump, the system will attempt to make HELLO.html using the pandoc software.

In addition, it is possible to create a PDF output by typing either:
    
    make HELLO.pdf
    make HELLO.booklet.pdf

You can also manually trigger a rebuild of the HTML with:
    make HELLO.html

Note that "HELLO" could be any name you choose. It's possible to make multiple publications on a single etherbox.

### sftp to the box
    
    host: etherbox.local or ip-address-of-the-box
    user: pi
    password: raspberry
    protocol: sftp

*sftp* is handy when people want to customize the index of the Etherbox on the fly. 
They will be able to create/delete folders, upload/delete large files etc.

Various *sftp* clients  are available [FileZilla]( https://filezilla-project.org/) for GNU/Linux or [Cyberduck]( https://cyberduck.io/) for MacOS

### Delete a pad

Add the tag  __NO@PUBLISH__ (without @) on top of the pad. This causes the dumps to get deleted -- and in any case will remove the page from the index.

### Archive the pads

Connect via SSH, and run script:
    
    eb_backup.sh

This will create two files in /home/pi/www/backups. One for the etherpad history (an sql dump) and the other a gzipped snapshot of the "etherdump" folder including any HTML/PDF outputs.
This script can also be triggered via the makefile by typing:
    
    make backup

### Changing the frequency of the cron

By default, pads are dumped every 30 minutes. You can change the frequency that the pads get dumped, and output documents are made. You do this by editing the "crontab":
    
    crontab -e

When you type this command, it opens up a text file with mostly comments that explain cron. At the bottom of the file is a special line that lists a script to run with numbers that indicate how frequently.

```bash
# ┌───────────── minute (0 - 59)
# │ ┌───────────── hour (0 - 23)
# │ │ ┌───────────── day of month (1 - 31)
# │ │ │ ┌───────────── month (1 - 12)
# │ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday;
# │ │ │ │ │                                   7 is also Sunday on some systems)
# │ │ │ │ │
# │ │ │ │ │
# *  *  *  *  * command to execute
# For example, you can run a backup of all your user accounts
# at 5 a.m every week with:
# 0 5 * * 1 tar -zcf /var/backups/home.tgz /home/
#
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/pi/bin
# m h  dom mon dow   command
*/30 * * * * /home/pi/cron.sh 2> /home/pi/www/cron.log.txt
```
The key part is the last line. The */30 means that the script happens every 30 minutes. You could use */5 to update the outputs every 5 minutes for instance. The downside is that this might make the pads slower when the outputs are being generated. (Note also the added PATH variable so that the scripts run with the same $PATH as the pi user.)

> The software utility cron is a time-based job scheduler in Unix-like computer operating systems. https://en.wikipedia.org/wiki/Cron


### Resetting a box for future use (delete all pads, etc)

Connect via SSH, and run script:
    
    eb_reset.sh

### Placing Etherbox in your network

By default, the Etherbox includes software to create it's own hotspot named "etherbox". For work sessions with more than 20 people, we typically use the Raspberry Pi in conjunction with a small OpenWRT router to provide a more robust hotspot. The following diagrams show different network configurations used over the last years.



### Booklet printing with a makefile

The booklet printing rule defined in the default Makefile is based on the class OSP blog post *How to Print A Booklet in 19 Easy steps* < http://blog.osp.kitchen/live/how-to-print-a-booklet-in-16-steps.html >
    
A straightforward rendering of these steps in single monolithic make rule could look like this:

```makefile
%.booklet.pdf: %.pdf
       pdftk_utils.py $< pad --multiple 4 --output $*.01.pdf
       pdftops -paper match $*.01.pdf $*.01.ps
       psbook -s`pdftk_utils.py $*.01.pdf count` $*.01.ps $*.02.ps
       psnup -2 -PA4 $*.02.ps $*.03.ps
       ps2pdf $*.03.ps $@
       rm $*.01.pdf $*.01.ps $*.02.ps $*.03.ps
```

However, the fun of a makefile is the abilty to define incremental transformations, and let *make* put the sequence of steps together itself! Here are the final set of rules used in the default Makefile:

```makefile
%.pdf: %.html
    weasyprint $< $@

# PDF to Postscript
%.m4.ps: %.m4.pdf
    pdftops -paper match $< $@

# Postscript to PDF
%.pdf: %.ps
    ps2pdf $< $@

# Ensure a PDF has a multiple of 4 pages
%.m4.pdf: %.pdf
    pdftk_utils.py $< pad --multiple 4 --output $@

%.book.ps: %.m4.ps %.m4.pdf
    psbook -s`pdftk_utils.py $*.m4.pdf count` $< $@

%.booklet.ps: %.book.ps
    psnup -2 -PA4 $< $@
```