From 705ce9573edf8e03b5d9087fbddbd0fc05c568ae Mon Sep 17 00:00:00 2001 From: David Howells Date: Tue, 9 Jun 2020 13:36:44 +0100 Subject: [PATCH] man: Add kafs-dns(8) Add a manual page for the kafs-dns internal helper program as Debian doesn't put it in /usr/libexec/ but rather puts it in /usr/bin/. Reported-by: Bill MacAllister Signed-off-by: David Howells --- man/kafs-dns.8 | 123 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 man/kafs-dns.8 diff --git a/man/kafs-dns.8 b/man/kafs-dns.8 new file mode 100644 index 0000000..c0accc3 --- /dev/null +++ b/man/kafs-dns.8 @@ -0,0 +1,123 @@ +.\" +.\" Copyright (C) 2020 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" +.TH KAFS-DNS 8 "9 Jun 2020" Linux "AFS kernel address resolver" +.SH NAME +kafs-dns \- AFS filesystem address resolution helper +.SH SYNOPSIS +\fB/usr/libexec/kafs-dns\fR [OPTION]... +.br +\fB/usr/libexec/kafs-dns\fR -D [OPTION]... +.br +\fB/usr/libexec/kafs-dns\fR -V +.PP +Where options are: +.PP +.RS +[-v] [-c ]* [-N ] [-o ] +.RE +.SH DESCRIPTION +This program is invoked by the +.BR request-key (8) +kernel upcall handling program to handle an address resolution request on +behalf of the in-kernel AFS filesystem driver to find the Volume Location +servers for a cell. It is capable of using static configuration, NSS and DNS +SRV and AFSDB record lookups. +.PP +Note that this program is not meant to be called directly, though it does have +a debugging mode that can be used. +.PP +The first form of the command, without the \fB-D\fR flag cannot be called +directly as it requires an under-construction kernel key as its parameter. +.PP +The debugging form, in which \fB-D\fR is given, doesn't require a key, but +must be given a proposed key description and a callout information string. +Information about what it is doing is dumped to the output. The result blob +may be binary and so is not dumped to stdout, but can be dumped to a file with +\fB-o\ \fR. +.PP +The available options are: +.SH ARGUMENTS +.IP -D +Execute in debug mode. +.IP -v +Increase the verbosity of the output. This may be specified multiple times. +.IP "-c " +Specify a configuration file to read instead of the system default. This may +be specified multiple times and the configuration files are read and applied in +order. +.IP "-N " +Apply a restriction to the lookup performed for the listed cells (if any are). +Restrictions include: +.RS +.IP "-N vl-srv" +Don't use SRV records to find Volume Location servers. +.IP "-N vl-afsdb" +Don't use AFSDB records to find Volume Location servers. +.IP "-N vl-all" +Don't use SRV or AFSDB records to find Volume Location servers. +.IP "-N vl-host" +Don't look cell name up as hostname to find a Volume Location server. +.IP "-N vl-dns" +Don't do any lookups to find Volume Location servers. Use only the static +configuration. +.RE +.IP "-o " +Specify a file in which to dump the proposed payload with which to instantiate +a resolver key. +.IP "-V" +Display version information and exit. +.PP +The key description, \fB\fR, should be the name of a cell prefixed by +"afsdb:". +.PP +The callout information string, \fB\fR, is a comma separated list +of none or more of the following items: +.IP "ipv4" +Get IPv4 addresses only. +.IP "ipv6" +Get IPv6 addresses only. +.IP "srv=" +Allow the extra information that can be gleaned from SRV records to be +rendered as output format \fB\fR, where is a number. +.SH EXIT STATUS +.IP 0 +On success. +.IP 1 +If an error occurs during processing. +.IP 2 +If a command line error occurs. +.IP 3 +If bad configuration is detected. +.SH EXAMPLE +.PP +The program can be called with something like: +.PP +.RS +.nf +/usr/libexec/kafs-dns -D afsdb:example.com srv=1 +.fi +.RE +.PP +The program can also be invoked indirectly with something like: +.PP +.RS +.nf +keyctl request2 dns_resolver afsdb:example.com srv=1 @s +.fi +.RE +.PP +which will return the serial number of a key that can then be displayed. +.SH SEE ALSO +.ad l +.nh +.BR kafs (7), +.BR kafs\-client.conf (5), +.BR keyctl (1), +.BR request-key (8) -- 2.50.1