Add man page and clarify CLI for kra-connector

10 files changed, 255 insertions, 62 deletions

diff --git a/base/ca/src/org/dogtagpki/server/ca/rest/KRAConnectorService.java b/base/ca/src/org/dogtagpki/server/ca/rest/KRAConnectorService.java
index 0216558bf..4ef1b7ea3 100644
--- a/base/ca/src/org/dogtagpki/server/ca/rest/KRAConnectorService.java
+++ b/base/ca/src/org/dogtagpki/server/ca/rest/KRAConnectorService.java
@@ -24,6 +24,7 @@ import javax.ws.rs.core.Request;
 import javax.ws.rs.core.Response;
 import javax.ws.rs.core.UriInfo;
 
+import com.netscape.certsrv.apps.CMS;
 import com.netscape.certsrv.base.BadRequestException;
 import com.netscape.certsrv.base.EBaseException;
 import com.netscape.certsrv.base.PKIException;
@@ -52,14 +53,26 @@ public class KRAConnectorService extends PKIService implements KRAConnectorResou
     @Override
     public Response addConnector(KRAConnectorInfo info) {
 
-        if (info == null) throw new BadRequestException("KRA connector info is null.");
+        if (info == null) throw new BadRequestException("Missing KRA connector info.");
 
         try {
             KRAConnectorProcessor processor = new KRAConnectorProcessor(getLocale(headers));
             processor.addConnector(info);
             return createNoContentResponse();
         } catch (EBaseException e) {
-            e.printStackTrace();
+            CMS.debug(e);
+            throw new PKIException(e.getMessage());
+        }
+    }
+
+    @Override
+    public Response addHost(String host, String port) {
+        try {
+            KRAConnectorProcessor processor = new KRAConnectorProcessor(getLocale(headers));
+            processor.addHost(host, port);
+            return createNoContentResponse();
+        } catch (EBaseException e) {
+            CMS.debug(e);
             throw new PKIException(e.getMessage());
         }
     }
@@ -67,32 +80,27 @@ public class KRAConnectorService extends PKIService implements KRAConnectorResou
     @Override
     public Response removeConnector(String host, String port) {
 
-        if (host == null) throw new BadRequestException("KRA connector host is null.");
-        if (port == null) throw new BadRequestException("KRA connector port is null.");
+        if (host == null) throw new BadRequestException("Missing KRA connector host.");
+        if (port == null) throw new BadRequestException("Missing KRA connector port.");
 
         try {
             KRAConnectorProcessor processor = new KRAConnectorProcessor(getLocale(headers));
             processor.removeConnector(host, port);
             return createNoContentResponse();
         } catch (EBaseException e) {
-            e.printStackTrace();
+            CMS.debug(e);
             throw new PKIException(e.getMessage());
         }
     }
 
     @Override
-    public Response removeConnectorForm(String host, String port) {
-        return removeConnector(host, port);
-    }
-
-    @Override
     public Response getConnectorInfo() {
 
         try {
             KRAConnectorProcessor processor = new KRAConnectorProcessor(getLocale(headers));
             return createOKResponse(processor.getConnectorInfo());
         } catch (EBaseException e) {
-            e.printStackTrace();
+            CMS.debug(e);
             throw new PKIException(e.getMessage());
         }
     }
diff --git a/base/common/src/com/netscape/certsrv/system/KRAConnectorClient.java b/base/common/src/com/netscape/certsrv/system/KRAConnectorClient.java
index 7abb1bde8..a9c5efdaa 100644
--- a/base/common/src/com/netscape/certsrv/system/KRAConnectorClient.java
+++ b/base/common/src/com/netscape/certsrv/system/KRAConnectorClient.java
@@ -46,6 +46,11 @@ public class KRAConnectorClient extends Client {
         client.getEntity(response, Void.class);
     }
 
