- What I did

Add a new zsh function to the completion file contrib/completion/zsh/_docker.

The bulk of the function is copy and paste from the documentation of --cap-add (Subject to review: I barely read through them, assuming the docs on the web are a good initial version. I did not investigate if the list of capabilities can be obtained in an automated manner.).

The function is called when tab completing docker run --cap-add= (or drop).

The suggested completion should look like that (depending on a user's configuration of zsh's tab completion):

>> docker run --cap-add=
special capability value:
ALL  -- enable/disable all capabilities
off by default capabilities:
AUDIT_CONTROL    -- Enable and disable kernel auditing; change auditing filter rules; retrieve auditing st
BLOCK_SUSPEND    -- Employ features that can block system suspend.
DAC_READ_SEARCH  -- Bypass file read permission checks and directory read and execute permission checks.
IPC_LOCK         -- Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)).
...

The function checks:

if --cap-add or --cap-drop is completed. In the former case, off-by-default capabilities are suggested. In the latter case on-by-default capabilities are suggested (I took that idea from the bash completion).
if --cap-add=ALL or --cap-drop=ALL are present on the current command line. If --cap-add=ALL is present in the command line, then --cap-drop= will also suggest off-by-default capabilities (and vice versa). This should look something like that:

special capability value:
ALL  -- enable/disable all capabilities
on by default capabilities:
AUDIT_WRITE       -- Write records to kernel auditing log.
CHOWN             -- Make arbitrary changes to file UIDs and GIDs (see chown(2)).
...
off by default capabilities:
AUDIT_CONTROL    -- Enable and disable kernel auditing; change auditing filter rules; retrieve auditing st
BLOCK_SUSPEND    -- Employ features that can block system suspend.
DAC_READ_SEARCH  -- Bypass file read permission checks and directory read and execute permission checks.
...

The function does not check any other already-present settings of --cap-add. I.e. docker run --cap-add=BLOCK_SUSPEND --cap-add=<TAB> will still suggest BLOCK_SUSPEND as option. (Subject for discussion. My impression is it's not worth increasing the complexity of the completion function for such a corner case.)

- How I did it

Sticking to zsh's builtin features. I use the opt_args associative array to detect what's already specified in --cap-add on the command line. If the option is given multiple times, $opt_args[--cap-add] will be colon separated. I didn't add any logic to handle that case but rely on *ALL* matching exactly the ALL value and ALL doesn't occur in any other capability.

- How to verify it

Typed interactively a few examples

docker run --cap-add=<TAB>

docker run --cap-drop=<TAB>

docker run --cap-add=ALL --cap-drop=<TAB>

docker run --cap-add=DAC_READ_SEARCH --cap-add=ALL --cap-add=MAC_OVERRIDE --cap-drop=<TAB>

- Description for the changelog

Add suggestions for docker run --cap-{add,drop}=<TAB> in the zsh completion

- A picture of a cute animal (not mandatory but encouraged)

May 01 '20 18:05 pseyfert

ping?

Sep 16 '20 20:09 pseyfert

rebased

Jan 14 '21 23:01 pseyfert

Codecov Report

Merging #2485 (34f478a) into master (cde469b) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #2485   +/-   ##
=======================================
  Coverage   57.04%   57.04%           
=======================================
  Files         297      297           
  Lines       18655    18655           
=======================================
  Hits        10641    10641           
  Misses       7154     7154           
  Partials      860      860

Jan 14 '21 23:01 codecov-io

What's your (docker's) status on this one? From my side it's good to merge. Just rebased onto current master.

Mar 05 '21 08:03 pseyfert

ping?

any more review comments?
happy with my responses to the previous round of comments?
happy to merge as-is or should we close this pr and start over from the current master branch?

Aug 25 '22 19:08 pseyfert

zsh completion: complete capabilities after --cap-{add,drop}

Codecov Report