sslserver

Section: User Commands (1)
Index Return to Main Contents
 

NAME

sslserver - accept TLS connections and setup TLS CTX  

SYNOPSIS

sslserver [ opts ] host port prog  

DESCRIPTION

opts is a series of getopt-style options, host is a host name or IP address, port is a TCP port, and prog is one or more arguments specifying a program to run for each accepted connection.

The server's address is given by host and port.  

BINDINGS

sslserver will be attached to the primary IP address of host while the host name is fed through qualification using dns_ip6_qualify. If host is given as dotted decimal IPv4 or compactified IPv6 address, sslserver will bind uniquely to those. In order to bind sslserver to a LLU IPv6 address (ie. fe80::a:b:c) additionally the interface name -Iifname has to be provided.

Note: The kernel might use temporary changing SLAAC addresses.

sslserver can be instructed to be multi-homing capable while binding to all available IP addresses. Now host is given as 0.0.0.0 or ::.

Further, sslserver can be forced to provide dual-stack capabilities, thus allowing IPv4 and IPv6 clients to attach to the same instance once host equals ':0' as pseudo IP address.

port may be a numeric port number or a port name. If port is 0, sslserver will choose a free port.  

SERVING

sslserver listens for connections from TCP clients. Typically, for each connection, it runs prog, with file descriptor 0 reading from, and file descriptor 1 writing to a child process ssl. If however sslserver is called with the option -n, it communcates with prog on mutually chosen, arbitrary file descriptors. prog needs to support the UCSPI-TLS API. The ssl process attempts an TLS accept via the network. If it succeeds, it translates data between prog and the network, performing any necessary TLS encoding and decoding. Before running prog, sslserver reads and sets certain environment variables.

sslserver exits when it receives SIGTERM.  

OPTIONS

General Options:
-q
Quiet. Do not print error messages.
-Q
(Default.) Print error messages.
-v
Verbose. Print error and status messages.
-V
Print additional verbose TLS connection informations (protocol and cipher).

Connection options:

-1
After preparing to receive connections, print the local port number to standard output.
-4
Use IPv4 sockets for connections.
-6
Use IPv6 connections. This will set PROTO to TCP6 and put IPv6 addresses in TCP6LOCALIP and TCP6REMOTEIP.
-c n
Do not handle more than n simultaneous connections. If there are n simultaneous connections copies of prog running, defer acceptance of a new connection until one copy finishes. n must be a positive integer. The default value is 40.
-x rules.cdb
Follow the rules compiled into rules.cdb by tcprules. These rules may specify setting environment variables or rejecting connections from bad sources. You can rerun tcprules to change the rules while sslserver is running.
-X
With -x rules.cdb or -y rules.cdb, allow connections even if rules.cdb does not exist. Normally sslserver will drop the connection if cdb does not exist.
-y rules.cdb
Evaluate and follow IP rules compiled into rules.cdb prior of doing a DNS or IDENT lookup. A shared rules.cdb is possible. In case the IP address lookup deliveres a 'deny', the connection is closed immediately. If the lookup result is an explicit 'allow', the given environment variables are considered and the preceeding -x rules.cdb evaluation is omitted.
-B banner
Write banner to the network immediately after each TLS connection is made. The banner is subject to TLS encryption.
-g gid
Switch group ID to gid after preparing to receive connections. gid must be a positive integer.
-u uid
Switch user ID to uid after preparing to receive connections. uid must be a positive integer.
-U
Same as -g $GID -u $UID. Typically, $GID and $UID are set by envuidgid.
-I ifname
Bind to the network interface ifname ("eth0" on Linux, for example). This is only defined and needed for IPv6 link-local addresses.
-b n
Allow a backlog of approximately n pending connections.
-o
Leave IP options alone. If the client is sending packets along an IP source route, send packets back along the same route.
-O
(Default.) Kill IP options. A client can still use source routing to connect and to send data, but packets will be sent back along the default route.
-d
Delay sending data for a fraction of a second whenever the remote host is responding slowly. This is currently the default, but it may not be in the future; if you want it, set it explicitly.
-D
Never delay sending data; enable TCP_NODELAY.
-t n
Give up on the $SSLREMOTEINFO connection attempt after n seconds. The default value is: 26.
-T n
Give up on the TLS connection attempt after n seconds. The default value is: 26.
-w n
Give up on a connection or program after waiting n seconds for read or write. The default value is: 3600.

