QUICKSTART GUIDE Release 30.3 ======================================================================== General Information / Warnings ======================================================================== Windows users: In Linux, the operating system of the router, all commands and other inputs are case sensitive. If you are unfamiliar with Linux, please make sure to enter the commands, filenames, volume labels, etc. exactly as shown. Passwords: Passwords and keys entered through the GUI are saved in nvram in clear text, and are copied in clear text to the restore script. Please take whatever measures you deem appropriate to protect this data. Share Permissions: Share permissions for SMB and FTP access are not saved in nvram, but are read/written directly from the shared resource. While the access lists are saved/restored, it may be necessary to reset the access permissions after a restore. Space Management: This utility will save multiple versioned backups of the user nvram and jffs directory (if jffs is active) by router. It is the users responsibility to perform space management on the USB stick as required. JFFS Restore: Some of the later code levels also clear jffs during a restore to factory defaults. (Things such as OpenVPN certificates and TrendMicro data are now stored in the jffs space. In order to fully restore your system, you therefore need to run jffs-restore.sh following nvram-restore.sh MAC list filters: There have been multiple changes in the handling of MAC list filters between various firmware releases. Most cases will be handled correctly by the exception processing during a restore. However, if the MAC filters are incorrect after the restore, they may be cleared by running clear-maclist.sh Additional Options: For advanced users, the nvram-save.sh script now has several new options. These can be displayed through a help option, nvram-save.sh -h NVRAM User Save/Restore Utility nvram-save.sh Version 26.1 Options: -h this help msg -v Print version/perform consistency check -b Backup mode - save for restore to same router (default) -m Migration mode - transfer settings to another router -i inifile Specify custom nvram variable ini file -clk Include clkfreq/overclock setting (Backup mode only) -nojffs Skip backup of jffs storage -nouser Skip execution of user exit script Package Contents: nvram-save.sh Main user script nvram-excp-merlin.sh Script called automatically during restore for code level specific processing nvram-restore.sh User script to restore saved user NVRAM variables jffs-restore.sh User script to restore jffs directory nvram-merlin.ini NVRAM variable control file nvram-sample.ini Example user NVRAM control file with only basic variables nvram-user-sample.sh An example user exit script that creates a tar backup of the jffs directory clear-maclist.sh Script to clear MAC list filters in case of problems detecting the correct format (multiple changes between firmware levels) save-mynvram.sh A small script that can save/restore a small number of user specified nvram settings QuickStart.txt Documentation in DOS/WIN format Changelog.txt Version history in DOS/WIN format ======================================================================== Step (1) - Prepare the USB Stick ======================================================================== - Plug the USB stick into your main computer. Format the USB stick and give it a volume label of ASUS NOTE1: Any volume label may be used. If you change the label, use your new label in place of 'ASUS' in the remainder of this guide. NOTE2: Most USB sticks come pre-formatted as FAT32 or exFAT. exFat is generally not supported by the ASUS routers, and FAT32 does not support access permissions under Linux (access is global). For most Windows users, NTFS is preferred so that the USB stick may be easily transferred to a Windows PC. If using an Apple OS, MS-DOS format may be preferred (which is really FAT32) for PC compatibility. Of course, advanced users may format the stick to any desired type, including Linux EXT2, EXT3 or EXT4. Note that some early MIPS based routers, such as the N66U, do not support EXT4 disk format. - Remove the USB stick from your computer and plug it into the router ======================================================================== Step (2) - SSH into the router ======================================================================== SSH access to the router is required to execute the save and restore scripts. - If SSH is not enabled on the router go to the Administration/System page (default is http://192.168.1.1/Advanced_System_Content.asp) and click the radio button to enable SSH, and then click Apply to save the change. - Open an SSH session on your computer using an SSH client such as PuTTY, WinSCP, FileZilla, MobaXterm, etc. ======================================================================== Step (3) - Install NVRAM Save/Restore Utility Menu ======================================================================== Copy and paste the command below into an SSH session: /usr/sbin/curl --retry 3 "https://raw.githubusercontent.com/Xentrk/nvram-save-restore-utility/master/nsrum" -o "/jffs/scripts/nsrum" && sleep 5 && chmod 755 /jffs/scripts/nsrum && sh /jffs/scripts/nsrum One the menu is installed, you can type 'nsrum' to run the menu from the command line. ======================================================================== Step (4) - Install NVRAM Save/Restore Utility Files ======================================================================== Select "Option 1 - Install NVRAM Save/Restore Utility Files" ======================================================================== Step (5) - Run the script to save the user nvram and jffs directory ======================================================================== - At the SSH prompt enter The root level directory on the USB drive is /tmp/mnt. The firemware creates a symbolic link at the root level directory to point /mnt to /tmp/mnt. Type 'nsru' to access the installation directory on /tmp/mnt directory. Alernatively, you can access the directory using the 'cd' command. ls /mnt (you should see the name of the volume label of the USB stick - ASUS) cd /mnt/ASUS/nsru (change to the USB stick directory) By default, all of the nvram utility data files are placed in the current working directory, /mnt/ASUS/nsru. The installation will also create a backup subdirectory (/mnt/ASUS/nsru/backup) to keep the generated save/restore files separate from the utility scripts. To start the backup process ./nvram-save.sh This executes the script in Backup Mode, you should see Saving messages. ./nvram-save.sh -M or -m This executes the script in Migration Mode, for moving the settings from one router to another. In this mode some settings are not copied, for example the wireless transmit power. You may also perform a Migration Mode restore using the data saved in normal Backup Mode. The -M or -m migration option is still supported however for backwards compatibility. - You now have a script on the USB that will restore the user settings named nvram-restore-yyyymmddhhmm_MODEL-macid.sh where yyyymmddhhmm is the timestamp of the saved setting MODEL is the router model (e.g. RT-AC88U) macid In Backup Mode, this is the last two bytes of the router MAC address (for example E1F2) In Migration Mode, this will be MIGR - If you want to look at the contents of the restore script.... cat nvram-restore-yyyymmddhhmm_MODEL-macid.sh | more The following files are also created in the data directory: nvram-all-yyyymmddhhmm_MODEL-macid.txt which is a sorted nvram show output of all the nvram variables and their values. Note that this file also contains system level variables which should not be modified by the end user. nvram-usr-yyyymmddhhmm_MODEL-macid.txt which is a text listing of the variables and their values saved by the utility organized by the save categories. nvram-ini-yyyymmddhhmm_MODEL-macid.txt which contains a copy of the ini file used to create the nvram-restore script. A log file, nvram-util.log is also created in the current directory which logs the run activity of nvram-save.sh (including the jffs backup), nvram-restore.sh and jffs-restore.sh which will be executed later. NOTE: Existing run data IS NOT migrated to the nvram-util.log file, but an existing nvram-util.log file will be used if present. NOTE: With the introduction of a 'Clean restore' (described in the restore section) it will be easier to view the nvram-usr text file to determine the contents of any saved nvram variable. At this point, you have a saved copy of the nvram variables which have been set through the Web GUI. Entries will also be made in the router syslog documenting the running of the utility. If you have enabled JFFS storage on the router, a copy of the /jffs directory will also be saved to the USB stick. - Name of the saved directory is /jffs-yyyymmddhhmm_MODEL-macid, where macid is the same previously defined You can now do a Reset to factory defaults on the router, remove the USB stick as a backup or take the USB stick to another router to transfer the settings if run in Migration mode. If you are preparing for a code update, the following steps are recommended: - Reset to factory defaults (optional, but the safest to reset before code load as well) - Load new code via router gui - Reset to factory defaults (this is the important reset and must be performed prior to the restore) ======================================================================== Step (6) - Run the script to restore the user nvram and/or the jffs directory ======================================================================== - To execute the restore Plug the USB stick into the router. Go to the Administration/System page (default is http://192.168.1.1/Advanced_System_Content.asp) If you performed a factory reset: - SSH may now be disabled and must be re-enabled. - If you had previously changed the Router Login Name from the default 'admin', you should change it back to be the same as when you performed the nvram-save step to use the customized login. Otherwise, the login/password will be admin/admin. Open an SSH prompt as described in Step (2) above. ls /mnt (you should see the name of the volume label of the USB stick - ASUS) cd /mnt/ASUS/nsru (change to the USB stick directory) Executing ./nvram-restore.sh without any parameters will scan the nvram-util.log file and find the latest saved values and ask you to confirm the restore. If you did not specify the migration option during the save, you will now be presented with an additional option: - "Perform a migration restore [Y/N]?" This will perform a migration restore from a full save backup, excluding the same nvram settings that would be excluded if a migration save had been initially performed. A message will be presented if the save file does not support a migration restore. If you do not select a migration restore, the following option will be presented: - "Perform a clean restore and remove ununsed NVRAM variables [Y/N]?" Answering Y (yes) here will only restore those variables which already exist in the current nvram. This can be useful, for example, after doing a factory reset on a lower level of code, and you want to eliminate nvram variables which were only used on a later level or fork. You can also provide the yyyymmddhhmm_MODEL-macid parameter on the command line to load a specific set of saved values You may also continue to use the utility as before, and execute the a specific restore script (and specify -clean or -migr as a single parameter to perform a clean restore or migration restore as described above, the default is to restore all values). ./nvram-restore-yyyymmddhhmm_MODEL-macid.sh (execute the restore to the same router) or ./nvram-restore-yyyymmddhhmm_MODEL-macid.sh -clean (execute a clean restore to the same router) or ./nvram-restore-yyyymmddhhmm_MODEL-macid.sh -migr (execute a migration restore to a new router) or ./nvram-restore-yyyymmddhhmm_MODEL-MIGR.sh (execute the restore to a new router) The restore will also look at the code level where the save was performed and the currently active code level and will make adjustments as necessary for documented code specific variables (automatically calls nvram-excp-merlin.sh). WARNING: If doing a migration restore, make sure both your old router and new router are not on the network at the same time. Having both active could result in duplicate resources, such as SSIDs and DHCP servers. Doing a migration restore will also automatically be performed with the -clean option. If you wish to restore your /jffs directory this must be done manually via a second script jffs-restore.sh - make sure JFFS is enabled on the router To restore the entire directory Open a SSH prompt as described in Step (2) above. ls /mnt (you should see the name of the volume label of the USB stick - ASUS) cd /mnt/ASUS/nsru (change to the USB stick directory) Executing ./jffs-restore.sh without any parameters will scan the nvram-util.log file and find the latest jffs backup directory and ask you to confirm the restore. You can also provide the yyyymmddhhmm-macid code on the command line to restore a specific backup directory. ./jffs-restore.sh yyyymmddhhmm_MODEL-macid (copy the entire backup /jffs-yyyymmddhhmm_MODEL-macid directory from the USB stick to the router flash, replacing the current /jffs contents) OR You can access the /tmp/ASUS/nsru/jffs-yyyymmddhhmm_MODEL-macid and copy individual files as needed back to the router /jffs directory or subdirectories. Entries are also made in the router syslog and nvram-util.log documenting the running of the nvram-restore or jffs-restore. ======================================================================== Saving the data for later use ======================================================================== Of course, you can keep the data on the USB Stick for future use/backup. If you wish, you can also copy the data off the USB Stick back to your PC for safe keeping. If you do this, and later copy the data back to a USB Stick for use, it is likely you will need to restore the correct permissions for the scripts. Plug the USB stick with the copied files into the router Open an SSH prompt as described in Step (2) above ls /mnt (you should see the name of the volume label of your USB stick - ASUS for example) cd /mnt/ASUS (change to the USB stick directory, where ASUS is the volume label of the USB stick) chmod 755 ./*.sh (this ensures the package script files are executable) If using a FAT32 formatted USB stick, you may skip this step. Executing this command on a USB stick with these formats will generate a permissions error which can safely be ignored. ======================================================================== Errata and Version Specific Information ======================================================================== - Using FAT32 disk format for the USB stick Prior to Release 22 for this disk format, you may experience some errors as the scripts attempt to ensure that the correct permissions are setup for the files. These errors show as CHMOD failures and can be safely ignored. As of Release 22, these errors will be supressed. - Backup directory The generated save/restore files are stored in a 'backup' subdirectory /tmp/mnt/ASUS/nsru/backup - Syslog logging of utility runs As of Release 14, entries are also made in the router syslog documenting the running of the nvram utilities - Clean Restore Clean restore was added in release 18, and restores only those nvram settings which are initialized by a factory reset - Migration Restore from full save This option was added in release 25, and will be available during the nvram-restore execution. The save file must also have been generated with release 25.2 or above. - Logging of restore operations As of Release 14, entries are also made in the router syslog documenting the running of the nvram-restore or jffs-restore. As of Release 16, entries are also made in the nvram-util.log file documenting the running of the nvram-restore or jffs-restore. - SAMBA and FTP with Guest Access Following a nvram-restore operation, if guest access was specified for SAMBA or FTP, the router will present an alert and you must re-verify your desire to allow guest access. This is done to ensure the security of router/LAN. ======================================================================== INI File Format and Options ======================================================================== The INI file format for the nvram definitions follows the 'standard' format of a section header followed by data. For example [System - Basic] time_zone_dst time_zone time_zone_dstoff There are additional controls which can be added. - To exclude an entire section from backup, comment # the section header #[System - Basic] time_zone_dst time_zone time_zone_dstoff - To exclude an indivdual nvram setting from backup, comment # that setting [System - Basic] #time_zone_dst time_zone time_zone_dstoff - To exclude the setting from being saved during a migration save (or restored during a migration restore), prefix it with a @. This is only valid for individual settings and is not valid on the section header. [System - Basic] @time_zone_dst time_zone time_zone_dstoff - To force a setting to always be included in the restore, even if it would normally be excluded on a 'clean' restore, prefix the setting with a + . This may also be used to preserve custom nvram settings across a factory reset. This is only valid for individual settings and is not valid on the section header. [System - Basic] +time_zone_dst time_zone time_zone_dstoff - To force a setting to always be included in the save, even if it is an empty value, prefix the setting with a % . This will force some variables which may have a valid empty setting to be saved/restored. This is only valid for individual settings and is not valid on the section header. [System - Basic] %time_zone_dst time_zone time_zone_dstoff - To combine the above flags and force both the save of an empty value and force it to be restored even if it is not present after a factory reset, prefix the setting with a & . This is only valid for individual settings and is not valid on the section header. [System - Basic] &time_zone_dst time_zone time_zone_dstoff - The last section header in the default nvram-merlin.ini file is for user added nvram settings, such as may be used in custom scripting. For example (also using the force save prefix) for a user nvram variable 'blacklist_enable' [User Adds] +blacklist_enable