TechInfoDepot:DD-WRT/HDsamba2

HDsamba2
Currently at version 5.0. (September 30st 2009) - (see also HDsamba2 update to samba3)

An install and boot script system that will allow you to easily install Optware Samba2 and use your DD-WRT router as a Samba2 USB HD NAS device.

All you need to do is to setup a few pre-install details, run the install script and HDsamba2 will do the rest for you.

Notice
Important Note: (Thanks to AtMi)

There is an issue with the Reboot Button in the dd-wrt web-GUI.

This issue affects HDsamba, and all other script based methods of unmounting USB devices. Testing has shown that the Reboot Button in web-GUI DOES NOT RUN THE USB UNMOUNT SCRIPT.

Soft reboots (that are made after changing and pressing Apply Settings Button ) does however run the USB unmount scripts and thus cleanly unmount the drive... but the Reboot Button under Administration, DOES NOT UNMOUNT THE USB DRIVE before reboot happens.

At this time, I'm suggesting people use putty to reboot the router with the "reboot" command. This will call the unmount script naturally.

Better still, configure the SESbutton, and simply unmount your HD manually before you reboot.

A bug has been listed in the tracker, and I hope this minor change can be made to avoid confusion for those wanting a simple USB storage solution.

If you are using a Cisco WRT610Nv2, you may want to avoid HDsamba as it does not seem to be heavily used/tested on this platform. I have given up after about 4 hours of reading forums and trying nearly everything!

Background
The Goal:

A quick, painless method of installing and setting up NAS on a broadcom router.The scripts are designed to be intelligent in the sense that they can detect bad web-GUI settings, improperly partitioned disks, errors on disks, unmount problems, processes that fail to execute or terminate, and other unexpected failures.

