Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RELAYD.CONF(5)		    BSD	File Formats Manual		RELAYD.CONF(5)

NAME
     relayd.conf -- relay daemon configuration file

DESCRIPTION
     relayd.conf is the	configuration file for the relay daemon, relayd(8).

SECTIONS
     relayd.conf is divided into seven main sections:

     Macros
	   User-defined	variables may be defined and used later, simplifying
	   the configuration file.

     Global Configuration
	   Global settings for relayd(8).  Do note that	the config file	allows
	   global settings to be added after defining tables in	the config
	   file, but those tables will use the built-in	defaults instead of
	   the global settings below them.

     Tables
	   Table definitions describe a	list of	hosts, in a similar fashion to
	   pf(4) tables.  They are used	for relay and redirection target se-
	   lection with	the described options and health checking on the host
	   they	contain.

     Redirections
	   Redirections	are translated to pf(4)	rdr-to rules for stateful for-
	   warding to a	target host from a health-checked table	on layer 3.

     Relays
	   Relays allow	application layer load balancing, SSL acceleration,
	   and general purpose TCP proxying on layer 7.

     Protocols
	   Protocols are predefined settings and filter	rules for relays.

     Within the	sections, a host address can be	specified by IPv4 address,
     IPv6 address, interface name, interface group, or DNS hostname.  If the
     address is	an interface name, relayd(8) will look up the first IPv4 ad-
     dress and any other IPv4 and IPv6 addresses of the	specified network in-
     terface.  A port can be specified by number or name.  The port name to
     number mappings are found in the file /etc/services; see services(5) for
     details.

     The current line can be extended over multiple lines using	a backslash
     (`\').  Comments can be put anywhere in the file using a hash mark	(`#'),
     and extend	to the end of the current line.	 Care should be	taken when
     commenting	out multi-line text: the comment is effective until the	end of
     the entire	block.

     Argument names not	beginning with a letter, digit,	or underscore must be
     quoted.

     Additional	configuration files can	be included with the include keyword,
     for example:

	   include "/usr/local/etc/relayd.conf.local"

MACROS
     Macros can	be defined that	will later be expanded in context.  Macro
     names must	start with a letter, digit, or underscore, and may contain any
     of	those characters.  Macro names may not be reserved words (for example,
     table, relay, or timeout).	 Macros	are not	expanded inside	quotes.

     For example:

	   www1="10.0.0.1"
	   www2="10.0.0.2"
	   table <webhosts> {
		   $www1
		   $www2
	   }

GLOBAL CONFIGURATION
     Here are the settings that	can be set globally:

     interval number
	     Set the interval in seconds at which the hosts will be checked.
	     The default interval is 10	seconds.

     log (updates|all)
	     Log state notifications after completed host checks.  Either only
	     log the updates to	new states or log all state notifications,
	     even if the state didn't change.  The host	state can be up	(the
	     health check completed successfully), down	(the host is down or
	     didn't match the check criteria), or unknown (the host is dis-
	     abled or has not been checked yet).

     prefork number
	     When using	relays,	run the	specified number of processes to han-
	     dle relayed connections.  This increases the performance and pre-
	     vents delays when connecting to a relay.  relayd(8) runs 3	relay
	     processes by default and every process will handle	all configured
	     relays.

     timeout number
	     Set the global timeout in milliseconds for	checks.	 This can be
	     overridden	by the timeout value in	the table definitions.	The
	     default interval is 200 milliseconds and it must not exceed the
	     global interval.  Please note that	the default value is optimized
	     for checks	within the same	collision domain - use a higher	time-
	     out, such as 1000 milliseconds, for checks	of hosts in other sub-
	     nets.  If this option is to be set, it should be placed before
	     overrides in tables.

