ssl_multicert.config -> ssl_multicert.yaml

Replace the ssl_multicert.config format with YAML format, following the
pattern established by sni.yaml. The new ssl_multicert.yaml uses a
top-level 'ssl_multicert' key containing a sequence of certificate
entries.

This also includes a Python migration script for converting existing
configs.

Author: bneradt

configs/records.yaml.default.in

@@ -199,7 +199,7 @@ records:
 ##############################################################################
 # SSL Termination. Docs:
 #    https://docs.trafficserver.apache.org/en/latest/admin-guide/files/records.yaml.en.html#client-related-configuration
-#    https://docs.trafficserver.apache.org/en/latest/admin-guide/files/ssl_multicert.config.en.html
+#    https://docs.trafficserver.apache.org/en/latest/admin-guide/files/ssl_multicert.yaml.en.html
 ##############################################################################
       verify:
         server:

configs/ssl_multicert.config.default configs/ssl_multicert.yaml.defaultconfigs/ssl_multicert.config.default renamed to configs/ssl_multicert.yaml.default

@@ -1,12 +1,12 @@
 #
-# ssl_multicert.config
+# ssl_multicert.yaml
 #
 # Documentation:
-#    https://docs.trafficserver.apache.org/en/latest/admin-guide/files/ssl_multicert.config.en.html
+#   https://docs.trafficserver.apache.org/en/latest/admin-guide/files/ssl_multicert.yaml.en.html
 #
 # Allows a TLS certificate and private key to be tied to a specific
 # hostname or IP address. At load time, the certificate is parsed to
-# extract the subject CN and all the DNS subjectAltNames.  The
+# extract the subject CN and all the DNS subjectAltNames. The
 # certificate will be presented for connections requesting any of the
 # hostnames found in the certificate. Wildcard names in the certificates
 # are supported, but only of the form '*.domain.com', ie. where '*'
@@ -18,7 +18,11 @@
 #
 # Fields:
 #
-# dest_ip=ADDRESS
+# ssl_cert_name: FILENAME
+#   The name of the file containing the TLS certificate. This is the
+#   only field that is required to be present (unless action is tunnel).
+#
+# dest_ip: ADDRESS
 #   The IP (v4 or v6) address that the certificate should be presented
 #   on. This is now only used as a fallback in the case that the TLS
 #   ServerNameIndication extension is not supported. If ADDRESS is
@@ -30,37 +34,58 @@
 #   accepted on the specified port. IPv6 addresses must be enclosed by
 #   square brackets if they have a port, eg, [::1]:80.
 #
-# ssl_key_name=FILENAME
+# ssl_key_name: FILENAME
 #   The name of the file containing the private key for this certificate.
 #   If the key is contained in the certificate file, this field can be
 #   omitted.
 #
-# ssl_ca_name=FILENAME
+# ssl_ca_name: FILENAME
 #   If your certificates have different Certificate Authorities, you
 #   can optionally specify the corresponding file here.
 #
-# ssl_cert_name=FILENAME
-#   The name of the file containing the TLS certificate. This is the
-#   only field that is required to be present.
+# ssl_ocsp_name: FILENAME
+#   The name of the file containing the OCSP response for stapling.
 #
-# ssl_key_dialog=[builtin|exec:/path/to/program]
+# ssl_key_dialog: builtin|exec:/path/to/program
 #   Method used to provide a pass phrase for encrypted private keys.
 #   Two options are supported: builtin and exec
 #     builtin - Requests passphrase via stdin/stdout. Useful for debugging.
 #     exec: - Executes a program and uses the stdout output for the pass
 #       phrase.
 #
-# action=[tunnel]
-#   If the tunnel matches this line, traffic server will not participate
-#   in the handshake.  But rather it will blind tunnel the SSL connection.
-#   If the connection is identified by server name, an openSSL patch must
-#   be applied to enable this functionality.  See TS-3006 for details.
-#
-# Examples:
-#   ssl_cert_name=foo.pem
-#   dest_ip=*	ssl_cert_name=bar.pem ssl_key_name=barKey.pem
-#   dest_ip=209.131.48.79	ssl_cert_name=server.pem ssl_key_name=serverKey.pem
-#   dest_ip=10.0.0.1:99 ssl_cert_name=port99.pem
-#   ssl_cert_name=foo.pem ssl_key_dialog="exec:/usr/bin/mypass foo 'ba r'"
-#   ssl_cert_name=foo.pem action=tunnel
-#   ssl_cert_name=wildcardcert.pem ssl_key_name=privkey.pem
+# ssl_ticket_enabled: 0|1
+#   Enable or disable session tickets for this certificate.
+#
+# ssl_ticket_number: NUMBER
+#   Number of session tickets to issue for new TLSv1.3 connections.
+#
+# action: tunnel
+#   If the connection matches this entry, traffic server will not participate
+#   in the handshake. Instead, it will blind tunnel the SSL connection.
+#
+# Example configuration:
+#
+# ssl_multicert:
+#   - ssl_cert_name: server.pem
+#
+#   - ssl_cert_name: bar.pem
+#     ssl_key_name: barKey.pem
+#     dest_ip: "*"
+#
+#   - ssl_cert_name: server.pem
+#     ssl_key_name: serverKey.pem
+#     dest_ip: "209.131.48.79"
+#
+#   - ssl_cert_name: port99.pem
+#     dest_ip: "10.0.0.1:99"
+#
+#   - ssl_cert_name: foo.pem
+#     ssl_key_dialog: "exec:/usr/bin/mypass foo 'ba r'"
+#
+#   - action: tunnel
+#     dest_ip: "192.168.1.1"
+#
+#   - ssl_cert_name: wildcardcert.pem
+#     ssl_key_name: privkey.pem
+
+ssl_multicert:

