Inspect and Edit ICE Authority Files with iceauth

ICE authority files hold the cookies that let clients join an X session, and iceauth reads and edits them safely. Examples use iceauth 1.0.9 from Debian package x11-xserver-utils 7.7+10build2, as installed on this machine. Allow fifteen minutes.

You need: a shell and an authority file you are allowed to read. Root is not normally required.
Warning: authentication records contain secrets. Do not paste real cookies into tickets, chat or shell history. The example below uses a disposable file with a deliberately fake cookie.

1. Check the installed command

Confirm the binary and version before trusting the syntax below. These are ordinary, read-only commands:

$ command -v iceauth
/usr/bin/iceauth
$ iceauth -V
iceauth 1.0.9
$ dpkg-query -W -f='${Package} ${Version}\n' x11-xserver-utils
x11-xserver-utils 7.7+10build2

The command accepts an authority file with -f. Without it, iceauth uses whichever file the current session has selected, which is convenient for inspection but easy to overlook in a script meant to update a different file. Use an explicit -f path for anything repeatable.

Checkpoint: if iceauth -V reports a different version, check iceauth -u and the local manpage before copying these examples. The interface is small, but selector matching is implementation-sensitive.

2. Inspect the current file without changing it

Display the session's path before opening the file. If your desktop setup does not expose one, use the explicit path passed to the application or session that created it:

$ printf 'ICEAUTHORITY=%s\n' "${ICEAUTHORITY:-<not set>}"
ICEAUTHORITY=<not set>
$ iceauth info
$ iceauth list

An unset ICEAUTHORITY does not prove no authority file exists, only that the variable is not set. If you know the file, inspect it explicitly:

$ iceauth -f /path/to/authority info
$ iceauth -f /path/to/authority list

info gives file-level details, including whether it is locked and how many entries it holds. list prints the records themselves. Treat that output as sensitive: it includes protocol, network identifier, authentication name and authentication data, so avoid redirecting it to a shared log.

If iceauth reports that it is creating a new authority file, stop and check the path. A typo can turn a harmless inspection into a new file that is not the one your session actually uses.

3. Practise on a disposable file first

Do not test an edit against a live session file. This creates a temporary authority file, adds one record, displays it, and saves it. The values below are syntactically valid test data, not real credentials:

$ AUTHFILE=/tmp/iceauth-demo.$$.authority
$ trap 'rm -f "$AUTHFILE"' EXIT
$ printf '%s\n' \
    'add ICE 00 127.0.0.1/unix:10 MIT-MAGIC-COOKIE-1 0123456789abcdef0123456789abcdef' \
    'info' \
    'list' \
    'exit' | iceauth -f "$AUTHFILE" -v
iceauth:  creating new authority file /tmp/iceauth-demo.12345.authority
Authority file:       /tmp/iceauth-demo.12345.authority
Number of entries:    1
Changes made:         yes
ICE 00 127.0.0.1/unix:10 MIT-MAGIC-COOKIE-1 0123456789abcdef0123456789abcdef
Writing authority file /tmp/iceauth-demo.12345.authority

The process ID in the temporary path varies each run. The five fields after add are protocol name, protocol data, network ID, authentication name and authentication data; this implementation expects protocol data and authentication data in hexadecimal. Use values from the actual service or a trusted export for a real record, never a newly invented cookie.

exit saves the changes made during this session.
quit abandons them instead.

$ printf '%s\n' 'add ICE 00 example/unix:10 MIT-MAGIC-COOKIE-1 0123456789abcdef0123456789abcdef' 'quit' | iceauth -f "$AUTHFILE"
$ iceauth -f "$AUTHFILE" list
ICE 00 127.0.0.1/unix:10 MIT-MAGIC-COOKIE-1 0123456789abcdef0123456789abcdef

Checkpoint: a later list confirms what was actually saved. If a record is wrong, remove it before using the file, or discard the temporary file through the trap and start again.

4. Move records between files with a review point

For a remote login or another user, the usual pattern is to extract selected records from one authority file and merge them into another. A source file can hold several credentials, so narrow the extraction with the protocol, protocol data, network ID and authentication name selectors described by iceauth help extract, rather than copying the whole file without a reason:

$ iceauth help extract
extract entries into a file
extract filename <protoname=$> <protodata=$> <netid=$> <authname=$>

$ is the wildcard selector; replace it only where you mean to restrict a field. Write the extracted file into a protected temporary directory, inspect it under its own path, then merge it into the destination:

$ umask 077
$ WORKDIR=$(mktemp -d /tmp/iceauth-transfer.XXXXXX)
$ SOURCE=/path/to/source-authority
$ DEST=/path/to/destination-authority
$ iceauth -f "$SOURCE" extract "$WORKDIR/records" ICE '$' '127.0.0.1/unix:10' 'MIT-MAGIC-COOKIE-1'
$ iceauth -f "$WORKDIR/records" info
$ iceauth -f "$DEST" merge "$WORKDIR/records"
$ iceauth -f "$DEST" list

Do not run the merge while the destination application is actively rewriting the same file, unless it documents that as supported. Keep the transfer file private and remove it once you have confirmed the destination:

$ case "$WORKDIR" in
    /tmp/iceauth-transfer.*) rm -rf -- "$WORKDIR" ;;
    *) printf 'refusing to remove unexpected path: %s\n' "$WORKDIR" >&2; exit 1 ;;
esac

Destructive action: that removal is a recursive delete. Checking the path pattern first stops a bad $WORKDIR from taking something else with it.

5. Remove a record only after checking its selectors

remove deletes matching entries from the selected file once you save with exit. This is security-sensitive and can cut off clients that depend on the record. List the file first, copy the exact selectors, and back up a real file before changing it:

$ cp --preserve=mode,timestamps /path/to/authority /path/to/authority.before-iceauth
$ iceauth -f /path/to/authority list
$ iceauth -f /path/to/authority
iceauth> remove ICE 00 127.0.0.1/unix:10 MIT-MAGIC-COOKIE-1
iceauth> list
iceauth> quit

This example ends with quit, so the removal is discarded while you review the result. Re-run it and use exit only once you have confirmed the match is the record you actually mean to remove.

Recovery: restore from the backup, but only after checking that no newer authority changes would be overwritten by doing so.

6. Treat locks as a warning, not an obstacle

iceauth locks the authority file while it works, and info reports the lock state.

-i ignores locking entirely, which can let concurrent writers corrupt or overwrite each other's changes.
-b breaks locks outright, and is even more disruptive.

Use either option only after identifying the process holding a stale lock and following your session or distribution's recovery procedure. Do not solve an access error by reaching for sudo automatically: root may create a file it now owns, or expose credentials in a privileged shell history. Fix ownership and permissions deliberately, and keep the authority file's private mode: it should never be world-readable.

Done means

You confirmed the installed iceauth version and selected the intended authority file explicitly.
You inspected info and list output without publishing authentication data.
You tested add, exit and quit against disposable data before touching a live file.
You narrowed transfers before merge and kept extracted records private.
You backed up a real file before remove and know how to abandon an unsaved change.
You left locks alone unless you had diagnosed a stale lock and accepted the concurrency risk.