doc: Clarify kdc --ports / [kdc] ports (fix #1223)

kdc/kdc.8

@@ -89,7 +89,24 @@ Makes the kdc listen on port 80 and handle requests encapsulated in HTTP.
 .It Fl P Ar portspec , Fl Fl ports= Ns Ar portspec
 Specifies the set of ports the KDC should listen on.
 It is given as a
-white-space separated list of services or port numbers.
+white-space separated list of ports.
+A port value of
+.Sq +
+indicates that the standard ports should be used.
+Other values should be service names or port numbers as resolved by
+.Xr getservbyname 3 
+(e.g.,
+.Dq kerberos/udp ,
+.Dq kerberos/tcp ,
+.Dq 8088/udp ,
+etc.), or plain numeric port numbers (e.g.,
+.Dq 9088
+).
+Plain numeric port numbers will be used with both UDP and TCP.
+See also the
+.Dq [kdc] ports
+configuration parameter discussion in
+.Xr krb5.conf 5 .
 .It Fl Fl addresses= Ns Ar list of addresses
 The list of addresses to listen for requests on.
 By default, the kdc will listen on all the locally configured
@@ -214,4 +231,5 @@ There should be a way to specify protocol, port, and address triplets,
 not just addresses and protocol, port tuples.
 .Sh SEE ALSO
 .Xr kinit 1 ,
-.Xr krb5.conf 5
+.Xr krb5.conf 5,
+.Xr getservbyname 3

lib/krb5/krb5.conf.5

@@ -798,6 +798,27 @@ Maximum size of a kdc request.
 If set pre-authentication is required.
 .It Li ports = Va "list of ports"
 List of ports the kdc should listen to.
+The list should be double-quoted if it contains more than one
+port specification, and the ports should be separated by space
+or tab characters.
+A port value of
+.Dq +
+means "all the standard ports" for the service, otherwise
+each port value should be of a form resolvable by
+.Xr getservbyname 3
+such as
+.Dq someservicename/tcp ,
+.Dq 12345/udp ,
+or
+.Dq 12345/tcp .
+If a numeric value is given with the
+.Sq /
+and protocol name are missing then that port will be used on
+both, UDP and TCP.
+For example,
+.Dq + 8088/tcp
+means
+.Dq serve on the standard ports and also on port 8088 with TCP .
 .It Li addresses = Va "list of interfaces"
 List of addresses the kdc should bind to.
 .It Li enable-http = Va BOOL
@@ -1468,4 +1489,5 @@ ones.
 .Xr kinit 1 ,
 .Xr krb5_openlog 3 ,
 .Xr strftime 3 ,
+.Xr getservbyname 3 ,
 .Xr verify_krb5_conf 8