Add man page and clarify CLI for kra-connector

4 files changed, 172 insertions, 17 deletions

diff --git a/base/java-tools/man/man1/pki-ca-kraconnector.1 b/base/java-tools/man/man1/pki-ca-kraconnector.1
new file mode 100644
index 000000000..5cea6ad29
--- /dev/null
+++ b/base/java-tools/man/man1/pki-ca-kraconnector.1
@@ -0,0 +1,98 @@
+.\" 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-ca-kraconnector 1 "June 10, 2016" "version 10.3" "PKI CA-KRA Connector 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-ca-kraconnector \- Command-Line Interface for managing CA-KRA connectors.
+
+.SH SYNOPSIS
+.nf
+\fBpki\fR [CLI options] \fBca-kraconnector\fR
+\fBpki\fR [CLI options] \fBca-kraconnector-show\fR
+\fBpki\fR [CLI options] \fBca-kraconnector-add\fR --input-file <input file> | --host <KRA host> --port <KRA port>
+\fBpki\fR [CLI options] \fBca-kraconnector-del\fR --host <KRA host> --port <KRA port>
+.fi
+
+.SH DESCRIPTION
+.PP
+The \fBpki-ca-kraconnector\fR commands provide command-line interfaces to manage CA-KRA
+connectors.  This command should be applied against CAs only.
+
+When keys are archived, the CA communicates with the KRA through authenticated
+persistent connections called Connectors.  Because the CA initiates the communication,
+the connector configuration is performed on the CA only.  A Connector is automatically
+configured on the issuing CA whenever a KRA is set up by \fBpkispawn\fR.
+
+A CA may have only one KRA connector.  This connector can be configured to talk to
+multiple KRAs (for high availability) only if the KRAs are clones.
+.PP
+\fBpki\fR [CLI options] \fBca-kraconnector\fR
+.RS 4
+This command is to list available KRA connector commands.
+.RE
+.PP
+\fBpki\fR [CLI options] \fBca-kraconnector-show\fR
+.RS 4
+This command is to view the configuration settings for the CA-KRA connector configured
+on the CA.  These details can be redirected to a file, modified as needed, and used as the
+input file for the \fBca-kraconnector-add\fR command.
+.RE
+.PP
+\fBpki\fR [CLI options] \fBca-kraconnector-add\fR --input-file <input_file>
+.RS 4
+This command is to configure the CA-KRA connector on the CA subsystem.  The input file
+is an XML document as provided by the \fBca-kraconnector-show\fR command.
+
+A CA-KRA connector can only be created from an input file only if a connector does not already
+exist.  If one already exists, it should be removed first.
+.RE
+.PP
+\fBpki\fR [CLI options] \fBca-kraconnector-add\fR --host <KRA host> --port <KRA Port>
+.RS 4
+This command is to add a host to an existing CA-KRA connector.
+.RE
+.PP
+\fBpki\fR [CLI options] \fBca-kraconnector-del\fR --host <KRA Host> --port <KRA Port>
+.RS 4
+This command is to delete a host from the CA-KRA connector on a CA.  If the last KRA
+host is removed, the connector configuration is removed from the CA.
+.RE
+
+.SH OPTIONS
+The CLI options are described in \fBpki\fR(1).
+
+.SH OPERATIONS
+To view available CA-KRA connector commands, type \fBpki ca-kraconnector\fP. To view each command's usage, type \fB pki ca-kraconnector-<command> \-\-help\fP.
+
+All CA-KRA connector commands must be executed as the CA administrator.
+
+To retrieve the CA-KRA connector configuration from the CA:
+
+.B pki <CA admin authentication> ca-kraconnector-show
+
+One of the most common use cases for these commands is to add a KRA clone to an existing CA-KRA connector for
+high availability.  This can be done using the pki ca-kraconnector-add command as shown:
+
+.B pki <CA admin authentication> ca-kraconnector-add --host kra2.example.com --port 8443
+
+To delete a KRA clone from the connector:
+
+.B pki <CA admin authentication> ca-kraconnector-del --host kra2.example.com --port 8443
+
+.SH AUTHOR
+Ade Lee <alee@redhat.com>.
+
+.SH COPYRIGHT
+Copyright (c) 2016 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.
diff --git a/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorAddCLI.java b/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorAddCLI.java
index aa92bee34..7327c40de 100644
--- a/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorAddCLI.java
+++ b/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorAddCLI.java
@@ -24,8 +24,10 @@ import javax.xml.bind.JAXBContext;
 import javax.xml.bind.Unmarshaller;
 
 import org.apache.commons.cli.CommandLine;
