Query ucf's Configuration Database with ucfq

You will use ucfq to answer a practical packaging question: which package registered a configuration file, does the file still exist, and has a user changed it? The command reads ucf's database and reports status without editing the file or accepting a configuration choice.

Allow about ten minutes. You need a shell and the Debian or Ubuntu ucf package. The examples were checked with package version 3.0043+nmu1 on this machine. They only query state, so they normally need no elevated privileges.

1. Confirm the installed command

Check which executable will run, then read the installed command's help:

$ command -v ucfq
/usr/bin/ucfq
$ ucfq --help
Usage: ucfq [options]
Author: Manoj Srivastava <[email protected]>
  where options are:
 --help                This message.
 --debug               Turn on debugging mode.
 --verbose             Make the script more verbose.
 --with-colons         A compact, machine readable version of the output.
 --state-dir </path/>  Set the state directory to /path/ instead of the
                       default /var/lib/ucf.

The installed help confirms the useful options: human-readable output by default, colon-separated output for scripts, extra diagnostics, and an alternate state directory. The man page calls the command a query of the ucf database.

2. Query a package name

Pass a package name when you want all registered files associated with that package:

$ ucfq unattended-upgrades
Configuration file                            Package             Exists Changed
/etc/apt/apt.conf.d/20auto-upgrades           unattended-upgrades Yes     No
/etc/apt/apt.conf.d/50unattended-upgrades     unattended-upgrades Yes     No

The first column is the registered configuration path. Package identifies the owning package recorded by ucf. Exists tells you whether the path is present on disk. Changed tells you whether the installed file differs from the version tracked by ucf.

Package arguments must not contain a slash. If you have a path, pass the full path instead. A package with no matching ucf records may produce only the headings, so an empty result is not proof that the package is absent.

$ ucfq /etc/apt/apt.conf.d/20auto-upgrades
Configuration file                            Package             Exists Changed
/etc/apt/apt.conf.d/20auto-upgrades           unattended-upgrades Yes     No

3. Query a file path directly

A full path is the most useful form when diagnosing one file. It also shows an important limitation: a path can exist without being registered with ucf.

$ ucfq /etc/ucf.conf
Configuration file                            Package             Exists Changed
/etc/ucf.conf                                                     Yes

Here Exists is Yes, but the package and changed columns are blank. That means the file exists on disk and this query did not find an associated ucf record. Do not infer a package owner from the filename. Check package ownership separately with your package manager when that is the question you need to answer.

For a missing path, the command keeps the path but has no package, existence or changed value:

$ ucfq /tmp/ucfq-no-such-file
Configuration file                            Package             Exists Changed
/tmp/ucfq-no-such-file

That output is a report, not an error message. Preserve the path and inspect the columns if you are turning the result into a diagnostic.

4. Request machine-friendly output

Use --with-colons, or its short form -w, when a script needs stable separators instead of headings and aligned columns:

$ ucfq --with-colons unattended-upgrades
/etc/apt/apt.conf.d/20auto-upgrades:unattended-upgrades:Yes:No
/etc/apt/apt.conf.d/50unattended-upgrades:unattended-upgrades:Yes:No
$ ucfq -w /tmp/ucfq-no-such-file
/tmp/ucfq-no-such-file:::

The fields are path, package, exists and changed. Empty fields remain empty, so do not split a record and assume every field has a value. A path or package name containing a colon would also need careful handling in a parser; use the format for the ordinary ucf data it is designed to report, and validate input before using it in automation.

Capture the command's status separately from its text. A successful query can still report an unregistered or missing file. Conversely, a non-zero status means the query itself needs investigation rather than that the file is necessarily changed.

5. Use an alternate state directory only for a deliberate comparison

ucfq normally reads ucf state from /var/lib/ucf. The --state-dir option points it at another directory, which is useful for testing or examining a prepared copy:

$ state_dir='/path/to/ucf-state-copy'
$ ucfq --state-dir "$state_dir" /etc/apt/apt.conf.d/20auto-upgrades

Replace the placeholder with a directory containing the state you intend to inspect. An empty or unrelated directory can make valid registrations appear to be missing. This option does not migrate state, repair the database or change the default location.

Do not point it at an arbitrary directory while trying to repair a problem. First make a read-only copy using your normal backup process, then query that copy explicitly. If permissions prevent a normal query of the real state directory, investigate ownership and access before reaching for sudo; elevated privileges are not normally required for the standard command.

6. Avoid the common interpretation traps

• Changed is not the same as broken. It indicates a difference from ucf's recorded version. Review the file and package policy before overwriting anything.
• Exists is not ownership. A present file with blank package data may simply be outside ucf's registry.
• A package query is not a package installation check. It reports registered configuration records, not every file shipped by a package.
• Verbose and debug output is for investigation. Do not parse it as the compact format; use --with-colons for automation.

There is no undo step for these examples because they only read the database and filesystem metadata. If a later command proposes replacing a changed configuration file, stop and make a backup before accepting that change.