[Pki-devel] [PATCH] 623 Added pki-audit man page.
Endi Sukma Dewata
edewata at redhat.com
Fri Jul 17 22:29:31 UTC 2015
On 7/15/2015 5:13 PM, Endi Sukma Dewata wrote:
> Thanks for the comments. Please take a look at the updated patch.
>
> On 7/14/2015 12:17 PM, Matthew Harmsen wrote:
>> This was a little confusing as the ticket is for a kra-audit man page.
>> I think I understand a bit better after reading comment #4,
>
> Yes, the command is removed from all subsystems except TPS because of
> the database upgrade requirement.
>
>> however, I
>> still have the following questions/comments:
>>
>> * What is '<TPS admin authentication>', and how does one obtain this?
>
> I added a reference to the Authentication section in pki(1) and an
> explanation that the user must be in the Administrators group.
>
>> * The 'pki tps-audit-mod --help' command shows the following:
>>
>> usage: tps-audit-mod [OPTIONS...]
>> --action <action> Action: update (default), enable, disable.
>> --help Show help options
>> --input <file> Input file containing audit configuration.
>> --output <file> Output file to store audit configuration.
>>
>> where the man page does not talk about the 'update (default)' switch
>> for the '--action <action>' option.
>>
>> One or more EXAMPLES would be nice, although this will probably suffice
>> for the first pass at a man page.
>
> To clarify this I created a separate description for each usage:
> * pki tps-audit-mod --action <action>
> * pki tps-audit-mod --input <file path>
>
> I removed the "update (default)" from the CLI since it can be confusing.
Please take a look at the new patch (#623-2). The patch now contains
just the new pki-audit man page and line wrapping in the pki man page.
The CLI changes to remove the non-working command from non-TPS
subsystems have been posted as a separate patch (#636).
--
Endi S. Dewata
-------------- next part --------------
>From 32c8296725bd02492a8b06b22fe19829fd56914a Mon Sep 17 00:00:00 2001
From: "Endi S. Dewata" <edewata at redhat.com>
Date: Tue, 30 Jun 2015 11:33:02 -0400
Subject: [PATCH] Added pki-audit man page.
A new man page has been added for the pki <subsystem>-audit CLI.
Due to database upgrade issue the command is currently only
available in TPS.
https://fedorahosted.org/pki/ticket/1437
---
base/java-tools/man/man1/pki-audit.1 | 104 +++++++++++++++++++++++++++++++++++
base/java-tools/man/man1/pki.1 | 10 +++-
specs/pki-core.spec | 1 +
3 files changed, 113 insertions(+), 2 deletions(-)
create mode 100644 base/java-tools/man/man1/pki-audit.1
diff --git a/base/java-tools/man/man1/pki-audit.1 b/base/java-tools/man/man1/pki-audit.1
new file mode 100644
index 0000000000000000000000000000000000000000..e1c84885035df9bf831090a916c931b403b53a9c
--- /dev/null
+++ b/base/java-tools/man/man1/pki-audit.1
@@ -0,0 +1,104 @@
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH pki-audit 1 "Jun 30, 2015" "version 10.2" "PKI Audit Management Commands" Dogtag Team
+.\" Please adjust this date whenever revising the man page.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh disable hyphenation
+.\" .hy enable hyphenation
+.\" .ad l left justify
+.\" .ad b justify to both left and right margins
+.\" .nf disable filling
+.\" .fi enable filling
+.\" .br insert line break
+.\" .sp <n> insert n+1 empty lines
+.\" for man page specific macros, see man(7)
+.SH NAME
+pki-audit \- Command-Line Interface for managing Certificate System audit configuration.
+
+.SH SYNOPSIS
+.nf
+\fBpki\fR [CLI options] \fB<subsystem>-audit\fR
+\fBpki\fR [CLI options] \fB<subsystem>-audit-show\fR [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-audit-mod --action <action>\fR [command options]
+\fBpki\fR [CLI options] \fB<subsystem>-audit-mod --input <input file>\fR [command options]
+.fi
+
+.SH DESCRIPTION
+.PP
+The \fBpki-audit\fR commands provide command-line interfaces to manage audit
+configuration in the specified subsystem. Currently the only valid subsystem
+is \fBtps\fR.
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-audit\fR
+.RS 4
+This command is to list the available audit commands the subsystem.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-audit-show\fR [command options]
+.RS 4
+This command is to show the audit configuration in the subsystem.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-audit-mod --action <action>\fR [command options]
+.RS 4
+This command is to the audit status in the subsystem.
+.RE
+.PP
+\fBpki\fR [CLI options] \fB<subsystem>-audit-mod --input <input file>\fR [command options]
+.RS 4
+This command is to modify the audit configuration in the subsystem.
+.RE
+
+.SH OPTIONS
+The CLI options are described in \fBpki\fR(1).
+
+.SH OPERATIONS
+To view available audit commands, type \fBpki <subsystem>-audit\fP. To view
+each command's usage, type \fB pki <subsystem>-audit-<command> \-\-help\fP.
+
+All audit commands must be executed with the subsystem's admin authentication
+(the user must be in the Administrators group). See also the Authentication
+section in \fBpki\fP(1).
+
+.SS Viewing audit configuration
+
+To view the audit configuration in TPS execute the following command:
+
+.B pki <TPS admin authentication> tps-audit-show
+
+To download the audit configuration from TPS into a file execute the following
+command:
+
+.B pki <TPS admin authentication> tps-audit-show --output <output file>
+
+.SS Changing audit status
+
+To enable/disable audit in TPS execute the following command:
+
+.B pki <TPS admin authentication> tps-audit-mod --action <action>
+
+where action is enable or disable.
+
+.SS Modifying audit configuration
+
+To modify the audit configuration in TPS, download the current configuration
+using the above \fBtps-audit-show\fP command, edit the file, then execute the
+following command:
+
+.B pki <TPS admin authentication> tps-audit-mod --input <input file>
+
+Optionally, a --output <output file> option may be specified to download the
+effective configuration after the modification.
+
+.SH AUTHORS
+Endi S. Dewata <edewata at redhat.com>.
+
+.SH COPYRIGHT
+Copyright (c) 2015 Red Hat, Inc. This is licensed under the GNU General Public
+License, version 2 (GPLv2). A copy of this license is available at
+http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
+
+.SH SEE ALSO
+.BR pki(1)
diff --git a/base/java-tools/man/man1/pki.1 b/base/java-tools/man/man1/pki.1
index 41ee3d3da10adfa77fa94856d9829f5e6c2ecb78..3de8f6e922755f9550d57dcba4695bd5aff1d1ae 100644
--- a/base/java-tools/man/man1/pki.1
+++ b/base/java-tools/man/man1/pki.1
@@ -102,7 +102,9 @@ Alternatively, the connection parameters can be specified as a URI:
where the URI is of the format \fI<protocol>://<hostname>:<port>\fP.
.SS Authentication
-Some commands require authentication. These are commands that are restricted to particular sets of users (such as agents or admins) or those operations involving certificate profiles that require authentication.
+Some commands require authentication. These are commands that are restricted
+to particular sets of users (such as agents or admins) or those operations
+involving certificate profiles that require authentication.
To execute a command without authentication:
@@ -133,7 +135,11 @@ To authenticate with a username by interactively prompting for a password:
Prompting for a user password is not suitable for automated batch processing.
.SS Client Authentication Setup
-A client certificate associated with the desired PKI server must be used for client authentication. This can be done by importing the client certificate into an NSS security database and passing the values to the relevant options provided by the \fBpki\fP CLI framework.
+
+A client certificate associated with the desired PKI server must be used for
+client authentication. This can be done by importing the client certificate
+into an NSS security database and passing the values to the relevant options
+provided by the \fBpki\fP CLI framework.
To achieve this, execute the following commands to set up an NSS security database for use by the \fBpki\fP client, import the client certificate into the NSS database, and list information (including the nickname of the client certificate) stored in the NSS database:
diff --git a/specs/pki-core.spec b/specs/pki-core.spec
index 06fd9c7d333c424705a416c655098176df7e7a73..5ab8c841aea250e693fe95fd76847a76cbfa0b81 100644
--- a/specs/pki-core.spec
+++ b/specs/pki-core.spec
@@ -859,6 +859,7 @@ systemctl daemon-reload
%{_javadir}/pki/pki-tools.jar
%{_datadir}/pki/java-tools/
%{_mandir}/man1/pki.1.gz
+%{_mandir}/man1/pki-audit.1.gz
%{_mandir}/man1/pki-cert.1.gz
%{_mandir}/man1/pki-client.1.gz
%{_mandir}/man1/pki-group.1.gz
--
1.9.3
More information about the Pki-devel
mailing list