commit 01af3ee5928de2bacaf62210672e1e51524bd41d
Author: Ade Lee <a...@redhat.com>
Date: Fri Jun 10 22:18:03 2016 -0400
Add man page and clarify CLI for kra-connector
Ended up changing the CLI for kra-connector to make things a lot
clearer as discussed with Endi.
Tested adding and removing host/port and installing and removing KRAs
(which call the install/remove connector calls).
Please review.
AdeFrom 01af3ee5928de2bacaf62210672e1e51524bd41d Mon Sep 17 00:00:00 2001
From: Ade Lee <a...@redhat.com>
Date: Fri, 10 Jun 2016 22:18:03 -0400
Subject: [PATCH] Add man page and clarify CLI for kra-connector
---
.../server/ca/rest/KRAConnectorService.java | 17 ++--
.../certsrv/system/KRAConnectorClient.java | 5 ++
.../certsrv/system/KRAConnectorResource.java | 8 +-
base/java-tools/man/man1/pki-ca-kraconnector.1 | 98 ++++++++++++++++++++++
.../cmstools/system/KRAConnectorAddCLI.java | 63 ++++++++++++--
.../cmstools/system/KRAConnectorRemoveCLI.java | 21 ++++-
.../cms/servlet/admin/KRAConnectorProcessor.java | 78 +++++++++++------
.../python/pki/server/deployment/pkihelper.py | 6 +-
specs/pki-core.spec | 1 +
9 files changed, 245 insertions(+), 52 deletions(-)
create mode 100644 base/java-tools/man/man1/pki-ca-kraconnector.1
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 0216558bf6fb64d6bdb2a13dbb04954015dd0824..2e5ea3c5f71e8c99ce34fff81d00cd06db358396 100644
--- a/base/ca/src/org/dogtagpki/server/ca/rest/KRAConnectorService.java
+++ b/base/ca/src/org/dogtagpki/server/ca/rest/KRAConnectorService.java
@@ -65,6 +65,18 @@ public class KRAConnectorService extends PKIService implements KRAConnectorResou
}
@Override
+ public Response addHost(String host, String port) {
+ try {
+ KRAConnectorProcessor processor = new KRAConnectorProcessor(getLocale(headers));
+ processor.addHost(host, port);
+ return createNoContentResponse();
+ } catch (EBaseException e) {
+ e.printStackTrace();
+ throw new PKIException(e.getMessage());
+ }
+ }
+
+ @Override
public Response removeConnector(String host, String port) {
if (host == null) throw new BadRequestException("KRA connector host is null.");
@@ -81,11 +93,6 @@ public class KRAConnectorService extends PKIService implements KRAConnectorResou
}
@Override
- public Response removeConnectorForm(String host, String port) {
- return removeConnector(host, port);
- }
-
- @Override
public Response getConnectorInfo() {
try {
diff --git a/base/common/src/com/netscape/certsrv/system/KRAConnectorClient.java b/base/common/src/com/netscape/certsrv/system/KRAConnectorClient.java
index 7abb1bde853e125a9cf6c16f0e192441e1946827..a9c5efdaa3922bdf05327d5afc30d0d8c09edef5 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 2bf2f19580e5a97b0d2613a2df5032677d5b0484..cf52c66b07e717ddfc1c84e8717e7493d3e24def 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 0000000000000000000000000000000000000000..d4bb8cbfbd215debee1bbb5ea7f8ce06f1036333
--- /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-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 authenicated
+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 kraconnector commands for the subsystem.
+.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 KRA 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 and port are 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 clone KRA to a CA 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 9443
+
+To delete a KRA from the connector:
+
+.B pki <CA admin authentication> ca-kraconnector-del --host kra2.example.com --port 9443
+
+.SH AUTHOR
+Ade Lee <a...@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 aa92bee34725b6985b607f2e679b73e4dfb6ec3c..a8296d5fed3763499140689f3d8f3cd79c208c7a 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,46 @@ 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);
+ //check if connector exists
+ boolean connectorExists = true;
+ try {
+ @SuppressWarnings("unused")
+ KRAConnectorInfo info = kraConnectorCLI.kraConnectorClient.getConnectorInfo();
+ } catch (ConnectorNotFoundException e) {
+ connectorExists = false;
+ }
- kraConnectorCLI.kraConnectorClient.addConnector(info);
+ 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);
- MainCLI.printMessage("Added KRA Connector");
+ 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 host and port to KRA Connector");
+ }
}
}
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 5f0f63b1ab9f5d5e27138ff5fa176083a3aaa660..2c722770afcfaaf4e317b7ca2eacd1c03608b392 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,14 +74,14 @@ 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);
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 88c1c6f238287dd5f1cd8927a0ea32aa00831050..ae1dae5c14258c38263d3c526871d4ad8b4c51f8 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 50146af99f72209e366b032543bd3e34f769218d..1be984d12a051794b4e2c7fa242c4f74997acd41 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 3e6e974aec4483885f1d367575d730c3453fd695..15987ea31cf5187bc27c5a4add1503c7c708d354 100644
--- a/specs/pki-core.spec
+++ b/specs/pki-core.spec
@@ -1029,6 +1029,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}
--
2.4.3
_______________________________________________
Pki-devel mailing list
Pki-devel@redhat.com
https://www.redhat.com/mailman/listinfo/pki-devel