+    public void addHost(String host, String port) {
+        Response response = kraConnectorClient.addHost(host, port);
+        client.getEntity(response, Void.class);
+    }
+
     public void removeConnector(String host, String port) {
         Response response = kraConnectorClient.removeConnector(host, port);
         client.getEntity(response, Void.class);
diff --git a/base/common/src/com/netscape/certsrv/system/KRAConnectorResource.java b/base/common/src/com/netscape/certsrv/system/KRAConnectorResource.java
index 2bf2f1958..cf52c66b0 100644
--- a/base/common/src/com/netscape/certsrv/system/KRAConnectorResource.java
+++ b/base/common/src/com/netscape/certsrv/system/KRAConnectorResource.java
@@ -17,13 +17,10 @@
 // --- END COPYRIGHT BLOCK ---
 package com.netscape.certsrv.system;
 
-import javax.ws.rs.Consumes;
-import javax.ws.rs.FormParam;
 import javax.ws.rs.GET;
 import javax.ws.rs.POST;
 import javax.ws.rs.Path;
 import javax.ws.rs.QueryParam;
-import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.Response;
 
 import org.jboss.resteasy.annotations.ClientResponseType;
@@ -50,10 +47,9 @@ public interface KRAConnectorResource {
     public Response removeConnector(@QueryParam("host") String host, @QueryParam("port") String port);
 
     @POST
-    @Path("remove")
-    @Consumes({ MediaType.APPLICATION_FORM_URLENCODED })
+    @Path("addHost")
     @ClientResponseType(entityType=Void.class)
-    public Response removeConnectorForm(@FormParam("host") String host, @FormParam("port") String port);
+    public Response addHost(@QueryParam("host") String host, @QueryParam("port") String port);
 
     @GET
     @ClientResponseType(entityType = KRAConnectorInfo.class)
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) {
diff --git a/base/server/cms/src/com/netscape/cms/servlet/admin/KRAConnectorProcessor.java b/base/server/cms/src/com/netscape/cms/servlet/admin/KRAConnectorProcessor.java
index 88c1c6f23..ae1dae5c1 100644
--- a/base/server/cms/src/com/netscape/cms/servlet/admin/KRAConnectorProcessor.java
+++ b/base/server/cms/src/com/netscape/cms/servlet/admin/KRAConnectorProcessor.java
@@ -164,10 +164,11 @@ public class KRAConnectorProcessor extends CAProcessor {
         }
 
         if (connectorExists) {
-            String host = cs.getString(PREFIX + ".host");
-            String port = cs.getString(PREFIX + ".port");
+            String currentHost = cs.getString(PREFIX + ".host");
+            String currentPort = cs.getString(PREFIX + ".port");
 
-            if ((!host.equals(newHost)) || (!port.equals(newPort))) { //existing connector is not the same
+            if ((!currentHost.equals(newHost)) || (!currentPort.equals(newPort))) {
+                //existing connector is not the same
 
                 // check transport cert
                 String transportCert = cs.getString(PREFIX + ".transportCert");
@@ -176,29 +177,8 @@ public class KRAConnectorProcessor extends CAProcessor {
                     throw new BadRequestException("KRA connector has already been defined for this CA");
                 }
 
-                String hostport = newHost + ":" + newPort;
-                if (host.indexOf(' ') != -1) { // host is a list
-                    String[] hostList = host.trim().split(" ");
-                    for (String h : hostList) {
-                        if (h.equals(hostport)) {
-                            CMS.debug("addConnector: connector for " + hostport +
-                                    " is already present.  Returning success");
-                            return;
-                        }
-                    }
-
-                    CMS.debug("addConnector: adding " + hostport + " to KRA connector host list");
-                    cs.putString(PREFIX + ".host", host + " " + hostport);
-                    cs.commit(true);
-                    replaceConnector();
-                    return;
-                } else { // host is not a list, turn it into one
-                    CMS.debug("addConnector: adding " + hostport + " to KRA connector");
-                    cs.putString(PREFIX + ".host", host + ":" + port + " " + hostport);
-                    cs.commit(true);
-                    replaceConnector();
-                    return;
-                }
+                addHostPortToConnector(cs, newHost, newPort, currentHost, currentPort);
+                return;
             }
         }
 
@@ -242,4 +222,50 @@ public class KRAConnectorProcessor extends CAProcessor {
         return info;
     }
 
+    public void addHost(String newHost, String newPort) throws EPropertyNotFound, EBaseException {
+        IConfigStore cs = CMS.getConfigStore();
+
+        if ((newHost == null) || (newPort == null)) {
+            CMS.debug("addHost: malformed request.  newHost, newPort or transport cert is null");
+            throw new BadRequestException("Bad Request: KRA host or port not defined");
+        }
+
+        if (connectorExists) {
+            String currentHost = cs.getString(PREFIX + ".host");
+            String currentPort = cs.getString(PREFIX + ".port");
+
+            if ((!currentHost.equals(newHost)) || (!currentPort.equals(newPort))) {
+                addHostPortToConnector(cs, newHost, newPort, currentHost, currentPort);
+            }
+        } else {
+            throw new BadRequestException(
+                    "Cannot add host:port to existing connector.  Connector does not exit");
+        }
+    }
+
+    private void addHostPortToConnector(IConfigStore cs, String newHost, String newPort, String currentHost,
+            String currentPort) throws EBaseException {
+        String hostport = newHost + ":" + newPort;
+        if (currentHost.indexOf(' ') != -1) {
+            // host is a list
+            String[] hostList = currentHost.trim().split(" ");
+            for (String h : hostList) {
+                if (h.equals(hostport)) {
+                    CMS.debug("addHost: connector for " + hostport +
+                            " is already present.  Returning success");
+                    return;
+                }
+            }
+
+            CMS.debug("addHostPort: adding " + hostport + " to KRA connector host list");
+            cs.putString(PREFIX + ".host", currentHost + " " + hostport);
+        } else {
+            // host is not a list, turn it into one
+            CMS.debug("addHostPort: adding " + hostport + " to KRA connector");
+            cs.putString(PREFIX + ".host", currentHost + ":" + currentPort + " " + hostport);
+        }
+        cs.commit(true);
+        replaceConnector();
+    }
+
 }
diff --git a/base/server/python/pki/server/deployment/pkihelper.py b/base/server/python/pki/server/deployment/pkihelper.py
index 50146af99..1be984d12 100644
--- a/base/server/python/pki/server/deployment/pkihelper.py
+++ b/base/server/python/pki/server/deployment/pkihelper.py
@@ -3068,7 +3068,7 @@ class KRAConnector:
                 # noinspection PyBroadException
                 # pylint: disable=W0703
                 try:
-                    self.execute_using_sslget(
+                    self.execute_using_pki(
                         ca_port, ca_host, subsystemnick,
                         token_pwd, krahost, kraport)
                 except Exception:
@@ -3119,7 +3119,9 @@ class KRAConnector:
                    "-P", "https",
                    "-d", self.mdict['pki_database_path'],
                    "-c", token_pwd,
-                   "ca-kraconnector-del", krahost, str(kraport)]
+                   "ca-kraconnector-del",
+                   "--host", krahost,
+                   "--port", str(kraport)]
 
         output = subprocess.check_output(command,
                                          stderr=subprocess.STDOUT)
diff --git a/specs/pki-core.spec b/specs/pki-core.spec
index ec6c0f52e..73e60bf0e 100644
--- a/specs/pki-core.spec
+++ b/specs/pki-core.spec
@@ -1027,6 +1027,7 @@ systemctl daemon-reload
 %{_mandir}/man1/pki-user-membership.1.gz
 %{_mandir}/man1/pki-ca-profile.1.gz
 %{_mandir}/man1/pki-tps-profile.1.gz
+%{_mandir}/man1/pki-ca-kraconnector.1.gz
 %endif
 
 %if %{with server}