TLS connection options:

-n
Delay setup of TLS environment until a STARTTLS/STLS command has been issued by the client.
-N
(Default.) Setup the TLS environment immediately.
-s
Store client and server certificate information in the environment, a la mod_ssl.
-S
(Default.) Do not store client and server certificate information in the environment.

X509 certificate and encryption options:

-3
Read a null-terminated key password from file descriptor 3.
-m
(Mail.) Require valid client certificates, but don't check for matching FQDN.
-z
(Host.) Require valid client certificates and match FQDN (if given) against SAN/DN.
-Z
(Default.) Do not require client certificates.

Data-gathering options:

-h
(Default.) Look up the remote host name in DNS to set the environment variable $SSLREMOTEHOST. In this case, additionally the CN/SAN in the X509 certificate can be checked, provided, the option -z is set.
-H
Do not look up the remote host name in DNS; remove the environment variable $SSLREMOTEHOST. To avoid loops, you must use this option for servers on TCP port 53.
-p
Paranoid. After looking up the remote host name in DNS, look up the IP addresses in DNS for that host name, and remove the environment variable $SSLREMOTEHOST if none of the addresses match the client's IP address.
-P
(Default.) Not paranoid.
-l localname
Do not look up the local host name in DNS; use localname for the environment variable $SSLLOCALHOST. A common choice for localname is 0. To avoid loops, you must use this option for servers on TCP port 53.
-r
Attempt to obtain $SSLREMOTEINFO from the remote host.
-R
(Default.) Do not attempt to obtain $SSLREMOTEINFO from the remote host. To avoid loops, you must use this option for servers on TCP ports 53 and 113.
-e
Set protocol environment a la tcpserver . Set $TCPLOCALIP, $TCPLOCALPORT, $TCPLOCALHOST, $TCPREMOTEIP, $TCPREMOTEPORT, $TCPREMOTEHOST, and $TCPREMOTEINFO as well as for IPv6 connections additionally $TCP6LOCALIP, $TCP6LOCALPORT, $TCP6LOCALHOST together with $TCP6REMOTEIP, $TCP6REMOTEPORT, $TCP6RMEOTEHOST and $TCP6INTERFACE from the current $TLS environment (see below).
-E
(Default.) Do not set any tcpserver environment variables.
 

DNS RESOLVER SETTINGS

Use $DNSCACHEIP to set the DNS resolver IP dynamically irrespectively from the settings in /etc/resolv.conf. If the environment variable $LOCALDOMAIN is populated, this name will be appended to unqualified host names. Additional rewriting of local to public names is facilitated in case the file /etc/dnswritefile exists and is populated, or alternatively the environment variable $DNSREWRITEFILE points to a differnent file.  

ENVIRONMENT VARIABLES READ

sslserver acknowledges the environment variable MAXCONIP=n where n is the number of sslserver children spawned for a particular remote IP address. n is initally set to the general connection limit c provided as call argument. MAXCONIP is typically defined in sslserver's rules.cdb for a given condition and thus only active meeting those. MAXCONIP defaults 0 meaning no restriction.  

TLS ENVIRONMENT VARIABLES READ