TABLES
     Tables are	used to	group a	set of hosts as	the target for redirections or
     relays; they will be mapped to a pf(4) table for redirections.  Tables
     may be defined with the following attribute:

     disable  Start the	table disabled - no hosts will be checked in this ta-
	      ble.  The	table can be later enabled through relayctl(8).

     Each table	must contain at	least one host address;	multiple hosts are
     separated by newline, comma, or whitespace.  Host entries may be defined
     with the following	attributes:

     ip	ttl number
	    Change the default time-to-live value in the IP headers for	host
	    checks.

     parent number
	    The	optional parent	option inherits	the state from a parent	host
	    with the specified identifier.  The	check will be skipped for this
	    host and copied from the parent host.  This	can be used to prevent
	    multiple checks on hosts with multiple IP addresses	for the	same
	    service.  The host identifiers are sequentially assigned to	the
	    configured hosts starting with 1; it can be	shown with the
	    relayctl(8)	show summary commands.

     priority number
	    Change the route priority used when	adding a route.	 If not	speci-
	    fied, the kernel will set a	priority of 8 (RTP_STATIC).  In	ordi-
	    nary use, a	fallback route should be added statically with a very
	    high (e.g. 52) priority.  Unused in	all other modes.

     retry number
	    The	optional retry option adds a tolerance for failed host checks;
	    the	check will be retried for number more times before setting the
	    host state to down.	 If this table is used by a relay, it will
	    also specify the number of retries for outgoing connection at-
	    tempts.

     For example:

	   table <service> { 192.168.1.1, 192.168.1.2, 192.168.2.3 }
	   table <fallback> disable { 10.1.5.1 retry 2 }

	   redirect "www" {
		   listen on www.example.com port 80
		   forward to <service>	check http "/" code 200
		   forward to <fallback> check http "/"	code 200
	   }

     Tables are	used by	forward	to directives in redirections or relays	with a
     set of general options, health-checking rules, and	timings; see the
     REDIRECTIONS and RELAYS sections for more information about the forward
     context.  Table specific configuration directives are described below.
     Multiple options can be appended to forward to directives,	separated by
     whitespaces.

     The following options will	configure the health-checking method for the
     table, and	is mandatory for redirections:

     check http	path [host hostname] code number
	     For each host in the table, verify	that retrieving	the URL	path
	     gives the HTTP return code	number.	 If hostname is	specified, it
	     is	used as	the "Host:" header to query a specific hostname	at the
	     target host.  To validate the HTTP	return code, use this shell
	     command:

		   $ echo -n "HEAD <path> HTTP/1.0\r\n\r\n" | \
			   nc <host> <port> | head -n1

	     This prints the status header including the actual	return code:

		   HTTP/1.1 200	OK

     check https path [host hostname] code number
	     This has the same effect as above but wraps the HTTP request in
	     SSL.

     check http	path [host hostname] digest string
	     For each host in the table, verify	that retrieving	the URL	path
	     produces non-binary content whose message digest matches the de-
	     fined string.  The	algorithm used is determined by	the string
	     length of the digest argument, either SHA1	(40 characters)	or MD5
	     (32 characters).  If hostname is specified, it is used as the
	     "Host:" header to query a specific	hostname at the	target host.
	     The digest	does not take the HTTP headers into account.  Do not
	     specify a binary object (such as a	graphic) as the	target of the
	     request, as relayd.conf expects the data returned to be a string.
	     To	compute	the digest, use	this simple command:

		   $ ftp -o - http://host[:port]/path |	sha1

	     This gives	a digest that can be used as-is	in a digest statement:

		   a9993e36476816aba3e25717850c26c9cd0d89d

     check https path [host hostname] digest string
	     This has the same effect as above but wraps the HTTP request in
	     SSL.

     check icmp
	     Ping hosts	in this	table to determine whether they	are up or not.
	     This method will automatically use	ICMP or	ICMPV6 depending on
	     the address family	of each	host.

     check script path
	     Execute an	external program to check the host state.  The program
	     will be executed for each host by specifying the hostname on the
	     command line:

		   /usr/local/bin/checkload.pl front-www1.private.example.com

	     relayd(8) expects a positive return value on success and zero on
	     failure.  Note that the script will be executed with the privi-
	     leges of the "_relayd" user and terminated	after timeout mil-
	     liseconds.

     check send	data expect pattern [ssl]
	     For each host in the table, a TCP connection is established on
	     the port specified, then data is sent.  Incoming data is then
	     read and is expected to match against pattern using shell glob-
	     bing rules.  If data is an	empty string or	nothing	then nothing
	     is	sent on	the connection and data	is immediately read.  This can
	     be	useful with protocols that output a banner like	SMTP, NNTP,
	     and FTP.  If the ssl keyword is present, the transaction will oc-
	     cur in an SSL tunnel.

     check ssl
	     Perform a complete	SSL handshake with each	host to	check their
	     availability.

     check tcp
	     Use a simple TCP connect to check that hosts are up.

     The following general table options are available:

     interval number
	     Override the global interval and specify one for this table.  It
	     must be a multiple	of the global interval.

     timeout number
	     Set the timeout in	milliseconds for each host that	is checked us-
	     ing TCP as	the transport.	This will override the global timeout,
	     which is 200 milliseconds by default.

     The following options will	set the	scheduling algorithm to	select a host
     from the specified	table:

     mode hash
	     Balances the outgoing connections across the active hosts based
	     on	the hashed name	of the relay, the hashed name of the table,
	     and the IP	address	and port of the	relay.	Additional input can
	     be	fed into the hash by looking at	HTTP headers and GET vari-
	     ables; see	the PROTOCOLS section below.  This mode	is only	sup-
	     ported by relays.

     mode least-states
	     Forward each outgoing connection to the active host with the
	     least active pf(4)	states.	 This mode is only supported by	redi-
	     rections.

     mode loadbalance
	     Balances the outgoing connections across the active hosts based
	     on	the hashed name	of the relay, the hashed name of the table,
	     the source	IP address of the client, and the IP address and port
	     of	the relay.  This mode is only supported	by relays.

     mode random
	     Distributes the outgoing connections randomly through all active
	     hosts.  This mode is only supported by relays.

     mode roundrobin
	     Distributes the outgoing connections using	a round-robin sched-
	     uler through all active hosts.  This is the default mode and will
	     be	used if	no option has been specified.  This mode is supported
	     by	redirections and relays.

     mode source-hash
	     Balances the outgoing connections across the active hosts based
	     on	the hashed name	of the redirection or relay, the hashed	name
	     of	the table, and the source IP address of	the client.  This mode
	     is	only supported by relays.

