Where is official documentation about locking mechanisms for etckeeper, apt, and/or dpkg?

Question

Context:

Want to put a lock on etckeeper/apt hook activity during special backup.

Objective is to preserve whole package integrity, e.g., wait until any package installation is complete, and then prevent new installation from starting until special backup is complete.

Found shell script under cron which appears to be attempting to a lock on

/var/cache/etckeeper/packagelist.pre-install

but actually it is not performed atomically and so it is flawed. I presume the cron shell script is part of Ubuntu 16.04 installation, not a part of etckeeper release. Flawed lock code shown below.

Searched for etckeeper documentation about use of /var/cache/etckeeper/packagelist.pre-install as lock file. Found no documentation. But did find a piece of script file which writes to /var/cache/etckeeper/packagelist.pre-install without treating it as a lock file. At this time I am presuming that /var/cache/etckeeper/packagelist.pre-install is not intended to serve as a lock file interface for etckeeper. Etckeeper internal script not treating /var/cache/etckeeper/packagelist.pre-install as a lock file shown below.

Question 1: Is there (and if so where is) documentation on etckeeper locking mechanism, or a developers portal to issue a requestion for clarification?

There are plenty of questions and much discussion on stackexchange sites about the use of

/var/lib/apt/lists/lock    (we call it apt lock below)

and

/var/lib/dpkg/lock     (we call it dpkg lock below)

as locks for apt and dpkg respectively. All of the communications are concerned with stuck locks, how to diagnose them, and how to unstick them. However, I kind find no references to official apt and dpkg documentation specifying those lock files use as a formal interface.

Question 2: Is there (and if so where is) documentation on apt lock mechanism and/or dpkg lock mechanism as public interfaces?

Flawed lock attempt shell script, probably provided by Ubuntu 16.04:

$ sudo cat /etc/cron.daily/etckeeper
#!/bin/sh
set -e
if [ -x /usr/bin/etckeeper ] && [ -e /etc/etckeeper/etckeeper.conf ]; then
    . /etc/etckeeper/etckeeper.conf
    if [ "$AVOID_DAILY_AUTOCOMMITS" != "1" ]; then
        # avoid autocommit if an install run is in progress
        lockfile=/var/cache/etckeeper/packagelist.pre-install
        if [ -e "$lockfile" ] && [ -n "$(find "$lockfile" -mtime +1)" ]; then
            rm -f "$lockfile" # stale
        fi
        if [ ! -e "$lockfile" ]; then
            AVOID_SPECIAL_FILE_WARNING=1
            export AVOID_SPECIAL_FILE_WARNING
            if etckeeper unclean; then
                etckeeper commit "daily autocommit" >/dev/null
            fi
        fi
    fi
fi

Etckeeper internal shell scipt writing to packagelist.pre-install and not treating it as a lock - hence I don't think it was intended as a lock interface.

$ sudo cat /etc/etckeeper/pre-install.d/10packagelist 
#!/bin/sh
# This list will be later used when committing.
mkdir -p /var/cache/etckeeper/
etckeeper list-installed > /var/cache/etckeeper/packagelist.pre-install
etckeeper list-installed fmt > /var/cache/etckeeper/packagelist.fmt

Answer 1

1. The cron job is treating /var/cache/etckeeper/packagelist.pre-install as evidence that an installation is being processed, so it shouldn’t archive anything just yet. That file isn’t supposed to be a lock file, but the cron job is using it as a substitute.

   However I wouldn’t particularly worry about etckeeper and any lock files it has or hasn’t. If you want a consistent backup of an etckeeper managed tree, use the VCS’s features (but don’t forget any ignored files).

2. The dpkg locks are documented (albeit briefly) as public interfaces in frontend.txt (/usr/share/doc/dpkg-dev/frontend.txt in dpkg-dev).