Install on TomatoUSB and FreshTomato

Entware on FreshTomato (and other TomatoUSB forks)

               

Introduction

This page will take you through the process of installing Entware on a USB storage device plugged in to a Broadcom-based router running the FreshTomato open-source custom firmware (as well as any of the myriad other earlier iterations of the TomatoUSB project). This content was originally adapted from this Gist and subsequently been updated to reflect any changes needed as the project has evolved over time.

Requirements

• A USB storage device - this can be a standard flash drive, external hard drive, or even a (micro)SD card inserted into a USB card reader. It should meet or exceed the USB version of the port it occupies, and be able to have its entire contents erased, if they haven't been already. In years past the size of the drive was a matter of concern, but as of 2021 the smallest storage devices on the market are at least 8 GiB, which is more than enough even for users who intend to install a large number of packages. A bare-bones Entware installation is only slightly more than 100 MiB, and additional storage is only needed when you install new packages.
• A USB-capable router running any TomatoUSB fork, such as FreshTomato, that allows a connection to be made to its shell environment via Telnet, SSH or the web administrtation pages, for issuing the needed installation commands.

Installing Entware

Start by transferring any files you may have on the storage device you intend to use with Entware to some other device or location. It will henceforth be dedicated to your router and completely erased by the following process. Once it is empty, or what remains is safe to erase, connect it to your Tomato-based device.

⚡ Note: When considering your choice of storage device on which to install Entware, remember that while USB 3.0 is much faster, when active it produces radio interference on the same 2.4Ghz frequencies used by wireless routers to communicate with other devices. If your environment is already "noisy" or you're often connected near the margins of your router's wireless coverage, you may wish to consider using a USB 2.0 device.

Configuring the Tomato firmware

💡 A Word About Filesystems And How To Choose One 💡

The choice of filesystem largely comes down to personal preference, but since the Tomato firmware uses the Linux kernel, most users find that using Linux's native "Fourth Extended File System" (commonly referred to as ext4) results in the best performance. It also provides a feature called journaling, which helps to prevent data loss in the event of unexpected power loss (and often the first step in troubleshooting a home network is unplugging the router's power cord). NTFS and HFS+ offer partial (metadata-only) journaling, but it is insufficient for repairing data corruption, and none of the others offered by Tomato perform any journalling at all. However, depending on your use case, you may at times wish to unmount your Entware drive from the Tomato admin settings and connect it to a computer in order to transfer files or manipulate package configurations, but that's only an option if you've chosen a file system compatible with the computer. In short, Windows users may wish to choose to format their Entware partition as NTFS, FAT or exFAT in the steps to follow, and likewise, MacOS users to choose HFS or HFS+. These instructions will assume the use of ext4 going forward.

In your Tomato device's admin panel (located at http://192.168.1.1/ by default), navigate to the USB and NAS section and load the USB Support page to make sure that the following options are set:

     

The Core USB Support and USB Storage Support settings are required in all environments. In addition, at least one of the USB version support must be active to match your storage drive, as well as one of the filesystem options to match the filesystem you format it with below.

Make sure the "Automount" is also checked if you want the usb partition be be mounted automatically later.

Click the "Save" button at the bottom of the page and then check the USB Status section directly above. Your USB stick should be listed there, and if "Yes" is shown under the Mounted column, click it to unmount the drive. The subsequent steps are going to partition and format the drive, and neither can be done in a mounted state.

Partition and format the storage device

⚠️ ❗ Attention: These next steps will completely ERASE the USB device's existing contents! ❗ ⚠️

Find the /dev assignment for your device

Connect to your router using SSH or Telnet, or (if available in your distribution of Tomato) the in-browser shell available at Tools ► System Commands in the web admin panel. Input the command /sbin/fdisk -l and press Enter to list all the connected block (a/k/a file storage) devices and their partitions. Here is an example of the expected output when using a SanDisk Ultra Fit 128GB:

# /sbin/fdisk -l
  Disk /dev/mtdblock0: 512 KiB, 524288 bytes, 1024 sectors
  Units: sectors of 1 * 512 = 512 bytes
  Sector size (logical/physical): 512 bytes / 512 bytes
  I/O size (minimum/optimal): 512 bytes / 512 bytes

  ⋯

  Disk /dev/sda: 115.69 GiB, 124218507264 bytes, 242614272 sectors
  Disk model: Ultra Fit
  Units: sectors of 1 * 512 = 512 bytes
  Sector size (logical/physical): 512 bytes / 512 bytes
  I/O size (minimum/optimal): 512 bytes / 512 bytes
  Disklabel type: dos
  Disk identifier: 0x01234567

  Device     Boot   Start       End   Sectors   Size Id Type
  /dev/sda1            63 242613629 242613567 115.7G  b Win95 FAT32