REDIRECTIONS
     Redirections represent a pf(4) rdr-to rule.  They are used	for stateful
     redirections to the hosts in the specified	tables.	 pf(4) rewrites	the
     target IP addresses and ports of the incoming connections,	operating on
     layer 3.  The configuration directives that are valid in the redirect
     context are described below:

     disable
	     The redirection is	initially disabled.  It	can be later enabled
	     through relayctl(8).

     forward to	<table>	[port number] options ...
	     Specify the tables	of target hosts	to be used; see	the TABLES
	     section above for information about table options.	 If the	port
	     option is not specified, the first	port from the listen on	direc-
	     tive will be used.	 This directive	can be specified twice - the
	     second entry will be used as the backup table if all hosts	in the
	     main table	are down.  At least one	entry for the main table is
	     mandatory.

     listen on address [ip-proto] port port [interface name]
	     Specify an	address	and a port to listen on.  pf(4)	will redirect
	     incoming connections for the specified target to the hosts	in the
	     main or backup table.  The	port argument can optionally specify a
	     port range	instead	of a single port; the format is
	     min-port:max-port.	 The optional argument ip-proto	can be used to
	     specify an	IP protocol like tcp or	udp; it	defaults to tcp.  The
	     rule can be optionally restricted to a given interface name.

     route to <table> [port number] options ...
	     Like the forward to directive, but	directly routes	the packets to
	     the target	host without modifying the target address using	a
	     pf(4) route-to rule.  This	can be used for	"direct	server return"
	     to	force the target host to respond via a different gateway.
	     Note that hosts have to accept sessions for the same address as
	     the gateway, which	is typically done by configuring a loopback
	     interface on the host with	this address.

     session timeout seconds
	     Specify the inactivity timeout in seconds for established redi-
	     rections.	The default timeout is 600 seconds (10 minutes).  The
	     maximum is	2147483647 seconds (68 years).

     sticky-address
	     This has the same effect as specifying sticky-address for an rdr-
	     to	rule in	pf.conf(5).  It	will ensure that multiple connections
	     from the same source are mapped to	the same redirection address.

     [match] pftag name
	     Automatically tag packets passing through the pf(4) rdr-to	rule
	     with the name supplied.  This allows simpler filter rules.	 The
	     optional match keyword will change	the default rule action	from
	     pass in quick to match in to allow	further	evaluation in the pf
	     ruleset using the tagged name rule	option.

