What it is

The stick itself

The FFP-stick is an USB stick (or an external USB disk) which uses the advantages offered by usb_key_func.sh to install and start FFP on a ZyXEL NAS.

FFP

The fonz fun_plug is a collection of applications compiled and packaged by fonz. On the FFP-stick it by default offers shell access via telnet, but many packages are available, including ssh(d), lighttpd, rsync(d), buildtools, editors,midnight commander, transmission and many more.

0.5

'The original' (well, of course there have been the versions 0.1-0.4, but they have never been very popular).
This version needs a kernel with has (depricated) OABI support.

0.6

A testing version for EABI kernels.

0.7

Available for both OABI (oarm/oabi) and EABI (arm). To keep it simple, there are two OABI versions, oarm and oabi. Don't mix them up. More info here.
Starting with FFP-stick 2012-01-31 the ABI of the kernel is autodetected, and FFP 0.7 is installed, and starting with version 2012-03-06 0.7/oabi is installed, if applicable.

How to install

Download the zipfile here, (also have a look in the beta folder, for the lastest version) and extract it on a USB stick (or -disk) of at least 256MB (64MB for FFP 0.5), having only one primary partition (unpartitioned space is no problem), FAT formatted. Plug it in the NAS, and reboot. During install the NAS needs to have internet access, as it will download the ffp base package from http://ffp.inreto.de. In a few minutes a telnet daemon will be started.
That's it.

Warning

The stick will be repartitioned and reformatted, so except the contents of the zipfile, all data on the stick will be lost.

NSA-310, having firmware 4.40 or newer

Rename nsa310_check_file_C0.ZyPrivate to nsa310_check_file_C0, replacing the original nsa310_check_file_C0.

NSA325(-v2)

On the NSA325 you'll have to use a rear port. The (USB3) front port doesn't work.

NSA-220, having firmware 2.20 or older

Owners of a NSA-220, firmware 2.20 or older should rename nsa220_check_file.220- to nsa220_check_file, replacing the original nsa220_check_file.

Troubleshooting

If the stick is not re-partitioned, you might have been bitten by the timing issue

If the stick is repartitioned (can be seen in the webinterface) but doesn't work as expected, have a look at the logfile ffpboot.log on the stick. When no telnet daemon is started, wait at least 30 minutes before switching off the box, or removing the stick. There is a timeout of 1000 seconds in the script in waiting for the stick to be automounted, after which the script will mount it 'manually' (scriptically?). Then the logfile ffpboot.log will be moved to the FAT partition of the stick.

And then?

Now you have a telnet shell, and now?

Sshd

First you can enable and start sshd, which is a more secure and powerful shell:

For chrooted installations (The default for stick 2012-03-19 and older and/or firmware older than 4.40) there are two predefined logins: user with password user, and root with password root. Of course you should change those default passwords (using the command 'passwd [<username>]) before exposing this interface to the big evil web.

For not chrooted installations, (The default for stick 2012-05-28 and firmware 4.40+) there is one login: root with your admin password.

When the ssh server is started, and you are able to login via ssh, you can stop and disable telnet:

/ffp/start/telnetd.sh stop
chmod a-x /ffp/start/telnetd.sh

(Some background: FFP will run all executables in /ffp/start, on startup. So toggling the executable bit selects which daemons to start)

Other packages

Unfortunately the packages for 0.5, 0.6, 0.7/arm and 0.7/oarm are not interchangeable.

0.5

Download

wget url_of_package.tgz

Install

funpkg -i package.tgz

0.6

Fonz' packages for 0.6 can be found here. So far I'm not aware of 3rd party packages.

Download & Install

The same as for FFP 0.5

0.7

Fonz' packages for 0.7 can be found here. There are also 3th party packages here and here.
You are encouraged to use uwsiteloader.sh (as described here) to install extra repositories, and to use slacker (installed with the FFP base package) to download and install extra packages.

Download & Install

slacker -Ui

The 'old' way used in FFP 0.5 & 0.6 also works.

External links

Tutorial on packagesHere is a nice tutorial for building your own packages. Afaik this covers 0.5, 0.6 and 0.7. Only creating redistributal packages is different.
For 0.5:

Warning

FFP is originally designed for the Dlink DNS-323/Conceptronic CH3SNAS. It contains some tools which are for use in those boxes only, like /ffp/sbin/store-passwd.sh, (There is a small list of scripts which are automatically deleted in function CleanUp() in after_booting.sh), and Fonz' package dns323-utils-nnn.tgz. It's generally not a good idea to run those scripts on your NAS.

Size of the USB stick

A new FFP-stick (0.5) will have about 50MB in use. If only having shell access via ssh or telnet is enough for you, a 64MB stick is fine. For 0.6 and 0.7 I recommend at least 128MB. But if you want to go nuts, and just install everything
FFP 0.5:

FFP on the harddisk

usb_key_func.sh will test all mountpoint for the existance of a executable ffproot/after_booting.sh, and execute the first found. So when you want to install FFP on the harddisk, create a share ffproot, and put after_booting.sh and rootfs.tgz in it. The script has to be executable:

chmod a+x /i-data/md0/ffproot/after_booting.sh

and remove the executable flag from the sample on stick:

chmod a-x /after_booting.sh

Then reboot the box. FFP will be installed on harddisk (the NAS needs to have internet access).
Of course you can also copy your existing FFP installation to harddisk.
You will still need to have the stick plugged in on each reboot, as the usb_key_func.sh script is needed to launch FFP.

Anatomy of the FFP stick

An FFP stick has two (primary) partitions, the first has a FAT (vfat) filesystem, the second one ext3. Both partitions show up in the webinterface.

FAT partition

The FAT partition is mounted by the NAS at boot, and contains usb_key_func.sh, which does the rest. Further the logfile is written here.

ext3 partition

The ext3 partition contains a directory ffproot, which contains a number of empty directories (bin,sbin,var,usr,proc,...) a etc and a ffp directory, and the script after_booting.sh.
When the firmware automounts the ext3 partition, this is detected by a helper script running in background, which calls after_booting.sh. This script builds the FFP environment.
On the Medion P89626/P89630 this partition is ext2, because the build-in mke2fs doesn't support ext3.

NSA 210, 220, 221

The firmware partitions are bindmounted on these empty directories, and FFP is chrooted on ffproot.

NSA 310, 320, Medion P89626/P89630

On the 3x0 the rootfs is a cpio archive which is compiled in the kernel. For some reason it's not possible to bindmount directories from such a fs on another directory. So another strategy is used.
The rootfs is doubled in /tmp/bindroot, using hardlinks and bindmounts. Symlinks to ffproot/ffp and ffproot/etc are created, and FFP is chrooted on /tmp/bindroot.

/etc and /log

On the 3x0/Medion /etc gets a special treatment. Because it should be able to edit those files from the FFP shell, hardlinks cannot be used. (Editing a file could break the link, leaving two copies, one inside the chroot, and one (unchanged) outside). So a tmpfs is created, in which the contents of /etc is copied (to /tmp/bindroot/tmp/.etc), and which is bindmounted both on /etc and /tmp/bindroot/etc/original. Samba (which already runs) doesn't like this /etc hijacking, and is restarted for that reason.
/log is hijacked for the same reason. The firmware changes the logs, to hardlinks should break.

The chroot

The reason for using a chroot is that it's not automatically safe to share the /etc directory between FFP and the firmware. They both use /etc/password. This problem is bypassed by chrooting.
To be able to examine (and change) the firmware /etc directory, it's bindmounted on /etc/original.

Starting with version 2012-05-28 fw 4.40+, FFP is no longer chrooted.

Uninstalling

Unless you have installed FFP on harddisk, removing the stick and rebooting will remove every trace of the FFP-stick from your NAS.
When you did install on harddisk, remove the stick, reboot, and remove the ffproot share.

Firmware upgrade

Before upgrading the firmware, first switch off the box, and remove the FFP-stick. The firmware updater could interfere with FFP.
BTW, updating the firmware could break your FFP-stick. It has happened three times:

2.30. The initial mountpoint of the stick changed from /mnt to /mnt/parnerkey. The file nsa220_check_key (the NSA220 was the only ZyXEL NAS at that time) had to be changed.

3.24. The mount options 'iocharset=utf8,shortname=mixed' were added to the initial mount of the stick, effectively restricting the filesystem to FAT only. A major modification of usb_key_func.sh was needed to solve that. FFP cannot run from a FAT filesystem, so the repartitioning part had to be added.

4.40 on the NSA-310. The checksum salt was changed from /bin/libzy.so to /etc/Zy_Private. The file nsa310_check_file_C0 had to be changed to solve that. Unfortunately firmware 4.40 for the 320 and 325 still uses /bin/libzy.so, and also use nsa310_check_file_C0.

4.61. The boot process is streamlined, which increases the risk of the timing issue.

Known issues

Backup Planner synchronization

At least in firmware 4.40 Backup Planner synchronization doesn't work in cooperation with FFP. The reason is a script which cannot handle the double mounts. Solution: In /i-data/md0/.zyxel/zy-pkgs/bin/gen_zysync_sever_config.sh change line

USB Copy/Eject device

When using the USB copy button followed by a 'Eject device' in the webinterface, the webinterface crashes as soon as you actually pull the device.
This behaviour is seen on the 3x0, fw 4.40.
Fixed in 2012-05-28.

User quota

User quota might not work. It's not working on the Medion P89626/P89630. Solution unknown

Webinterface shows stick partitions twice

Both partitions of the stick will show up twice in the webinterface. (It might be three times for the 3x0/Medion). This is just a cosmetic problem. The webinterface backend reads /proc/mounts to generate the webinterface data, and it gets confused by the double mounts.
Fixed in 2012-05-28, for fw 4.40+

Timing issue

During boot of the kernel, a reset is send to the USB bus(ses). Then all connected USB devices have to (re)initialize, and announce themselves to the system. The kernel doesn't wait for that, USB is hotplug, so they can announce themselves whenever they are ready.

Later, during userland boot, the startscript probes all mass storage devices for the existence of a valid usb_key_func.sh, and executes it if certain conditions are met. The start of FFP relies on this script.

If the stick hasn't announced itself by then, it's not probed, and so the script is not executed.

Some stick are not fast enough. Unfortunately, this is about bootup time, which is not related to write/read speeds. So it's not easy to tell if a stick will do.

Workarounds

During boot the checksum of sysdisk.img on sda1 is calculated, and if it doesn't match a stored value, a fresh copy is extracted from flash. This happens after the kernel has reset the USB bus, and before the mass storage devices are probed. As the flash memory of the box is slow, the boot process can be delayed substantially by forcing the box to extract a fresh sysdisk.img, giving the stick more time to announce itself.
This can be done by a script in /ffp/start/:

This will add a few bytes to the file, causing it to be exchanged on next boot.

Manually starting

Sometimes you might want to start the stick manually. For instance when you're hit by the timing issue. You'll need a root shell, which can be got by using the Telnet backdoor or the SSH server.
There are two different cases, a new stick (which has to be repartitioned and formatted) and an existing stick.
For a new stick the script has to unmount the stick, to be able to repartition it. Unfortunately the firmware automounts it. So the processes responsible for this has to be killed.
The stick needs to be mounted to /mnt/parnerkey. This is the place where it's normally mounted on startup. The script refuses to run from another mountpoint, for safety reasons. (The device containing the script is going to be reformatted. You don't want mistakes here.)