There will typically be many entries identified as "Disk /dev/mtdblock…" which you can ignore, as these comprise the Tomato device's internal storage. The entries for removable storage will also always follow the pattern /dev/sdX, where X is another lowercase letter. Thus, when we see the listing for Disk /dev/sda, a ~116 GiB block device, approximating the listed capacity of the 128 GiB USB flash drive that was just connected to it (all storage devices lose some capacity after being formatted), we now know that our Entware device is mapped to the path /dev/sda by the system.

Create a new partition table and partition(s)

Issue the /sbin/fdisk command again, followed by the mapped /dev address of your storage device. Following the results of the example above, the full command would be: /sbin/fdisk /dev/sda. Here's another sample output…

# /sbin/fdisk /dev/sda
  The number of cylinders for this disk is set to 15102.
  There is nothing wrong with that, but this is larger than 1024,
  and could in certain setups cause problems with:
  1) software that runs at boot time (e.g., old versions of LILO)
  2) booting and partitioning software from other OSs
     (e.g., DOS FDISK, OS/2 FDISK)

  Command (m for help):

You can safely ignore the warning about the number of cylinders, which only concerns operating systems several decades old. The last line is a prompt for an action, all of which are assigned one letter shortcuts that are listed by the help command. As it shows, 'help' is assigned to the M key, and pressing that key followed by the Enter key displays:

Command Action
a       toggle a bootable flag
b       edit bsd disklabel
c       toggle the dos compatibility flag
d       delete a partition
l       list known partition types
n       add a new partition
o       create a new empty DOS partition table
p       print the partition table
q       quit without saving changes
s       create a new empty Sun disklabel
t       change a partition's system id
u       change display/entry units
v       verify the partition table
w       write table to disk and exit

Now that your familiar with the program, start by pressing the O key and then Enter to create a new partition table. Confirm the choice and when that is complete press N then Enter to create a new partition in the table. Choose "Primary partition" and assign it partition number "1". Unless you plan to create multiple partitions (such as a "swap" partition, or one to act as a kind of network-attached storage), accept the preset first and last sectors for the partition by just pressing Enter at those prompts. When finished, press P to print the new partition table and partition, and the output should resemble:

Disk /dev/sda:  115.69 GiB, 124218507264 bytes, 242614272 sectors
15102 cylinders, 255 heads, 63 sectors/track
Units: sectors of 1 * 512 = 512 bytes

Device         Boot StartCHS    EndCHS        StartLBA     EndLBA    Sectors    Size Id Type
/dev/sda1           0,1,1       1023,254,63         63  242613629  236284020  115.7G 83 Linux

The entry for Type that's shown is appropriate if you intend to format it using the ext4 filesystem, otherwise it should be changed. Do so by pressing the T key followed by Enter to change a partition system Id. Enter the partition number you used above and at the prompt for a Hex code, choose an appropriate value from the following list:

 0 Empty                  1c Hidden W95 FAT32 (LBA) a0 Thinkpad hibernation
 1 FAT12                  1e Hidden W95 FAT16 (LBA) a5 FreeBSD
 4 FAT16 <32M             3c Part.Magic recovery    a6 OpenBSD
 5 Extended               41 PPC PReP Boot          a8 Darwin UFS
 6 FAT16                  42 SFS                    a9 NetBSD
 7 HPFS/NTFS              63 GNU HURD or SysV       ab Darwin boot
 a OS/2 Boot Manager      80 Old Minix              af HFS / HFS+
 b Win95 FAT32            81 Minix / old Linux      b7 BSDI fs
 c Win95 FAT32 (LBA)      82 Linux swap             b8 BSDI swap
 e Win95 FAT16 (LBA)      83 Linux                  be Solaris boot
 f Win95 Ext'd (LBA)      84 OS/2 hidden C: drive   eb BeOS fs
11 Hidden FAT12           85 Linux extended         ee EFI GPT
12 Compaq diagnostics     86 NTFS volume set        ef EFI (FAT-12/16/32)
14 Hidden FAT16 <32M      87 NTFS volume set        f0 Linux/PA-RISC boot
16 Hidden FAT16           8e Linux LVM              f2 DOS secondary
17 Hidden HPFS/NTFS       9f BSD/OS                 fd Linux raid autodetect
1b Hidden Win95 FAT32

If all has gone as expected, complete the process by writing the new partition table to the device by pressing W then Enter, which will return you to the original shell environment.

Format the new partition

