-.TH ovs\-pki 8 "May 2008" "Open vSwitch" "Open vSwitch Manual"
+.de IQ
+. br
+. ns
+. IP "\\$1"
+..
+.TH ovs\-pki 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
.SH NAME
ovs\-pki \- OpenFlow public key infrastructure management utility
.SH SYNOPSIS
-\fBovs\-pki\fR [\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR]
+Each command takes the form:
.sp
-Stand\-alone commands with their arguments:
+\fBovs\-pki\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR]
+.sp
+The implemented commands and their arguments are:
.br
\fBovs\-pki\fR \fBinit\fR
.br
-\fBovs\-pki\fR \fBreq\fR \fINAME\fR
-.br
-\fBovs\-pki\fR \fBsign\fR \fINAME\fR [\fITYPE\fR]
-.br
-\fBovs\-pki\fR \fBreq+sign\fR \fINAME\fR [\fITYPE\fR]
-.br
-\fBovs\-pki\fR \fBverify\fR \fINAME\fR [\fITYPE\fR]
-.br
-\fBovs\-pki\fR \fBfingerprint\fR \fIFILE\fR
+\fBovs\-pki\fR \fBreq\fR \fIname\fR
.br
-\fBovs\-pki\fR \fBself-sign\fR \fINAME\fR
-.sp
-The following additional commands manage an online PKI:
-.br
-\fBovs\-pki\fR \fBls\fR [\fIPREFIX\fR] [\fITYPE\fR]
-.br
-\fBovs\-pki\fR \fBflush\fR [\fITYPE\fR]
+\fBovs\-pki\fR \fBsign\fR \fIname\fR [\fItype\fR]
.br
-\fBovs\-pki\fR \fBreject\fR \fIPREFIX\fR [\fITYPE\fR]
+\fBovs\-pki\fR \fBreq+sign\fR \fIname\fR [\fItype\fR]
.br
-\fBovs\-pki\fR \fBapprove\fR \fIPREFIX\fR [\fITYPE\fR]
+\fBovs\-pki\fR \fBverify\fR \fIname\fR [\fItype\fR]
.br
-\fBovs\-pki\fR \fBprompt\fR [\fITYPE\fR]
+\fBovs\-pki\fR \fBfingerprint\fR \fIfile\fR
.br
-\fBovs\-pki\fR \fBexpire\fR [\fIAGE\fR]
+\fBovs\-pki\fR \fBself\-sign\fR \fIname\fR
.sp
-Each \fITYPE\fR above is a certificate type, either \fBswitch\fR
+Each \fItype\fR above is a certificate type, either \fBswitch\fR
(default) or \fBcontroller\fR.
.sp
The available options are:
contents that should not be exposed.
.TP
-\fBreq\fR \fINAME\fR
-Generates a new private key named \fINAME\fR\fB\-privkey.pem\fR and
-corresponding certificate request named \fINAME\fR\fB\-req.pem\fR.
+\fBreq\fR \fIname\fR
+Generates a new private key named \fIname\fR\fB\-privkey.pem\fR and
+corresponding certificate request named \fIname\fR\fB\-req.pem\fR.
The private key can be intended for use by a switch or a controller.
This command should ideally be run on the switch or controller that
will use the private key to identify itself. The file
-\fINAME\fR\fB\-req.pem\fR must be copied to the CA machine for signing
+\fIname\fR\fB\-req.pem\fR must be copied to the CA machine for signing
with the \fBsign\fR command (below).
This command will output a fingerprint to stdout as its final step.
the \fB\-D\fR or \fB\-\^\-dsaparam\fR option (see below) may be used to
specify an alternate location.
-\fINAME\fR\fB\-privkey.pem\fR has sensitive contents that should not be
-exposed. \fINAME\fR\fB\-req.pem\fR may be safely made public.
+\fIname\fR\fB\-privkey.pem\fR has sensitive contents that should not be
+exposed. \fIname\fR\fB\-req.pem\fR may be safely made public.
.TP
-\fBsign\fR \fINAME\fR [\fITYPE\fR]
-Signs the certificate request named \fINAME\fR\fB\-req.pem\fR that was
+\fBsign\fR \fIname\fR [\fItype\fR]
+Signs the certificate request named \fIname\fR\fB\-req.pem\fR that was
produced in the previous step, producing a certificate named
-\fINAME\fR\fB\-cert.pem\fR. \fITYPE\fR, either \fBswitch\fR (default) or
+\fIname\fR\fB\-cert.pem\fR. \fItype\fR, either \fBswitch\fR (default) or
\fBcontroller\fR, indicates the use for which the key is being
certified.
produced by \fBreq\fR. (The \fB\-b\fR or \fB\-\^\-batch\fR option
suppresses the verification step.)
-The file \fINAME\fR\fB\-cert.pem\fR will need to be copied back to the
+The file \fIname\fR\fB\-cert.pem\fR will need to be copied back to the
switch or controller for which it is intended. Its contents may
safely be made public.
.TP
-\fBreq+sign\fR \fINAME\fR [\fITYPE\fR]
+\fBreq+sign\fR \fIname\fR [\fItype\fR]
Combines the \fBreq\fR and \fBsign\fR commands into a single step,
outputting all the files produced by each. The
-\fINAME\fR\fB\-privkey.pem\fR and \fINAME\fR\fB\-cert.pem\fR files must
+\fIname\fR\fB\-privkey.pem\fR and \fIname\fR\fB\-cert.pem\fR files must
be copied securely to the switch or controller.
-\fINAME\fR\fB\-privkey.pem\fR has sensitive contents and must not be
+\fIname\fR\fB\-privkey.pem\fR has sensitive contents and must not be
exposed in transit. Afterward, it should be deleted from the CA
machine.
key. However, it is also more convenient.
.TP
-\fBverify\fR \fINAME\fR [\fITYPE\fR]
-Verifies that \fINAME\fR\fB\-cert.pem\fR is a valid certificate for the
-given \fITYPE\fR of use, either \fBswitch\fR (default) or
+\fBverify\fR \fIname\fR [\fItype\fR]
+Verifies that \fIname\fR\fB\-cert.pem\fR is a valid certificate for the
+given \fItype\fR of use, either \fBswitch\fR (default) or
\fBcontroller\fR. If the certificate is valid for this use, it prints
-the message ``\fINAME\fR\fB\-cert.pem\fR: OK''; otherwise, it prints an
+the message ``\fIname\fR\fB\-cert.pem\fR: OK''; otherwise, it prints an
error message.
.TP
-\fBfingerprint\fR \fIFILE\fR
-Prints the fingerprint for \fIFILE\fR. If \fIFILE\fR is a
+\fBfingerprint\fR \fIfile\fR
+Prints the fingerprint for \fIfile\fR. If \fIfile\fR is a
certificate, then this is the SHA\-1 digest of the DER encoded version
of the certificate; otherwise, it is the SHA\-1 digest of the entire
file.
.TP
-\fBself-sign\fR \fINAME\fR
-Signs the certificate request named \fINAME\fB\-req.pem\fR using the
-private key \fINAME\fB-privkey.pem\fR, producing a self-signed
-certificate named \fINAME\fB\-cert.pem\fR. The input files should have
+\fBself\-sign\fR \fIname\fR
+Signs the certificate request named \fIname\fB\-req.pem\fR using the
+private key \fIname\fB\-privkey.pem\fR, producing a self-signed
+certificate named \fIname\fB\-cert.pem\fR. The input files should have
been produced with \fBovs\-pki req\fR.
Some controllers accept such self-signed certificates.
-.SH "ONLINE COMMANDS"
-
-An OpenFlow PKI can be administered online, in conjunction with
-.BR ovs\-pki\-cgi (8)
-and a web server such as Apache:
-
-.IP \(bu
-The web server exports the contents of the PKI via HTTP. All files in
-a PKI hierarchy files may be made public, except for the files
-\fBpki/controllerca/private/cakey.pem\fR and
-\fBpki/switchca/private/cakey.pem\fR, which must not be exposed.
-
-.IP \(bu
-\fBovs\-pki\-cgi\fR allows newly generated certificate requests for
-controllers and switches to be uploaded into the
-\fBpki/controllerca/incoming\fR and \fBpki/switchca/incoming\fR
-directories, respectively. Uploaded certificate requests are stored
-in those directories under names of the form
-\fIFINGERPRINT\fB\-req.pem\fR, which \fIFINGERPRINT\fR is the SHA\-1
-hash of the file.
-
-.IP \(bu
-These \fBovs\-pki\fR commands allow incoming certificate requests to
-be approved or rejected, in a form are suitable for use by humans or
-other software.
-
-.PP
-The following \fBovs\-pki\fR commands support online administration:
-
-.TP
-\fBovs\-pki\fR \fBls\fR [\fIPREFIX\fR] [\fITYPE\fR]
-Lists all of the incoming certificate requests of the given \fITYPE\fR
-(either \fBswitch\fR, the default, or \fBcontroller\fR). If
-\fIPREFIX\fR, which must be at least 4 characters long, is specified,
-it causes the list to be limited to files whose names begin with
-\fIPREFIX\fR. This is useful, for example, to avoid typing in an
-entire fingerprint when checking that a specific certificate request
-has been received.
-
-.TP
-\fBovs\-pki\fR \fBflush\fR [\fITYPE\fR]
-Deletes all certificate requests of the given \fITYPE\fR.
-
-.TP
-\fBovs\-pki\fR \fBreject\fR \fIPREFIX\fR [\fITYPE\fR]
-Rejects the certificate request whose name begins with \fIPREFIX\fR,
-which must be at least 4 characters long, of the given type (either
-\fBswitch\fR, the default, or \fBcontroller\fR). \fIPREFIX\fR must
-match exactly one certificate request; its purpose is to allow the
-user to type fewer characters, not to match multiple certificate
-requests.
-
-.TP
-\fBovs\-pki\fR \fBapprove\fR \fIPREFIX\fR [\fITYPE\fR]
-Approves the certificate request whose name begins with \fIPREFIX\fR,
-which must be at least 4 characters long, of the given \fITYPE\fR
-(either \fBswitch\fR, the default, or \fBcontroller\fR). \fIPREFIX\fR
-must match exactly one certificate request; its purpose is to allow
-the user to type fewer characters, not to match multiple certificate
-requests.
-
-The command will output a fingerprint to stdout and request that you
-verify that it is correct. (The \fB\-b\fR or \fB\-\^\-batch\fR option
-suppresses the verification step.)
-
-.TP
-\fBovs\-pki\fR \fBprompt\fR [\fITYPE\fR]
-Prompts the user for each incoming certificate request of the given
-\fITYPE\fR (either \fBswitch\fR, the default, or \fBcontroller\fR).
-Based on the certificate request's fingerprint, the user is given the
-option of approving, rejecting, or skipping the certificate request.
-
-.TP
-\fBovs\-pki\fR \fBexpire\fR [\fIAGE\fR]
-
-Rejects all the incoming certificate requests, of either type, that is
-older than \fIAGE\fR, which must in one of the forms \fIN\fBs\fR,
-\fIN\fBmin\fR, \fIN\fBh\fR, \fIN\fBday\fR. The default is \fB1day\fR.
-
.SH OPTIONS
-.TP
-\fB\-k\fR \fItype\fR | \fB\-\^\-key=\fItype\fR
+.IP "\fB\-k\fR \fItype\fR"
+.IQ "\fB\-\^\-key=\fItype\fR"
For the \fBinit\fR command, sets the public key algorithm to use for
the new PKI hierarchy. For the \fBreq\fR and \fBreq+sign\fR commands,
sets the public key algorithm to use for the key to be generated,
The \fItype\fR may be \fBrsa\fR (the default) or \fBdsa\fR.
-.TP
-\fB\-B\fR \fInbits\fR | \fB\-\^\-bits=\fInbits\fR
+.IP "\fB\-B\fR \fInbits\fR"
+.IQ "\fB\-\^\-bits=\fInbits\fR"
Sets the number of bits in the key to be generated. When RSA keys are
in use, this option affects only the \fBinit\fR, \fBreq\fR, and
\fBreq+sign\fR commands, and the same value should be given each time.
The value must be at least 1024. The default is 2048.
-.TP
-\fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR
+.IP "\fB\-D\fR \fIfile\fR"
+.IQ "\fB\-\^\-dsaparam=\fIfile\fR"
Specifies an alternate location for the \fBdsaparam.pem\fR file
required by the \fBreq\fR and \fBreq+sign\fR commands. This option
affects only these commands, and only when DSA keys are used.
The default is \fBdsaparam.pem\fR under the PKI hierarchy.
-.TP
-\fB\-b\fR | \fB\-\^\-batch\fR
+.IP "\fB\-b\fR"
+.IQ "\fB\-\^\-batch\fR"
Suppresses the interactive verification of fingerprints that the
-\fBsign\fR and \fBapprove\fR commands by default require.
+\fBsign\fR command by default requires.
-.TP
-\fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR
+.IP "\fB\-d\fR \fIdir\fR"
+.IQ "\fB\-\^\-dir=\fR\fIdir\fR"
Specifies the location of the PKI hierarchy to be used or created by
the command (default: \fB@PKIDIR@\fR). All commands, except \fBreq\fR,
need access to a PKI hierarchy.
-.TP
-\fB\-f\fR | \fB\-\^\-force\fR
+.IP "\fB\-f\fR"
+.IQ "\fB\-\^\-force\fR"
By default, \fBovs\-pki\fR will not overwrite existing files or
directories. This option overrides this behavior.
-.TP
-\fB\-l\fR \fIfile\fR | \fB\-\^\-log=\fIfile\fR
+.IP "\fB\-l\fR \fIfile\fR"
+.IQ "\fB\-\^\-log=\fIfile\fR"
Sets the log file to \fIfile\fR. Default:
\fB@LOGDIR@/ovs\-pki.log\fR.
-.TP
-\fB\-h\fR | \fB\-\^\-help\fR
+.IP "\fB\-h\fR"
+.IQ "\fB\-\^\-help\fR"
Prints a help usage message and exits.
-
-.SH "SEE ALSO"
-
-.BR ovs\-controller (8),
-.BR ovs\-openflowd (8),
-.BR ovs\-pki\-cgi (8)
projects / cascardo / ovs.git / blobdiff