Options (switches) in after_booting.sh

There are a few option which can be switched on by uncommenting one or more lines.
Note: you'll have to use an editor which supports Linux line endings. For Windows this could be PsPad.

Create a /ffp symlink in rootfs

Uncomment FFPSYMLINK=1
This will work only when the rootfs is writable. It's useful to use FFP-tool in php scripts. For instance imagemagick

Do not chroot FFP

Uncomment NOCHROOT=1
When you have a /ffp symlink, it's not necessary anymore to chroot. This has big advantages, but, when FFP is not chrooted, it means it will share the firmware /etc directory. FFP packages are supposed to use /ffp/etc for their configuration files, but at least the login uses /etc/passwd. The default telnet login is login-less, so that's not an issue, but ssh can give problems.
FFP commands will not work unless you change the PATH, or supply the full path.
I wrote a workaround for the passwd issue:

Change the root password when not chrooted

Uncomment CHANGEROOTPASSWORD=1
after_booting.sh can change the root password (and other passwords). By default it will change the password of root to 'root', and add a user 'user' with password 'user'.
BTW, by default there will be no home directories.

NSA3x0, firmware 4.20+

The root password seems not to be an issue anymore. It's the same as the admin password you supplied.

Choose FFP version

Starting with FFPStick 2012-03-06 by default FFP 0.7/arm or 0.7/oabi is installed, depending on the ABI support of the kernel. If EABI is supported, 0.7/arm is installed, else 0.7/oabi.
This can be overruled by changing the FFPVERSION value.

