From: Graham Leggett Date: Mon, 26 Feb 2018 14:10:51 +0000 (+0000) Subject: Add the ctlogconfig man page to the docs build. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=5a3b0ecbe09b9a5dac6769361759d0b0adb49ab1;p=apache Add the ctlogconfig man page to the docs build. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1825373 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/man/ctlogconfig.8 b/docs/man/ctlogconfig.8 new file mode 100644 index 0000000000..e6f2c5a466 --- /dev/null +++ b/docs/man/ctlogconfig.8 @@ -0,0 +1,149 @@ +.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +.\" DO NOT EDIT! Generated from XML source. +.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "CTLOGCONFIG" 8 "@date@" "Apache HTTP Server" "ctlogconfig" + +.SH NAME +ctlogconfig \- Certificate Transparency log configuration tool + +.SH "SYNOPSIS" + +.PP +\fBctlogconfig\fR \fI/path/to/db\fR \fBdump\fR + +.PP +\fBctlogconfig\fR \fI/path/to/db\fR \fBconfigure-public-key\fR [ \fIlog-id\fR|\fIrecord-id\fR ] \fI/path/to/public-key\&.pem\fR + +.PP +\fBctlogconfig\fR \fI/path/to/db\fR \fBconfigure-url\fR [ \fIlog-id\fR|\fIrecord-id\fR ] \fIlog-URL\fR + +.PP +\fBctlogconfig\fR \fI/path/to/db\fR \fBvalid-time-range\fR \fIlog-id\fR|\fIrecord-id\fR \fImin-timestamp\fR \fImax-timestamp\fR + +.PP +\fBctlogconfig\fR \fI/path/to/db\fR \fBtrust\fR \fIlog-id\fR|\fIrecord-id\fR + +.PP +\fBctlogconfig\fR \fI/path/to/db\fR \fBdistrust\fR \fIlog-id\fR|\fIrecord-id\fR + +.PP +\fBctlogconfig\fR \fI/path/to/db\fR \fBforget\fR \fIlog-id\fR|\fIrecord-id\fR + + +.TP +\fIlog-id\fR +This is the id of the log, which is the SHA-256 hash of the log's public key, provided in hexadecimal format\&. This string is 64 characters in length\&. +.TP +\fIrecord-id\fR +This is the record number in the database, as displayed by the \fBdump\fR sub-command, prefixed with \fB#\fR\&. As an example, \fB#4\fR references the fourth record in the database\&. (Use shell escaping as necessary\&.) +.TP +\fI/path/to/public-key\&.pem\fR +This is a file containing the log's public key in PEM format\&. The public key is not stored in the database\&. Instead, a reference to the file is stored\&. Thus, the file cannot be removed until the public key in the database is removed or changed\&. +.TP +\fImin-timestamp\fR, \fImax-timestamp\fR +A timestamp is a time as expressed in the number of milliseconds since the epoch, ignoring leap seconds\&. This is the form of time used in Signed Certificate Timestamps\&. This must be provided as a decimal number\&. Specify \fB-\fR for one of the timestamps if it is unknown\&. For example, when configuring the minimum valid timestamp for a log which remains valid, specify \fB-\fR for \fImax-timestamp\fR\&. SCTs received from this log by the proxy are invalid if the timestamp is older than \fImin-timestamp\fR or newer than \fImax-timestamp\fR\&. + + +.SH "SUMMARY" + +.PP +ctlogconfig is a tool for creating and maintaining a log configuration database, for use with mod_ssl_ct\&. + +.PP +Refer first to Log configuration in the mod_ssl_ct documentation\&. + +.PP +Refer to the examples below for typical use\&. + + +.SH "SUB-COMMANDS" + + +.TP +dump +Display configuration database contents\&. The record id shown in the output of this sub-command can be used to identify the affected record in other sub-commands\&. +.TP +configure-public-key +Add a log's public key to the database or set the public key for an existing entry\&. The log's public key is needed to validate the signature of SCTs received by a proxy from a backend server\&. (The database will be created if it does not yet exist\&.) +.TP +configure-url +Add a log's URL to the database or set the URL for an existing entry\&. The log's URL is used when submitting server certificates to logs in order to obtain SCTs to send to clients\&. (The database will be created if it does not yet exist\&.) +.TP +valid-time-range +Set the minimum valid time and/or the maximum valid time for a log\&. SCTs from the log with timestamps outside of the valid range will not be accepted\&. Use - for a time that is not being configured\&. (The database will be created if it does not yet exist\&.) +.TP +trust +Mark a log as trusted, which is the default setting\&. This sub-command is used to reverse a \fIdistrust\fR setting\&. (The database will be created if it does not yet exist\&.) +.TP +distrust +Mark a log as distrusted\&. (The database will be created if it does not yet exist\&.) +.TP +forget +Remove information about a log from the database\&. + +.SH "EXAMPLES" + +.PP +Consider an Apache httpd instance which serves as a TLS server and a proxy\&. The TLS server needs to obtain SCTs from a couple of known logs in order to pass those to clients, and the proxy needs to be able to validate the signature of SCTs received from backend servers\&. + +.PP +First we'll configure the URLs for logs where server certificates are logged: + +.nf + + $ ctlogconfig /path/to/conf/log-config configure-url http://log1\&.example\&.com/ + $ ctlogconfig /path/to/conf/log-config configure-url http://log2\&.example\&.com/ + $ ctlogconfig /path/to/conf/log-config dump + Log entry: + Record 1 + Log id : (not configured) + Public key file: (not configured) + URL : http://log1\&.example\&.com/ + Time range : -INF to +INF + Log entry: + Record 2 + Log id : (not configured) + Public key file: (not configured) + URL : http://log2\&.example\&.com/ + Time range : -INF to +INF +.fi + +.PP +Next we'll set the public key of a log where the certificate of our only backend server is published\&. In this case it is the log with URL http://log2\&.example\&.com/ which has already been configured\&. + +.nf + + $ ctlogconfig /path/to/conf/log-config configure-public-key \\ + $ ctlogconfig /path/to/conf/log-config dump + Log entry: + Record 1 + Log id : (not configured) + Public key file: (not configured) + URL : http://log1\&.example\&.com/ + Time range : -INF to +INF + Log entry: + Record 2 + Log id : (not configured) + Public key file: /path/to/conf/log2-pub\&.pem + URL : http://log2\&.example\&.com/ + Time range : -INF to +INF +.fi + diff --git a/docs/manual/style/build.properties b/docs/manual/style/build.properties index ff512659ce..fbef3ae89b 100644 --- a/docs/manual/style/build.properties +++ b/docs/manual/style/build.properties @@ -10,6 +10,7 @@ retired = no manpages.8 = \ apachectl \ + ctlogconfig \ fcgistarter \ htcacheclean \ httpd \