The golden rule with HDsamba, is that every command issued has at least one verification stage. If something fails, the log files (see /tmp/HSsamba/*.log) should contain everything you need to identify the problem.

HDsamba2 will: AND IF SOMETHING GOES WRONG, HDSAMBA2 WILL TELL YOU WHAT HAPPENED
 * Provide an easy way to relocate /jffs to an USB-drive
 * Provides an easy way to handle multiple USB-drives
 * Installs e2fsprogs and swap-utils to /jffs to address disk integrity and memory swap
 * Installs Optware to /opt
 * Installs Samba2 with an initial configuration file that works out of the box
 * Installs xinetd to provide SWAT for Samba that works out of the box
 * Mounts your Optware partition for you
 * Mounts your Swap partition for you
 * Mounts your NAS partition for you
 * Allows you to configure the Routers (ez)sesbutton to unmount the disk drive on press

HDsamba2 Pre-requisites
HDsamba2 has successfull install reports with these routers and builds:
 * WRT600N v1.1 Eko BS-v24-preSP2 mini-usb - build 12387 using the -mini install parameter.
 * WRT600N Eko Mini_usb_ftp svn11487 using the -mini install parameter.
 * WRT600N v1.1 Eko Mega svn11482
 * WRT600N v1.1 Eko Mega svn11604
 * WRT350N Eko Mega svn11296
 * WRT600  Eko Mega svn11482  and a 1TB HD
 * WL-500gP v1 Eko Mega svn11218
 * WL-500W Eko Mega svn11218
 * WRT610 v1.0 SVN revision 13491M NEWD-2 Eko

Install a DD-WRT version with USB support
To make your life easy; install a firmware that already has USB support... You can find these here http://www.dd-wrt.com/dd-wrtv3/dd-wrt/downloads.html" Try under / others / eko / V24_TNG /

HDsamba2 has been tested with Eko's 11218 and up mega builds. They work.

Keep in mind you will need 300-400 kb of free JFFS space to run some utilities. This may influence your partition layout because you might need to relocate JFFS to a USB-drive with some builds.

Partition you HD
Version 5 of HDsamba2 allows you to easily use a free order of partition on one USB-drive and even allows to spawn the different partition needed across multiple USB-drives.

Please make sure you have at least one of each partitions with following requirements:

First - ext3 - approx. 500MB to 1GB (Optware and HDsamba2 core scripts...) Second - linux swap - approx. 128MB to 256MB (Swap partition for the router) Third - ext3 - (NAS data, this is the space that Samba will share)

If you want to relocate JFFS to an USB-Drive you need a forth partition:

Forth - ext3 - approx. 32MB to 128MB (JFFS)

HDsamba2 does not only support ext3 filesystem. You can also use ext2 and fat32. Only JFFS relocation has to be to an ext3 partition. But is it strongly recommended to use ext3 on all program/data partitions. ext2 should work fine, too, but has a bigger risk of data loss during power failures. Similar applies to fat32 which has in addition further problems with big files (> 4GB). NTFS is not supported because DD-WRT currently has no NTFS driver for read/write.

Although it is possible do not use fat32. Any question about this or that not working in conjunction with fat32 will result in the answer to use ext3. If you want to mount your USB-drive to a windows system use ext3 and one of the ext3 driver that can be found at http://www.fs-driver.org/ or http://www.ext2fsd.com/.


 * You can a Linux live cd to partition your HD.

Config a Time server
Point your browser to 192.168.1.1, or whatever your router's IP is...

web-GUI -> tab: Setup -> tab: Basic setup -> section: Time Settings

Set a Time Server

This helps stop e2fsck from running disc checks when there is no reason. It may seem like a small detail, but it's important! http://www.pool.ntp.org/ can help ( time.windows.com works fine )
 * Set a Time Server* (The install script will detect if you are lazy...)

Configure JFFS support
We need a small JFFS to run disc checks from, as repairs are best run on unmounted disks. Again you probably want around 300-400kb available. (You will need more than this however if you install with the -MINI parameter, as extra libraries will be installed.) See Jffs for a guide of how to enable a jffs drive on your router

If you have enabled jffs in webgui you can relocate jffs to an USB-drive. This of course implies that the USB-drive jffs residues on, can not be checked automatic during startup. This should not lead to issues as data on jffs is seldom accessed and because of that has a reduced risk of getting corrupted. Nevertheless do not store valuable data on a relocated jffs partition. The partition you choose to be jffs has to be of ext3 file system.

The relocation process of jffs happens during HDsamba2 installation. You will be asked weather you want to relocate jffs and if you approve you can choose the desired partition via a text-base-choice-screen. Commands needed to activate the jffs mount during startup will be written into nvram (need about 2000 bytes) and afterwards you are requested to restart the router and restart the installation process. Later you can move the jffs partition with the script "relocate_jffs" located in /mnt/HDsamba/scripts/. You can delete the jffs relocation during startup by typing nvram set rc_startup="" in the console.

Please note that if you choose to relocate jffs during startup process it will delete any existing user startup script.

Config USB support
Under Services -> USB in the web-GUI, enable the following
 * Core USB Support
 * USB Storage Support
 * USB 2.0 (or the version your HD supports)
 * ext2/ext3 Support

NO NEED to specify an AUTOMOUNT, or startup script, as HDsamba2 boot script automatically runs when dd-wrt boots. And part of the boot script is to check for USB drive integrity, which is best done on an unmounted drive!

Safe shutdown script
HDsamba2 will automatically configure your router with a shutdown script to unmount USB drives cleanly on reboot (and thus save your HD wear and tear).It will also execulte any executeable startup script in /opt/etc/init.d/K* prior to unmount the USB-drives. The shutdown script is automatically integrated with the dd-wrt .rc_shutdown system.

Ok, that's it. You have met all the prerequisites. You are ready to run the install script.

Time to install
Putty into your router. Connect your Hard Disk to the router.

For Mega and Big firmware builds run: $ cd /tmp $ wget http://www.3iii.dk/linux/optware/v5install.HDsamba2 $ sh /tmp/v5install.HDsamba2

For Mega and Big K2.6 version builds, use the following code: $ cd /tmp $ wget http://www.3iii.dk/linux/optware/v5install.HDsamba2_K26 $ sh /tmp/v5install.HDsamba2_K26 Now follow the instructions on your screen, and answer some questions, after reboot the log files are HDsamba2's way of telling you what went right, and if anything went wrong. Enjoy your NAS.

When you are asked to enter partition id for opt, swap, data, note that what the question is looking for is a syntax which is disk.partition; so common responses for people who followed the Tutorial about USB drive partitioning would answer 0.1 for Opt, 0.2 for Swap, and 0.3 for Data.

Read the section HDsamba2 Log files for a guide to the .log files.

Read the section HDsamba2 boot system for an overview of the steps and tasks performede during the boot process of HDsamba2.

For Mini firmware builds run: $ cd /tmp $ wget http://www.3iii.dk/linux/optware/v5install.HDsamba2 $ sh /tmp/v5install.HDsamba2 -mini

For Mini K2.6 firmware builds use: $ cd /tmp $ wget http://www.3iii.dk/linux/optware/v5install.HDsamba2_K26 $ sh /tmp/v5install.HDsamba2_K26 -mini

Now follow the instructions on your screen, and answer some questions, after reboot the log files are HDsamba2's way of telling you what went right, and if anything went wrong. Enjoy your NAS.

Read the section HDsamba2 Log files for a guide to the .log files.

Read the section HDsamba2 boot system for an overview of the steps and tasks performed during the boot process of HDsamba2.

NOTES about Mini:
 * The -mini parameter will install additional OpenWRT libraries from the whiterussian build, and config the OpenWRT-wrapper to load these libraries correctly for running the Swap utilities.


 * Also note: This addition is still under development and is thus still in beta testing


 * UPDATE on -mini parameter:
 * MULTIPLE reports of success using -mini parameter with WRT600N and mini_usb_ftp svn11487

Notes on HDsamba2 V5 mounting system
HDsamba2 V5 includes a new mounting system. To be able to use HDsamba2 with multiple USB-Drives is needed to secure that the desired partition will always be mounted even if dd-wrt switches logical units of the USB-discs. This is done by identifying the USB-Discs by it's GUID and then mounts given partition number on the drive having the specified GUID. This mixing safe mount is done transparent in the background. The information which disc has to be mounted where is located in /jffs/etc/config/ in files *.mountinfo. The safe mount script does also verify that the given partition is really mounted. A stripped down version of this safe mount script is also used to mount a relocated jffs.

It is also possible to add user custom mount points that get automatic mounted during start-up too. This can be a custom mount can be installed via the script detection_custom that can be found in /mnt/HDsamba/scripts/. the information for custom mountpoints is stored in /jffs/etc/config/ in files named *.mountpoint.custom

Any USB-Drives mounted via the HDsamba2 mounting system are automaticly unmounted during reboot. Any user custom mounts and data partition mount are executed after optware startup and should have full Large file support.

Please not that user custom mounts are not checked automaticly (will be version 6, though).

Not that during mount the script will create a .bad_shutdown.flag in /jffs/etc/config/. This flag will be removed in the unmount script if everything is unmounted fine. This means that finding this .bad_shutdown.flag file does not necessary indicate a bad shutdown had happened. Finding this file is bad, when you have run the unmount script (either using shell or by a appropriate configured the SES / AOSS / EZ-SETUP / WPS Button )

Notes on SES / AOSS / EZ-SETUP / WPS Button Function
If you enable this feature: There is no feedback feature implemented at this time, sorry.
 * press and hold the button for a couple of seconds.
 * Your Hardrive LED should flicker.
 * Release button and wait (no more than 30 seconds)
 * Unplug HD safely.

If you don't trust it, putty in and run a mount command the first couple of times you try using the SES button. IT DOES UNMOUNT THE DRIVE, you just need to give it 30 seconds max (see below as to why...)

To remount your drive you have 2 options:

1) Plug the drive back in, reboot your router. Or alternatively, reboot your router, plug drive in later, as the HDsamba2 boot script will continue to look (indefinitely) for a USB partition until it finds one.

2) Plug the drive back in, and press and briefly hold the SES button a SECOND TIME. This will remount the drive and restart Samba.

A firewall note
HDsamba2 (as of version 3 upwards ) no longer requires dmesg output. This means there is no longer an issue with firewall logging.

Troubleshooting HDsamba2
If at anytime you experience problems: Take a look at the log files. The log files are HDsamba2's way of telling you what went right or wrong during the boot process. Groups of the log files are stored at three locations during the boot process:

The three locations of the log files:
 * /tmp/HDsamba/*.log (These will always be the most recent log files)
 * /mnt/HDsamba/logs/*.log (These are copied from /tmp in the event of a successful init.startup)
 * /mnt/data/Logs (These are copied from /tmp when Samba is started)

Use command: cat /tmp/HDsamba/boot.log to read the boot.log file

The log files are your friend, if you're having problems, post the log files in the dd-wrt forum. HDsamba2 uses the log files to tell you what went right or wrong during the boot process.

HDsamba2 boot system
HDsamba2 is automatically initialized on router startup from files stored in /jffs/etc/config:

init.startup executes first Task 1: checks for /jffs and waits 30 seconds or until it appears Task 2: checks for a time sever and waits 30 seconds or until it appears Task 3: waits for HD to be plugged in, if it isn't already, infinite wait Task 4: mounts the swap partition Task 5: runs a check on paritions 1 and 3, may take time if there are problems Task 6: mounts /mnt Passes execution to /mnt/HDsamba/scripts/mount.usb

NOTE: If you partition your HD with a Linux boot CD that doesn't use a time server it is likely your HD will read it was created in 1970. This date will cause e2fsck to force a check of disk partitions created this far in the past, as a result EXPECT DELAYS ON YOUR FIRST BOOT OF HDSAMBA2.

mount.usb executes next Task 1: mounts the /mnt/opt to /opt to allow optware to function Task 2: Starts any optware by executing any executeable startup script in /opt/etc/init.d/S* Task 3: mounts the NAS partition to /mnt/data Task 4: mounts any further partition specified by user Task 5: starts Proftp*, waits for it to start, or 30 seconds whatever happens first *This only occurs if ProFTP is enabled in the web GUI Finally, it copies all log files to /mnt/HDsamba/logs/ for easy viewing later.

During and after execution of the boot scripts, the log files will contain information about performance of each of the tasks during execution of the init.startup and mount.usb scripts; what went right and what went wrong.

/mnt/HDsamba/scripts/detection
With this script you can set the partitions that will mount HDsamba2. This script is useful if you have copied your data to another partition or your HDD is not recognised any more because of an exchanged casing. If you see an error like

SAFEMOUNT: No disc can be found with GUID XXXXXXXX, exiting

you should probably run this script. You will also find it on the server, so if your HDD is not mounted, no need to search for it.

Usage (Server Version): wget -O /tmp/detection http://www.3iii.dk/linux/optware/detection sh /tmp/detection

/mnt/HDsamba/scripts/detection.custom
This script work similar to the detection script. It is useful to specify additional user mounts that will be mounted during HDsamba2 Startup. The script will question for an path to mount to and a partition to be mounted. If the path is non-existent it will be created by the detection.custom script. The path will not be created upon HDsamba2 startup. So if you specify a path on /tmp the custom mount can fail during startup. A good mountpoint would be on a usb-drive (like /mnt/data/USB-key, /mnt/data2 ). There's no limit on how many custom mountpoint can be specified but ony one custom mointpoint will be created per script call. If you want tmore custom mountpoints call teh script multiple times. You can mount the same partition on multiple paths ( part1 to /mnt/data2 and /mnt/ftp ). If you want to delete your custom mountpoints type : rm /jffs/etc/config/*.mountinfo.custom in command line.

/mnt/HDsamba/scripts/relocate_jffs
With this script you can relocate your jffs partition to an USB-drive. Note that you will normally need to reinstall HDsamba2 because data of your jffs from flash is not copied over to jffs on USB-drive.

/mnt/HDsamba/scripts/network.usb

 * Simple question based method of quickly setting up smb.conf
 * Stores a backup of your smb.conf config file.
 * Now also does the same for swat config, using the subnet your specify to restrict access.
 * Requires a reboot when completed, or a manual restart of HDsamba2.

/mnt/HDsamba/scripts/jffs.repair
jffs.repair is currently not included into HDsamba2 V5. The jffs.repair version from V3 can not be reused. You can get the same result by installing HDsamba2 again over the corrupted one.

Re-installs files to /jffs if you had to wipe /jffs or do a firmware upgrade

NOTE for Mini builds: can also be run as /mnt/HDsamba/scripts/jffs.repair -mini This enables library support on smaller builds that don't support open-wrt (As mentioned the Mini build support is still under development and must thus be considered in beta stage)

The /mnt/HDsamba/scripts/jffs.repair script will:
 * install e2fsprogs to jffs
 * install swap-utils to jffs
 * configure the open-wrt wrapper
 * install the HDsamba2 startup scripts

It also configures the SESbutton.

/mnt/HDsamba/scripts/unmount.sesbutton
Allows the sesbutton to mount and unmount your Hard drive. The install script copies this file to /jffs/etc/config/ to enable this feature You can copy this file yourself to enable it. You can also rm /jffs/etc/config/unmount.sesbutton to deactivate this feature

/mnt/HDsamba/scripts/forcecheck.usb
Simulates a bad shutdown... the advantage to this, is if you want to force a full disk check on your partitions, running this will force such a check on your next boot. Good for the data paranoid, like me...

HDsamba2 Shutdown System
The unmount scripts work this way:

1. Execute any executable kill script found in /opt/etc/init.d/k* - This includes Samba and Xinet and gives them up to 30 seconds to report a clean termination - usually this is instant unless there is a problem

2. Turns off the Swap Parition - gives it up to 30 seconds to report a clean stop - usually this is instant unless there is a problem

3. Turn off ProFTP - gives it up to 30 seconds to report a clean stop - usually this is instant unless there is a problem

4. Saves permanent logs to /mnt/HDsamba/logs I want to avoid writing to /jffs as much as possible so the rest of the script is not logged

5. Attempts to unmount the USB-Drives ( specified via three normal HDsamba2 mountpoints plus any custom mountpoints) in 'normal' mode. Gives 15 seconds for this to happen. This usually completes in 5 - 10 seconds. This will shut down the drives 95-98% of the time. NOTE: partitions that have been mounted manually via a mount command are not unmounted.

6. Check if the HD is still mounted. If so, try unmounting again in 'lazy' unmount mode. 99.9999% of the time this solves any lingering HD reads/writes, and shuts the drive down cleanly. The script provides another 15 seconds to complete this process, or as much of that time that is needed. NOTE: partitions that have been mounted manually via a mount command are not unmounted.

7. Last check, are the drives still mounted? I have never encountered this problem to date but I admit it's a possibillity due to other processes or unforseen modifications. If the script at this point does not find any mounted drives left (that have mountpoint info), it will remove the .bad_shutdown.flag in jffs to indicate everything is OK and no aggressive drive check during next boot is needed.

8. Script is finished.

Advanced - adding load and kill of more packages
The custom starting system changes with version 5 of HDsamba. You can still add user daemons that start during startup and are killed during reboot/shutdown/unmount.

The right place not to put your startup scripts in is /opt/etc/init.d/

For a starting daemon place a file starting with "S" (for start) in that directory. A file beginning with "K" will be executed during kill. Normally the "S" or "K" letter should be followed by a two digit number and at last a description what that file will start. You hsould not forget to make this file executable with "chmod +x filename".

The two digit number has the use of specify the row in which script stare executed. S00bla starts first followed by S01blabla,..... and last is S99blasdfs. The same is also true for the killing scripts. Lowest number comes first. Keep in mind that mounting of the data partition happens after starting optware services from /opt/etc/init.d/.

HDsamba2 Version 5 has already some script located in /opt/etc/init.d/ and uses the system described to start it'S own processed, too.

It's not for all of us, but it does give the more advanced users out there the opportunity to customize their HDsamba2 setup.

A note from the developer
Bug reports, issues, reports of success and failure on various builds are always welcome.

For Version 3 of HDsamba2 reports/problems are welcome in this forum thread Together is how we continue to make DD-WRT stay the best router firmware out there.

For Version 5 of HDsamba2 reports/problems are welcome in this forum thread. Please notice that in the forum thread for HDsamba2 V3 there is already a lot of information posted about special problems that do also apply for version 5.

= Links =
 * How to mount a Fat32 partition (forum post). Please note: Optware will not run properly from a Fat32 partition, use Fat32 only for a data partition.
 * Forum discussion about scsi-idle options
 * Additional fs and USB kernel modules
 * How I got Windows and Samba to work with Chinese filenames

Samba3 links:
 * Script to update your HDsamba2 to samba3 forum post
 * Steps to upgrade HDsamba2 from using Samba v2.x to Samba v3.x (forum post) effectively making it HDsamba3
 * Unslung (home of Optware) wiki on Samba3
 * The Official Samba 3.2.x HOWTO and Reference Guide
 * HDsamba2 v3.0 and samba3 with some security easy way... (forum post)