Welcome to the chkrelease wiki!

chkrelease.sh is a simple bash shell script that uses the OS’s md5sum or md5 commands to cryptographically check the integrity of files on the filesystem that are found in a .tar file. This is useful for quickly verifying the integrity of a release of source code after, or while, it is deployed. As it does not rely on any version control system, it can be used on servers without the need to install additional SCM software and thereby eliminates the possibility (and temptation) of tainting development with changes made in a production environment.

The utility was designed with the Unix toolbox philosophy in mind, which means it is readily useable as a filter (a stage in a pipeline). Probably the simplest use case is to use the script to overwrite only files which have changed from the previous release by piping its output to tar. While you do this, the script can also show you a progress report on standard error so you know how far along the audit you are.

How to use chkrelease.sh

The following sections are a pseudo-manual. The most up-to-date information is always available by running

chkrelease.sh --help

and asking the code, itself.

Synopsis

Options

Examples

The simplest use of this script is:

chkrelease.sh tarfile.tar

This usage will compare the contents of tarfile.tar with the current directory hierarchy and reports any differences it finds on standard output. No output means no differences were found.

If you would like a continuous count of the script’s progress, pass it the --progress option. If the current working directory is not the intended target of the comparison with tarfile.tar, pass the target path as the second parameter.

chkrelease.sh --progress tarfile.tar ~/mydir

This will compare the contents of tarfile.tar with the directory hierarchy that begins at ~/mydir, and will show you a count of the progress which includes

• the total number of files to be audited (i.e., the number of files contained within tarfile.tar)
• the current count of audited files
• the current count of files found not to cryptographically match

Large tar files can take a long time to check. Thus, you can also run chkrelease.sh in the background and periodically ask it to give you a progress report. To do this, simply send the chkrelease.sh process a SIGHUP like so:

$ chkrelease.sh tarfile.tar &         # start chkrelease and run it in the background
[1] 2672                              # the system reports the process ID is 2672
$ work work work                      # you busy yourself doing other things
$ kill -HUP 2672                      # you get curious about the progress of chkrelease.sh

Total number of files to audit: 7331
Total number of files audited:  3269
Total number of files modified: 964
Total number of files skipped:  1
$ 

Caveats

Since chkrelease.sh has a singular purpose, it should not be considered a security utility. The script does not verify that a filesystem directory hierarchy contains only the files also contained in the tar file, it merely checks that those files which do exist on the filesystem and in the tar file match exactly. Therefor, it is conceivable that an attacker could place additional files on the filesystem which chkrelease.sh will not detect.

Additionally, since chkrelease.sh does not verify file metadata, it is also possible that files may exist but have improper (insecure) permissions set on them.

Finally, though chkrelease.sh can handle a compressed tar file (e.g., a tarfile.tgz), the script runs an order of magnitude slower for such files since it needs to uncompress each file individually. It is therefore strongly encouraged to uncompress your tar files before feeding them to chkrelease.sh first.

To Do (aka. Feature Wish List)

There are still a number of things that chkrelease.sh can not do that I would like it to do, including:

• Check a filesystem against a tar file (instead of checking a tar file against a filesystem) to report on differences in files that exist on the filesystem but do not exist in the tar file
• Simplify deployment by adding something akin to a --deploy option so that a pipeline need not be used

Frequently Asked Questions (FAQ)

These are some frequently asked questions regarding the use of, rationale behind, and other curiosities about this project.

Can’t I just use Capistrano?

Yeah, that works, too. Of course, Capistrano and chkrelease do different things. Specifically, Capistrano is a remote server automation tool and chkrelease is a release-auditing tool. In other words, if you use Capistrano to automate some of your tasks, you might consider telling Capistrano to run chkrelease.sh at some point during those tasks.