Random info

The 'firmware /etc' is mounted on /etc/original for chrooted installations.

When logging in via ssh takes a long time, > 10 seconds between username and password, it could be a DNS issue. Try to put 'UseDNS no' in /ffp/etc/ssh/sshd_config, and restart sshd.

The files

usb_key_func.sh

On boot the script usb_key_func.sh on the stick is launched by the firmware. This script copies itself to a ramdrive, and executes that in background.
When the stick has only one partition which is FAT formatted, and contains a script after_booting.sh in its root, the background script will wait until the stick is unmounted, and then it will repartition the stick in 2 partitions, a +/- 16MB FAT partition, and the remaining space an ext3 partition. This is because FFP cannot run from a FAT partition.
The background script will wait until the firmware mounts the partitions, move the logfile to the FAT partition, and execute ffproot/after_booting.sh from the EXT3 partition.
When the firmware does not automatically remount the stick, the background script will to do it itself, after a timeout of 1000 seconds.
Starting with version 2011-07-15 most functions are put in fun_plug.sh, and usb_key_func.sh is just it's loader

fun_plug.sh

Starting with version 2011-07-15:
On boot this script is launched by usb_key_func.sh. When the stick has only one partition which is FAT formatted, and contains a script after_booting.sh in its root, the script will copy all files to ramdrive, unmount the FAT partition, repartition the stick in 2 partitions, a +/- 16MB FAT partition, and the remaining space an ext3 partition. This is because FFP cannot run from a FAT partition. Then it will copy the files back.
The script copies itself to a ramdrive, and executes that in background.
The background script will wait until the firmware mounts the partitions, move the logfile to the FAT partition, and execute ffproot/after_booting.sh from the EXT3 partition.
When the firmware does not automatically remount the stick, the background script will to do it itself, after a timeout of 1000 seconds.

after_booting.sh

This script will extract and remove rootfs.tgz and fun_plug.tgz, if available. If no executable ffproot/ffp/bin/busybox is found, it will try to download fun_plug.tgz from http://ffp.inreto.de/ffp/0.7/, and extract it. When it cannot download fun_plug.tgz, it will just sit and wait until someone puts it on the share.
Then it creates a new root for FFP, by binding /bin, /sbin, /var, ... on the new root, and starts FFP.

nsaNNN_check_file, STGNNN_check_file

The firmware checks for the existence of this file. This file should contain the full path of usb_key_func.sh, and the full path of a salted md5sum file. If the checksum fits, the script is executed.
Different boxes use a different filename, but their functionality is all equal.

salted_md5sum.Zy_Private

Contains a salted md5sum of usb_key_func.sh, used by all 2nn boxes, and the Medions

salted_md5sum.libzy.so

Contains a salted md5sum of usb_key_func.sh, used by the 310, 320 and 325.

salted_md5sum.libzy.so.5xx

Contains a salted md5sum of usb_key_func.sh, used by the 540.

md5sum

Executable. Is necessary for the NSA-210.

mkdosfs

Executable. Is necessary for the Medion boxes

rootfs.tgz

Contains a rootfs for FFP, and some conf files.

ffpboot.log