Several different commands are included with the Tomato firmware for the purpose of formatting new partition so they can begin storing data, each for a different filesystem. This example will show the command for creating an ext4 filesystem, however you can opt instead to use /usr/sbin/mkntfs or /sbin/mkfs.vfat for the Windows-compatible NTFS or FAT32, or /usr/sbin/mkfs.hfsplus for the MacOS- compatible HFS+, at your discretion. The command's final argument should always be the new partitions/dev mapping that was shown in the output from pressing P in fdisk above, and always consists of the original dev address plus a number to indicate a single partition on the device. In this example we're using the -L flag to give the device a fixed label as well as the -O flag used for tuning the default options.

/usr/sbin/mkfs.ext4 -L ENTWARE -O^metadata_csum /dev/sda1

This completes the preparation of the device for an Entware installation. Now the device must be mounted again before the installation script can be executed.

Mount the new partition

Entware requires that the new partition be mounted at the /opt directory every time the router powers on. That is accomplished by adding a line to its Init script from within the web admin panel that instructs the system to automatically mount it there whenever it detects the new partition's UUID (Universally Unique Identifier) being connected. The /sbin/blkid command will tell you what that UUID is.

# /sbin/blkid
  /dev/sda1: LABEL="ENTWARE" UUID="01234567-89ab-cdef-0123-456789abcdef"

Now navigate to "Administration | Scripts" in the admin console, make sure the "Init" tab is selected, and add the follow there on its own line, using your UUID from above.

echo 'UUID=01234567-89ab-cdef-0123-456789abcdef /opt ext4 rw,noatime 0 2' >>/etc/fstab

Click the "Save" button at the bottom of the page, and then click "Reboot..." at the top to test that your device will be mounted automatically by the router at /opt. When the reboot is complete, return to the "USB and NAS | USB Support" page of the admin console and confirm that your device is listed under Attached Devices and that something like what's below appears in the Description column.

"Partition 'ENTWARE' ext4 (115.69 GB / 115.69 GB free) is mounted on /opt"

Install Entware

Reconnect your Telnet/SSH session with the router or return to the "Tools | System Commands" web shell and issue the following command:

• On ARM devices:

  /usr/bin/wget -O- http://bin.entware.net/armv7sf-k2.6/installer/generic.sh | sh

• On MIPS devices:

  These are not supported by the current Entware. You can, however, install the deprecated Entware-ng as described here.

Verify the installation

Reboot the router once again by clicking the "Reboot..." button at the top of the admin console. Once it restarts, reconnect your Telnet/SSH session with the router or return to the web shell at "Tools | System Commands" and run opkg list. You should see a list of the possible packages that you can install. If you don't, something went wrong; start by making sure that your device is mounted to /opt (use the /bin/mount command).

Starting and stopping Entware services automatically

Some of the most useful packages in the Entware repository are services which should be started automatically by the system whenever it turns on and gracefully shut down before it reboots or turns off. Luckily, all TomatoUSB forks, including FreshTomato, will execute a file named mount.autorun containing a shell script, if it is present, after mounting a device and likewise with an unmount.autostop file before it reboots or shuts down. We can use this to hook Entware's service management system into the Tomato firmware.

First, install a simple console text editor from the Entware repository. If you don't already have a preference, two good options are nano and Midnight Commander's mcedit, which you can install with opkg install nano and opkg install mc, respectively. Once the installation is complete, use the editor to create a file named mount.autorun in the root of your Entware partition (nano /opt/mount.autorun or mcedit /opt/mount.autorun) with the following contents:

#!/bin/sh
# SPDX-License-Identifier: BSD-2-Clause

/usr/bin/logger -t Entware "Starting Entware services..."

if [ -x /opt/etc/init.d/rc.unslung ]; then
  if /opt/etc/init.d/rc.unslung start; then
    /usr/bin/logger -t Entware "Successfully finished starting Entware services."
  else
    /usr/bin/logger -t Entware "ERROR: Unable to start Entware services."
  fi
fi

exit 0

Save the file and exit the editor (Ctrl+O then Ctrl+X in nano, or F2 then F10 in mcedit), then issue the following command to make the script executable:

/bin/chmod 0755 /opt/mount.autorun

The logger commands in the script will allow you to conveniently see from the web admin console's "Status | Logs" page whether or not your Entware services were successfully started any time the router turns on.

Now repeat the same process, but this time using the filename unmount.autostop with these contents,...

#!/bin/sh
# SPDX-License-Identifier: BSD-2-Clause

if [ -x /opt/etc/init.d/rc.unslung ]; then
  /opt/etc/init.d/rc.unslung stop
fi

/bin/umount /opt || { /bin/umount -l /opt; sleep 10; }

exit 0

...and then make it executable as well with the /bin/chmod command.

/bin/chmod 0755 /opt/unmount.autostop

Well done 🎉

Congratulations, you've successfully completed the Entware setup process for your Tomato-based router. We hope you find it useful and rewarding. 👍🏻