Jump to: navigation, search

V3/Logging and output

Overview

The output, logging, and command-line options of our install/management tools are inconsistent. This RFE aims to clean up some of the inconsistency.

Specifically it addresses:

  • Inconsistencies between console output and log files
  • Tools using either --verbose or --debug used for the same purpose

And some collateral issues:

  • The --version option missing in some tools
  • The problem of e.g. an accidental ipa-server-install overwriting ipaserver-install.log by the useless message, "The server is already installed"

This is part of #2652 Framework for admin/install tools


Design

Each command will have these command-line options (added automatically by the framework):

 --version        show program's version number and exit
 -h, --help       show the help message and exit
 output and logging options:
   -q, --quiet    Output only errors
   -v, --verbose  Print debugging information
   --log-file     (alternate) log file name

The precise meanings of the output options are:

 (nothing): print INFO-level messages and above to stderr
 -q: only print ERROR-level messages and above to stderr
 -v: print all messages to stderr, prefixed with severity level

In all cases, if there is a log file, all messages go to it

In commands that currently have it, the `-d, --debug` option will become a deprecated alias for --verbose.

Note that this RFE only adds new options, so backwards compatibility is maintained.


The tools will use the following log message severities:

  • CRITICAL for fatal errors
  • ERROR for critical things that the admin must see even in --quiet mode
  • WARNING for things that need to stand out in the log
  • INFO to display normal messages
  • DEBUG to spam about everything the program does
  • a plain print statement for things that should not be log, for example interactive prompting should use the console and follow up with a DEBUG mentioning the final value


The commands check their arguments and most do some validation and possible interactive prompting before doing any modification of the system. Since the system is not changed, the user can always re-run with --verbose if there are problems in this phase. Logging information from this phase to a file is useless. The file logging will start after the validation/prompting. The first logged message(s) will mention the command and options used.


Use Cases

  1. User runs several /usr/sbin/ipa-* commands with the --help option
  2. User sees that the logging-related options are the same in all of those programs.
  1. User runs an ipa-* command with the -q option
  2. User only sees errors.
  1. User runs an ipa-* command (possibly with --log-file, if the command doesn't log by default)
  2. User later reviews the log file and finds all relevant information.


Implementation

The RFE will be implemented gradually as new commands are ported to the framework. The following table will be updated as work progresses.

Command --version --quiet --verbose --debug --log-file Changed in version
ipa-ldap-updater present added added present added 3.1 (e437491); 3.2 (55cfd06)
ipa-replica-prepare present added added present added 3.1 (f6a5647); 3.2 (26c4987)
ipa-server-certinstall added added added not added (-d means --dirsrv) added 3.3 (02214c4); 3.4 (02be7ac)
ipa-adtrust-install present - - present -
ipa-ca-install present - - present -
ipa-client-automount - - - present (no -d) -
ipa-client-install present - - present -
ipa-compat-manage - - - present -
ipa-csreplica-manage present - present - -
ipa-dns-install present - - present -
ipa-getkeytab - present - - -
ipa-join - present - present -
ipa-managed-entries - - - present -
ipa-nis-manage - - - present -
ipa-replica-conncheck present present - present -
ipa-replica-install present - - present -
ipa-replica-manage present - present - -
ipa-rmkeytab - - - present -
ipa-server-install present - - present -
ipa-upgradeconfig present present - present -
ipactl - - - present -

RFE author

Pviktorin