This logfile is made on each boot on the FAT partition. Because the firmware will unmount the stick after running usb_key_func.sh, it is copied to RAM when the initial script exits. (On the Medion boxes the logfile will be create in RAM initially, because the stick is mounted readonly). In RAM it will log the background script actions, and it will be moved back as soon as the firmware remounts the stick. Further the background script will try to put it back when a fatal error occurs during repartitioning and formatting.
A typical logfile (well, not completely typical, this one is made on ZyXEL firmware chrooted on Debian on a NSA-220) looks like this:

will restart samba. Especially useful when you changed the configuration

exit_ffp function

Using the same interface, exit_ffp will stop FFP, and unmount it's mounts. You can add an extra command, which will be executed unchrooted

exit_ffp reboot

will stop FFP cleanly, and reboot the box.

Release notes

2015-10-12

Added:

Support for the NAS326

2015-09-13

Fixed:

Squashed this bug. A /mnt/HD_a2 link was not available for the NAS5XX. Only after_booting.sh is changed.

2015-09-03

Added:

Support for the NAS540 and NAS520. Only for firmware 5.10+. Older firmwares with a 64kB page size are not supported.

2014-12-02

Added:

Recognition support for the 310S and 320S.

2013-11-24

Added:

Cleanup after download also removes 'fp.master' stuff

Script also supports EMCLifeline, although that needs a different starter, which is supplied with the lifeline package (see Iomega wiki).

Support for 'embedded FFP' (as opposed to 'downloaded FFP'), as preparation for a new zypkg.

Recognition support for the NSA325v2

2012-10-20

Changed:

In addition to the root shell, now also the admin shell is changed to /ffp/bin/sh for unchrooted installations.

Fixed:

Patched this bug in FFP 0.7. The patch will only be applied on a fresh install of FFP.

2012-09-03

Changed:

Instead of hijacking /etc/profile, now the root shell is changed in /etc/passwd to /ffp/bin/sh for unchrooted installation.

User 'user' is removed. It seems nobody uses it, and at least one person has had an intruder on that account.

Cleaned up the logfile, as some messages were read as errors by users.

Cleaned up unneeded directories for unchrooted installations. after_booting.sh will create them when needed.

Removed the execute_outside_chroot helper thread for the TDC Homebox, as it seems to stop the FFP boot.

Added a /etc/mtab symlink

When /ffp/etc/ffp.version fails, /ffp/etc/ffp_version is used for chroot/no chroot decisions.

2012-05-28

Changed:

On an eabi system (fw >= 4.40) ffp is by default no longer chrooted.

On a not chrooted system /etc/profile is adapted, to add ffp globally.

On a chrooted system with a writable rootfs /i-data and /e-data are no longer doubled, but moved, and the orignal /i-data and /e-data directories are exchanged by symlinks to the new locations (which are inside the chroot)

On a chrooted 3xx or Medion box /etc is no longer hijacked by a bindmount, but by a symlink.

The ffp start and stop function is streamlined. It's now (theoretically) possible to stop ffp and start it again. * An option is added to auto-enable ssh on installation

Removed the possibility to change the root password at an unchrooted installation.

2012-03-19

Fixed:

An USB device is mounted by process myhotplug, on /mnt/sdxn. Then process zyshd will create a mountpoint in /e-data, and move the mount. It turned out that sometimes FFP was started from the /mnt mountpoint. This caused problems.

2012-03-17

Changed:

Starting with firmware 4.40 the NSA-310 uses /etc/Zy_Private as salt. So I changed nsa310_check_file_C0 to use another salted_checksum.

2012-03-06

execute_outside_chroot didn't work on oabi boxes. I built a work-around, but am not content yet. The work-around has as side-effect that all executions are logged. This can be a problem when eeecute_outside_chroot is called frequently. Don't know what happens if the logfile exceeds the size of usb partition 1, about 10 MB.

2012-01-31

Added:

Support for FFP 0.7

Automatic detection of OABI/EABI support.

Changed:

By default FFP 0.7 is installed. The 'arm' version when EABI is supported, else oarm.

2010-11-09

2010-11-02

Initial release of 3rd generation FFP-stick.
Main change in contrast to the 2nd generation: The stick is automatically repartition and formatted. FFP needs an ext2/3 partition, while usb_key_func.sh needs a vfat partition.]]