These variables define the run-time environment of sslserver and are used to specify X509 certificates and keyfile per connection.
$SSL_USER=name
The user, reading the certificates and keyfile.
$SSL_GROUP=group
The respective user group.
$SSL_UID=uid
The numerical UID of the $SSL_USER.
$SSL_CHROOT=path
Perform reading of certificates and keyfile in a $SSL_CHROOT jail.
$CAFILE=path
If set, overrides the compiled-in CA file name. The CA file contains the list of CAs used to verify the client certificate. Certificates in $CAFILE are processed when the server starts.
$CADIR=path
If set, overrides the compiled-in CA directory name. The CA directory contains certificates files used to verify the client certificate. This list augments the list from $CAFILE. Certificates in $CADIR are processed during certificate verification.
$CERTFILE=path
If set, overrides the compiled-in certificate file name. The server presents this certificate to clients.
$CERTCHAINFILE=path
If set, overrides the compiled-in certificate chainfile name. The server presents this list of certificats to clients. Note: Providing $CERTCHAINFILE has precedence over $CERTFILE. Certificates in this file needs to be 'ordered' starting from the uppermost root certificates and placing your host's certificate at the end.
$CIPHERS=string
If set, override the compiled-in TLS cipher list defining the security level for the connection. A typical choice would be 'TLSv1+HIGH:!SSLv2:!MD5'.
$DHFILE=path
If set, overrides the compiled-in DH parameter file name.
$KEYFILE=path
If set, overrides the compiled-in key file name. The key is used when loading the server certificate. Setting $KEYFILE to the empty instructs the server not to use a keyfile when loading it's certificate.
$VERIFYDEPTH=n
If set, overrides the compiled-in verification depth. Default: 1.
$CCAFILE=path
If set, overrides the compiled-in client CA file name for client certificate request. The client CA file contains the list of CAs sent to the client when requesting a client certificate. Note: Setting of $CCAFILE is required while using the option -z or -m. However, declaring $CCAFILE=- disables (on a per-connection base) the client certificate request.
$CCAVERIFY
If set, sslserver requests a valid client certificate on a per-connection base, unlike the general option -z.
 

TLS ENVIRONMENT VARIABLES SET

Note: The term 'SSL' here is due to historical reasons.

In case sslserver is called with the option -e, the following mod_ssl environment variables are provided:

SSL_PROTOCOL
The TLS protocol version (TLSv1, ...).
SSL_SESSION_ID
The hex-encoded SSL session id.
SSL_CIPHER
The cipher specification name.
SSL_CIPHER_USEKEYSIZE
Number of cipher bits (actually used).
SSL_CIPHER_ALGKEYSIZE
Number of cipher bits (possible).
SSL_VERSION_INTERFACE
The mod_ssl program version.
SSL_VERSION_LIBRARY     
The OpenSSL/LibreSSL program version.
SSL_CLIENT_M_VERSION    
The version of the client certificate.
SSL_CLIENT_M_SERIAL     
The serial of the client certificate.
SSL_CLIENT_S_DN 
Subject DN in client's certificate.
SSL_CLIENT_S_DN_x509    
Component of client's Subject DN.
SSL_CLIENT_I_DN 
Issuer DN of client's certificate.
SSL_CLIENT_I_DN_x509    
Component of client's Issuer DN.
SSL_CLIENT_V_START      
Validity of client's certificate (start time).
SSL_CLIENT_V_END        
Validity of client's certificate (end time).
SSL_CLIENT_A_SIG        
Algorithm used for the signature of client's certificate.
SSL_CLIENT_A_KEY        
Algorithm used for the public key of client's certificate.
SSL_CLIENT_CERT 
PEM-encoded client certificate.
SSL_CLIENT_CERT_CHAIN n 
PEM-encoded certificates in client certificate chain.
SSL_CLIENT_VERIFY       
NONE, SUCCESS, GENEROUS or FAILED:reason.
SSL_SERVER_M_SERIAL     
The serial of the server certificate.
SSL_SERVER_S_DN 
Subject DN in server's certificate.
SSL_SERVER_S_DN_x509    
Component of server's Subject DN.
SSL_SERVER_I_DN 
Issuer DN of server's certificate.
SSL_SERVER_I_DN_x509    
Component of server's Issuer DN.
SSL_SERVER_V_START      
Validity of server's certificate (start time).
SSL_SERVER_V_END        
Validity of server's certificate (end time).
SSL_SERVER_A_SIG        
Algorithm used for the signature of server's certificate.
SSL_SERVER_A_KEY        
Algorithm used for the public key of server's certificate.
SSL_SERVER_CERT 
PEM-encoded server certificate.
For SSL_CLIENT_x_DN_x509 and SSL_SERVER_x_DN_x509, x509 denotes a component of the DN: C, ST, L, O, OU, CN, T, I, G, S, D, UID, Email.

