RELAYD.CONF

RELAYD.CONF(5) OpenBSD Programmer’s ManualRELAYD.CONF(5)
http://www.openbsd.org/cgi-bin/man.cgi?query=relayd.conf&sektion=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 six main sections:
? Macros
User-defined variables may be defined and used later, simplifying
the configuration file.
? Global Configuration
Global settings for relayd(8).
? 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 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 protocol handlers and settings for relays.
? Within the sections, a host address can be specified by IPv4 address,
IPv6 address, or DNS hostname.? 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.
? Comments can be put anywhere in the file using a hash mark (`#’), and ex-
tend to the end of the current line.
? Additional configuration files can be included with the include keyword,
for example:
include “/etc/relayd.conf.local”
MACROS
Macros can be defined that will later be expanded in context.? Macro
names must start with a letter, and may contain letters, digits, and un-
derscores.? 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:
? demote group
Enable the global carp(4) demotion option, resetting the carp de-
motion counter for the specified interface group to zero on
startup and to 128 on shutdown of the daemon.? For more informa-
tion on interface groups, see the group keyword in ifconfig(8).
? 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 5 relay
processes by default and every process will handle all configured
relays.
? send trap
Send an SNMP trap when the state of a host changes.? relayd(8)
will try to connect to snmpd(8) and request it send a trap to the
registered trap receivers; see snmpd.conf(5) for more information
about the configuration.
? timeout number
Set the global timeout in milliseconds for checks.? This can be
overriden by the timeout value in the table definitions.? The de-
fault 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.
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
table.? The table can be later enabled through relayctl(8).
? Each table must contain at least one host; multiple hosts are separated
by newline, comma, or whitespace.?Host entries may be defined with the
following attribute:
? 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 al-
so specify the number of retries for outgoing connection attempts.
? For example:
table <service> { 192.168.1.1, www.houquner.com, 192.168.2.3 }
table <backup> 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 <backup> 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.
? 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 content whose message digest matches the defined string.
The algorithm used is determined by the string length of the
digest argument, either SHA1 (40 characters) or MD5 (32 charac-
ters).? If hostname is specified, it is used as theHost:”
header to query a specific hostname at the target host.? The di-
gest does not take the HTTP headers into account.?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 specifing 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:
? demote group
Enable the per-table carp(4) demotion option.? This will incre-
ment the carp demotion counter for the specified interface group
if all hosts in the table are down.? For more information on in-
terface groups, see the group keyword in ifconfig(8).
? 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 algoritm 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 table.? Additional input can be fed in-
to the hash by looking at HTTP headers and GET variables; see the
PROTOCOLS section below.? This mode is only supported by relays.
? mode loadbalance
Balances the outgoing connections across the active hosts based
on the hashed name of the table, the source and destination ad-
dresses, and the corresponding ports.? This mode is only support-
ed 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.
REDIRECTIONS
Redirections represent a pf(4) rdr 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 port from the listen on directive
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 manda-
tory.
? listen on address 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 rdr rule can be optionally restricted
to a given interface name.
? sticky-address
This has the same effect as specifying sticky-address for an rdr
rule in pf.conf(5).? It will ensure that multiple connections
from the same source are mapped to the same redirection address.
? tag name
Automatically tag packets passing through the pf(4) rdr rule with
the name supplied.? This allows simpler filter rules.
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.
? forward to address [port port] [retry number]
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.
The optional host retry option will be used as a tolerance for
failed host connections; the connection will be retried for
number more times.
? 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.
? forward to nat lookup [retry number]
When redirecting connections with an rdr rule in pf.conf(5) to a
relay listening on localhost, this directive will look up the re-
al 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 look up a pri-
vate key in /etc/ssl/private/address.key and a public certificate
in /etc/ssl/address.crt, where address is the specified IP ad-
dress of the relay to listen on.? 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.
? timeout seconds
Specify the timeout in seconds for accepted sessions.? The de-
fault timeout is 600 seconds (10 minutes).
PROTOCOLS
Protocols are templates defining actions and settings for relays.?They
allow setting generic TCP options, SSL settings, and actions specific to
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:
? [direction] [type] action [marked id] [log]
Define an action for the selected entity.?The optional log key-
word will log the entity name and the value and the optional
marked keyword requires that the session has been marked with a
given identifier in order to execute the action.? The actions are
dependent on the underlying application protocol.
? [direction] may be one of:
? request
Handle the data stream from the client to the relay, like HTTP
requests.?This is the default if the direction directive is
omitted.
? response
Handle the data stream from the target host to the relay, like
HTTP server replies.
? [action] may be one of:
? cookie? Look up the entity as a value in the Cookie header when using the
http protocol.? This type is only available with the direction
request.
? header? Look up the entity in the application protocol headers, like HTTP
headers in http mode.
? path 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:
? request path filter “/index.html”
request path filter “foo=bar*” from “/cgi-bin/t.cgi”
? query 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? 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:
? request url filter “example.com/index.html”
request url filter “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/
? [action] may be one of:
? append value to key
Append the specified value to a protocol entity with the selected
name.? When using the http protocol, key will indicate a speci-
fied HTTP header.?If key does not exist in the request, it will
be created with the value set to 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.
$TIMEOUT? The configured session timeout of the relay.
? change key to value
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 value set to value.
The value string may contain predefined macros that will be ex-
panded at runtime, as detailed for the append directive above.
? expect value from key
Expect an entity key and match against value using shell globbing
rules.? If the entity is not present or the value doesn’t match,
the connection will be dropped.
? expect [digest] key
Expect an entity key with any possible value.? This is the short
form of expect * from key.
If the digest keyword is specified, compare the message digest of
the entity against the defined string.? The algorithm used is de-
termined by the string length of the key argument, either SHA1
(40 characters) or MD5 (32 characters).? To compute the digest,
use this simple command:
? $ echo -n “example.com/path/?args” | sha1
? filter value from key
Like the expect .. from directive above, but drop any connections
with the specified entity key and a matching value.
? filter [digest] key
Like the expect directive above, but drop any connections with
the specified entity key and any possible value.? This is the
short form of filter * from key.
? hash key
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 key
Log the name and the value of the entity.
? mark [value from] key with id
Mark the session with the specified identifier (a positive number
between 1 and 65535) if the specified condition matches.? Note
that the mark action does not accept the marked option (see
above).
? label string
Add a label to subsequently added actions.? The label will be
printed as part of the error message if the return error option
is set and may contain HTML tags, for example:
? label “<a href=’http://example.com/advisory.pl?id=7359‘>
Advisory provided by example.com</a>”
url filter digest 5c1e03f58f8ce0b457474ffb371fd1ef
url filter digest 80c1a7b8337462093ef8359c57b4d56a
no label
? no label
Do not set a label for subsequently added actions; this is the
default.
? remove key
Remove the entity with the selected name.
? return error [option]
Return an error reponse 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:
ciphers string
Set the string defining the SSL cipher suite.? If not
specified, the default value HIGH:!ADH 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.
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 3682.
ip ttl? 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.
FILES
/etc/relayd.conf relayd(8) configuration file.
? /etc/services Service name database.
? /etc/ssl/address.crt
/etc/ssl/private/address.key Location of the relay SSL server certifi-
cates, where address is the configured IP
address of the relay.
EXAMPLES
This configuration file would create a service www'' which load bal-
ances four hosts and falls back to one host containing asorry 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
? tag REDIRECTED
? forward to <phphosts> port 8080 timeout 300
check http “/” digest “630aa3c2f…”
forward to <sorryhost> port 8080 timeout 300 check icmp
}
? 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
session timeout, and include thesessid” variable in the hash to cal-
culate the target host:
http protocol “http_ssl” {
header append “$REMOTE_ADDR” to “X-Forwarded-For”
header append “$SERVER_ADDR:$SERVER_PORT” to “X-Forwarded-By”
header change “Keep-Alive” to “$TIMEOUT”
query hash “sessid”
cookie hash “sessid”
path filter “*command=*” from “/cgi-bin/index.cgi”
? 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 dis-
played 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
}
SEE ALSO
relayctl(8), relayd(8), snmpd(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>.
OpenBSD 4.3 March 3, 2008? 11

转载请注明：Kermit的网站 » RELAYD.CONF