DiskStation .pat Files

How to create patch files (.pat)

It’s easy to create a patch file that will work on any DiskStation. Note that this won’t help much to modify an existing official firmware from Synology as parts of the checksum file are unknown. Update: It is not easy anymore since they now actually check the checksums. Or is it not? Read on…

Patch file structure

A patch file (.pat) is a simple .tar (see tar(1)) file. It can contain any files but at least needs the following two files in the top level folder to work:

• checksum.syno – dummy file, contents does not matter, an empty file is okay. Update: not anymore, see above.
• updater – an executable script or binary which will be run by the DS after the patch has been downloaded. See below.

Create a patch file using the following commands:

touch checksum.syno
chmod +x updater
tar -cvpf mypatch.pat updater checksum.syno <and_more_files_as_needed>

Patch file execution procedure

This is what happens downloading a patch file to the DS using the firmware update routine (see /var/log/messages).

1. The patch file is saved as /volume1/upd@te.pat.
2. The folder /volume1/upd@te and the files /tmp/update.progress and /tmp/update.message are removed (if they exist).
3. The folder /volume1/upd@te is created (/bin/mkdir -p /volume1/upd@te > /dev/null 2>&1).
4. The patch file is untarred to /volume1/upd@te (/bin/tar xpf "/volume1/upd@te.pat" -C /volume1/upd@te > /dev/null 2>&1).
5. The checksum is ‹verified›. The DS only checks for the presence of the file checksum.syno at this stage. The updater program included in official patch files does use the contents. See the next section of this page. Update: this is not true anymore for firmwares >= 494. The routine now checks the contents of the checksum.syno file. However, it only checks the files that are listed. You can add more files and not list them and they will not be removed. Schauy from the German forums has found another way to run stuff as root.
6. The program updater is executed with root privileges (/volume1/upd@te/updater -v /volume1).
7. While the updater program runs, the status page is beeing reloaded about every three seconds.
8. After the updater program has finished, the DS will do a ‹cleanup›, i.e. the folder /volume1/upd@te and the patch file /volume1/upd@te.pat are removed.

The updater program

The updater program can be a shell script. The following example will not modify anything on the DS and will terminate at 99% with an error. It shows, however, how to influence the progress page the user sees while the updater program runs.

#!/bin/sh
#
# flipflip's updater example for Synology's "update firmware" routine
#


# Stage "Analyzing"

for progress in 0 25 50 75 100; do

    echo "A:${progress}:" > /tmp/update.progress
    /bin/sleep 3

done


# Stage "Updating Programs"

for progress in 0 25 50 75 100; do

    echo "P:${progress}:" > /tmp/update.progress
    /bin/sleep 3

done


# Stage "Updating Configurations"

for progress in 0 25 50 75 99; do

    echo "C:${progress}:" > /tmp/update.progress
    /bin/sleep 3

done


echo "extramsg=\"this was a test, nothing has been done.\" > /tmp/update.message
echo "C:-99:" > /tmp/update.progress

exit 99


# eof

A few explanations:

• The working directory of the program is /usr/syno/synoman/tools (i.e. the path of the update.cgi firmware update routine).
• The format of the /tmp/update.progress file is %c:%d: (possibly parsed by sscanf() or similar)
• If one leaves the updater program at C:99:, the update progress screen will reload forever. The cleanup (last point above) will happen, though.
• If one leaves at a negative value (e.g C:-99), as in the example above, the DS will show the error Data can not be applied. and Unknown error occurs (Error No:99).. Cleanup is done as well. In this case the DS won’t reboot and will offer a back button to the user.
• Valid values for exit are described in bash(1), section EXIT STATUS. In short: 0 = successfully terminated, 1-125 = error occured, 126 = not executable, 127 = file not found, (128+n).. = terminated on fatal signal n.
• If one leaves at C:100, the DS will immediately reboot. The reboot counter on the update progress page will start to count down and reload the admin interface after 180 seconds.
• /tmp/update.message can be used to have a (only a short one in DSM 2.0!) message displayed in the web interface after the patch terminates. Note: quote the whole message in quotation marks (as in the example above) and don’t use further quotation marks in the message. Not sure if escaped quotation marks work (never tested).

Universal Patch File

Download this universal patch file script which allows you to create working .pat files for the DiskStation.

• syno-universal-pat_20080227.tar.gz (4kb)