Other TLS environment variables set: PROTO, SSLLOCALHOST, SSLLOCALIP, SSLLOCALPORT, SSLREMOTEHOST, SSLREMOTEINFO, SSLREMOTEIP, SSLREMOTEPORT.

TCP environment variables set: TCPLOCALHOST, TCPLOCALIP, TCPLOCALPORT, TCPREMOTEHOST, TCPREMOTEINFO, TCPREMOTEIP, TCPREMOTEPORT.

TCP6 environment variables set: TCP6INTERFACE, TCP6LOCALHOST, TCP6LOCALIP, TCP6LOCALPORT, TCP6REMOTEHOST, TCP6REMOTEIP, TCP6REMOTEPORT.

 

LOGGING AND ERROR MESSAGES

sslserver prints particular state information for individual connections in case -v is specified. Here, the local and remote IP addresses and port together with the number of used/available/ip connection limited children:


  sslserver: status 1/40/0
  sslserver: pid xxxx from ip
  sslserver: [ok|deny] xxxx local:localip:localport remotehost:remoteip:remoteport 
  sslserver: ended by xyz status nnnn

If MAXCONIP is given as global environment variable, one may encounter:


  sslserver: status z/40/maxconip
  sslserver: WARNING ip connection limit of maxconip exceeded for: remoteip

Rather, if MAXCONIP is read from the rules.cdb, the following message might appear:


  sslserver: status 1/40/0
  sslserver: pid xxxx from ip
  sslserver: deny xxxx ... ip connection limit:maxconip exceeded
  sslserver: ended by xyz status nnnn

In all cases, the resolved host names depends on the usage of l, -h and -p. If -V is instead given as argument, lines like


  sslserver: tls xxxx accept TLSv1.2:ECDH-RSA-AES256-GCM-SHA384
  sslserver: tls xxxx accept TLSv1.3:TLS_CHACHA20_POLY1305_SHA256

show additionally the negotiated cipher suite. Error and particular messages TLS error messages are provided, if possible:

sslerver: error: (111) unable to speak TLS from: ... for pid: ... DH lib
TLS handshake failure.
sslserver: error: (111) unable to accept TLS from: ... for pid: ... system lib
The remote socket was prematurely closed; usually because the X.509 cert was not accepted by the client.
sslserver: info: valid client cert received for pid: pid
A client X.509 cert has been accepted for mutual authentication.
 

SEE ALSO

sslhandle(1), sslclient(1), sslconnect(1), sslcat(1), https@(1), ucspi-tls(2), tcprules(1), tcprulescheck(1), tcpserver(1), tcp-environ(5)  

REFERENCE

http://httpd.apache.org/docs/2.4/mod/mod_ssl.html

 

Index

NAME
SYNOPSIS
DESCRIPTION
BINDINGS
SERVING
OPTIONS
DNS RESOLVER SETTINGS
ENVIRONMENT VARIABLES READ
TLS ENVIRONMENT VARIABLES READ
TLS ENVIRONMENT VARIABLES SET
LOGGING AND ERROR MESSAGES
SEE ALSO
REFERENCE
This document was created by man2html, using the manual pages.
Time: 13:07:39 GMT, July 14, 2025