Nvram is one of the big Tomato monsters — poorly designed, poorly implemented, undocumented, poorly understood, the cause of much confusion and grief, and … mission-critical. Most users are not interested in understanding, wanting only to be told what to do, or to tell others what to do. This article is for the benefit of those few users who do want understanding. It is not for casual users, nor for developers, but for system administrators or reasoning users. All the particulars in this article are for the RT-N16, running some form of Tomato 1.28.
Most people assume that NVRAM refers to a list of several hundred configuration settings that are stored in a part of the flash memory. They further assume that the nvram command provides access to that list of settings, so that the user can query, retrieve, and change settings.
But there are, in fact, two lists. Sometimes these two lists may have the same contents, sometimes not.
Tomato uses the term "nvram" for both of these lists (as well as for the program, and its running process, that is used to manage these two lists). Until there is consensus on standard terminology that distinguishes between the two lists, I will use the terms "flashed NVRAM" and "cached NVRAM", consistently in this article. Any reader can easily replace the term "cached NVRAM" by their personal preference. For example, one person prefers the term "in-memory DB".
1. These two lists that may both be referred to as "nvram", are:
1.1 The physical, flashed NVRAM, the body of which consists of Null-terminated lines. The contents can be read in /dev/mtd4, and the partition table can be found in /proc/mtd.
1.2 The virtual, cached NVRAM list of settings, used by the nvram process. The contents cannot be found in a file, not even a /proc pseudofile. (The form that this list, used by the nvram process, takes between invocations of the nvram program — what it is called, where it is stored, and how — is certainly not transparent.)
The cached NVRAM is only accessible via the nvram command.
The nvram command never reports to the user about the physical, flashed NVRAM.
The nvram command does not report the differences between the two lists.
The cached NVRAM may change hundreds of times without the flashed NVRAM being reflashed.
2. The nvram command only reports on or changes the cached NVRAM, not the flashed NVRAM. There are only two invocations of nvram that change the flashed NVRAM, namely:
2.1 nvram commit — this flashes the NVRAM from the cache.
2.2 nvram erase — this flashes the entire NVRAM with 0xFF.
(nvram erase only exists since Tomato 1.28)
All other invocations of the nvram command only read from or write to the cashed NVRAM. In particular:
"nvram get" does not read the flashed NVRAM!
"nvram set" does not change the flashed NVRAM!
"nvram show" does not display the flashed NVRAM!
"nvram find" does not search the flashed NVRAM!
"nvram export" does not retrieve the flashed NVRAM!
The nvram command never shows a user the contents of the flashed NVRAM!
The nvram command does not access the contents of the flashed NVRAM!
The nvram command only writes to the flashed NVRAM. It does not read it.
This is extremely important. Many users are completely unaware of this.
3. There are 3 ways to erase the flashed NVRAM (filling the partition with 0xFF):
3.1 mtd-erase -d nvram
3.2 nvram erase # this is a new option, added to the nvram command since 1.28.
3.3 The GUI [erase nvram "thorough"] — this erases the flashed NVRAM and then reboots, which results in the NVRAM being reflashed with the firmware defaults.
(How might an "unthorough" erasure be accomplished?)
4. nvram commit (or the GUI Admin Debug "NVRAM Commit") cause the cached NVRAM to be flashed.
5. Some people say you must erase NVRAM both before and after installing new firmware. Why?
5.1 When you erase NVRAM in the GUI, the forces an immediate reboot after the erase. When the boot process sees the empty NVRAM, it flashes the default NVRAM that comes with the (old) FW. In other words, the GUI makes it impossible to reflash with an erased flashed NVRAM. The reason for erasing (and rebooting) before installing new firmware is … _ .
5.2 When you erase NVRAM after installing the new FW (and then reboot) the NVRAM will be flashed from the new FW's defaults. The reason you must erase NVRAM after installing new firmware is: … _ .
5.3 The Reboot page offers the option to erase the NVRAM after flashing the new firmware. Perhaps an option should be added to erase the NVRAM before flashing the new firmware? Perhaps these two options should be the default actions, if they are so necessary?
6. The flash memory partition table is in /proc/mtd. On the RT-N16 it looks like this:
dev: size erasesize name
mtd0: 00040000 00020000 "pmon"
mtd1: 01fa0000 00020000 "linux"
mtd2: 0061bc00 00020000 "rootfs"
mtd3: 018a0000 00020000 "jffs2"
mtd4: 00020000 00020000 "nvram"
Note that the RT-N16's NVRAM partition has 131072 bytes, but only the last 32768 bytes are used for NVRAM. Note also that the smallest amount of data that can be written (flashed) is one erase-block. Note that in the above example, the erase-block size is 131072 bytes. Thus, when only one bit in the NVRAM is changed (and "committed"), the entire partition is re-flashed.
7. When making changes on the GUI pages, [Save] will reflash the NVRAM. But other processes may read and update the cached NVRAM, and possibly even the flashed NVRAM. The wireless driver may be such a process.
8. For example, every time the Scheduler runs, the (cached) NVRAM is updated. That may be once a minute. There are half a million minutes in a year. The nvram will report all these changes if you ask it to. If all those changes are actually flashed every minute, that's a lot of flashings.
9. Administration > Debugging gives you the option not to flash NVRAM every time you make the most minuscule change in the GUI. You can then run "nvram commit" when appropriate.
One might ask questions such as:
1. What are the differences between flashed NVRAM and cached NVRAM?
1.1 What changes have been made to the cached NVRAM since the NVRAM was last flashed (committed)?
2. What are the differences between the Firmware defaults and the flashed NVRAM (or the cached NVRAM)?
3. What is the value of a particular setting in the flashed NVRAM? (the equivalent of nvram find)
4. How can I make a (backup) copy of the flashed NVRAM and the cached NVRAM, in the same format?
5. What are the Firmware (default) NVRAM settings?
There are tools to address the preceding questions.
6. When was the cached NVRAM last changed? What was the most recent change?
7. When was the NVRAM last flashed (committed, written)?
8. How many times has the NVRAM been flashed?
9. How many times can I expect it to be flashed before it fails? (A WRT54G Ver.2 for example.) Experts say 5,000 times for older chips, to more than 100,000 times for the newest chips.
10. What failure modes can be expected from NVRAM overflash?