+import org.apache.commons.cli.Option;
 import org.apache.commons.cli.ParseException;
 
+import com.netscape.certsrv.system.ConnectorNotFoundException;
 import com.netscape.certsrv.system.KRAConnectorInfo;
 import com.netscape.cmstools.cli.CLI;
 import com.netscape.cmstools.cli.MainCLI;
@@ -40,10 +42,27 @@ public class KRAConnectorAddCLI extends CLI {
     public KRAConnectorAddCLI(KRAConnectorCLI kraConnectorCLI) {
         super("add", "Add KRA Connector", kraConnectorCLI);
         this.kraConnectorCLI = kraConnectorCLI;
+
+        createOptions();
     }
 
     public void printHelp() {
-        formatter.printHelp(getFullName() + " <File Name> [OPTIONS...]", options);
+        formatter.printHelp(
+                getFullName() + " --input-file <file> | --host <KRA host> --port <KRA port>", options);
+    }
+
+    public void createOptions() {
+        Option option = new Option(null, "host", true, "KRA host");
+        option.setArgName("host");
+        options.addOption(option);
+
+        option = new Option(null, "port", true, "KRA port");
+        option.setArgName("port");
+        options.addOption(option);
+
+        option = new Option(null, "input-file", true, "Input file");
+        option.setArgName("input-file");
+        options.addOption(option);
     }
 
     public void execute(String[] args) throws Exception {
@@ -66,20 +85,47 @@ public class KRAConnectorAddCLI extends CLI {
 
         String[] cmdArgs = cmd.getArgs();
 
-        if (cmdArgs.length < 1) {
-            System.err.println("Error: No file name specified.");
+        if (cmdArgs.length != 0) {
+            System.err.println("Error: Too many arguments specified.");
             printHelp();
             System.exit(-1);
         }
 
-        FileInputStream fis = new FileInputStream(cmdArgs[0].trim());
+        String kraHost = cmd.getOptionValue("host");
+        String kraPort = cmd.getOptionValue("port");
+        String inputFile = cmd.getOptionValue("input-file");
 
-        JAXBContext context = JAXBContext.newInstance(KRAConnectorInfo.class);
-        Unmarshaller unmarshaller = context.createUnmarshaller();
-        KRAConnectorInfo info = (KRAConnectorInfo) unmarshaller.unmarshal(fis);
-
-        kraConnectorCLI.kraConnectorClient.addConnector(info);
+        //check if connector exists
+        boolean connectorExists = true;
+        try {
+            @SuppressWarnings("unused")
+            KRAConnectorInfo info = kraConnectorCLI.kraConnectorClient.getConnectorInfo();
+        } catch (ConnectorNotFoundException e) {
+            connectorExists = false;
+        }
 
-        MainCLI.printMessage("Added KRA Connector");
+        if (inputFile != null) {
+            if (connectorExists) {
+                System.err.println("Error: Cannot add new connector from file.  " +
+                        "Delete the existing connector first");
+                System.exit(-1);
+            }
+            FileInputStream fis = new FileInputStream(inputFile);
+            JAXBContext context = JAXBContext.newInstance(KRAConnectorInfo.class);
+            Unmarshaller unmarshaller = context.createUnmarshaller();
+            KRAConnectorInfo info = (KRAConnectorInfo) unmarshaller.unmarshal(fis);
+
+            kraConnectorCLI.kraConnectorClient.addConnector(info);
+            MainCLI.printMessage("Added KRA connector");
+
+        } else {
+            if (!connectorExists) {
+                System.err.println("Error: Cannot add new host to existing connector.  " +
+                        "No connector currently exists");
+                System.exit(-1);
+            }
+            kraConnectorCLI.kraConnectorClient.addHost(kraHost, kraPort);
+            MainCLI.printMessage("Added KRA host \"" + kraHost + ":" + kraPort + "\"");
+        }
     }
 }
diff --git a/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorRemoveCLI.java b/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorRemoveCLI.java
index 5f0f63b1a..562ee542a 100644
--- a/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorRemoveCLI.java
+++ b/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorRemoveCLI.java
@@ -20,6 +20,7 @@ package com.netscape.cmstools.system;
 import java.util.Arrays;
 
 import org.apache.commons.cli.CommandLine;
+import org.apache.commons.cli.Option;
 
 import com.netscape.cmstools.cli.CLI;
 import com.netscape.cmstools.cli.MainCLI;
@@ -34,10 +35,22 @@ public class KRAConnectorRemoveCLI extends CLI {
     public KRAConnectorRemoveCLI(KRAConnectorCLI kraConnectorCLI) {
         super("del", "Remove KRA connector from CA", kraConnectorCLI);
         this.kraConnectorCLI = kraConnectorCLI;
+
+        createOptions();
     }
 
     public void printHelp() {
-        formatter.printHelp(getFullName() + " <KRA Host> <KRA Port> [OPTIONS...]", options);
+        formatter.printHelp(getFullName() + " [OPTIONS...]", options);
+    }
+
+    public void createOptions() {
+        Option option = new Option(null, "host", true, "KRA host");
+        option.setArgName("host");
+        options.addOption(option);
+
+        option = new Option(null, "port", true, "KRA port");
+        option.setArgName("port");
+        options.addOption(option);
     }
 
     public void execute(String[] args) throws Exception {
@@ -61,17 +74,17 @@ public class KRAConnectorRemoveCLI extends CLI {
 
         String[] cmdArgs = cmd.getArgs();
 
-        if (cmdArgs.length != 2) {
+        if (cmdArgs.length != 0) {
             System.err.println("Error: Incorrect number of arguments specified.");
             printHelp();
             System.exit(-1);
         }
 
-        String kraHost = args[0];
-        String kraPort = args[1];
+        String kraHost = cmd.getOptionValue("host");
+        String kraPort = cmd.getOptionValue("port");
 
         kraConnectorCLI.kraConnectorClient.removeConnector(kraHost, kraPort);
 
-        MainCLI.printMessage("Removed KRA connector \""+kraHost + ":" + kraPort +"\"");
+        MainCLI.printMessage("Removed KRA host \"" + kraHost + ":" + kraPort + "\"");
     }
 }
diff --git a/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorShowCLI.java b/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorShowCLI.java
index 680b151ed..4e3498b94 100644
--- a/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorShowCLI.java
+++ b/base/java-tools/src/com/netscape/cmstools/system/KRAConnectorShowCLI.java
@@ -4,7 +4,6 @@ import java.util.Arrays;
 
 import com.netscape.certsrv.system.KRAConnectorInfo;
 import com.netscape.cmstools.cli.CLI;
-import com.netscape.cmstools.cli.MainCLI;
 
 public class KRAConnectorShowCLI extends CLI {
 
@@ -31,7 +30,6 @@ public class KRAConnectorShowCLI extends CLI {
 
         // Print the KRA Connector Information.
 
-        MainCLI.printMessage("KRA Connector Information");
         System.out.println();
         String host = info.getHost().trim();
         if (host.indexOf(' ') == -1) {