doc/admin-guide/files/index.en.rst

@@ -34,7 +34,7 @@ Configuration Files
    records.yaml.en
    remap.config.en
    splitdns.config.en
-   ssl_multicert.config.en
+   ssl_multicert.yaml.en
    sni.yaml.en
    storage.config.en
    strategies.yaml.en
@@ -72,7 +72,7 @@ Configuration Files
 :doc:`splitdns.config.en`
    Configures DNS servers to use under specific conditions.
 
-:doc:`ssl_multicert.config.en`
+:doc:`ssl_multicert.yaml.en`
    Configures |TS| to use different server certificates for SSL termination
    when listening on multiple addresses or when clients employ SNI.
 

doc/admin-guide/files/records.yaml.en.rst

@@ -3973,24 +3973,24 @@ SSL Termination
    ===== ======================================================================
 
 
-.. ts:cv:: CONFIG proxy.config.ssl.server.multicert.filename STRING ssl_multicert.config
+.. ts:cv:: CONFIG proxy.config.ssl.server.multicert.filename STRING ssl_multicert.yaml
    :deprecated:
 
-   The location of the :file:`ssl_multicert.config` file, relative
+   The location of the :file:`ssl_multicert.yaml` file, relative
    to the |TS| configuration directory. In the following
    example, if the |TS| configuration directory is
    `/etc/trafficserver`, the |TS| SSL configuration file
    and the corresponding certificates are located in
    `/etc/trafficserver/ssl`::
 
-      CONFIG proxy.config.ssl.server.multicert.filename STRING ssl/ssl_multicert.config
+      CONFIG proxy.config.ssl.server.multicert.filename STRING ssl/ssl_multicert.yaml
       CONFIG proxy.config.ssl.server.cert.path STRING etc/trafficserver/ssl
       CONFIG proxy.config.ssl.server.private_key.path STRING etc/trafficserver/ssl
 
 .. ts:cv:: CONFIG proxy.config.ssl.server.multicert.exit_on_load_fail INT 1
 
    By default (``1``), |TS| will not start unless all the SSL certificates listed in the
-   :file:`ssl_multicert.config` file successfully load.  If false (``0``), SSL certificate
+   :file:`ssl_multicert.yaml` file successfully load.  If false (``0``), SSL certificate
    load failures will not prevent |TS| from starting.
 
 .. ts:cv:: CONFIG proxy.config.ssl.server.cert.path STRING /config
@@ -3999,21 +3999,21 @@ SSL Termination
    and validation new SSL sessions. If this is a relative path,
    it is appended to the |TS| installation PREFIX. All
    certificates and certificate chains listed in
-   :file:`ssl_multicert.config` will be loaded relative to this path.
+   :file:`ssl_multicert.yaml` will be loaded relative to this path.
 
 .. ts:cv:: CONFIG proxy.config.ssl.server.private_key.path STRING NULL
 
    The location of the SSL certificate private keys. Change this
    variable only if the private key is not located in the SSL
    certificate file. All private keys listed in
-   :file:`ssl_multicert.config` will be loaded relative to this
+   :file:`ssl_multicert.yaml` will be loaded relative to this
    path.
 
 .. ts:cv:: CONFIG proxy.config.ssl.server.cert_chain.filename STRING NULL
 
    The name of a file containing a global certificate chain that
    should be used with every server certificate. This file is only
-   used if there are certificates defined in :file:`ssl_multicert.config`.
+   used if there are certificates defined in :file:`ssl_multicert.yaml`.
    Unless this is an absolute path, it is loaded relative to the
    path specified by :ts:cv:`proxy.config.ssl.server.cert.path`.
 
@@ -4522,7 +4522,7 @@ OCSP Stapling Configuration
    The directory path of the prefetched OCSP stapling responses. Change this
    variable only if you intend to use and administratively maintain
    prefetched OCSP stapling responses. All stapling responses listed in
-   :file:`ssl_multicert.config` will be loaded relative to this
+   :file:`ssl_multicert.yaml` will be loaded relative to this
    path.
 
 HTTP/2 Configuration