RELAYS
     Relays will forward traffic between a client and a	target server.	In
     contrast to redirections and IP forwarding	in the network stack, a	relay
     will accept incoming connections from remote clients as a server, open an
     outgoing connection to a target host, and forward any traffic between the
     target host and the remote	client,	operating on layer 7.  A relay is also
     called an application layer gateway or layer 7 proxy.

     The main purpose of a relay is to provide advanced	load balancing func-
     tionality based on	specified protocol characteristics, such as HTTP head-
     ers, to provide SSL acceleration and to allow basic handling of the un-
     derlying application protocol.

     The relay configuration directives	are described below:

     disable
	     Start the relay but immediately close any accepted	connections.

     [transparent] forward [with ssl] to address [port port] options ...
	     Specify the address and port of the target	host to	connect	to.
	     If	the port option	is not specified, the port from	the listen on
	     directive will be used.  Use the transparent keyword to enable
	     fully-transparent mode; the source	address	of the client will be
	     retained in this case.

	     The with ssl directive enables client-side	SSL mode to connect to
	     the remote	host.  Verification of server certificates can be en-
	     abled by setting the ca file option in the	protocol section.

	     The following options may be specified for	forward	directives:

	     retry number
		     The optional host retry option will be used as a toler-
		     ance for failed host connections; the connection will be
		     retried for number	more times.

	     inet    If	the requested destination is an	IPv6 address,
		     relayd(8) will forward the	connection to an IPv4 address
		     which is determined by the	last 4 octets of the original
		     IPv6 destination.	For example, if	the original IPv6 des-
		     tination address is 2001:db8:7395:ffff::a01:101, the ses-
		     sion is relayed to	the IPv4 address 10.1.1.1 (a01:101).

	     inet6 address-prefix
		     If	the requested destination is an	IPv4 address,
		     relayd(8) will forward the	connection to an IPv6 address
		     which is determined by setting the	last 4 octets of the
		     specified IPv6 address-prefix to the 4 octets of the
		     original IPv4 destination.	 For example, if the original
		     IPv4 destination address is 10.1.1.1 and the specified
		     address prefix is 2001:db8:7395:ffff::, the session is
		     relayed to	the IPv6 address 2001:db8:7395:ffff::a01:101.

     forward to	<table>	[port port] options ...
	     Like the previous directive, but connect to a host	from the spec-
	     ified table; see the TABLES section above for information about
	     table options.  This directive can	be specified multiple times -
	     subsequent	entries	will be	used as	the backup table if all	hosts
	     in	the previous table are down.  At least one entry for the main
	     table is mandatory.

     forward to	destination options ...
	     When redirecting connections with a rdr-to	rule in	pf.conf(5) to
	     a relay listening on localhost, this directive will look up the
	     real destination address of the intended target host, allowing
	     the relay to be run as a transparent proxy.  If an	additional
	     forward to	directive to a specified address or table is present,
	     it	will be	used as	a backup if the	NAT lookup failed.

     listen on address [port port] [ssl]
	     Specify the address and port for the relay	to listen on.  The re-
	     lay will accept incoming connections to the specified address.
	     If	the port option	is not specified, the port from	the listen on
	     directive will be used.

	     If	the ssl	keyword	is present, the	relay will accept connections
	     using the encrypted SSL protocol.	The relay will attempt to look
	     up	a private key in /usr/local/etc/ssl/private/address:port.key
	     and a public certificate in /usr/local/etc/ssl/address:port.crt,
	     where address is the specified IP address and port	is the speci-
	     fied port that the	relay listens on.  If these files are not
	     present, the relay	will continue to look in
	     /usr/local/etc/ssl/private/address.key and
	     /usr/local/etc/ssl/address.crt.  See ssl(8) for details about SSL
	     server certificates.

     protocol name
	     Use the specified protocol	definition for the relay.  The generic
	     TCP protocol options will be used by default; see the PROTOCOLS
	     section below.

     session timeout seconds
	     Specify the inactivity timeout in seconds for accepted sessions.
	     The default timeout is 600	seconds	(10 minutes).  The maximum is
	     2147483647	seconds	(68 years).

SSL RELAYS
     In	addition to plain TCP, relayd(8) supports the Secure Sockets Layer
     (SSL) and Transport Layer Security	(TLS) cryptographic protocols for au-
     thenticated and encrypted relays.	TLS is the successor of	the original
     SSL protocol but the term SSL can refer to	either of the protocols	in
     relayd.conf.  relayd(8) can operate as an SSL client or server to offer a
     variety of	options	for different use cases	related	to SSL.

     SSL client
	     When configuring the relay	forward	statements with	the with ssl
	     directive,	relayd(8) will enable client-side SSL to connect to
	     the remote	host.  This is commonly	used for SSL tunneling and
	     transparent encapsulation of plain	TCP connections.  See the
	     forward to	description in the RELAYS section for more details.

     SSL server
	     When specifying the ssl keyword in	the relay listen statements,
	     relayd(8) will accept connections from clients as an SSL server.
	     This mode is also known as	"SSL acceleration".  See the listen on
	     description in the	RELAYS section for more	details.

     SSL client	and server
	     When combining both modes,	SSL server and client, relayd(8) can
	     filter SSL	connections as a man-in-the-middle.  This combined
	     mode is also called "SSL inspection".  The	configuration requires
	     additional	X.509 certificate settings; see	the ca key description
	     in	the PROTOCOLS section for more details.

     When configured for "SSL inspection" mode,	relayd(8) will listen for in-
     coming connections	which have been	diverted to the	local socket by	PF.
     Before accepting and negotiating the incoming SSL connection as a server,
     it	will look up the original destination address on the diverted socket,
     and pre-connect to	the target server as an	SSL client to obtain the re-
     mote SSL certificate.  It will update or patch the	obtained SSL certifi-
     cate by replacing the included public key with its	local server key be-
     cause it doesn't have the private key of the remote server	certificate.
     It	also updates the X.509 issuer name to the local	CA subject name	and
     signs the certificate with	its local CA key.  This	way it keeps all the
     other X.509 attributes that are already present in	the server certifi-
     cate, including the "green	bar" extended validation attributes.  Now it
     finally accepts the SSL connection	from the diverted client using the up-
     dated certificate and continues to	handle the connection and to connect
     to	the remote server.

