+@node Checking and querying, Complete grammar, Example configuration file, The configuration file
+@subsection Checking and querying the configuration file
+
+At a reasonably sized site, Become configuration files can get rather large,
+and becomes tricky to work out exactly who's allowed to do what and where.
+
+The @code{bcquery} tool provided allows Become configuration files to be
+verified and queried. It can be used to ensure that a file is syntactically
+correct before it is deployed, or to enquire about privileges granted.
+
+@menu
+* Verifying config files:: Checking a configuration file is correct
+* Querying config files:: Asking questions about privileges
+* Output formats:: Different ways of formatting output
+* Restricting output:: Being selective about what gets output
+* bcquery reference:: Complete command line reference
+@end menu
+
+@node Verifying config files, Querying config files, Checking and querying, Checking and querying
+@subsubsection Verifying configuration files
+
+A common use of @code{bcquery} is to ensure that a configuration file is
+actually valid. The command
+
+@example
+bcquery [-file @var{file}] -check
+@end example
+
+@noindent
+verifies that a configuration file conforms to Become's expectations. If
+there are any errors in @var{file}, they are reported, and @code{bcquery}
+will return a nonzero exit code.
+
+If no @var{file} is specified, @code{bcquery} will read the configuration
+file which Become itself reads by default, usually
+@code{/etc/become/become.conf}.
+
+
+@node Querying config files, Output formats, Verifying config files, Checking and querying
+@subsubsection Querying configuration files
+
+The @code{bcquery} program will list all rules which match a selected request
+pattern. For example, you can display all rules which allow a particular
+user to change identity, or all rules which allow people to assume root
+privileges on a particular host.
+
+@example
+bcquery [-file @var{file}] @var{query}
+@end example
+
+The following simple queries are supported:
+
+@table @asis
+@item @code{-from} @var{user}
+Matches any rule containing @var{user} in its `from' list.
+@item @code{-to} @var{user}
+Matches any rule containing @var{user} in its `to' list.
+@item @code{-host} @var{host}
+Matches any rule containing @var{host} in its host list.
+@item @code{-command} @var{cmd}
+Matches any rule containing @var{cmd} in its `command' list.
+@end table
+
+@noindent
+Simple queries can be combined using the following operators:
+
+@table @asis
+@item @var{query-a} @code{-or} @var{query-b}
+Matches a rule matched by either @var{query-a} or @var{query-b}.
+@item @var{query-a} @code{-and} @var{query-b}
+Matches a rule matched by both @var{query-a} and @var{query-b}.
+@item @code{-not} @var{query}
+Matches a rule which is not matched by @var{query}.
+@item @code{(} @var{query} @code{)}
+Matches a rule matched by @var{query} (overrides default precedence).
+@end table
+
+The @code{-and}, @code{-or} and @code{-not} operators may be written
+@code{&}, @code{|} and @code{!} respectively, if you prefer, and the
+@code{-and} operator is optional. These characters (and the parentheses
+@code{(} and @code{)}) may need to be quoted to prevent interpretation by the
+shell.
+
+Some examples may explain what's going on:
+
+@table @samp
+@item bcquery -from hacker
+Displays all rules applying to user `hacker'.
+@item bcquery -host somehost -to root
+Displays rules allowing people to become root on @code{somehost}.
+@end table
+
+
+@node Output formats, Restricting output, Querying config files, Checking and querying
+@subsubsection Output formats
+
+The @code{bcquery} program has two distinct output formats: `rows' and
+`columns'.
+
+The `columns' format is probably the simpler to understand, and certainly the
+easier to read. Each matching record is displayed with the lists of users,
+hosts and commands in columns. A query on the example configuration file
+(@pxref{Example configuration file}) is shown below:
+
+@example
+FROM TO HOST COMMAND
+
+frankie root ALL ALL
+selina
+
+fred news ALL ALL
+jim
+
+jim httpd www.somewhere.com /bin/kill
+bob /etc/init.d/httpd
+@end example
+
+@noindent
+The `columns' format can only show simple lists. A more complex class
+definition will show up as @samp{<complex>} in a `columns' format listing.
+
+The `rows' format is capable of displaying classes in their full generality,
+but is harder to parse and read. It displays each list in the form of an
+expression, in more or less the same syntax as a class definition
+(@pxref{Classes}).
+
+The default behaviour is to use `columns' format where possible, or `rows'
+format if some of the lists are too complex to be represented in columns.
+You can select a format explicitly using the @code{-columns} or @code{-rows}
+options, which is useful if you're trying to parse the output of
+@code{bcquery} with a script.
+
+
+@node Restricting output, bcquery reference, Output formats, Checking and querying
+@subsubsection Restricting output
+
+It's also possible to suppress bits of information about each matched rule.
+For example, you can show only the `from' list, or just the `to' and `host'
+lists. This is done with the @code{-output} option.
+
+Each list is given a letter; the `from' list is called @samp{f}, the `to'
+list @samp{t}, the host list @samp{h} and the command list @samp{c}. You can
+select which lists are displayed by giving the corresponding letters (the
+order isn't important). You can also turn individual lists on or off by
+preceding the characters with @samp{+} or @samp{-} characters. If you start
+with a @samp{+} or @samp{-}, then the last-set selection (or the initial
+default of all-lists-enabled) is modified.
+
+For example, @samp{-output ftc} shows only the `from', `to' and `command'
+lists. This could be written @samp{-output -h} too, to turn the hosts list
+off.
+
+This option is mainly useful with the `columns' output format (@pxref{Output
+formats}) to save scripts having to select columns out themselves.
+
+
+@node bcquery reference, , Restricting output, Checking and querying
+@subsubsection @code{bcquery} options summary
+
+@example
+bcquery [@var{option}@dots{}] [@var{query}]
+@end example
+
+The @var{option}s available are:
+
+@table @asis
+@item @code{-help}
+Displays a summary of the available options, and exits.
+
+@item @code{-file} @var{file}
+Read @var{file}, rather than the compiled-in default (usually
+@file{/etc/become/become.conf}).
+
+@item @code{-dump}
+Don't read a configuration file. Instead, display the query tree parsed from
+the command line. This is a debugging feature.
+
+@item @code{-check}
+Don't attempt to output any rules. Instead, just check the configuration
+file for validity.
+
+@item @code{-output} @var{spec}
+Selects which columns are to be displayed for each matching rule.
+For full details, see @ref{Restricting output}.
+
+@item @code{-columns}
+@itemx @code{-rows}
+Forces `columns' or `rows' output format. @xref{Output formats}.
+
+@item @code{-nohead}
+Suppress the header line at the top of the output in `columns' mode. Makes
+the output more amenable to automatic processing (but harder to read).
+
+@item @code{-from} @var{user}
+@itemx @code{-to} @var{user}
+@itemx @code{-host} @var{hostname}
+@itemx @code{-command} @var{cmd}
+Simple queries for selecting rules. @xref{Querying config files}.
+
+@item @code{-and}
+@itemx @code{-or}
+@itemx @code{-not}
+Operators for combining queries into something useful. @xref{Querying config
+files}.
+@end table
+
+
+@node Complete grammar, , Checking and querying, The configuration file