PROTOCOLS
     Protocols are templates defining settings and rules for relays.  They al-
     low setting generic TCP options, SSL settings, and	rules for the selected
     application layer protocol.

     The protocol directive is available for a number of different application
     layer protocols.  There is	no generic handler for UDP-based protocols be-
     cause it is a stateless datagram-based protocol which has to look into
     the application layer protocol to find any	possible state information.

     dns protocol
	     (UDP) Domain Name System (DNS) protocol.  The requested IDs in
	     the DNS header will be used to match the state.  relayd(8)	re-
	     places these IDs with random values to compensate for predictable
	     values generated by some hosts.

     http protocol
	     Handle the	HyperText Transfer Protocol (HTTP, or "HTTPS" if en-
	     capsulated	in an SSL tunnel).

     [tcp] protocol
	     Generic handler for TCP-based protocols.  This is the default.

     The available configuration directives are	described below:

     (block|pass|match)	[rule]
	     Specify one or more rules to filter connections based on their
	     network or	application layer headers; see the FILTER RULES	sec-
	     tion for more details.

     return error [option]
	     Return an error response to the client if an internal operation
	     or	the forward connection to the client failed.  By default, the
	     connection	will be	silently dropped.  The effect of this option
	     depends on	the protocol: HTTP will	send an	error header and page
	     to	the client before closing the connection.  Additional valid
	     options are:

	     style string
		     Specify a Cascading Style Sheet (CSS) to be used for the
		     returned HTTP error pages,	for example:

			   body	{ background: #a00000; color: white; }

     ssl option
	     Set the SSL options and session settings.	This is	only used if
	     SSL is enabled in the relay.  Valid options are:

	     ca	cert path
		     Specify a CA certificate for SSL inspection.  For more
		     information, see the ca key option	below.

	     ca	file path
		     This option enables CA verification in SSL	client mode.
		     The daemon	will load the CA (Certificate Authority) cer-
		     tificates from the	specified path to verify the server
		     certificates.

	     ca	key path password password
		     Specify a CA key for SSL inspection.  The password	argu-
		     ment will specify the password to decrypt the CA key
		     (typically	an RSA key).  This option will enable SSL in-
		     spection if the following conditions are true:

			   +o   SSL client mode is enabled by the listen	direc-
			       tive: listen on ... ssl.
			   +o   SSL server mode and divert lookups are enabled
			       by the forward directive: forward with ssl to
			       destination.
			   +o   The ca cert option is specified.
			   +o   The ca key option is specified.

	     ciphers string
		     Set the string defining the SSL cipher suite.  If not
		     specified,	the default value HIGH:!aNULL will be used
		     (strong crypto cipher suites without anonymous DH).  See
		     the CIPHERS section of openssl(1) for information about
		     SSL cipher	suites and preference lists.

	     [no] cipher-server-preference
		     Prefer the	server's cipher	list over the client's prefer-
		     ences when	choosing a cipher for the connection; disabled
		     by	default.

	     [no] client-renegotiation
		     Allow client-initiated renegotiation; enabled by default.
		     Disable to	mitigate a potential DoS risk.

	     ecdh [curve name]
		     Set a named curve to use when generating EC keys for
		     ECDHE-based cipher	suites with Perfect Forward Security
		     (PFS).  If	the curve name is not specified, the default
		     curve prime256v1 will be used.  ECDHE is enabled by de-
		     fault.

	     no	ecdh
		     Disable ECDHE support.

	     edh [params maximum]
		     Enable EDH-based cipher suites with Perfect Forward Secu-
		     rity (PFS)	for older clients that do not support ECDHE.
		     If	the maximum length of the DH params for	EDH is not
		     specified,	the default value of 1024 bits will be used.
		     Other possible values are numbers between 1024 and	8192,
		     including 1024, 1536, 2048, 4096, or 8192.	 Values	higher
		     than 1024 bits can	cause incompatibilities	with older SSL
		     clients.

	     no	edh  Disable EDH support.  This	is the default.

	     session cache value
		     Set the maximum size of the SSL session cache.  If	the
		     value is zero, the	default	size defined by	the SSL	li-
		     brary will	be used.  A positive number will set the maxi-
		     mum size in bytes and the keyword disable will disable
		     the SSL session cache.

	     [no] sslv2
		     Enable the	SSLv2 protocol;	disabled by default.

	     [no] sslv3
		     Disable the SSLv3 protocol; enabled by default.

	     [no] tlsv1
		     Disable the TLSv1/SSLv3.1 protocol; enabled by default.

     tcp option
	     Enable or disable the specified TCP/IP options; see tcp(4)	and
	     ip(4) for more information	about the options.  Valid options are:

	     backlog number
		     Set the maximum length the	queue of pending connections
		     may grow to.  The backlog option is 10 by default and is
		     limited by	the kern.somaxconn sysctl(8) variable.

	     ip	minttl number
		     This option for the underlying IP connection may be used
		     to	discard	packets	with a TTL lower than the specified
		     value.  This can be used to implement the Generalized TTL
		     Security Mechanism	(GTSM) according to RFC	5082.

	     ip	ttl number
		     Change the	default	time-to-live value in the IP headers.

	     [no] nodelay
		     Enable the	TCP NODELAY option for this connection.	 This
		     is	recommended to avoid delays in the relayed data
		     stream, e.g. for SSH connections.

	     [no] sack
		     Use selective acknowledgements for	this connection.

	     socket buffer number
		     Set the socket-level buffer size for input	and output for
		     this connection.  This will affect	the TCP	window size.

FILTER RULES
     Relays have the ability to	filter connections based on their network or
     application layer headers.	 Filter	rules apply options to connections
     based on the specified filter parameters.

     For each connection that is processed by a	relay, the filter rules	are
     evaluated in sequential order, from first to last.	 For block and pass,
     the last matching rule decides what action	is taken; if no	rule matches
     the connection, the default action	is to establish	the connection without
     any additional action.  For match,	rules are evaluated every time they
     match; the	pass/block state of a connection remains unchanged.

     The filter	action may be one of the following:

     block   The connection is blocked.	 If a block rule matches a new connec-
	     tion attempt, it will not be established.	block rules can	also
	     trigger for existing connections after evaluating application
	     layer parameters; any connection of the relay session will	be in-
	     stantly dropped.

     match   The connection is matched.	 This action does not alter the	con-
	     nection state, but	allows additional parameters to	the connec-
	     tion.

     pass    The connection is passed; relayd(8) will continue to process the
	     relay session normally.

     These filter parameters can be used in the	rules:

     request or	response
	     A relay session always consists of	two connections: the request,
	     a client initiating a new connection to a server via the relay,
	     and the response, the server accepting the	connection.  Depending
	     on	the protocol, an established session can be purely request/re-
	     sponse-based (like	HTTP), exchange	data in	a bidirectional	way
	     (like arbitrary TCP sessions), or just contain a single datagram
	     and an optional response (like UDP-based protocols).  But the
	     client always requests to communicate with	a remote peer; the
	     server.

     quick   If	a connection is	matched	by a rule with the quick option	set,
	     the rule is considered to be the last matching rule and any fur-
	     ther evaluation is	skipped.

     inet or inet6
	     Only match	connections with the specified address family, either
	     of	type IPv4 or IPv6.

     label string
	     The label will be printed as part of the error message if the
	     return error option is set	and may	contain	HTML tags, for exam-
	     ple:

		   block request url digest 5c1e03f58f8ce0b457474ffb371fd1ef \
			   label "<a href='http://example.com/adv.pl?id=7359'>\
			   Advisory provided by	example.com</a>"

     no	parameter
	     Reset a sticky parameter that was previously set by a matching
	     rule.  The	parameter is a keyword that can	be either label	or
	     tag.

     tag string
	     Add a "sticky" tag	to connections matching	this filter rule.
	     Tags can be used to filter	the connection by further rules	using
	     the tagged	option.	 Only one tag is assigned per connection; the
	     tag will be replaced if the connection is already tagged.

     tagged string
	     Match the connection if it	is already tagged with a given tag by
	     a previous	rule.

     The following parameters are available when using the http	protocol:

     method NAME
	     Match the HTTP request method.  The method	is specified by	name
	     and can be	either CONNECT,	COPY, DELETE, GET, HEAD, LOCK, MKCOL,
	     MOVE, OPTIONS, PATCH, POST, PROPFIND, PROPPATCH, PUT, TRACE, or
	     UNLOCK.

     type option [[digest] (key|file path) [value value]]
	     Match a specified HTTP header entity and an optional key and
	     value.  An	option can be specified	to modify the matched entity
	     or	to trigger an event.  The entity is extracted from the HTTP
	     request or	response header	and can	be either of type cookie,
	     header, path, query, or url.

	     Instead of	a single key, multiple keys can	be loaded from a file
	     specified by path that contains one key per line.	Lines will be
	     stripped at the first whitespace or newline character and any
	     empty lines or lines beginning with a hash	mark (`#') will	be ig-
	     nored.

	     If	the digest keyword is specified, compare the message digest of
	     the key against the defined string.  The algorithm	used is	deter-
	     mined by the string length	of the key argument, either SHA1 (40
	     characters) or MD5	(32 characters).  To compute the digest, for
	     example for a url,	use this simple	command:

		   $ echo -n "example.com/path/?args" |	sha1

     [type] may	be one of:

     cookie option [key	[value value]]
	     Look up the entity	as a value in the Cookie header.  This type is
	     only available with the direction request.

     header option [key	[value value]]
	     Look up the entity	in the application protocol headers, like HTTP
	     headers in	http mode.

     path option [key [value value]]
	     Look up the entity	as a value in the URL path when	using the http
	     protocol.	This type is only available with the direction
	     request.  The key will match the path of the requested URL	with-
	     out the hostname and query	and the	value will match the complete
	     query, for	example:

		   block path "/index.html"
		   block path "/cgi-bin/t.cgi" value "foo=bar*"

     query option [key [value value]]
	     Look up the entity	as a query variable in the URL when using the
	     http protocol.  This type is only available with the direction
	     request, for example:

		   # Will match	/cgi-bin/example.pl?foo=bar&ok=yes
		   request query expect	"bar" from "foo"

     url option	[[digest] key [value value]]
	     Look up the entity	as a URL suffix/prefix expression consisting
	     of	a canonicalized	hostname without port or suffix	and a path
	     name or prefix when using the http	protocol.  This	type is	only
	     available with the	direction request, for example:

		   block url "example.com/index.html"
		   block url "example.com/test.cgi?val=1"

	     relayd(8) will match the full URL and different possible suf-
	     fix/prefix	combinations by	stripping subdomains and path compo-
	     nents (up to 5 levels), and the query string.  For	example, the
	     following lookups will be done for
	     http://www.example.com:81/1/2/3/4/5.html?query=yes:

		   www.example.com/1/2/3/4/5.html?query=yes
		   www.example.com/1/2/3/4/5.html
		   www.example.com/
		   www.example.com/1/
		   www.example.com/1/2/
		   www.example.com/1/2/3/
		   example.com/1/2/3/4/5.html?query=yes
		   example.com/1/2/3/4/5.html
		   example.com/
		   example.com/1/
		   example.com/1/2/
		   example.com/1/2/3/

     [option] may be one of:

     append  Append the	specified value	to a protocol entity with the selected
	     key name.	If it does not exist, it will be created with the new
	     value.

	     The value string may contain predefined macros that will be ex-
	     panded at runtime:

		   $REMOTE_ADDR	 The IP	address	of the connected client.
		   $REMOTE_PORT	 The TCP source	port of	the connected client.
		   $SERVER_ADDR	 The configured	IP address of the relay.
		   $SERVER_PORT	 The configured	TCP server port	of the relay.
		   $SERVER_NAME	 The server software name of relayd(8).
		   $TIMEOUT	 The configured	session	timeout	of the relay.

     hash    Feed the value of the selected entity into	the load balancing
	     hash to select the	target host.  See the table keyword in the
	     RELAYS section above.

     log     Log the key name and the value of the entity.

     remove  Remove the	entity with the	selected key name.

     set     Like the append directive above, but change the contents of the
	     specified entity.	If key does not	exist in the request, it will
	     be	created	with the new value.

	     The value string may contain predefined macros that will be ex-
	     panded at runtime,	as detailed for	the append directive above.

FILES
     /usr/local/etc/relayd.conf		       relayd(8) configuration file.

     /etc/services			       Service name database.

     /usr/local/etc/ssl/address.crt
     /usr/local/etc/ssl/address:port.crt
     /usr/local/etc/ssl/private/address.key
     /usr/local/etc/ssl/private/address:port.key
					       Location	of the relay SSL
					       server certificates, where
					       address is the configured IP
					       address and port	is the config-
					       ured port number	of the relay.

     /usr/local/etc/ssl/cert.pem	       Default location	of the CA bun-
					       dle that	can be used with
					       relayd(8).

EXAMPLES
     This configuration	file would create a redirection	service	"www" which
     load balances four	hosts and falls	back to	one host containing a "sorry
     page":

	   www1=front-www1.private.example.com
	   www2=front-www2.private.example.com
	   www3=front-www3.private.example.com
	   www4=front-www4.private.example.com

	   interval 5

	   table <phphosts> { $www1, $www2, $www3, $www4 }
	   table <sorryhost> disable { sorryhost.private.example.com }

	   redirect "www" {
		   listen on www.example.com port 8080 interface trunk0
		   listen on www6.example.com port 80 interface	trunk0

		   pftag REDIRECTED

		   forward to <phphosts> port 8080 timeout 300 \
			   check http "/" digest "630aa3c2f..."
		   forward to <sorryhost> port 8080 timeout 300	check icmp
	   }

     It	is possible to specify multiple	listen directives with different IP
     protocols in a single redirection configuration:

	   redirect "dns" {
		   listen on dns.example.com tcp port 53
		   listen on dns.example.com udp port 53

		   forward to <dnshosts> port 53 check tcp
	   }

     The following configuration would add a relay to forward secure HTTPS
     connections to a pool of HTTP webservers using the	loadbalance mode (SSL
     acceleration and layer 7 load balancing).	The HTTP protocol definition
     will add two HTTP headers containing address information of the client
     and the server, set the "Keep-Alive" header value to the configured ses-
     sion timeout, and include the "sessid" variable in	the hash to calculate
     the target	host:

	   http	protocol "http_ssl" {
		   match header	append "X-Forwarded-For" \
			   value "$REMOTE_ADDR"
		   match header	append "X-Forwarded-By"	\
			   value "$REMOTE_ADDR:$SERVER_PORT"
		   match header	set "Keep-Alive" value "$TIMEOUT"

		   match query hash "sessid"
		   match hash "sessid"

		   pass
		   block path "/cgi-bin/index.cgi" value "*command=*"

		   ssl { sslv2,	ciphers	"MEDIUM:HIGH" }
	   }

	   relay "sslaccel" {
		   listen on www.example.com port 443 ssl
		   protocol "http_ssl"
		   forward to <phphosts> port 8080 mode	loadbalance check tcp
	   }

     The second	relay example will accept incoming connections to port 2222
     and forward them to a remote SSH server.  The TCP nodelay option will al-
     low a "smooth" SSH	session	without	delays between keystrokes or displayed
     output on the terminal:

	   protocol "myssh" {
		   tcp { nodelay, socket buffer	65536 }
	   }

	   relay "sshforward" {
		   listen on www.example.com port 2222
		   protocol "myssh"
		   forward to shell.example.com	port 22
	   }

     The following relay example will configure	"SSL inspection" as described
     in	the SSL	RELAYS section.	 To start, first generate a new	local CA key
     and certificate:

	   # openssl req -x509 -days 365 -newkey rsa:2048 \
		   -keyout /usr/local/etc/ssl/private/ca.key \
		   -out	/usr/local/etc/etc/ssl/ca.crt

     An	SSL server key and self-signed cert for	127.0.0.1 are also required;
     see listen	on in the RELAYS section for more details about	certificate
     locations.	 Configure the packet filter with a matching divert rule in
     pf.conf(5):

	   # Divert incoming HTTPS traffic to relayd
	   pass	in on vlan1 inet proto tcp to port 443 \
		   divert-to localhost port 8443

     And finally configure the SSL inspection in relayd.conf:

	   http	protocol httpfilter {
		   return error

		   pass
		   match label "Prohibited!"
		   block url "social.network.example.com/"

		   # New configuration directives for SSL Interception
		   ssl ca key "/etc/ssl/private/ca.key"	password "password123"
		   ssl ca cert "/etc/ssl/ca.crt"
	   }

	   relay sslinspect {
		   listen on 127.0.0.1 port 8443 ssl
		   protocol httpfilter
		   forward with	ssl to destination
	   }

     The next simple router configuration example can be used to run redun-
     dant, health-checked WAN links:

	   table <gateways> { $gw1 ip ttl 1, $gw2 ip ttl 1 }
	   router "uplinks" {
		   route 0.0.0.0/0
		   forward to <gateways> check icmp
	   }

SEE ALSO
     relayctl(8), relayd(8), ssl(8)

HISTORY
     The relayd.conf file format, formerly known as hoststated.conf, first ap-
     peared in OpenBSD 4.1.  It	was renamed to relayd.conf in OpenBSD 4.3.

AUTHORS
     The relayd(8) program was written by Pierre-Yves Ritschard
     <pyr@openbsd.org> and Reyk	Floeter	<reyk@openbsd.org>.

CAVEATS
     relayd(8) Verification of SSL server certificates is based	on a static CA
     bundle and	relayd(8) currently does not support CRLs (Certificate Revoca-
     tion Lists).

BSD				 July 11, 2014				   BSD

NAME | DESCRIPTION | SECTIONS | MACROS | GLOBAL CONFIGURATION | TABLES | REDIRECTIONS | RELAYS | SSL RELAYS | PROTOCOLS | FILTER RULES | FILES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=relayd.conf&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help